OneOS-V2/docs/superpowers/specs/2026-07-26-complex-ledger-column-customization-design.md

OneOS V2 复杂台账列个性化设计说明

日期：2026-07-26
状态：已完成产品需求与设计方案确认

1. 背景与目标

车辆资产页已经具备表格列宽调整、显示列选择和显示顺序调整能力，但 OneOS V2 设计规范尚未覆盖这些交互。本次将三项能力上升为所有复杂台账页面的通用规则，并以车辆资产页作为标准示例。

目标用户包括使用 OneOS V2 复杂台账的 PC/Web 用户，以及按规范设计、开发和验收台账页面的团队。用户的核心任务是根据当前工作内容调整列宽、选择显示列、排列列顺序，并在需要时恢复默认配置。

2. 范围

2.1 包含

• PC/Web 复杂台账表格的列宽拖拽调整。
• 可选业务列的显示与隐藏。
• 可选业务列的显示顺序调整。
• 单列宽度恢复和完整配置恢复默认。
• 按“用户 + 台账页面”保存和恢复配置。
• 鼠标、键盘和读屏操作规则。
• 配置加载、保存失败及表格字段变更时的兼容处理。
• 浅色和暗色主题下的状态表现。

2.2 不包含

• 不新增或改变车辆资产页的业务字段。
• 不改变复杂台账的筛选、分页、导入、导出或行内操作逻辑。
• H5 单列卡片列表不提供列宽、列显隐和列排序操作。
• 不跨台账复用列配置，也不在不同账号之间共享配置。

3. 规范组织

采用“分章主规则 + 总览摘要 + 交叉引用”的组织方式：

• src/resources/design-system/DESIGN.md：增加强制原则摘要，声明复杂台账必须提供列宽、列显隐、列排序和恢复默认能力。
• src/resources/design-system/chapters/03-components.md：承载完整组件与交互规则。
• src/resources/design-system/chapters/06-accessibility.md：承载焦点、键盘替代、读屏播报规则。
• src/resources/design-system/chapters/02-layout.md：说明 PC/Web 表格适用范围、H5 卡片排除规则及表格横向滚动关系。
• 车辆资产页作为标准实现示例被引用，本次不修改其业务功能。

4. 信息架构与组件关系

列个性化由两类入口组成：

1. 表头分隔线上的列宽调节把手，负责单列宽度调整和单列宽度恢复。
2. 台账工具栏中的“列设置”按钮，打开设置弹层，集中处理列显隐、列顺序和完整恢复默认。

列设置弹层包含标题、恢复默认入口、列项目列表、取消和确认操作。每个可选业务列包含显隐复选框、拖拽把手及键盘上移/下移操作；固定列显示固定标识和限制说明。

5. 列宽调整

• 表头分隔线提供约 12px 的可操作命中区。默认仅显示细分隔线，悬停、聚焦或拖动时用主题主色增强。
• 拖动过程实时预览列宽，鼠标释放时结束调整并触发保存。
• 普通业务列宽度限制为 90–480px。
• 首个核心识别列建议限制为 120–360px；具体默认宽度由字段内容决定。
• 达到最小或最大边界后停止变化，不允许列宽无限缩小或撑宽。
• 双击调节把手只恢复当前列的默认宽度。
• 末尾操作列不提供调节把手，宽度由设计者依据操作组件规范固定。
• 表格容器仍遵守局部横向滚动规则，列宽个性化不得造成整页横向滚动。

6. 列显隐与列顺序

• “列设置”位于复杂台账工具栏，使用图标按钮并提供文字提示和无障碍名称。
• 设置弹层内，复选框控制列显隐，拖拽把手控制列顺序。
• 设置弹层中的修改先保存在临时状态；点击“确认”后一次应用并保存，点击“取消”不改变当前列表。
• “全选/全不选”只影响可选业务列，不影响固定列。
• 首个核心识别列必须显示、不可换序，但允许在规定范围内调宽。
• 末尾操作列必须显示、不可换序、不可调宽。
• 其他业务列可以显示或隐藏、调整顺序和调整列宽。
• 可选业务列只能在两端固定列之间排序，不能越过固定列。

7. 恢复默认

• 双击表头调节把手恢复当前列的默认宽度。
• 列设置弹层中的“恢复默认”同时恢复列宽、显隐和顺序。
• 完整恢复不使用危险确认弹窗。用户触发后先在弹层中预览默认布局，点击“确认”后应用并保存；点击“取消”保留原配置。

8. 保存、加载与兼容

• 保存范围为“用户 + 台账页面”，建议存储键包含 userId + ledgerId + schemaVersion。
• 配置至少包含 columnWidths、visibleColumns 和 columnOrder。
• 列宽在拖动结束后保存；列显隐和列顺序在弹层确认后保存。
• 保存过程不得阻塞台账浏览和操作。
• 再次进入同一台账时自动恢复该用户的配置。
• 初始化时先建立规范默认配置，再合并已保存配置，降低加载期间的布局跳动。
• 新增字段按设计者定义的默认显隐状态和默认位置插入。
• 已删除字段自动忽略，不能导致整份用户配置失效。
• 配置损坏、版本不兼容或加载失败时回退默认配置并轻提示，不阻塞台账数据加载。
• 保存失败时保留当前会话内的配置，并提示“当前设置暂未同步，下次进入可能恢复默认”。
• H5 卡片列表忽略 PC 列配置，但不得删除已经保存的 PC 配置。

9. 无障碍与键盘

• “列设置”按钮提供明确的 aria-label、展开状态和弹层关联。
• 打开弹层后焦点进入弹层，关闭后回到触发按钮；按 Esc 可关闭。
• 列宽调节把手可聚焦。方向键每次调整 8px，Shift + 方向键 每次调整 24px，Home 恢复当前列默认宽度。
• 读屏实时播报列名和当前宽度。
• 列排序除拖拽外，必须提供“上移/下移”按钮；到达边界或属于固定列时禁用并说明原因。
• 显隐复选框必须与列名关联。固定列控件禁用，并以文字说明不可隐藏。
• 拖动、排序、恢复默认、保存成功和保存失败均通过 aria-live="polite" 播报，不能只依赖颜色传达状态。
• 所有可聚焦控件使用主题 Focus Token；视觉分隔线可以为 2–3px，但操作命中区不得随之缩小。

10. 视觉与主题

• 列宽把手、焦点、选中和拖拽目标状态全部消费 OneOS V2 主题 Token，不使用硬编码品牌色。
• 浅色和暗色主题均需保持表头分隔线、焦点和拖拽状态的可辨识度。
• 固定列通过文字或图标加文字说明，不只使用灰色或禁用色表达限制。
• 列设置弹层沿用 OneOS V2 Web 浮层、复选框、按钮和间距规范，不新增独立视觉体系。

11. 验收标准

• 鼠标可在边界内实时调整所有允许调宽的列。
• 键盘可完成等价调宽，并能恢复单列默认宽度。
• 用户可显示或隐藏所有可选业务列。
• 用户可通过拖拽以及上移/下移按钮调整所有可选业务列顺序。
• 两类固定列始终遵守显示、换序和调宽限制。
• 取消设置不改变当前列表；确认后一次应用并保存。
• 双击把手只恢复当前列；“恢复默认”恢复列宽、显隐和顺序。
• 同一用户重新进入同一台账时恢复配置，不同用户或不同台账之间互不影响。
• 新增或删除字段后，历史配置仍可正常合并和使用。
• 配置加载或保存失败时台账仍可操作，并给出符合规范的轻提示。
• H5 卡片列表不出现任何列控制入口，且不会清除 PC 配置。
• 浅色、暗色主题以及键盘焦点、读屏播报均通过验收。

12. 标准示例

src/prototypes/vehicle-management/components/ListView.tsx 中的车辆资产台账作为交互参考，已经展示表头调宽把手、双击恢复、列设置入口、列显隐和列拖拽排序。规范落地时以本文确认的通用边界为准，尤其需要补足持久化、键盘替代、最大宽度和保存失败处理等通用要求。