企业官网建设流程全解析

Actual Budget 23.10.0 版本解析：移动端下拉同步、笔记 Markdown 支持与暗色主题全面落地

【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual

Actual 是一个本地优先（local-first）的个人财务管理应用，其桌面端与移动端共享同一套数据模型与同步协议。本文围绕 23.10.0 版本（Docker tag：23.10.0）的发布内容展开，重点讲解移动端「下拉触发银行同步」「预算页新增 spent 列」、笔记 Markdown 渲染，以及暗色主题分阶段落地的完整过程，并结合当前仓库源码说明这些能力的真实实现方式与使用场景。读完本文，你将能够理解这些版本特性背后的组件设计、依赖选择和代码路径，并能在自己的部署与二次开发中直接使用对应能力。

版本概览

Actual 23.10.0 发布于 2023-10-03，包含 Actual 主应用与 Actual Server 两个组件的同步更新。主应用侧围绕三个核心方向展开：

• 移动端体验：下拉刷新触发银行同步、预算页新增「spent」列、修复多类移动端交互问题；
• 内容呈现：笔记（notes）支持 Markdown 渲染；
• 主题与报表：暗色主题最后一阶段（预算与全局文件）落地、报表响应式改进、Net Worth 图 Y 轴缩放优化、Cash Flow 报表默认展示月数由 30 调整为 5。

服务端（Actual Server）侧则新增了可通过环境变量配置的上传大小限制，并补充了丹麦 Spar Nord 银行的 GoCardless 集成。

按发布说明的原始归类，本次改动可分为 Features、Enhancements、Bugfix、Maintenance 四类，下文按功能主题组织展开。

移动端：下拉触发银行同步

「移动端下拉刷新即可触发银行同步」是本版本最直观的交互改进（PR #1663）。它把桌面端需要进入设置或手动点击同步的操作，收敛为移动端用户最熟悉的「下拉刷新」手势。

实现基础：PullToRefresh 组件

该能力基于react-simple-pull-to-refresh库封装而成，组件位于 PullToRefresh.tsx。其封装要点如下：

• 外层使用overflow: auto的容器承载滚动；
• 内部配置pullDownThreshold={80}，即下拉距离达到 80px 时触发刷新；
• resistance={2}控制下拉的阻尼系数，手感更平滑；
• 强制将onRefresh包成异步函数，因为该库在传入同步onRefresh时会报错；
• 通过 emotion 的css为下拉提示区（.ptr__pull-down）与内容区（.ptr__children）定制样式。

<BasePullToRefresh pullDownThreshold={80} resistance={2} className={css({ '& .ptr__pull-down': { textAlign: 'center' }, '& .ptr__children': { overflow: 'hidden auto' }, ...(props.style || {}), })} {...props} onRefresh={async () => { await props.onRefresh?.(); }} />

从调用路径看，账户列表页 AccountsPage.tsx 将下拉刷新直接绑定到onSync，即「下拉 = 执行一次同步」：

<PullToRefresh onRefresh={onSync}>

同样，交易列表 TransactionListWithBalances.tsx 也复用了该组件，并通过isPullable={!isLoading && !!onRefresh}控制「加载中不可再触发下拉」。

同步按钮的配套修复

与下拉刷新配套，本版本还修复了移动端同步按钮的样式（PR #1665），确保手势入口与按钮入口在视觉与行为上保持一致，避免两套入口并存时的体验割裂。

移动端：预算页新增 spent 列

移动端预算表新增了「spent」（已支出）列（PR #1651），让用户在手机上即可直观对比「本月已花多少、还剩多少预算」。

源码实现：按预算类型取数

该列在 BudgetTable.tsx 中通过CellValue组件按预算类型动态取数：

<CellValue<'envelope-budget' | 'tracking-budget', 'total-spent'> binding={ budgetType === 'tracking' ? trackingBudget.totalSpent : envelopeBudget.totalSpent } type="financial" >

• 追踪预算（tracking budget）读取trackingBudget.totalSpent；
• 信封预算（envelope budget）读取envelopeBudget.totalSpent。

也就是说，spent 列在两种预算模式下均有数据支撑，移动端与桌面端在取数口径上保持一致。同时该列支持点击展开/收起（toggleSpentColumn），并受「三列模式（show3Columns）」状态约束，避免窄屏下信息过载。

同期的移动端标签统一

PR #1639 将移动端账户页的BUDGETED标签统一改为FOR BUDGET，与桌面端标签措辞对齐。这是移动端信息架构向桌面端靠拢的一个小但重要的信号：移动端并非桌面端的简单缩略，而是逐步对齐功能语义。

笔记支持 Markdown

本版本让预算类别、账户等处的笔记（notes）从纯文本升级为 Markdown 渲染（PR #1587），为记账备注、预算说明等场景提供了轻量排版能力。

渲染管线

笔记渲染组件位于 Notes.tsx，其渲染分支使用react-markdown，并叠加了三类插件：

const remarkPlugins = [sequentialNewlinesPlugin, remarkGfm, remarkBreaks];

• remark-gfm：支持表格、删除线、任务列表等 GFM 扩展语法；
• sequentialNewlinesPlugin：把连续空行解析为换行（源自 markdown.ts 中的自定义 fromMarkdown 扩展）；
• remarkBreaks：将单行换行（newlineToBreak）渲染为<br>，保证「所见即所得」的换行体验。

链接统一经rehype-external-links处理为target="_blank"并附带rel="noopener noreferrer"，避免笔记中的外链在新窗口打开时存在安全风险。

编辑态与展示态分离

Notes组件通过editable属性区分两种形态：

• 编辑态：渲染原生<textarea>，占位符为Notes (markdown supported)，提示用户可直接书写 Markdown；
• 展示态：渲染为排版后的 Markdown 富文本，markdownBaseStyles（markdown.ts）统一定义了段落间距、列表缩进、引用块、行内代码、表格边框等样式，并支持随主题（theme.markdownDark等）切换。

由于整个组件复用useResponsive判断窄屏宽度，移动端与桌面端在编辑框宽度等细节上也会自动适配。

暗色主题的阶段性落地

23.10.0 完成了暗色主题的第三至第六阶段（PR #1487/#1503/#1512/#1513），覆盖范围如下：

主题令牌（tokens）集中在 component-library 的 themes 目录（light.css/dark.css/midnight.css），配合 palette.css 的调色板体系，组件通过theme.markdownNormal这类语义化变量取值，因此暗色主题覆盖新页面的过程，本质上就是把硬编码颜色替换为语义令牌。

版本内还包含两个直接相关的回归修复：PR #1703 修复了暗色主题下侧边栏账户同步状态的显示回归；PR #1752 修复了若干小的回归问题。

报表与移动端体验改进

• Net Worth 图 Y 轴缩放优化（PR #1709）：改进了净值图在数值跨度大时的坐标轴表现，避免可读性损失。
• Cash Flow 报表默认月数调整（PR #1723）：默认展示月数从 30 改为 5，让默认视图聚焦近期现金流，而不是被冗长时间线淹没。
• 报表响应式改进（PR #1592）：报表组件在窄屏下自适应布局，与移动端对齐。
• 修复 Safari 的 blur 性能问题（PR #1646）：消除在 Safari 中因 blur 事件处理导致的可感知卡顿。

关键 Bugfix 与行为修正

移动端与桌面端的细节修复是本版本的重要组成部分，以下按影响面归类：

• 移动端信息展示：隐藏组与隐藏收入类别不再显示（#1654/#1656）、收入组显示真实名称（#1679）、恢复交易列表的粘性日期分组头（#1698）、修复交易列表首次滑动需要先交互的问题（#1706）、修复日程状态标签定位（#1669）。
• 移动端导航：修复「返回」行为（#1648）、访问不存在的页面时重定向回预算页（#1721）。
• 加密密钥：按回车键时正确提交新密钥而非取消输入（#1634）。
• 对账（reconcile）：提示改为使用已清算余额（cleared balance）而非全部交易余额（#1678）。
• 导入：修复 v23.9.0 报告的 QFX 导入问题（#1649）。
• 类别相关：自动补全不再包含不可选择的类别组（#1681）、按空值过滤交易时显示空备注而非报错（#1708）。
• 日程（schedules）：完成后或重建时保留日程名称（#1728）、日程搜索栏不再被大量日程挤压变窄（#1729）、复选标签不再出现多行（#1687）、修复navigateToSchedule属性（#1645）。
• 目标（Goals）：修复报表预算模板中的 bug 并提速（#1718）、修复超预算判定条件（#1738）。
• 暗色主题回归：侧边栏同步状态（#1703）及其余小回归（#1752）。

工程与维护：技术债清理与基础设施升级

Maintenance 类改动反映了该版本背后的工程方向，值得关注的有：

• 构建与依赖：改用swc-loader并开启 SWC source maps（#1650/#1659），显著加速本地编译；升级absurd-sql并移除patch-package依赖（#1632）；升级better-sqlite3至 8.6.0，修复桌面应用导出数据时的崩溃（#1643）。
• TypeScript 化：多个组件从类组件/JS 迁移为函数组件与 TSX，包括预算页（#1566）、日程表相关组件（#1644/#1691）、IncomeHeader（#1670）、BudgetMonthCountContext（#1722），并加强数据实体类型（#1680）。
• Hook 与组件收敛：全量改用useCategorieshook 获取类别（#1597）、用useFormat替换format（#1630）、新增通用 AnchorLink/ButtonLink 组件（#1701）与 Button 的link类型支持（#1725）、合并useMergedRefs（#1733）。
• Lint 策略：eslint 规则从error调整为warn，CI 仍按警告即失败处理，本地开发体验更友好（#1599）。
• 测试与数据：为测试预算加入 mock 日程数据（#1672）、VRT（视觉回归测试）固定版本并放开更多遮罩区域（#1641）。
• 其他：移除privacyMode功能开关（该功能已 GA，见 #1688）、新增实验性 OFX 解析器以替代 node-libofx（#1600）、移动端图标去掉白色边框（#1705）、CI 在 master 分支不再取消进行中的任务（#1692）。

Actual Server：上传限制与银行集成

服务端 23.10.0 同样有两个值得记录的改动：

• 可配置的上传限制（PR #245）：通过环境变量调整上传大小上限，允许部署者放宽限制以支持更大文件（如大体积的预算文件、备份或导入文件）。此前上传限制为硬编码，需要修改代码才能调整。
• GoCardless 新增 Spar Nord（丹麦）银行支持（PR #257）：扩大银行同步覆盖范围，相关适配逻辑位于 sync-server 的 app-gocardless 模块。
• 构建修复（PR #265）：确保 edge 构建从正确的仓库拉取 master 构建产物。

如何升级与验证

Actual 主应用通过 Docker 部署时，将镜像标签指定为23.10.0即可：

# 拉取 23.10.0 镜像 docker pull actualbudget/actual-server:23.10.0

注：发布说明中 Docker tag 与 Actual/Actual Server 版本号均为23.10.0，两者同步发布。不同部署方式（Electron 桌面端、自托管 sync-server 等）可参考仓库根目录的 docker-compose.yml 与 sync-server.Dockerfile 了解编排方式。

升级后建议按以下清单验证本次涉及的核心功能：

1. 在移动端账户页下拉，确认触发同步且出现同步提示；
2. 在移动端预算页确认 spent 列可显示并支持点击切换；
3. 在类别/账户笔记中输入**加粗**、- 列表、`代码`等 Markdown 语法，确认展示态正确渲染；
4. 切换暗色主题，依次检查预算、报表、设置、日程等页面无颜色回归；
5. 在服务端环境变量中调整上传限制后上传大文件，确认配置生效。

小结

23.10.0 是一次「移动端体验补全 + 内容呈现升级 + 主题工程收官」的版本：下拉同步让移动端银行同步触手可及，spent 列补齐了移动端预算的常用信息，Markdown 笔记则让备注具备了轻量排版能力，而暗色主题的阶段性推进在六个阶段后覆盖到预算与全局文件，完成了整体主题体系的统一。同时，swc 构建提速、TypeScript 迁移、依赖升级等维护性工作为后续版本的迭代质量奠定了基础。

【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual