Actual 24.11.0 版本深度解析规则模板引擎、Upcoming 计划长度与 Dashboards 实验特性【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actualActual 是一个本地优先local-first的个人财务管理应用其 24.11.0 版本围绕「自动化与可定制性」带来了一批显著改进。本文以该版本的官方发布文档为骨架结合仓库源码深入拆解规则模板Handlebars 模板与公式、Upcoming 计划显示长度、Dashboards 仪表盘增强、账户管理迁移与文件迁移等核心特性帮助读者理解每个改进背后的实现机制与实际使用方法。版本概览与升级方式Actual 24.11.0 于 2024 年 11 月发布官方发布文档packages/docs/blog/2024-11-03-release-24.11.0.md给出的 Docker 镜像标签为24.11.0可直接用于自托管部署。本版本的核心改进集中在四条主线SimpleFIN 银行同步 API 调用优化针对 Actual Server实验性支持设置 Upcoming 计划显示时长即未来多远距离的周期性交易显示在账户视图实验性 Dashboards 功能的多项改进实验性的规则模板化支持规则「设置」动作中引入 Handlebars 模板语法。此外还包含大量对移动端、CSV 导入、规则引擎、报表的 Bug 修复与维护性重构详见下文各节。规则模板引擎在「设置」动作中使用 Handlebars功能来源本次发布的规则模板功能来自两个 PR#3305为 set 动作引入基于 Handlebars 语法的规则动作模板#3619将模板能力扩展到payee_name字段。这意味着用户可以把规则动作写成{{ ... }}形式的模板表达式由引擎在规则匹配时动态求值而不是使用固定值。底层实现原理规则动作的核心实现在 packages/loot-core/src/server/rules/action.ts。其中Action类支持的操作类型ACTION_OPS包括set设置字段值支持固定值、公式、模板三种模式set-split-amount设置拆分金额支持固定金额、百分比、公式等分配方式link-schedule关联到计划交易prepend-notes/append-notes在备注前/后追加文本delete-transaction删除交易置 tombstone 标记。当set动作携带options.template时构造函数会调用Handlebars.compile(options.template, { noEscape: true })预编译模板并在exec()阶段执行// 源码节选packages/loot-core/src/server/rules/action.ts if (options?.template) { this.handlebarsTemplate Handlebars.compile(options.template, { noEscape: true, }); }执行模板时传入的上下文包含交易对象的所有字段并额外注入today当前日期变量object[this.field] this.handlebarsTemplate({ ...object, today: currentDay(), });Handlebars 总是返回字符串因此引擎按目标字段类型做转换见exec()中的 switchnumber 字段parseFloat转换结果为 NaN 时回退为 0避免数据库写入失败date 字段parseDate后校验合法性非法时写入9999-12-31作为显眼占位并输出错误日志boolean 字段字符串true判定为真。内置模板 Helper模板之所以强大是因为项目注册了大量内置 Helper。它们在 packages/loot-core/src/server/rules/handlebars-helpers.ts 中定义并在 packages/loot-core/src/server/rules/index.ts 中通过registerHandlebarsHelpers()统一注册按类别可分为字符串处理Helper说明regex正则替换支持/regex/flags语法如{{regex value /\d/ X}}replace普通替换支持正则字面量/.../flagsreplaceAll全局替换concat拼接多个参数数学运算Helper说明add/sub/div/mul/mod算术运算支持多参数如{{add a b c}}floor/ceil/round/abs取整与绝对值min/max最小值/最大值fixed保留指定位小数如{{fixed amount 2}}日期运算Helper说明day/month/year提取日期分量format按自定义格式输出日期addDays/subDays/addMonths/subMonths/addWeeks/subWeeks/addYears/subYears日期加减setDay将日期调整到指定「星期几」以本周为基准debug输出日志用于调试日期 Helper 底层基于date-fns与项目封装的#shared/months工具实现所有日期函数输入输出统一为yyyy-MM-dd格式。实际应用示例利用这些 Helper可以构建出非常灵活的规则动作例如# 给商家名补全把 COFFEE 统一改为 COFFEE SHOP set payee_name to template {{replaceAll payee_name COFFEE COFFEE SHOP}} # 备注前追加当前日期 prepend-notes {{format today yyyy-MM-dd}}: # 将金额四舍五入到整数 set amount to template {{round amount}}注意set动作在payee_name字段上执行模板后源码会将object[payee] newaction.ts即创建新的收款人实体这正是 #3619 将模板扩展到payee_name的核心逻辑。相关 Bug 修复本次发布同时修复了模板功能初期的问题#3632修复 action 规则模板中的转义escaping问题#3749修复规则模板中使用日期函数的问题#3704修复无法通过规则修改 Payee 的问题#3705修复 off-budget 账户被错误设置分类的问题。这些修复说明模板引擎在发布前经历了密集的实战打磨也提醒使用者在升级后重新验证已有规则行为。实验性特性设置 Upcoming 计划显示长度功能来源Upcoming Length 控制来自 PR#3310Add option to set how far out the upcoming scheduled transactions are shown in the account view与#3639Add info text to Upcoming Length control并配套#3651为其添加了功能开关feature flag。功能说明在账户视图中「Upcoming」区域会显示未来一段时间内即将发生的周期性计划交易。旧版本这个时间窗是固定的而 24.11.0 允许用户自定义「提前多少天」显示这些计划交易。配置项与预设值UI 组件实现在 packages/desktop-client/src/components/schedules/UpcomingLength.tsx底层偏好值为同步偏好upcomingScheduledTransactionLength通过useSyncedPref读写。预设选项集中在 packages/loot-core/src/shared/schedules.ts默认值DEFAULT_UPCOMING_SCHEDULE_DAYS 77 天预设选项UPCOMING_LENGTH_PRESET_VALUES11 天、71 周、142 周、oneMonth1 个月、currentMonth当月月底自定义值任意非预设字符串都会被识别为自定义长度isCustomUpcomingLength界面提供 Custom length 输入框CustomUpcomingLength组件。设置界面包含说明文字明确两点该设置只影响计划交易的显示距离计划日期多少天开始出现在账户账本中不改变预算数据的存储方式该设置可以随时更改。由于是同步偏好SyncedPref该设置会随预算文件同步多端保持一致。使用方式进入 Schedules计划设置或账户视图的相关入口打开名为schedules-upcoming-length的弹窗见 UpcomingLength.tsx选择预设值或输入自定义天数点击 Save 保存即可。修改会立即影响账户视图中 upcoming 交易的显示范围。实验性 Dashboards 的多项改进Dashboards仪表盘作为实验功能在本版本中得到集中打磨#3587支持在内部报表页面快速重命名 widget组件名称#3588让「add widgets」按钮始终可见降低操作成本#3626修复实验性报表页导入非自定义报表 widget 的问题#3633修复自定义报表的「show uncategorized」与「show off budget」选项。这些改进主要落在 packages/desktop-client/src/components/reports 目录下配合#3611移除 Spending Report 的功能开关正式开放与#3615即使账户开启了银行同步也始终显示「import transactions」按钮一起提升了报表与数据导入的整体可用性。账户管理与文件迁移管理页的整合功能来源PR#3584Moving file settings to the management page and enabling budget file relocation是本版本在文件管理上的重要变化将文件设置迁移到管理页面management page统一管理支持预算文件的重新定位relocation。配套修复#3600当迁移migrations不同步时弹出引导弹窗避免用户在状态不一致时操作#3717修复下载预算时的竞态条件race condition#3736服务器 URL 配置错误时增加额外错误处理#3697支持使用 ngrok 隧道接入 actual-sync 服务器方便远程联调。这些改动涉及 packages/desktop-client 与 packages/sync-server 两个包体现了 24.11.0 对自托管部署体验的持续优化。Actual Server 侧改进发布文档的 Server 部分同样包含值得关注的变化银行同步优化#482请求账户列表时不再从 SimpleFIN 拉取交易减少不必要的 API 调用#483SimpleFIN 同步单个账户时只拉取该账户的交易#470银行交易排序扩展存在bookingDateTime时按时间排序#473 / #481将 N26、Fineco意大利/英国加入历史数据受限银行列表#486调整 EASYBANKBAWAATWW的access_valid_for_days为 179 天。配置与部署#480允许通过环境变量覆盖数据目录为容器化部署提供更大灵活性#487修复初始设置时迁移未正确运行的问题。维护#432为app-sync.js集成 FileService#478为银行集成消息设置正确的日志级别。以上改动集中在 packages/sync-server/src 下如app-sync.ts、app-gocardless、app-simplefin等目录实际部署时可参考 packages/sync-server/README.md 与 docker-compose.yml。其他值得关注的变化界面与交互#3549[Mobile] 允许更新已有交易的账户#3554侧边栏仅滚动账户列表按钮保持固定#3622[Mobile] Cleared 标记改为开关toggle交互#3684账户页新增 Reconcile对账按钮#3648帮助相关条目整合到单一菜单#3691帮助菜单中加入 goal template 参考指南。CSV 导入#3543在多次 CSV 导入之间保存 in/out 模式设置#3605修复 CSV 仅含 3 列时的导入问题#3613导入按钮显示将要导入的准确交易数量#3499维护为 CSV 导入对话框补充 E2E 测试。预算与目标#3617新增目标模板从 N 个月前的预算复制#3695修复 tracking budget 中预算复制失效的问题#3721修复模板通知不显示的问题#3511修复年度计划模板在提前于交易日期做预算时行为不正确的问题。移动端与报表修复#3343修复移动端模态框滚动缓慢#3602确保移动端预算视图金额为正#3679修复 Spending Report 第 28 天起的累计总额错误#3723修复 Monthly Spending Report 前三月的平均值计算#3725修复标签名含正则特殊字符时标签过滤导致崩溃的问题。维护与工程化#3471用emotion/css替换 glamor CSS-in-JS 库#3553减小桌面应用包体积#3580移除electron-is-dev依赖#3365为account/rules.ts添加更严格的类型大量组件完成 TypeScript 迁移ManagePayees、LoadBackupModal、NetWorth、ImportTransactionsModal 子组件、账户 header 等。总结Actual 24.11.0 是一个「自动化能力」与「使用体验」并重的版本规则模板引擎#3305、#3619把规则从「固定值替换」升级为「可编程表达式」配合内置的字符串、数学、日期 Helper可以实现高度自动化的交易分类与清洗核心实现位于 packages/loot-core/src/server/rules/action.ts 与 handlebars-helpers.tsUpcoming Length#3310让用户按天/周/月自由控制计划交易的显示窗口配置保存在同步偏好upcomingScheduledTransactionLength中Dashboards 与报表获得多项实验性增强Spending Report 正式开放管理页整合与文件迁移#3584、SimpleFIN API 优化#482、#483分别提升了文件管理与银行同步的效率。如需深入源码推荐从以下入口继续阅读规则动作实现 action.ts、规则测试快照 transaction-rules.test.ts.snap、计划配置常量 shared/schedules.ts、Upcoming Length 界面 UpcomingLength.tsx。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Actual 24.11.0 版本深度解析：规则模板引擎、Upcoming 计划长度与 Dashboards 实验特性
Actual 24.11.0 版本深度解析规则模板引擎、Upcoming 计划长度与 Dashboards 实验特性【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actualActual 是一个本地优先local-first的个人财务管理应用其 24.11.0 版本围绕「自动化与可定制性」带来了一批显著改进。本文以该版本的官方发布文档为骨架结合仓库源码深入拆解规则模板Handlebars 模板与公式、Upcoming 计划显示长度、Dashboards 仪表盘增强、账户管理迁移与文件迁移等核心特性帮助读者理解每个改进背后的实现机制与实际使用方法。版本概览与升级方式Actual 24.11.0 于 2024 年 11 月发布官方发布文档packages/docs/blog/2024-11-03-release-24.11.0.md给出的 Docker 镜像标签为24.11.0可直接用于自托管部署。本版本的核心改进集中在四条主线SimpleFIN 银行同步 API 调用优化针对 Actual Server实验性支持设置 Upcoming 计划显示时长即未来多远距离的周期性交易显示在账户视图实验性 Dashboards 功能的多项改进实验性的规则模板化支持规则「设置」动作中引入 Handlebars 模板语法。此外还包含大量对移动端、CSV 导入、规则引擎、报表的 Bug 修复与维护性重构详见下文各节。规则模板引擎在「设置」动作中使用 Handlebars功能来源本次发布的规则模板功能来自两个 PR#3305为 set 动作引入基于 Handlebars 语法的规则动作模板#3619将模板能力扩展到payee_name字段。这意味着用户可以把规则动作写成{{ ... }}形式的模板表达式由引擎在规则匹配时动态求值而不是使用固定值。底层实现原理规则动作的核心实现在 packages/loot-core/src/server/rules/action.ts。其中Action类支持的操作类型ACTION_OPS包括set设置字段值支持固定值、公式、模板三种模式set-split-amount设置拆分金额支持固定金额、百分比、公式等分配方式link-schedule关联到计划交易prepend-notes/append-notes在备注前/后追加文本delete-transaction删除交易置 tombstone 标记。当set动作携带options.template时构造函数会调用Handlebars.compile(options.template, { noEscape: true })预编译模板并在exec()阶段执行// 源码节选packages/loot-core/src/server/rules/action.ts if (options?.template) { this.handlebarsTemplate Handlebars.compile(options.template, { noEscape: true, }); }执行模板时传入的上下文包含交易对象的所有字段并额外注入today当前日期变量object[this.field] this.handlebarsTemplate({ ...object, today: currentDay(), });Handlebars 总是返回字符串因此引擎按目标字段类型做转换见exec()中的 switchnumber 字段parseFloat转换结果为 NaN 时回退为 0避免数据库写入失败date 字段parseDate后校验合法性非法时写入9999-12-31作为显眼占位并输出错误日志boolean 字段字符串true判定为真。内置模板 Helper模板之所以强大是因为项目注册了大量内置 Helper。它们在 packages/loot-core/src/server/rules/handlebars-helpers.ts 中定义并在 packages/loot-core/src/server/rules/index.ts 中通过registerHandlebarsHelpers()统一注册按类别可分为字符串处理Helper说明regex正则替换支持/regex/flags语法如{{regex value /\d/ X}}replace普通替换支持正则字面量/.../flagsreplaceAll全局替换concat拼接多个参数数学运算Helper说明add/sub/div/mul/mod算术运算支持多参数如{{add a b c}}floor/ceil/round/abs取整与绝对值min/max最小值/最大值fixed保留指定位小数如{{fixed amount 2}}日期运算Helper说明day/month/year提取日期分量format按自定义格式输出日期addDays/subDays/addMonths/subMonths/addWeeks/subWeeks/addYears/subYears日期加减setDay将日期调整到指定「星期几」以本周为基准debug输出日志用于调试日期 Helper 底层基于date-fns与项目封装的#shared/months工具实现所有日期函数输入输出统一为yyyy-MM-dd格式。实际应用示例利用这些 Helper可以构建出非常灵活的规则动作例如# 给商家名补全把 COFFEE 统一改为 COFFEE SHOP set payee_name to template {{replaceAll payee_name COFFEE COFFEE SHOP}} # 备注前追加当前日期 prepend-notes {{format today yyyy-MM-dd}}: # 将金额四舍五入到整数 set amount to template {{round amount}}注意set动作在payee_name字段上执行模板后源码会将object[payee] newaction.ts即创建新的收款人实体这正是 #3619 将模板扩展到payee_name的核心逻辑。相关 Bug 修复本次发布同时修复了模板功能初期的问题#3632修复 action 规则模板中的转义escaping问题#3749修复规则模板中使用日期函数的问题#3704修复无法通过规则修改 Payee 的问题#3705修复 off-budget 账户被错误设置分类的问题。这些修复说明模板引擎在发布前经历了密集的实战打磨也提醒使用者在升级后重新验证已有规则行为。实验性特性设置 Upcoming 计划显示长度功能来源Upcoming Length 控制来自 PR#3310Add option to set how far out the upcoming scheduled transactions are shown in the account view与#3639Add info text to Upcoming Length control并配套#3651为其添加了功能开关feature flag。功能说明在账户视图中「Upcoming」区域会显示未来一段时间内即将发生的周期性计划交易。旧版本这个时间窗是固定的而 24.11.0 允许用户自定义「提前多少天」显示这些计划交易。配置项与预设值UI 组件实现在 packages/desktop-client/src/components/schedules/UpcomingLength.tsx底层偏好值为同步偏好upcomingScheduledTransactionLength通过useSyncedPref读写。预设选项集中在 packages/loot-core/src/shared/schedules.ts默认值DEFAULT_UPCOMING_SCHEDULE_DAYS 77 天预设选项UPCOMING_LENGTH_PRESET_VALUES11 天、71 周、142 周、oneMonth1 个月、currentMonth当月月底自定义值任意非预设字符串都会被识别为自定义长度isCustomUpcomingLength界面提供 Custom length 输入框CustomUpcomingLength组件。设置界面包含说明文字明确两点该设置只影响计划交易的显示距离计划日期多少天开始出现在账户账本中不改变预算数据的存储方式该设置可以随时更改。由于是同步偏好SyncedPref该设置会随预算文件同步多端保持一致。使用方式进入 Schedules计划设置或账户视图的相关入口打开名为schedules-upcoming-length的弹窗见 UpcomingLength.tsx选择预设值或输入自定义天数点击 Save 保存即可。修改会立即影响账户视图中 upcoming 交易的显示范围。实验性 Dashboards 的多项改进Dashboards仪表盘作为实验功能在本版本中得到集中打磨#3587支持在内部报表页面快速重命名 widget组件名称#3588让「add widgets」按钮始终可见降低操作成本#3626修复实验性报表页导入非自定义报表 widget 的问题#3633修复自定义报表的「show uncategorized」与「show off budget」选项。这些改进主要落在 packages/desktop-client/src/components/reports 目录下配合#3611移除 Spending Report 的功能开关正式开放与#3615即使账户开启了银行同步也始终显示「import transactions」按钮一起提升了报表与数据导入的整体可用性。账户管理与文件迁移管理页的整合功能来源PR#3584Moving file settings to the management page and enabling budget file relocation是本版本在文件管理上的重要变化将文件设置迁移到管理页面management page统一管理支持预算文件的重新定位relocation。配套修复#3600当迁移migrations不同步时弹出引导弹窗避免用户在状态不一致时操作#3717修复下载预算时的竞态条件race condition#3736服务器 URL 配置错误时增加额外错误处理#3697支持使用 ngrok 隧道接入 actual-sync 服务器方便远程联调。这些改动涉及 packages/desktop-client 与 packages/sync-server 两个包体现了 24.11.0 对自托管部署体验的持续优化。Actual Server 侧改进发布文档的 Server 部分同样包含值得关注的变化银行同步优化#482请求账户列表时不再从 SimpleFIN 拉取交易减少不必要的 API 调用#483SimpleFIN 同步单个账户时只拉取该账户的交易#470银行交易排序扩展存在bookingDateTime时按时间排序#473 / #481将 N26、Fineco意大利/英国加入历史数据受限银行列表#486调整 EASYBANKBAWAATWW的access_valid_for_days为 179 天。配置与部署#480允许通过环境变量覆盖数据目录为容器化部署提供更大灵活性#487修复初始设置时迁移未正确运行的问题。维护#432为app-sync.js集成 FileService#478为银行集成消息设置正确的日志级别。以上改动集中在 packages/sync-server/src 下如app-sync.ts、app-gocardless、app-simplefin等目录实际部署时可参考 packages/sync-server/README.md 与 docker-compose.yml。其他值得关注的变化界面与交互#3549[Mobile] 允许更新已有交易的账户#3554侧边栏仅滚动账户列表按钮保持固定#3622[Mobile] Cleared 标记改为开关toggle交互#3684账户页新增 Reconcile对账按钮#3648帮助相关条目整合到单一菜单#3691帮助菜单中加入 goal template 参考指南。CSV 导入#3543在多次 CSV 导入之间保存 in/out 模式设置#3605修复 CSV 仅含 3 列时的导入问题#3613导入按钮显示将要导入的准确交易数量#3499维护为 CSV 导入对话框补充 E2E 测试。预算与目标#3617新增目标模板从 N 个月前的预算复制#3695修复 tracking budget 中预算复制失效的问题#3721修复模板通知不显示的问题#3511修复年度计划模板在提前于交易日期做预算时行为不正确的问题。移动端与报表修复#3343修复移动端模态框滚动缓慢#3602确保移动端预算视图金额为正#3679修复 Spending Report 第 28 天起的累计总额错误#3723修复 Monthly Spending Report 前三月的平均值计算#3725修复标签名含正则特殊字符时标签过滤导致崩溃的问题。维护与工程化#3471用emotion/css替换 glamor CSS-in-JS 库#3553减小桌面应用包体积#3580移除electron-is-dev依赖#3365为account/rules.ts添加更严格的类型大量组件完成 TypeScript 迁移ManagePayees、LoadBackupModal、NetWorth、ImportTransactionsModal 子组件、账户 header 等。总结Actual 24.11.0 是一个「自动化能力」与「使用体验」并重的版本规则模板引擎#3305、#3619把规则从「固定值替换」升级为「可编程表达式」配合内置的字符串、数学、日期 Helper可以实现高度自动化的交易分类与清洗核心实现位于 packages/loot-core/src/server/rules/action.ts 与 handlebars-helpers.tsUpcoming Length#3310让用户按天/周/月自由控制计划交易的显示窗口配置保存在同步偏好upcomingScheduledTransactionLength中Dashboards 与报表获得多项实验性增强Spending Report 正式开放管理页整合与文件迁移#3584、SimpleFIN API 优化#482、#483分别提升了文件管理与银行同步的效率。如需深入源码推荐从以下入口继续阅读规则动作实现 action.ts、规则测试快照 transaction-rules.test.ts.snap、计划配置常量 shared/schedules.ts、Upcoming Length 界面 UpcomingLength.tsx。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考