维刻 Vex / 文档 / 用户体验优先级改进

用户体验优先级改进

⏱ 预计阅读 4 分钟来源： Vex-Flutter · docs/validation/2026-10-18/用户体验优先级改进.md ✎ 在 GitHub 编辑此页

日期：2026-10-18。按“数据安全、输入稳定、性能、文件工作流、阅读舒适、视觉细节”的顺序落实本轮改进。以下为已验证范围，不代表整个产品或 98% 原型还原已经验收。

已落实

优先级	改进与验证
数据安全	关闭文档前先成功写入恢复记录；写入失败保留正文、撤销历史和重试机会。丢弃旧草稿不删除仍在编辑的未保存内容。写入期间继续输入则保留文档并更新恢复快照。重复关闭同一文档只处理一次。
并发安全	快照生成、关闭、恢复、丢弃和后台恢复刷新按序处理，避免不同文档交叠关闭漏掉草稿，或后台刷新使已丢弃的内容重新出现。失败不会阻塞后续重试。保存后关闭始终针对发起操作的文档，保存期间继续输入则取消关闭。
输入稳定	保存读取已确认的文档模型，不把尚未提交的输入法候选写入原文件。仅更新保存基线时保留源码输入候选、选区与导航状态；真正的外部正文修改仍使旧候选失效。
性能	隐藏导图只记录失效状态，显示或调用时再生成最新树和布局；可见导图保持即时更新。正文变化后的搜索匹配刷新不再额外重复通知整个工作区。未测量本项的耗时收益，不报告提速百分比。
文件工作流	重开已打开的路径直接定位现有文档，不重读磁盘覆盖本地编辑和撤销历史。异步读取以最后一次用户操作决定焦点，先前读取完成后不抢走新文档或新草稿；并发打开同一路径不生成重复文档。工作区销毁后拒绝迟到的打开结果。
阅读舒适	即时编辑与阅读共用正文边距：手机左右 25、顶部 28；桌面单栏左右 44、顶部 34；桌面分栏左右 34、顶部 24。覆盖 320/390/1280 宽度、明暗主题及最大正文字号 24。
视觉细节	自定义窗口和弹窗操作按钮补齐键盘焦点的品牌色背景与 2px 边框；保留关闭按钮的危险操作悬停效果和 46×32 固定尺寸。验证 Tab 导航、Enter 激活及布局不跳动。

自动保存仍默认关闭，恢复快照不等于自动保存原文件。本轮没有修改安装器的布局与业务逻辑。

自动回归

工作目录	命令	结果
`packages/vex_markdown_core`	`dart test`	19 项通过
`packages/vex_editor`	`flutter test --no-pub`	195 项通过
`packages/vex_mindmap`	`flutter test --no-pub`	14 项通过
`apps/vex`	`flutter test --no-pub`	184 项通过
仓库根目录	`flutter analyze --no-pub`	无问题
仓库根目录	已跟踪 Dart 文件及新增原生测试的格式检查	无需格式修改
仓库根目录	`python -m unittest discover -s scripts/tests -v`	20 项通过
仓库根目录	`design/scripts/verify*.cjs`	七组原型契约通过
仓库根目录	`python scripts/sync_brand_assets.py --check`	品牌资源一致

Dart/Flutter 合计 412 项，比本轮前的 381 项增加 31 项；此数量不包含下述原生集成测试，也不换算为覆盖率或视觉还原率。并发恢复场景先通过新增测试复现失败，再修复并复跑；应用全量测试在最终业务代码上重新通过。

专项用例位于 apps/vex/test/ 下的 recovery_workflow_test.dart、document_close_workflow_test.dart、file_open_workflow_test.dart、file_preferences_test.dart、workspace_refresh_test.dart、reading_comfort_test.dart 与 caption_focus_test.dart，输入控件用例补充在 packages/vex_editor/test/source_editor_test.dart。

Windows 原生检查

apps/vex/integration_test/experience_priorities_test.dart 在最终业务代码上通过 Windows Debug 构建与一项原生集成测试，覆盖：

1280×900、390×844、320×740 实际窗口客户区。
明暗主题、即时编辑与阅读、最大正文字号 24。
正文边距、文档内容与已保存状态不变、焦点按钮尺寸和 Tab 离开焦点。
共 14 张非空截图：12 张正文场景、2 张桌面键盘焦点场景。

已人工核看 390px 明色阅读、320px 暗色即时编辑和 1280px 明色窗口焦点截图，正文与工具栏未出现重叠，焦点边框可见。最大字号导致的标题自然换行属于压力场景，不是默认字号效果。

本机截图在 artifacts/ux-priorities-20261018/，不提交生成产物；在 Windows 的仓库根目录可按以下方式重新生成：

powershell

$env:VEX_CAPTURE_DIR = Join-Path $PWD 'artifacts/ux-priorities-20261018'
$env:CMAKE_BUILD_PARALLEL_LEVEL = '2'
$env:CL = '/MP1'
Push-Location apps/vex
try {
  flutter test --no-pub integration_test/experience_priorities_test.dart -d windows
} finally {
  Pop-Location
}

验收边界

输入法候选为自动化模拟状态检查；Windows 窄窗口不是手机真机、系统软键盘或系统中文输入法认证。
隐藏导图验证的是更新次数及最新内容正确性；长文档多轮时延、最差输入延迟和资源占用仍需专项测量。
恢复操作的并发保护不等于恢复文件损坏时的多版本回退。恢复文件损坏、磁盘耗尽及进程中断仍需进一步故障注入。
本轮未重新构建或安装全部平台安装包，也未完成 macOS/Linux 原生、物理移动设备或完整原型截图对照。
98% 还原度仍是目标，现有证据不足以宣布达标；已有发布门槛保持不变，不提前升级版本或创建正式发布标签。

💬 评论暂未开启
有疑问或建议，欢迎到 GitHub 提交 Issue 参与讨论。