UI 功能

使用编辑器、交易表单和查询报告来处理你的账本。下面的可执行配方针对 stock Fava 1.30.16，搭配 Beancount 3.2.3 和 beanquery 0.2.0；请遵循固定本地设置。

Beancount.io 使用一个单独的仪表板。其产品源码确认了用于编辑、查询、文档和设置的账本路由，以及若干 Fava 显示选项的消费者。这并不意味着 stock Fava 的键盘快捷键、插入规则、插件执行或 URL 路径成为托管兼容性的承诺。下图显示的是托管仪表板，而非 stock UI。

探索实时账本 →

1. 编辑与数据录入​

内置编辑器​

Stock Fava 的编辑器提供对账户、付款方和标签的自动补全功能。使用 default-file 来选择其初始源文件。insert-entry 还会将光标定位到该文件中最近的插入标记处；它不是核心的 Beancount 选项。

2000-01-01 custom "fava-option" "default-file"
2024-01-01 custom "fava-option" "insert-entry" "^Expenses:Food$"

此片段会选择其所在文件。2024 年 1 月 1 日之后与 Expenses:Food 匹配的新条目会被插入到标记之前，除非有更晚的适用规则或更晚的帖子账户优先。参见完整的多文件插入示例。

添加交易​

在 Stock Fava 中，点击 + 或按 n 即可打开交易表单。叙述字段接受以空格分隔的标签和链接，例如 Lunch #food ^receipt-001。账户名称必须已有 open 指令。

将以下完整账本保存为 ui-demo.beancount 以尝试下面的报告。正数支出是借方；负数现金账目是它的贷方。

option "title" "UI Demo"
option "operating_currency" "USD"
2024-01-01 open Assets:Checking USD
  fava-uptodate-indication: TRUE
2024-01-01 open Income:Salary USD
2024-01-01 open Expenses:Food USD
 
2024-01-02 * "Salary"
  Assets:Checking    3000.00 USD
  Income:Salary     -3000.00 USD
 
2024-01-03 * "Groceries" #food
  Expenses:Food       400.00 USD
  Assets:Checking    -400.00 USD
 
2024-01-04 balance Assets:Checking 2600.00 USD

运行 bea --file ui-demo.beancount check，然后运行 fava ui-demo.beancount。检查通过，余额为 2,600.00 USD。带 #template 的未来日期交易仍然是一个真实交易：该标签并不会使其成为惰性的可重用表单模板。请将假设性交易保留在单独的情景账本中。

2. 文档管理​

Stock Fava 可以通过将文档拖放到账户名称或日记行上来上传文档。配置一个真实的文档根目录，并保持其账户层级与你已开放的账户一致。

此可选片段可以添加到 ui-demo.beancount 中。首先在账本旁边创建一个 documents 目录。要尝试发现功能，请在 documents/Expenses/Food/ 内放置一个名为 2024-01-03-receipt.pdf 的真实文件。

option "documents" "documents"
plugin "fava.plugins.link_documents"
plugin "fava.plugins.tag_discovered_documents"

这些是 Fava 1.30.16 中实际随附的模块。Beancount 会发现在账户目录下带日期的文件；tag_discovered_documents 会添加 #discovered 标签。link_documents 会匹配 document 元数据到文档条目并链接它们。它不会从收据内容推断交易关联。将该元数据直接添加到现有的 Groceries 标题下，在其帖子之前：

  document: "2024-01-03-receipt.pdf"

该缩进行是元数据片段，而非独立的账本。在该文件存在的情况下，文档会获得 #linked，并与交易共享 ^dok-2024-01-03。缺少匹配文档会出错。有关确切的 stock 行为，请参阅带版本标记的文档链接插件。

3. 使用 BQL 进行查询与分析​

Stock Fava 的查询页面运行 Beancount 查询语言。在复现这些全账本结果之前，请清除全局时间/账户过滤器。这些 UI 过滤器可能会在查询运行前移除某些条目。

结果可以下载为 CSV。图表支持取决于结果类型：stock 帮助仅描述了两列，且第二列为日期或字符串加库存。任意一对数值列并不能保证图表生成。

实用查询示例​

在 Fava 的查询页面中针对 ui-demo.beancount 运行以下查询，或将每个带引号的查询传递给 bea --file ui-demo.beancount query。

月度支出摘要：

SELECT account, SUM(position) AS total
FROM postings
WHERE account ~ '^Expenses:'
  AND date >= 2024-01-01 AND date < 2024-02-01
GROUP BY account
ORDER BY account;

预期结果：Expenses:Food，400.00 USD。

按月收入与支出对比：

SELECT YEAR(date) AS year, MONTH(date) AS month,
       ROOT(account, 1) AS category, currency,
       SUM(number) AS signed_total
FROM postings
WHERE account ~ '^(Income|Expenses):'
GROUP BY year, month, category, currency
ORDER BY year, month, category, currency;

该查询保留了 Beancount 的符号，并按货币分别分组单位。收入 3,000.00 USD 减去支出 400.00 USD 剩下 2,600.00 USD。这是一个单位报告，而非换算或成本基准报告。IIF 在 beanquery 0.2.0 中不可用，且不支持一元 -position；通过分组两个账户类别，可以避免这两种操作。

4. 自定义与工作流​

自定义视图​

将以下 Fava 指令添加到示例账本中，以隐藏余额为零的账户并折叠投资分支：

2000-01-01 custom "fava-option" "show-closed-accounts" "false"
2000-01-01 custom "fava-option" "show-accounts-with-zero-balance" "false"
2000-01-01 custom "fava-option" "collapse-pattern" "^Assets:Investments"

它们会影响报告账户树。余额非零的账户仍然可见。核心形式如 option "show-closed-accounts" "false" 无法通过 Beancount 验证。

示例中的 fava-uptodate-indication: TRUE 元数据位于 open 下的独立缩进行。不要将其放在 open 行上，也不要引用布尔值。最新通过的余额检查显示绿色；失败的检查显示红色；随后的交易显示黄色。1 月 4 日的断言为绿色。由于这些日期较旧，也可能出现单独的灰色新鲜度指示符。

侧边栏链接​

对于标题为 UI Demo 的 stock 示例，以下完整路径通向其报告：

2024-01-01 custom "fava-sidebar-link" "January Expenses" "/ui-demo/income_statement/?time=2024-01"
2024-01-01 custom "fava-sidebar-link" "All Documents" "/ui-demo/documents/"

这些路径假设 stock Fava 安装在主机根目录。将 /ui-demo 替换为你的实际账本 slug，并包含任何服务器挂载前缀。参见自定义侧边栏链接以了解经过测试的 /jump 行为以及托管路由边界。

一般配置​

使用多个主文件启动 stock Fava 会在其账本切换器中创建单独的账本。通过 include 引入的文件仍然是一个账本的一部分，并作为可编辑的源文件出现；它们不是独立的账簿。

使用 Fava 选项设置 language、default-file 和 use-external-editor。外部编辑器需要 beancount:// 处理器，并能访问源文件。真正的 stock 扩展模块还包括 fava.ext.auto_commit 和 fava.ext.portfolio_list。扩展使用 custom "fava-extension"，并有自己的先决条件；它们与上面使用的 plugin 指令不同。参见 Fava 的版本化扩展帮助。

5. 性能与故障排除​

处理大量文件​

使用 include 按账户或期间组织账本。但 Beancount 仍会加载包含的文件，因此拆分一本书本身并不会减少报告输入。当你需要较小的报告时，请限制显示的日期并简化耗时的查询。

常见问题与修复​

• 账本错误： 运行 bea check 并检查 Fava 的错误报告。页面可能会在加载器存在错误时仍能渲染。
• 意外的选项行为： 检查测试的运行时，并使用带日期的 Fava 自定义指令。bea check 本身无法检测未知的 Fava 选项。
• 意外的查询总计： 清除全局过滤器，包含开封历史，并保持货币分离。
• 文档缺失： 检查目录是否存在、账户是否已开放、文件名是否以有效日期开头，以及交易的元数据是否与文档匹配。

为了对比，以下为故意无效的示例。绝不能将其复制到正在工作的账本中：

option "insert-entry" "Expenses:Food"
custom "fava-sidebar-link" "Label" "/jump?time=month"

第一个使用了未知的核心选项。第二个缺少必要的日期。stock 功能参考 描述了此版本的 UI 行为。