Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 QiuSW
|
19949349d6 | ||
|
QiuSW
|
1ac5f3e8ee | ||
|
QiuSW
|
2ed513bc25 |
@@ -1,86 +1,137 @@
|
|||||||
---
|
---
|
||||||
name: win-ui-ux-design
|
name: windows-ui-ux
|
||||||
description: Design, review, and implement professional Windows desktop UI/UX for WinUI 3, Windows App SDK, XAML, Fluent Design, and Windows-targeted Qt for Python applications using PySide or PyQt. Use when a task involves Windows desktop app shells or screens, Windows 桌面端界面, PySide6, PyQt6, PySide2, PyQt5, Qt Widgets, QML, navigation and windowing, title bars, NavigationView or framework-equivalent control selection, responsive XAML or Qt layouts, theme resources, QPalette or QSS, Mica or Acrylic, keyboard/mouse/touch interaction, accessibility, design-system specifications, UI audits, or translating designs into WinUI 3, PySide, or PyQt code.
|
description: 为 Windows 桌面应用设计、评审、制作 HTML 交互原型并实现专业 UI/UX，覆盖通用桌面交互、Windows/Fluent 平台规范，以及 WinUI 3、Windows App SDK、XAML、PySide、PyQt、Qt Widgets、QML 和 Go Gio 的框架适配。当任务涉及 Windows 应用外壳、导航、标签页、多窗口、多 Tab 数据工作台、表格筛选与行交互、表单验证、导入与前置命令、生成/更新/提交操作、对话框、反馈、长任务、主题颜色、Mica/Acrylic、响应式布局、键盘/鼠标/触控、无障碍、HTML 客户确认原型、现有桌面 UI 优化，或把已确认设计转换为 WinUI、Qt/Python 或 Gio/Go 代码时使用。
|
||||||
---
|
---
|
||||||
|
|
||||||
# Windows Desktop UI/UX Design
|
# Windows 桌面 UI/UX
|
||||||
|
|
||||||
Design for Windows as a keyboard-and-pointer-first, resizable, high-density desktop environment that may also receive touch and pen input. Prefer familiar platform behavior over ornamental novelty.
|
使用三层模型指导工作：
|
||||||
|
|
||||||
## Follow the core rules
|
1. **核心体验层**定义与语言和框架无关的任务、状态和交互契约；
|
||||||
|
2. **Windows 平台层**定义 Fluent 视觉、窗口化、输入和无障碍基线；
|
||||||
|
3. **框架适配层**把前两层映射到项目实际 API、生命周期和部署方式。
|
||||||
|
|
||||||
- Optimize the user's task flow before styling individual controls.
|
不得把某个框架的控件限制冒充通用 UX 原则，也不得把 HTML 原型当作原生行为、性能或无障碍已经通过验证的证明。
|
||||||
- Prefer WinUI controls, system resources, and built-in interaction behavior before creating custom UI.
|
|
||||||
- Treat keyboard, pointer, touch, screen reader, scaling, theme, and high contrast as one experience rather than later adaptations.
|
|
||||||
- Specify every meaningful state: default, hover, pressed, focus, selected, disabled, loading, empty, error, offline or unavailable, success, and undo when relevant.
|
|
||||||
- Use semantic tokens and theme resources. Never encode meaning with color alone or assume the light palette works in dark mode.
|
|
||||||
- Keep density appropriate for desktop work. Do not enlarge mobile patterns or hide routine commands behind touch-only gestures.
|
|
||||||
- Gate every API, control, and Toolkit recommendation by the project's Windows App SDK version, target OS, packaging model, and dependencies.
|
|
||||||
- Distinguish WinUI 3 (`Microsoft.UI.Xaml`) from UWP/WinUI 2 (`Windows.UI.Xaml`). Never copy APIs across them without verification.
|
|
||||||
|
|
||||||
## Run the workflow
|
## 核心规则
|
||||||
|
|
||||||
### 1. Establish constraints
|
- 先优化用户任务和恢复路径，再装饰单个控件。
|
||||||
|
- 优先使用目标框架的标准控件、主题资源和内置交互，再考虑自定义组件。
|
||||||
|
- 定义默认、悬停、按下、焦点、当前、选中、勾选、禁用、加载、空、错误、离线、成功和撤销等适用状态。
|
||||||
|
- 键盘、指针、触控、屏幕阅读器、缩放、浅色、深色和高对比度属于同一体验。
|
||||||
|
- 使用语义化 Token 管理颜色、字体、间距、几何、层级、图标和动效；不得只用颜色表达含义。
|
||||||
|
- 保持桌面生产力应用所需的信息密度，不放大移动端模式，也不把常用命令藏在手势或悬停中。
|
||||||
|
- 所有 API 与第三方控件建议都要对应项目的准确版本、目标 Windows、打包模型和依赖。
|
||||||
|
|
||||||
Inspect the project before proposing implementation details. Determine:
|
## 工作流
|
||||||
|
|
||||||
- framework and exact package versions;
|
### 1. 检查项目与约束
|
||||||
- minimum Windows version and packaged or unpackaged deployment;
|
|
||||||
- primary tasks, audience, localization, data density, and accessibility needs;
|
|
||||||
- expected window sizes, multi-window behavior, and resize/snap scenarios;
|
|
||||||
- primary input modes and whether touch optimization is required;
|
|
||||||
- brand constraints, light/dark behavior, and existing design tokens.
|
|
||||||
|
|
||||||
If information is missing, state conservative assumptions and keep version-sensitive recommendations conditional.
|
先检查项目文件、依赖和入口代码，确定：
|
||||||
|
|
||||||
### 2. Model the experience
|
- 实际语言、UI 框架、绑定和准确版本；
|
||||||
|
- 最低 Windows 版本、打包与部署方式；
|
||||||
|
- 用户、主要任务、数据规模、本地化和无障碍要求；
|
||||||
|
- 窗口尺寸、贴靠、多显示器、多窗口及输入方式；
|
||||||
|
- 品牌、现有设计 Token、浅色/深色和高对比度行为；
|
||||||
|
- 客户确认范围、原型保真度、审批人和变更流程。
|
||||||
|
|
||||||
Define the primary jobs, information hierarchy, window map, navigation model, and command surfaces. Keep top-level navigation shallow. Decide which work belongs in the main window, a secondary window, an inline surface, a flyout, or a modal dialog.
|
信息缺失时说明保守假设。版本敏感建议必须保持条件化。
|
||||||
|
|
||||||
Describe the happy path and recovery paths before producing mockups or XAML. Preserve user context across navigation, resize, refresh, and errors.
|
### 2. 读取平台基线并选择一个适配器
|
||||||
|
|
||||||
### 3. Define the visual system
|
Windows 项目始终读取：
|
||||||
|
|
||||||
Create a small semantic system for type, spacing, geometry, color, elevation, material, icons, and motion. Use Windows defaults unless the brand requires a deliberate deviation. Read [windows-foundations.md](references/windows-foundations.md) for current Fluent principles, responsive breakpoints, theme, material, and motion guidance.
|
- [Windows 视觉与布局基础](references/windows-foundations.md)
|
||||||
|
- [Windows 输入与无障碍](references/windows-input-accessibility.md)
|
||||||
|
|
||||||
### 4. Map intent to controls and patterns
|
根据实际依赖只选择一个实现适配器：
|
||||||
|
|
||||||
Select controls by interaction semantics, not by appearance or arbitrary item-count thresholds. Reuse commands across menus, toolbars, context menus, and accelerators. Read [controls-and-patterns.md](references/controls-and-patterns.md) before choosing navigation, collection, form, settings, feedback, or data-table patterns.
|
- WinUI 3 / Windows App SDK / `Microsoft.UI.Xaml`：读取 [WinUI 3 适配指南](references/adapter-winui3.md)。
|
||||||
|
- PySide/PyQt：先确认 Qt 5/6、绑定与 Qt Widgets/QML，再读取 [Qt 适配指南](references/adapter-qt.md)。
|
||||||
|
- Go Gio / `gioui.org`：读取 [Gio 适配指南](references/adapter-gio.md)。
|
||||||
|
|
||||||
### 5. Specify interaction and accessibility
|
框架未知时先检查项目清单、导入和构建文件。没有专用适配器时，仍使用核心体验层和 Windows 平台层，并输出“概念 → 目标控件/API → 版本依据 → 回退 → 验证”的适配表；不得臆造 API，也不要混写多套框架代码。
|
||||||
|
|
||||||
Document focus order, arrow-key behavior, access keys, accelerators, pointer affordances, context menus, touch targets, drag alternatives, accessible names, announcements, contrast, and scaling. Read [input-accessibility.md](references/input-accessibility.md) for the required interaction and accessibility baseline.
|
### 3. 建模任务、导航与状态
|
||||||
|
|
||||||
### 6. Engineer and validate
|
定义主要任务、信息层级、窗口图、导航模型、命令作用域和状态所有权。先写顺利路径，再写取消、失败、重试、撤销和恢复路径。
|
||||||
|
|
||||||
When implementation is requested, follow the existing architecture and centralize tokens, commands, and state. Preserve virtualization and avoid synchronous work on the UI thread. Read [engineering-validation.md](references/engineering-validation.md) for version gates, implementation practices, performance checks, and the test matrix.
|
涉及顶级导航、层级导航、静态标签、文档标签或多窗口时，读取 [导航、窗口与标签规范](references/core-navigation-tabs.md)。在实现前定义稳定身份、历史、焦点、状态恢复、未保存关闭协议、后台任务和窗口所有权。
|
||||||
|
|
||||||
Validate the result at realistic compact, medium, and wide window widths rather than only at a full-screen monitor resolution.
|
### 4. 选择交互模式
|
||||||
|
|
||||||
## Produce decision-ready output
|
按任务语义选择控件，不按截图或任意项目数量阈值选择。
|
||||||
|
|
||||||
For a new design, provide:
|
- 数据表格、网格或高密度列表：读取 [数据表格交互规范](references/core-data-table.md)，明确当前项、焦点、选择集、勾选集、筛选范围、行默认操作、右键目标和键盘模型。
|
||||||
|
- 表单、设置、编辑器或输入流程：读取 [表单与输入规范](references/core-form-input.md)，明确提交模式、验证时机、异步竞态、错误恢复和未保存策略。
|
||||||
|
- 对话框、确认、通知、进度或后台任务：读取 [对话框、反馈与任务规范](references/core-dialogs-tasks.md)，按风险与干扰程度选择反馈层级。
|
||||||
|
- 多个标签页均含顶部导入/配置、中部表格、底部生成/更新/提交：读取 [多 Tab 数据工作台规范](references/core-data-workspace.md)，统一页面骨架、命令分区与执行反馈。
|
||||||
|
|
||||||
1. assumptions and target scenarios;
|
跨按钮、菜单、上下文菜单和快捷键复用同一命令定义。所有指针加速路径都提供可见或键盘等价路径。
|
||||||
2. information architecture and window/navigation model;
|
|
||||||
3. annotated layout with responsive behavior;
|
|
||||||
4. control and command mapping;
|
|
||||||
5. semantic visual tokens;
|
|
||||||
6. interaction and state matrix;
|
|
||||||
7. accessibility requirements;
|
|
||||||
8. implementation notes and acceptance checks.
|
|
||||||
|
|
||||||
For a review, lead with findings ordered by severity. For each finding, identify the affected screen or control, user impact, violated Windows convention, and concrete correction. Separate correctness and accessibility defects from subjective polish suggestions.
|
### 5. 建立视觉系统
|
||||||
|
|
||||||
For implementation, change only the requested scope, reuse the project's patterns, build or run relevant checks, and report any API/version assumptions that remain unverified.
|
使用 Windows 平台层定义字体、间距、颜色、层级、材质、图标、动效、窗口宽度和强对比回退，再由选定框架适配器落实。默认呈现应具有一致的 Fluent/Windows 风格和颜色系统，而不是未经设计的框架原始界面；同时保留标准控件行为和目标框架可维护性。
|
||||||
|
|
||||||
## Reject common failure modes
|
视觉升级现有项目时，先盘点现有主题、控件封装和用户流程，再统一 Token 与高频组件。不要只改 QSS/XAML/绘制颜色而忽略状态、焦点、布局和错误反馈。
|
||||||
|
|
||||||
- Do not present obsolete UWP or archived Toolkit APIs as current WinUI 3 guidance.
|
### 6. 制作 HTML 交互原型并确认
|
||||||
- Do not recommend `ComboBox` for multiple selection; it does not support it.
|
|
||||||
- Do not assume the archived Windows Community Toolkit `DataGrid` is available in current WinUI 3 projects.
|
新产品、主要页面或显著改版在正式桌面实现前，制作可本地运行的 HTML/CSS/JavaScript 交互原型，并读取 [HTML 原型与交接规范](references/core-html-prototype.md)。
|
||||||
- Do not use emoji as structural interface icons; use platform glyphs or a consistent vector icon set.
|
|
||||||
- Do not force Acrylic onto every surface. Use materials to express hierarchy and provide readable solid fallbacks.
|
原型应：
|
||||||
- Do not require `AutomationProperties.Name` where a standard control already exposes an accurate accessible name; add explicit names when semantics are otherwise missing.
|
|
||||||
- Do not confirm every deletion by default. Prefer undo for frequent, recoverable actions and reserve modal confirmation for costly or irreversible consequences.
|
- 复用已定义 Token、真实文案、状态矩阵和窗口断点；
|
||||||
- Do not hard-code one window size, theme, DPI, locale, or input method as the design baseline.
|
- 覆盖主流程及关键加载、空、错误、禁用、确认和完成状态；
|
||||||
|
- 用可重置模拟数据，不连接生产凭据、数据库或不可逆操作；
|
||||||
|
- 对表格、表单、标签、工作台和对话框实现对应核心规范中的关键交互；
|
||||||
|
- 以书面清单确认信息架构、布局、视觉、文案、流程和状态。
|
||||||
|
|
||||||
|
向客户说明浏览器与目标桌面框架在原生控件、窗口管理、字体、系统材质、DPI、无障碍和性能上的差异。确认后建立“HTML 组件/状态 → 核心交互契约 → 目标适配器控件/API”的交接表。客户更改已确认设计时，先更新原型与验收记录。
|
||||||
|
|
||||||
|
小型、低风险、局部调整可说明理由后跳过原型门禁。
|
||||||
|
|
||||||
|
### 7. 实现与验证
|
||||||
|
|
||||||
|
遵循项目既有架构，集中管理 Token、命令和状态。保留虚拟化，不在 UI/事件线程执行阻塞工作，处理取消、重复提交、过期结果和窗口/页面销毁后的回调。
|
||||||
|
|
||||||
|
至少验证：
|
||||||
|
|
||||||
|
- 紧凑、中等、宽窗口，贴靠、最大化与跨显示器；
|
||||||
|
- 100%–200% 显示缩放与增大文本；
|
||||||
|
- 浅色、深色、高对比度及透明效果关闭；
|
||||||
|
- 仅键盘、鼠标及声明支持的触控；
|
||||||
|
- Narrator 与适用的无障碍检查工具；
|
||||||
|
- 空、真实、超大、长文本、失败、权限拒绝和慢任务数据；
|
||||||
|
- 最低支持 Windows 与当前支持目标；
|
||||||
|
- 干净环境中的最终打包产物。
|
||||||
|
|
||||||
|
## 交付物
|
||||||
|
|
||||||
|
新设计或改版至少提供：
|
||||||
|
|
||||||
|
1. 假设、用户和目标场景；
|
||||||
|
2. 信息架构、窗口/导航模型和响应式布局；
|
||||||
|
3. 核心交互与状态矩阵；
|
||||||
|
4. 语义视觉 Token；
|
||||||
|
5. 目标框架控件/API 映射及版本依据；
|
||||||
|
6. 键盘、指针、焦点与无障碍要求；
|
||||||
|
7. 加载、失败、取消、重试、确认、完成与撤销策略；
|
||||||
|
8. 验收与测试清单；
|
||||||
|
9. 需要客户确认时的可运行 HTML 原型、确认记录和桌面交接表。
|
||||||
|
|
||||||
|
评审时先报告阻断、严重和中等问题，再列视觉润色。每项指出位置、触发条件、用户影响、违反的规则和最小稳健修正。实现时只修改请求范围，运行相关构建或检查，并报告尚未验证的版本假设。
|
||||||
|
|
||||||
|
## 禁止的失败模式
|
||||||
|
|
||||||
|
- 不混用 WinUI/UWP 命名空间、PySide/PyQt 绑定或 Qt Widgets/QML 的实现习惯。
|
||||||
|
- 不假设 WinUI 3 自带已归档的 Toolkit `DataGrid`，不把 `ComboBox` 当多选控件。
|
||||||
|
- 不把 Qt QSS 当完整 CSS，不从工作线程触碰 Qt GUI 对象。
|
||||||
|
- 不把 Gio Material 默认主题称为 Fluent，不在每帧重建持久 Widget 状态，也不阻塞窗口事件循环。
|
||||||
|
- 不把 HTML DOM/CSS 逐字移植到桌面代码，不用浏览器原型证明原生性能和无障碍。
|
||||||
|
- 不混淆当前项、焦点、选择和勾选；不让单击、双击、复选框和行内按钮重复触发。
|
||||||
|
- 不把导入、筛选、行操作和工作流完成命令堆在一个区域，也不混淆只读“刷新”与写入“更新”。
|
||||||
|
- 不为所有删除或完成操作统一弹确认框，也不为普通成功统一弹模态对话框。
|
||||||
|
- 不为材质效果破坏标题栏、可读性、高对比度或纯色回退。
|
||||||
|
- 不硬编码单一窗口、主题、DPI、语言或输入方式。
|
||||||
|
|||||||
+3
-3
@@ -1,4 +1,4 @@
|
|||||||
interface:
|
interface:
|
||||||
display_name: "Windows UI/UX Design"
|
display_name: "Windows UI/UX 设计"
|
||||||
short_description: "设计、评审并实现专业的 Windows 桌面端体验"
|
short_description: "设计、原型确认并实现 Windows 桌面端体验"
|
||||||
default_prompt: "Use $win-ui-ux-design to design and review a Windows desktop app experience."
|
default_prompt: "使用 $windows-ui-ux 设计 Windows 桌面应用，先制作 HTML 交互原型供客户确认，再按项目实际框架选择 WinUI、Qt/PySide/PyQt 或 Gio 实现。"
|
||||||
|
|||||||
@@ -0,0 +1,135 @@
|
|||||||
|
# Go Gio Windows 桌面适配指南
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
1. 版本与适用边界
|
||||||
|
2. 即时模式架构与状态
|
||||||
|
3. Windows 视觉与布局
|
||||||
|
4. 核心交互模式映射
|
||||||
|
5. 文件、异步与长任务
|
||||||
|
6. 键盘、焦点与无障碍
|
||||||
|
7. 构建、测试与交付
|
||||||
|
8. 常见反模式
|
||||||
|
9. 官方资料
|
||||||
|
|
||||||
|
## 1. 版本与适用边界
|
||||||
|
|
||||||
|
生成代码前读取 `go.mod`、`go.sum`、入口文件和实际使用的 `gioui.org` 子包，确认 Go、Gio 与扩展包的准确版本。Gio 模块仍是 v1 之前版本，次版本可能包含不兼容变化；应固定已验证版本，并以该版本的包文档和示例为准。
|
||||||
|
|
||||||
|
Gio 适合需要 Go 单一技术栈、自绘界面、跨平台渲染和高度定制交互的桌面应用。它不会自动提供完整的 Windows Fluent 控件集，也没有与 WinUI `DataGrid`、`TabView`、`ContentDialog` 或 Mica 一一对应的内置组件。选择 Gio 意味着项目需要明确承担复合控件的状态、输入、焦点、语义、主题和测试成本。
|
||||||
|
|
||||||
|
## 2. 即时模式架构与状态
|
||||||
|
|
||||||
|
Gio 使用即时模式：应用读取窗口事件、更新持久状态，再在每个 `FrameEvent` 中布局并绘制当前帧。不能依赖上一帧留下的控件对象树。
|
||||||
|
|
||||||
|
- `widget.Clickable`、`widget.Editor`、列表位置、标签选择、筛选值和弹层状态等必须由页面或组件结构体长期持有，不能在每一帧的布局函数中重新创建。
|
||||||
|
- 领域数据与 UI 交互状态分离。记录以稳定 ID 识别，不以可见标题、排序后的行号或循环索引作为业务身份。
|
||||||
|
- 布局函数应接近纯函数：读取状态、消费本帧输入、产生操作；文件、网络、数据库和昂贵计算放在布局循环之外。
|
||||||
|
- 将导入、刷新、生成、更新、提交等动作建模为集中命令，统一管理启用条件、执行中、防重复、取消、结果和错误，不要只散落在 `Clicked()` 分支中。
|
||||||
|
- 通过显式页面状态描述空闲、加载、内容、空、筛选后为空、错误、离线/过期、权限拒绝和部分结果。
|
||||||
|
|
||||||
|
窗口事件循环必须处理 `FrameEvent` 与 `DestroyEvent`，并保证每个帧事件都完成提交。后台结果到达时更新线程安全的应用状态并调用 `Window.Invalidate()` 请求重绘；不要用忙循环持续刷新。
|
||||||
|
|
||||||
|
## 3. Windows 视觉与布局
|
||||||
|
|
||||||
|
`widget/material` 提供 Material Design 主题和样式，它不是 Windows Fluent 设计系统。Windows 项目应在 Gio 上建立一层薄的设计适配：集中定义语义颜色、字体、字号、间距、圆角、描边、阴影、状态层、图标和动效，再用这些 Token 组合组件。不要在各页面直接散布颜色和尺寸常量。
|
||||||
|
|
||||||
|
- Windows 字体优先使用系统可用的 Segoe UI Variable/Segoe UI，并准备缺失时的回退；验证中文字体与混排。
|
||||||
|
- 保留系统装饰窗口和标准关闭、最大化、最小化、调整大小行为。不要仅为“像 WinUI”而自制整套非客户区。
|
||||||
|
- 不宣称 Gio 内置原生 Mica/Acrylic。只有在隔离的 Windows 原生适配经过版本、性能、高对比度和失效测试后才启用，并始终提供纯色主题表面回退。
|
||||||
|
- 以 `layout.Context` 的 `Constraints` 决定紧凑、中等和宽布局，用 `layout.Flex`、`layout.Stack`、`layout.Inset` 和 `layout.List` 组合，不按全屏分辨率或固定像素坐标布局。
|
||||||
|
- 在断点切换时保留输入、焦点、选择、勾选、筛选、滚动、展开、任务和未保存状态。
|
||||||
|
|
||||||
|
主题至少覆盖浅色、深色、高对比度或可访问的强对比回退，并验证系统强调色不可用、透明效果关闭和远程桌面等场景。颜色不能成为错误、选择或状态的唯一线索。
|
||||||
|
|
||||||
|
## 4. 核心交互模式映射
|
||||||
|
|
||||||
|
### 导航与标签
|
||||||
|
|
||||||
|
Gio 没有内置完整 `NavigationView`/`TabView` 体验。用稳定页面 ID 维护顶级导航，用稳定标签 ID 维护文档工作区，并自行定义：键盘切换、焦点返回、关闭、重排、溢出、未保存确认、任务归属和状态恢复。标签标题只是显示文本，不能作为身份。
|
||||||
|
|
||||||
|
### 数据表格
|
||||||
|
|
||||||
|
大型表格使用 `layout.List` 或经过测量的自定义虚拟化行布局，只绘制可见区域，避免为每个单元格长期持有昂贵对象。列宽、表头、滚动、固定列和编辑行为需形成单独组件契约。
|
||||||
|
|
||||||
|
必须分别建模：
|
||||||
|
|
||||||
|
- 当前行/单元格；
|
||||||
|
- 键盘焦点；
|
||||||
|
- 选择集；
|
||||||
|
- 勾选集。
|
||||||
|
|
||||||
|
指针命中后先解析稳定记录 ID，再处理单击选择、双击默认操作、右键上下文目标、复选框和行内按钮。双击不能额外执行一次单击的破坏性动作；复选框或行内按钮消费事件后不能继续触发行默认操作。Ctrl/Shift 多选、Space 切换、Enter 调用、上下文菜单键或 Shift+F10 都要有明确规则。排序和筛选后按 ID 恢复有效状态，并向用户说明被筛选隐藏的勾选项。
|
||||||
|
|
||||||
|
### 表单
|
||||||
|
|
||||||
|
用持久的 `widget.Editor`、布尔/枚举选择状态和应用层字段模型构造表单。每个字段定义标签、说明、必填、格式、领域规则、验证时机、错误位置和提交模式。提交失败保留输入并将焦点移到首个错误；异步验证以请求 ID 或取消机制忽略旧结果。占位文本不能代替字段标签。
|
||||||
|
|
||||||
|
### 对话框、反馈与任务
|
||||||
|
|
||||||
|
Gio 中的对话框、浮层、信息条通常需要应用自行组合。模态层必须限制背景交互、建立正确绘制层级、将焦点移入、支持 Escape/关闭规则，并在关闭后将焦点返回触发点。只有不可逆、高代价或没有安全默认值的决定才阻塞确认。
|
||||||
|
|
||||||
|
普通成功使用内联状态或非阻塞通知；可恢复错误保留上下文并提供重试；长任务在页面内显示阶段、进度、取消和结果。不要为每次生成、更新或提交统一弹出成功对话框。
|
||||||
|
|
||||||
|
### 多 Tab 数据工作台
|
||||||
|
|
||||||
|
所有工作标签复用同一页面骨架：标题与说明、导入/配置/刷新等顶部前置命令、来源与校验状态、可伸展表格主区、选择摘要，以及生成/更新/提交等底部完成命令。每个命令显式绑定作用域、前置条件、风险、可逆性、确认策略和完成反馈。
|
||||||
|
|
||||||
|
## 5. 文件、异步与长任务
|
||||||
|
|
||||||
|
文件选择可使用 `gioui.org/x/explorer`，但必须遵循其窗口生命周期：每个窗口创建对应 `Explorer`，将窗口事件传给 `ListenEvents`，并从独立 goroutine 调用阻塞的 `ChooseFile`、`ChooseFiles` 或 `CreateFile`。返回句柄按 `io.Reader`、`io.Writer` 或相关接口使用，不要假设一定是 `*os.File` 或具有普通文件路径。
|
||||||
|
|
||||||
|
- goroutine 不直接无同步地修改布局正在读取的复合状态；通过 channel、互斥保护的结果或项目统一状态容器交接。
|
||||||
|
- I/O、网络、数据库与计算任务不得阻塞窗口事件循环。
|
||||||
|
- 长任务使用 `context.Context` 或等价取消协议，携带任务 ID，并在窗口关闭、标签关闭或新请求替代旧请求后丢弃过期结果。
|
||||||
|
- 任务提交阶段要定义幂等性；不能幂等时在进行中禁用重复命令并清楚显示原因。
|
||||||
|
- 后台状态改变后调用 `Window.Invalidate()`，不要依赖用户移动鼠标才看到结果。
|
||||||
|
|
||||||
|
## 6. 键盘、焦点与无障碍
|
||||||
|
|
||||||
|
用 `key.Filter` 声明需要接收的键事件，用 `key.FocusCmd` 请求焦点，并处理焦点进入、离开和方向移动。快捷键的作用域必须清晰；重复操作提供 Windows 常用快捷键或可发现的替代路径。所有仅右键、悬停、拖拽或触控可达的功能都需要键盘路径。
|
||||||
|
|
||||||
|
使用 `io/semantic` 为自定义组件公开合适的类别、标签、说明、启用、选择及其他状态。复合表格、标签、对话框和自绘输入承担比标准控件更高的语义责任；代码中存在语义操作不代表屏幕阅读器体验已正确，必须用 Windows Narrator 和无障碍检查工具执行真实任务测试。
|
||||||
|
|
||||||
|
焦点指示必须在浅色、深色与强对比背景上清晰；弹层打开和关闭、标签切换、删除当前记录、筛选后当前项消失时都要定义焦点落点。状态变化与错误需要可感知的文本和语义反馈，不能只改变颜色或播放动画。
|
||||||
|
|
||||||
|
## 7. 构建、测试与交付
|
||||||
|
|
||||||
|
Windows GUI 发布构建可按项目需要使用 `-ldflags="-H windowsgui"` 隐藏控制台，但开发构建应保留可诊断日志。锁定 Go/Gio/扩展模块版本，保存可复现构建命令，并在干净 Windows 环境验证产物、资源、字体、图标与文件选择器。
|
||||||
|
|
||||||
|
最低测试矩阵包括：最低支持 Windows 与当前 Windows 11；紧凑/中等/宽窗口、贴靠、最大化和多显示器；100%/125%/150%/200% 缩放；浅色、深色、强对比回退；键盘、鼠标及声明支持的触控；Narrator；空、真实、超大、错误、权限拒绝和慢任务数据；窗口/标签关闭、取消、重试和恢复。
|
||||||
|
|
||||||
|
交付前确认：
|
||||||
|
|
||||||
|
- [ ] 所有持久 Widget 状态未在帧布局中意外重建。
|
||||||
|
- [ ] 页面、标签和记录使用稳定 ID，而非索引或标题。
|
||||||
|
- [ ] 大型列表/表格只布局可见内容，并以真实数据测量。
|
||||||
|
- [ ] 后台任务不阻塞事件循环，状态同步无数据竞争，结果到达会触发重绘。
|
||||||
|
- [ ] 键盘、焦点、语义、对话框和上下文菜单已用真实辅助技术验证。
|
||||||
|
- [ ] Windows 视觉层使用集中 Token，且有纯色和强对比回退。
|
||||||
|
- [ ] 依赖版本、构建命令和自定义复合控件责任已记录。
|
||||||
|
|
||||||
|
## 8. 常见反模式
|
||||||
|
|
||||||
|
- 每帧重新创建 `widget.Clickable`、`widget.Editor` 或列表状态，导致输入和焦点丢失。
|
||||||
|
- 把 `widget/material` 的默认外观直接称为 Windows Fluent。
|
||||||
|
- 在事件循环中执行阻塞 I/O，或用持续重绘掩盖状态同步问题。
|
||||||
|
- 用排序后行号保存勾选或选择，导致筛选后作用于错误记录。
|
||||||
|
- 自绘表格、标签或弹层，却没有键盘、焦点、语义和屏幕阅读器测试。
|
||||||
|
- 假设 `x/explorer` 返回本地路径或 `*os.File`，或者在帧处理 goroutine 中调用其阻塞选择方法。
|
||||||
|
- 为视觉效果移除系统窗口能力，或把未经验证的 Windows 私有 API 变成必需依赖。
|
||||||
|
|
||||||
|
## 9. 官方资料
|
||||||
|
|
||||||
|
- [Gio 架构](https://gioui.org/doc/architecture)
|
||||||
|
- [Gio Widget 架构](https://gioui.org/doc/architecture/widget)
|
||||||
|
- [窗口事件与重绘](https://gioui.org/doc/architecture/window)
|
||||||
|
- [输入处理](https://gioui.org/doc/architecture/input)
|
||||||
|
- [布局系统](https://gioui.org/doc/architecture/layout)
|
||||||
|
- [layout 包](https://pkg.go.dev/gioui.org/layout)
|
||||||
|
- [widget 包](https://pkg.go.dev/gioui.org/widget)
|
||||||
|
- [Material 组件包](https://pkg.go.dev/gioui.org/widget/material)
|
||||||
|
- [键盘输入包](https://pkg.go.dev/gioui.org/io/key)
|
||||||
|
- [语义无障碍包](https://pkg.go.dev/gioui.org/io/semantic)
|
||||||
|
- [窗口 app 包](https://pkg.go.dev/gioui.org/app)
|
||||||
|
- [文件选择 explorer 包](https://pkg.go.dev/gioui.org/x/explorer)
|
||||||
@@ -0,0 +1,274 @@
|
|||||||
|
# Windows Qt / PySide / PyQt 适配指南
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
1. 确认绑定与 UI 技术
|
||||||
|
2. 将 Windows 交互意图映射到 Qt
|
||||||
|
3. 架构、对象生命周期与数据模型
|
||||||
|
4. 布局、窗口化与高 DPI
|
||||||
|
5. 主题、QSS、图标与 Windows 材质
|
||||||
|
6. 命令、键盘与无障碍
|
||||||
|
7. 线程、异步与响应速度
|
||||||
|
8. Designer、资源、设置与本地化
|
||||||
|
9. 部署与测试
|
||||||
|
10. 常见反模式
|
||||||
|
11. 交付检查清单
|
||||||
|
12. 官方资料
|
||||||
|
|
||||||
|
## 1. 确认绑定与 UI 技术
|
||||||
|
|
||||||
|
先检查 `pyproject.toml`、锁文件、requirements、导入语句和实际安装版本，再生成代码。
|
||||||
|
|
||||||
|
### 选择绑定
|
||||||
|
|
||||||
|
- 新项目优先选择 Qt 6 绑定，除非插件、操作系统或现有代码明确要求 Qt 5。
|
||||||
|
- PySide6 是 Qt 官方 Python 绑定，采用 LGPLv3/GPLv3/商业许可组合；发布前确认应用对 Qt 许可义务的满足方式。
|
||||||
|
- PyQt6 采用 GPLv3 或 Riverbank 商业许可，不提供 LGPL；闭源分发前必须确认许可方案。
|
||||||
|
- 维护现有 PySide2/PyQt5 项目时遵循项目版本，不要在 UI 改造中顺带升级主版本。
|
||||||
|
- 不要在一个进程或分发包中混用 PySide 与 PyQt。第三方组件的绑定必须与应用一致。
|
||||||
|
|
||||||
|
### 选择 UI 技术
|
||||||
|
|
||||||
|
| 场景 | 优先选择 |
|
||||||
|
|---|---|
|
||||||
|
| 高密度生产力工具、表格、菜单、工具栏、停靠面板 | Qt Widgets |
|
||||||
|
| 既有 `.ui` 文件或大量成熟 QWidget 控件 | Qt Widgets |
|
||||||
|
| 高度定制的视觉、连续动画、触控优先界面 | Qt Quick/QML |
|
||||||
|
| Widgets 与 QML 混合 | 仅在价值明确时采用，并定义边界、线程、焦点和无障碍责任 |
|
||||||
|
|
||||||
|
不要把 Qt Quick 仅当作“更现代的 Widgets”，也不要为了原生外观强行用 Widgets 实现复杂动画。根据任务、团队能力、组件生态、性能、部署和无障碍要求选择。
|
||||||
|
|
||||||
|
### 保持绑定 API 一致
|
||||||
|
|
||||||
|
- PySide 使用 `Signal`、`Slot`、`Property`；PyQt 使用 `pyqtSignal`、`pyqtSlot`、`pyqtProperty`。
|
||||||
|
- PySide 项目仅在项目已统一启用时使用 `snake_case` 或 `true_property` 特性；不要与默认 camelCase 风格随机混用。
|
||||||
|
- 生成示例时沿用仓库现有导入风格、枚举写法和 UI 构建方式。
|
||||||
|
|
||||||
|
## 2. 将 Windows 交互意图映射到 Qt
|
||||||
|
|
||||||
|
根据语义选择控件，不要逐字翻译 WinUI 控件名：
|
||||||
|
|
||||||
|
| Windows/WinUI 意图 | Qt Widgets 实现 | 说明 |
|
||||||
|
|---|---|---|
|
||||||
|
| 应用主窗口 | `QMainWindow` + `centralWidget` | 可组合菜单栏、工具栏、状态栏和停靠面板 |
|
||||||
|
| 顶级导航 | 带 Model 的 `QListView` + `QStackedWidget` | 小型静态同级页也可用 `QTabWidget`；导航必须有文本标签 |
|
||||||
|
| 文档标签页 | `QTabWidget` 或 `QTabBar` + 内容容器 | 定义关闭、重排、未保存和快捷键行为 |
|
||||||
|
| 辅助工作面板 | `QDockWidget` | 定义允许区域、浮动、关闭和状态恢复 |
|
||||||
|
| 分栏工作区 | `QSplitter` | 设置合理最小尺寸与折叠行为 |
|
||||||
|
| 页面级命令 | `QAction` + `QToolBar`/按钮 | 同一 `QAction` 复用于菜单、工具栏和快捷键 |
|
||||||
|
| 应用菜单 | `QMenuBar`、`QMenu`、`QAction` | 使用标准菜单分组和角色 |
|
||||||
|
| 上下文命令 | `QMenu` 或 `QAction` 集合 | 同时提供可见或键盘访问路径 |
|
||||||
|
| 列表 | `QListView` + `QAbstractListModel` | 动态或大型数据不要依赖 `QListWidget` |
|
||||||
|
| 表格 | `QTableView` + `QAbstractTableModel` | 排序/筛选使用 `QSortFilterProxyModel` |
|
||||||
|
| 树 | `QTreeView` + `QAbstractItemModel` | 保持展开、选择和键盘行为 |
|
||||||
|
| 简单表单 | `QFormLayout` + 标准输入控件 | 设置标签 Buddy、验证和错误位置 |
|
||||||
|
| 模态任务 | `QDialog` + `QDialogButtonBox` | 仅用于真正需要阻塞的决策或短任务 |
|
||||||
|
| 简单系统消息 | `QMessageBox` | 不要用于频繁状态或长文本工作流 |
|
||||||
|
| 内联信息条 | 自定义语义化 Banner `QWidget` | 包含图标、文本、操作和关闭入口，不要用状态栏替代关键错误 |
|
||||||
|
| 确定进度 | `QProgressBar` | 提供取消、失败和完成状态 |
|
||||||
|
| 阻塞进度 | `QProgressDialog` | 仅在确实需要窗口级阻塞时使用 |
|
||||||
|
| 持久设置 | `QSettings` | 先设置组织名和应用名，定义迁移与默认值 |
|
||||||
|
|
||||||
|
Qt Quick/QML 项目使用 Qt Quick Controls 的等价语义控件，并为 Python 暴露的状态使用 `Signal`、`Slot` 和带通知信号的 `Property`。不要把 QWidget 嵌入 QML 作为常规布局方案。
|
||||||
|
|
||||||
|
### 核心交互模式映射
|
||||||
|
|
||||||
|
**数据表格：** 使用 `QTableView`、自定义 `QAbstractTableModel` 与 `QSortFilterProxyModel`，以稳定记录 ID 维护业务选择和勾选状态。`currentIndex()`、`selectionModel()` 与模型中的勾选角色分别对应当前单元格、选择集和勾选集，不能互相替代。通过视图的 `clicked`、`doubleClicked`、`activated` 与 `customContextMenuRequested` 明确区分单击、双击、键盘调用和右键；右键先解析目标索引，再按产品规则决定是否改变选择。复选框和行内按钮的委托事件必须停止继续触发行默认操作。
|
||||||
|
|
||||||
|
**表单：** 使用标准编辑控件、`QFormLayout`、标签 Buddy 和字段旁固定错误区。格式约束可用 `QValidator` 或输入掩码，领域规则仍由应用层验证。避免在每次按键后弹框；提交失败时保留输入，聚焦首个错误，并给出问题与修复方式。异步验证以请求 ID 或取消机制忽略过期结果。
|
||||||
|
|
||||||
|
**导航与标签：** 顶级导航可用 Model 驱动的 `QListView` 配合 `QStackedWidget`；文档工作区使用 `QTabWidget`，或以 `QTabBar` 加内容容器构建。页面与标签都用稳定 ID 管理，不以标题或当前索引作为业务身份。关闭、重排和切换前定义未保存检查、焦点返回、筛选/选择/滚动恢复及后台任务所有权。
|
||||||
|
|
||||||
|
**对话框与任务：** `QDialog`/`QDialogButtonBox` 只承载必须阻塞的决策；普通状态与可恢复错误使用页面内 Banner、状态区或非模态面板。长任务由 worker 或线程池执行，通过队列信号回传进度与结果，并支持取消、重复提交防护、关闭后忽略回调及成功/失败/重试状态。
|
||||||
|
|
||||||
|
**多 Tab 数据工作台：** 每个页面统一采用垂直布局：标题与说明、顶部 `QToolBar`/命令区、来源或校验状态区、可伸展的 `QTableView` 主区、底部选择摘要与完成操作区。将同一 `QAction` 复用于按钮、菜单和快捷键。普通成功不弹 `QMessageBox`；只有不可逆、高代价或缺少安全默认值的操作才在执行前确认。
|
||||||
|
|
||||||
|
## 3. 架构、对象生命周期与数据模型
|
||||||
|
|
||||||
|
### 对象与职责
|
||||||
|
|
||||||
|
- 让 View 负责渲染和输入转发，让领域/应用服务负责业务规则、I/O 和持久化。
|
||||||
|
- 使用 `QObject` 的父子所有权管理 Qt 对象生命周期；不要同时建立不必要的 Python 强引用环。
|
||||||
|
- 对需要延迟销毁的 `QObject` 使用 `deleteLater()`，尤其是跨事件循环或线程退出时。
|
||||||
|
- 将共享用户操作建模为 `QAction`，避免在多个按钮和菜单处理器中复制逻辑。
|
||||||
|
- 在关闭窗口前处理未保存更改，但不要把业务保存逻辑塞入 `closeEvent()`。
|
||||||
|
|
||||||
|
### 信号与槽
|
||||||
|
|
||||||
|
- PySide 类中将作为连接目标的方法标记为 `@Slot(...)`；官方建议这样做以减少运行时开销，并正确表达线程亲和性。
|
||||||
|
- 让信号载荷传递不可变数据、标识符或轻量结果，不要跨线程传递需要在工作线程访问的 GUI 对象。
|
||||||
|
- 明确连接的所有者和断开时机，避免重复连接导致一次操作执行多次。
|
||||||
|
- QML 可见属性必须提供通知信号，否则绑定不会可靠更新。
|
||||||
|
|
||||||
|
### Model/View
|
||||||
|
|
||||||
|
- 动态、共享、可排序筛选或可能变大的数据使用 `QListView`、`QTableView`、`QTreeView` 与 `QAbstractItemModel` 派生模型。
|
||||||
|
- 一维和二维数据分别优先从 `QAbstractListModel`、`QAbstractTableModel` 开始，不要无必要直接实现完整 `QAbstractItemModel`。
|
||||||
|
- 使用 `QSortFilterProxyModel` 处理排序和筛选，不要为每次查询复制整个源数据集合。
|
||||||
|
- 插入、删除、移动和重置模型时使用正确的 begin/end 通知；不得只修改 Python 列表后强制刷新视图。
|
||||||
|
- 自定义绘制和编辑使用 `QStyledItemDelegate`；不要为每个单元格创建常驻 QWidget。
|
||||||
|
- `QListWidget`、`QTableWidget`、`QTreeWidget` 仅适合小型、简单、不会共享模型的数据。
|
||||||
|
|
||||||
|
## 4. 布局、窗口化与高 DPI
|
||||||
|
|
||||||
|
### 布局
|
||||||
|
|
||||||
|
- 使用 `QLayout` 派生布局、`QSizePolicy`、stretch、`sizeHint()` 和最小尺寸，不要用 `setGeometry()` 手工排列常规界面。
|
||||||
|
- 需要随宽度换行的自定义控件实现合理的 `heightForWidth()`；内容变化时调用 `updateGeometry()`。
|
||||||
|
- 为窗口定义可用的最小尺寸，而不是固定尺寸。长文本、翻译和字体放大后仍应可操作。
|
||||||
|
- 在少量语义断点下重排或显示/隐藏次要面板；不要在每次 `resizeEvent()` 中重建整棵 Widget 树。
|
||||||
|
- 响应式切换时保留焦点、选择、滚动、编辑和展开状态。
|
||||||
|
|
||||||
|
### 主窗口与窗口状态
|
||||||
|
|
||||||
|
- `QMainWindow` 只把一个控件设置为 `centralWidget`，再通过 Qt 提供的 API 管理菜单栏、工具栏、状态栏和 `QDockWidget`。
|
||||||
|
- 使用 `saveGeometry()`/`restoreGeometry()` 和 `QMainWindow.saveState()`/`restoreState()` 持久化窗口与停靠布局。
|
||||||
|
- 恢复窗口时检查当前屏幕可用区域，防止窗口因显示器移除或 DPI 变化而出现在屏幕外。
|
||||||
|
- 为辅助窗口定义所有者、模态性、任务栏显示、激活、关闭和共享数据生命周期。
|
||||||
|
- 优先保留原生窗口框架。无边框窗口需要自行正确实现缩放命中测试、拖动、系统菜单、标题按钮、Snap Layouts、高 DPI 和无障碍，除非产品价值足以承担成本，否则不要使用。
|
||||||
|
|
||||||
|
### 高 DPI 与多显示器
|
||||||
|
|
||||||
|
- Qt 6 以设备无关像素描述大多数 Widget、Quick、事件和窗口几何；不要再次手工乘系统缩放比例。
|
||||||
|
- 自定义像素绘制或图像几何时读取 `devicePixelRatio()`；不要把物理像素当作布局单位。
|
||||||
|
- 使用 SVG、`QIcon` 多尺寸资源或 `@2x` 高分辨率资源。验证 100%、125%、150%、200% 以及跨显示器移动。
|
||||||
|
- 屏幕几何使用 `QScreen` 的设备无关坐标；不要假设多个屏幕组成无间隙的物理像素网格。
|
||||||
|
|
||||||
|
## 5. 主题、QSS、图标与 Windows 材质
|
||||||
|
|
||||||
|
### 主题优先级
|
||||||
|
|
||||||
|
1. 优先让 `QStyle` 和系统 `QPalette` 提供平台行为与控件状态。
|
||||||
|
2. 用语义 Token 生成有限的自定义 `QPalette` 或组件级 QSS。
|
||||||
|
3. 只有品牌需要时才替换标准控件绘制或实现自定义 `QStyle`。
|
||||||
|
|
||||||
|
`QPalette` 为活动、非活动和禁用状态提供颜色组。覆盖颜色时同时定义这些状态，并独立验证浅色、深色和高对比度。
|
||||||
|
|
||||||
|
Qt 6.5 或更高版本可通过 `QGuiApplication.styleHints().colorScheme()` 读取系统配色方案，并监听 `colorSchemeChanged`。处理主题变化时也要响应 `QEvent.PaletteChange` 或 `QEvent.ApplicationPaletteChange`。使用前检查项目 Qt 版本；较旧版本不得生成不存在的 API。
|
||||||
|
|
||||||
|
Qt 6.10 或更高版本提供更多平台无障碍提示；低版本仍必须通过实际 Windows 高对比度测试验证，而不是自行猜测系统颜色。
|
||||||
|
|
||||||
|
### QSS
|
||||||
|
|
||||||
|
- QSS 不是完整 CSS：不要期待 Web 布局、CSS 变量、继承和选择器行为完全一致。
|
||||||
|
- 避免 `QWidget { ... }` 等大范围规则覆盖所有标准状态。
|
||||||
|
- 为 hover、pressed、checked、selected、disabled、focus、active/inactive 和高对比度定义可辨识行为。
|
||||||
|
- 使用动态属性选择器时，属性变化后按项目需要重新 polish；不要依赖偶然刷新。
|
||||||
|
- 样式表可能改变原生绘制和尺寸提示。修改后重新测试菜单、滚动条、输入法、焦点框、停靠窗口和高 DPI。
|
||||||
|
|
||||||
|
### 图标与 Windows 材质
|
||||||
|
|
||||||
|
- 使用一致的 SVG/`QIcon` 资源，为 normal、disabled、active、selected 等模式提供可读变体。
|
||||||
|
- 不要用 Emoji 作为结构图标，也不要依赖某台开发机才存在的字体图标。
|
||||||
|
- Qt Widgets/PySide 没有与 WinUI `MicaBackdrop` 完全等价的跨版本 API。需要 Mica/Acrylic 时，把 Windows 原生集成隔离为可选适配层，按 Windows/Qt 版本检查，并始终提供纯色 `QPalette` 回退。
|
||||||
|
- 不要为装饰效果移除原生标题栏、破坏高对比度或引入不可维护的全局事件过滤器。
|
||||||
|
|
||||||
|
## 6. 命令、键盘与无障碍
|
||||||
|
|
||||||
|
### 命令与键盘
|
||||||
|
|
||||||
|
- 用 `QAction` 集中管理文本、图标、启用/选中状态和快捷键，并复用于菜单、工具栏、按钮或上下文菜单。
|
||||||
|
- 标准操作优先使用 `QKeySequence.StandardKey`，避免硬编码与平台约定冲突的组合键。
|
||||||
|
- 使用 `QShortcut` 时设置合适的 `Qt.ShortcutContext`；不要让页面快捷键意外覆盖整个应用。
|
||||||
|
- 使用标签中的 `&` 和 `QLabel.setBuddy()` 提供访问键。处理中文界面时仍要检查访问键是否重复和是否可发现。
|
||||||
|
- 优先使用自然 Tab 顺序，仅在布局顺序无法表达正确流程时使用 `QWidget.setTabOrder()`。
|
||||||
|
- 所有悬停、右键和拖拽加速操作都必须有可见或键盘等价路径。
|
||||||
|
|
||||||
|
### 无障碍
|
||||||
|
|
||||||
|
- 标准 Widgets 与 Qt Quick Controls 已提供基础无障碍接口，优先复用它们。
|
||||||
|
- 仅在可见文本无法形成正确名称时设置 `accessibleName`；把补充说明放入 `accessibleDescription`。
|
||||||
|
- 为表单建立标签 Buddy 和合理焦点顺序；不要只通过占位符标识输入字段。
|
||||||
|
- 自定义 QWidget 需要公开正确角色、名称、状态、值、操作和事件；复杂控件根据需要实现 `QAccessibleInterface`/`QAccessibleWidget`。
|
||||||
|
- QML 自定义项使用 `Accessible` 附加属性公开角色、名称、描述和操作。
|
||||||
|
- 用 Narrator、Accessibility Insights/Inspect、键盘、高对比度和文本/显示缩放验证真实体验。
|
||||||
|
|
||||||
|
## 7. 线程、异步与响应速度
|
||||||
|
|
||||||
|
### GUI 线程规则
|
||||||
|
|
||||||
|
- `QWidget` 及其子类不是可重入对象，只能在 GUI 主线程创建和访问。Qt Quick 场景对象也不得从工作线程直接修改。
|
||||||
|
- 后台工作使用 worker `QObject` + `moveToThread()`，或 `QThreadPool` + `QRunnable`；根据项目复杂度选择一种模式并统一。
|
||||||
|
- 通过默认 AutoConnection 或显式 QueuedConnection 的信号把结果送回 GUI 线程。
|
||||||
|
- 对具有事件循环的接收者使用绑定对应的 Slot 装饰器，确保代码在接收对象所属线程执行。
|
||||||
|
- 在线程退出时使用 `quit()`、`wait()` 和 `deleteLater()` 建立明确的清理链；关闭窗口后不得让回调访问已销毁 UI。
|
||||||
|
- 不要对同一线程使用 BlockingQueuedConnection，这会导致死锁。
|
||||||
|
|
||||||
|
### 任务设计
|
||||||
|
|
||||||
|
- 长任务提供进度、取消和最终状态；取消必须检查任务是否仍可安全提交结果。
|
||||||
|
- 搜索、预览和重新加载使用请求 ID 或取消令牌忽略过期结果。
|
||||||
|
- 网络请求优先使用事件驱动的 `QNetworkAccessManager`，或在工作线程使用不会触碰 GUI 的客户端。
|
||||||
|
- 不要在槽函数中执行阻塞 I/O，也不要用频繁 `processEvents()` 掩盖冻结。
|
||||||
|
- 需要 `asyncio` 时沿用项目已有事件循环集成。采用 `PySide6.QtAsyncio` 前核对精确版本和支持范围，不要同时运行两个互相竞争的主事件循环。
|
||||||
|
|
||||||
|
## 8. Designer、资源、设置与本地化
|
||||||
|
|
||||||
|
- Qt Widgets Designer 生成的 `.ui` 文件应通过 `pyside6-uic`/`pyuic6` 生成代码，或由项目统一使用 `QUiLoader` 运行时加载。
|
||||||
|
- 不要手工编辑生成的 `ui_*.py`；在继承/组合的业务类中扩展界面，重新生成时避免丢失修改。
|
||||||
|
- PySide 官方建议优先使用与绑定版本匹配的 `pyside6-uic`，避免直接调用不匹配的独立 `uic`。
|
||||||
|
- 使用 `.qrc` 与 `pyside6-rcc`/对应 PyQt 工具管理图标和资源，或采用项目已经验证的包资源方案。
|
||||||
|
- 使用 `QSettings` 前设置组织名、域和应用名；为设置键、默认值、版本迁移和损坏恢复建立规范。
|
||||||
|
- 使用 `tr()`/翻译上下文和 `QTranslator` 进行本地化。不要拼接句子；测试复数、快捷键、长文本和从右到左布局。
|
||||||
|
|
||||||
|
## 9. 部署与测试
|
||||||
|
|
||||||
|
### 部署
|
||||||
|
|
||||||
|
- 固定 Python、绑定、Qt 和打包工具版本，并在干净虚拟环境中构建。
|
||||||
|
- PySide6 优先评估官方 `pyside6-deploy`；它使用 `pysidedeploy.spec` 保存配置，并支持 `--dry-run` 查看实际命令。
|
||||||
|
- PyQt 使用项目许可和工具链已验证的打包方案；不要把 PySide 部署命令用于 PyQt。
|
||||||
|
- 检查 Qt 平台插件、图像格式插件、QML imports、翻译、OpenSSL/多媒体依赖、MSVC Runtime、应用图标和资源是否完整。
|
||||||
|
- 在干净 Windows 虚拟机上测试首次启动、无开发环境运行、非 ASCII 路径、只读目录、多用户配置、升级与卸载。
|
||||||
|
- 发布前确认代码签名、安装器、文件关联、协议处理、自动更新和许可文件要求。
|
||||||
|
|
||||||
|
### 测试
|
||||||
|
|
||||||
|
- 使用 Qt Test/QTest 或项目现有测试栈覆盖关键 Widget、快捷键、模型通知和信号行为。
|
||||||
|
- 对 Model/View 测试插入、删除、移动、排序、筛选、编辑、空数据和超大数据。
|
||||||
|
- 对线程测试取消、窗口提前关闭、过期结果、异常和应用退出。
|
||||||
|
- 执行 Windows 测试矩阵：最低支持版本与当前 Windows 11；100%–200% 缩放；跨显示器；浅色、深色、高对比度；键盘、鼠标和声明支持的触控；Narrator。
|
||||||
|
- 测试打包产物，而不只测试源码环境。
|
||||||
|
|
||||||
|
## 10. 常见反模式
|
||||||
|
|
||||||
|
- 在同一项目中混用 `PySide6` 与 `PyQt6` 导入。
|
||||||
|
- 从工作线程调用 Widget 方法或把 Widget 传给 worker。
|
||||||
|
- 用 `time.sleep()`、同步网络或大循环阻塞 GUI 线程。
|
||||||
|
- 为动态表格使用 `QTableWidget` 并为每个单元格嵌入 Widget。
|
||||||
|
- 在每次窗口调整大小时销毁并重建全部页面。
|
||||||
|
- 用固定坐标、固定字体像素或手动 DPI 倍增代替 Qt 布局系统。
|
||||||
|
- 用全局 QSS 抹掉原生焦点、禁用、选择、高对比度和非活动窗口状态。
|
||||||
|
- 手工编辑 `pyside6-uic`/`pyuic6` 生成文件。
|
||||||
|
- 无版本检查地复制 Qt C++、旧 PySide2、PyQt5 或另一个绑定的示例。
|
||||||
|
- 为获得 Mica/Acrylic 无条件启用无边框窗口或私有 Windows API。
|
||||||
|
|
||||||
|
## 11. 交付检查清单
|
||||||
|
|
||||||
|
- [ ] 已确认绑定、精确版本、Qt Widgets/QML 路线和许可证。
|
||||||
|
- [ ] 未混用 PySide/PyQt 或绑定特有 API。
|
||||||
|
- [ ] 标准控件、Model/View、`QAction` 和布局系统得到优先使用。
|
||||||
|
- [ ] GUI 对象只在主线程访问，后台结果通过队列信号返回。
|
||||||
|
- [ ] 主题跟随系统，QSS 未破坏高对比度、焦点或禁用状态。
|
||||||
|
- [ ] 窗口在调整大小、贴靠、跨显示器和 100%–200% 缩放时可用。
|
||||||
|
- [ ] 键盘、上下文菜单、拖拽替代方式和无障碍语义完整。
|
||||||
|
- [ ] 加载、空、错误、取消、超时、过期结果和撤销状态已处理。
|
||||||
|
- [ ] Designer 生成代码、资源和设置具有可重复的生成/迁移流程。
|
||||||
|
- [ ] 已在干净 Windows 环境测试最终打包产物。
|
||||||
|
|
||||||
|
## 12. 官方资料
|
||||||
|
|
||||||
|
- [Qt for Python / PySide6](https://doc.qt.io/qtforpython-6/)
|
||||||
|
- [PyQt 与许可](https://riverbankcomputing.com/software/pyqt)
|
||||||
|
- [PySide 信号与槽](https://doc.qt.io/qtforpython-6/tutorials/basictutorial/signals_and_slots.html)
|
||||||
|
- [Qt 线程与 QObject](https://doc.qt.io/qt-6/threads-qobject.html)
|
||||||
|
- [Qt Model/View 编程](https://doc.qt.io/qt-6/model-view-programming.html)
|
||||||
|
- [Qt Widgets 布局管理](https://doc.qt.io/qt-6/layout.html)
|
||||||
|
- [Qt 高 DPI](https://doc.qt.io/qt-6/highdpi.html)
|
||||||
|
- [QStyleHints 与系统配色](https://doc.qt.io/qt-6/qstylehints.html)
|
||||||
|
- [Qt 样式表参考](https://doc.qt.io/qt-6/stylesheet-reference.html)
|
||||||
|
- [Qt 无障碍](https://doc.qt.io/qt-6/accessible.html)
|
||||||
|
- [QWidget 应用无障碍](https://doc.qt.io/qt-6/accessible-qwidget.html)
|
||||||
|
- [PySide6 部署](https://doc.qt.io/qtforpython-6/deployment/index.html)
|
||||||
|
- [pyside6-deploy](https://doc.qt.io/qtforpython-6/deployment/deployment-pyside6-deploy.html)
|
||||||
|
- [pyside6-uic](https://doc.qt.io/qtforpython-6/tools/pyside-uic.html)
|
||||||
@@ -0,0 +1,210 @@
|
|||||||
|
# WinUI 3 / Windows App SDK 适配指南
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
1. 选择方法
|
||||||
|
2. 导航与窗口外壳
|
||||||
|
3. 集合与结构化数据
|
||||||
|
4. 输入控件与表单
|
||||||
|
5. 命令与菜单
|
||||||
|
6. 反馈与临时界面
|
||||||
|
7. 常见页面模式
|
||||||
|
8. XAML 工程与版本门槛
|
||||||
|
9. 多 Tab 数据工作台映射
|
||||||
|
10. 发布验证与评审
|
||||||
|
11. 官方资料
|
||||||
|
|
||||||
|
## 1. 选择方法
|
||||||
|
|
||||||
|
根据语义和内置行为选择控件：
|
||||||
|
|
||||||
|
1. 确定用户是在导航、选择、调用、编辑、比较还是检查。
|
||||||
|
2. 优先选择已经实现预期键盘、焦点、选择、自动化和主题行为的控件。
|
||||||
|
3. 根据准确的 Windows App SDK 或 Toolkit 版本检查可用性。
|
||||||
|
4. 先自定义样式，再考虑模板；仅当交互模型不正确时才替换控件。
|
||||||
|
5. 记录第三方控件的无障碍、本地化、性能、维护和许可成本。
|
||||||
|
|
||||||
|
不要仅凭截图选择控件。两个控件可能外观相似，却向键盘和辅助技术公开不同的语义。
|
||||||
|
|
||||||
|
## 2. 导航与窗口外壳
|
||||||
|
|
||||||
|
| 意图 | 使用 | 避免 |
|
||||||
|
|---|---|---|
|
||||||
|
| 应用顶级目标位置 | `NavigationView` | 缺少 Windows 导航行为的自定义侧栏 |
|
||||||
|
| 少量静态同级视图 | `SelectorBar` 或适合内容的简单选择器 | 用文档式标签页表示无关目标位置 |
|
||||||
|
| 打开的文档或可关闭工作区 | `TabView` | 让 `NavigationView` 项目伪装成文档 |
|
||||||
|
| 分层位置路径 | `BreadcrumbBar` | 拼接文本和分隔符 |
|
||||||
|
| 分层数据 | `TreeView` | 递归嵌套 `ListView` 控件 |
|
||||||
|
| 列表与选中项 | 列表/详情模式 | 强制在模态窗口中显示所有详情 |
|
||||||
|
|
||||||
|
保持顶级导航浅、稳定且带标签。根据内容宽度、本地化、增长空间、窗口宽度和命令密度选择顶部或左侧 `NavigationView`，不要使用统一的项目数量规则。除非体验需要明确的自定义状态，否则让 `PaneDisplayMode="Auto"` 和控件阈值处理常见自适应行为。
|
||||||
|
|
||||||
|
仅当页面导航和后退堆栈符合体验时使用 `Frame`。后退导航时保留选择、筛选、滚动和未保存状态。没有可返回位置时不要显示后退按钮。
|
||||||
|
|
||||||
|
对于 Windows App SDK 1.7 或更高版本，优先使用 WinUI `TitleBar` 控件自定义标题栏，并与 `NavigationView` 协调。对于更早版本，使用受支持的 `Window.ExtendsContentIntoTitleBar` 和 `Window.SetTitleBar` 方案。保留标题按钮、拖动区域、系统菜单访问、活动/非活动外观和调整大小行为。
|
||||||
|
|
||||||
|
仅为真正并行或可分离的工作使用附加窗口，不要用它替代信息层级。定义所有者、激活、位置、关闭行为和状态同步。
|
||||||
|
|
||||||
|
## 3. 集合与结构化数据
|
||||||
|
|
||||||
|
| 需求 | 首选方案 | 说明 |
|
||||||
|
|---|---|---|
|
||||||
|
| 以文本为主的可选择集合 | `ListView` | 具有成熟的选择、分组、重排和虚拟化行为 |
|
||||||
|
| 统一的视觉磁贴 | `GridView` | 使用支持虚拟化的项目面板 |
|
||||||
|
| 灵活的列表/网格/自定义布局 | `ItemsView` | 支持布局切换并内置选择和无障碍的现代组合方式 |
|
||||||
|
| 底层自定义虚拟化布局 | `ItemsRepeater` | 选择、调用、焦点和自动化可能需要额外工程工作 |
|
||||||
|
| 层级 | `TreeView` | 支持单选和多选 |
|
||||||
|
| 简单只读行列 | 模板化 `ListView`/`ItemsView` | 提供表头和无障碍关系 |
|
||||||
|
| 完整的电子表格式编辑 | 经验证且持续维护的表格组件 | 验证键盘、UI Automation、虚拟化、排序、调整大小和编辑 |
|
||||||
|
|
||||||
|
不要用“20 行”等固定阈值决定使用 `ListView` 还是数据表格。应根据列关系、比较、排序、编辑、选择、虚拟化和键盘导航来选择。
|
||||||
|
|
||||||
|
Windows Community Toolkit `DataGrid` 文档已归档；它不是当前 WCT 8+ 的 WinUI 3 控件。对于新项目，评估当前仍在维护的方案，例如 Toolkit Labs `DataTable` 或社区 `WinUI.TableView`，并明确验证其成熟度和要求。不得静默引入依赖。
|
||||||
|
|
||||||
|
为大型或无上限集合保持虚拟化。未经测量，不要用通用面板替换虚拟化面板。提供加载、空、筛选后为空、部分数据、过期数据和加载失败状态。
|
||||||
|
|
||||||
|
选择行为应支持 Windows 约定：单击/点击选择单项，Ctrl 独立选择，Shift 范围选择，控件支持时用 Space 选择焦点项，并让可见选择状态与键盘焦点相互独立。
|
||||||
|
|
||||||
|
## 4. 输入控件与表单
|
||||||
|
|
||||||
|
| 意图 | 使用 | 重要区别 |
|
||||||
|
|---|---|---|
|
||||||
|
| 短文本或多行纯文本 | `TextBox` | 多行使用 `AcceptsReturn` 和合适的换行方式 |
|
||||||
|
| 富格式编辑 | `RichEditBox` | 不要用于普通多行文本 |
|
||||||
|
| 数值 | `NumberBox` | 仍需验证范围和领域约束 |
|
||||||
|
| 日期 | `DatePicker` 或 `CalendarDatePicker` | 在常驻选择器和紧凑日历输入间选择 |
|
||||||
|
| 时间 | `TimePicker` | 尊重区域格式 |
|
||||||
|
| 立即生效的开/关设置 | `ToggleSwitch` | 清楚标记状态 |
|
||||||
|
| 表单或批量列表中的选择 | `CheckBox` | 支持选中、未选中和可选的不确定语义 |
|
||||||
|
| 从少量可见选项中单选 | 分组的 `RadioButton` 控件 | 当空间或选项数量降低扫描效率时使用 `ComboBox` |
|
||||||
|
| 从紧凑列表中单选 | `ComboBox` | 不支持多选 |
|
||||||
|
| 多选 | `ListView`、`ItemsView`、复选列表或专用浮出控件 | 让用户能够复查已选值 |
|
||||||
|
| 有界连续值 | `Slider` | 显示当前值，并在需要时允许精确键盘输入 |
|
||||||
|
| 评分 | `RatingControl` | 仅用于真实的评分语义 |
|
||||||
|
|
||||||
|
将标签放在窄宽度、文本缩放和本地化后仍能保持清晰扫描顺序的位置。需要把独立标签关联到字段时，使用 `AutomationProperties.LabeledBy`。用文字而不是仅用颜色标记必填字段。输入前提供约束，在失焦或提交等合适边界验证，并同时说明问题和恢复方式。
|
||||||
|
|
||||||
|
不要在不说明未满足要求的情况下禁用主要操作。验证或网络失败时保留用户输入。对于长表单，定义草稿、取消、关闭和未保存更改行为。
|
||||||
|
|
||||||
|
## 5. 命令与菜单
|
||||||
|
|
||||||
|
使用 `StandardUICommand`、`XamlUICommand` 或项目的 `ICommand` 模式，只建模一次命令，再通过合适的界面公开。
|
||||||
|
|
||||||
|
| 界面 | 使用方式 |
|
||||||
|
|---|---|
|
||||||
|
| 主要页面命令 | 可见的 `Button` 或 `CommandBar` 命令 |
|
||||||
|
| 以文档为中心的应用菜单 | `MenuBar` |
|
||||||
|
| 对象特定命令 | `ContextFlyout`；富命令有帮助时优先 `CommandBarFlyout` |
|
||||||
|
| 额外或低频命令 | 次要 `CommandBar` 命令或溢出菜单 |
|
||||||
|
| 拆分默认/备选操作 | `SplitButton` |
|
||||||
|
| 仅菜单操作集 | `DropDownButton` 或 `MenuFlyout` |
|
||||||
|
| 高级用户路径 | `KeyboardAccelerator` 加工具提示/菜单快捷键文本 |
|
||||||
|
|
||||||
|
让关键命令无需悬停或手势即可发现。在上下文菜单中包含相关上下文命令，使指针、键盘、触控和辅助技术用户都有通用路径。使用访问键实现高效的 Alt 导航，使用快捷键执行重复操作。
|
||||||
|
|
||||||
|
使用“删除 3 个文件”等具体操作标签，不要只写“确定”。让破坏性命令在空间上分离并显示后果。操作常见且可恢复时提供撤销。
|
||||||
|
|
||||||
|
## 6. 反馈与临时界面
|
||||||
|
|
||||||
|
| 需求 | 使用 | 指南 |
|
||||||
|
|---|---|---|
|
||||||
|
| 内联状态、警告或可恢复错误 | `InfoBar` | 需要操作时保持可见；不要假设会自动消失 |
|
||||||
|
| 锚定到 UI 的首次使用教学 | `TeachingTip` | 谨慎展示，不要用于常规状态 |
|
||||||
|
| 阻塞式决策或不可逆后果 | `ContentDialog` | 仅当应用无法安全选择或无法提供撤销时询问 |
|
||||||
|
| 上下文选项或详情 | `Flyout` | 可解除，并与来源建立连接 |
|
||||||
|
| 确定性工作 | `ProgressBar` | 报告有意义的进度 |
|
||||||
|
| 不确定的短时等待 | `ProgressRing` | 保持周围上下文稳定 |
|
||||||
|
| 长时间/后台工作 | 页面内进度加取消/后台处理入口 | 不要让用户困在旋转指示器中 |
|
||||||
|
|
||||||
|
对于频繁的破坏性操作，优先立即完成并提供撤销，而不是反复确认。对于真正具有破坏性的对话框，让标题直接说明决策，并使用明确的按钮动词。
|
||||||
|
|
||||||
|
每个异步界面都需要成功、失败、超时、重试或替代路径；取消有意义时还需要取消策略。避免白屏和布局跳动；保留之前的内容或使用形状匹配的占位内容。
|
||||||
|
|
||||||
|
## 7. 常见页面模式
|
||||||
|
|
||||||
|
### 应用外壳
|
||||||
|
|
||||||
|
使用标题栏、顶级导航、页面标题、上下文命令和内容 Frame 或 Presenter。让标题栏拖动区域与交互式导航和搜索控件分离。
|
||||||
|
|
||||||
|
### 设置
|
||||||
|
|
||||||
|
仅在验证已安装 Toolkit 软件包后使用 Windows Community Toolkit `SettingsCard` 和 `SettingsExpander`。按用户意图分组，为不明显的后果添加说明，并让可恢复偏好立即生效。仅当更改代价高、延迟生效、涉及安全或无法安全恢复时使用“应用”、重启或确认。
|
||||||
|
|
||||||
|
### 列表/详情
|
||||||
|
|
||||||
|
在宽窗口中同时显示列表和详情。在紧凑窗口中于两者间导航，同时保留列表选择、滚动、筛选和键盘焦点。定义选中项被删除、被筛选掉或加载失败时的行为。
|
||||||
|
|
||||||
|
### 表单或编辑器
|
||||||
|
|
||||||
|
使用可预测的扫描路径，将相关控件分组，保持操作对齐一致，并为验证预留空间。明确保存状态：已保存、正在保存、未保存、冲突、离线或失败。为文档式工作提供撤销/重做。
|
||||||
|
|
||||||
|
### 空状态与错误状态
|
||||||
|
|
||||||
|
说明发生了什么、已知时说明原因，以及用户下一步能做什么。区分空状态：首次使用为空、筛选后为空、权限被拒绝、断开连接和加载失败是不同问题。
|
||||||
|
|
||||||
|
## 8. XAML 工程与版本门槛
|
||||||
|
|
||||||
|
生成 XAML 或 C# 前，读取项目文件、中央软件包属性、目标框架、Windows App SDK 与 Toolkit 版本、最低 Windows 版本及打包模型。WinUI 3 使用 `Microsoft.UI.Xaml`；`Windows.UI.Xaml`、WinUI 2 Gallery 和 UWP 示例只能作为迁移参考，不能直接复制。
|
||||||
|
|
||||||
|
版本敏感能力必须注明最低版本与回退策略。例如，WinUI `TitleBar` 控件需要 Windows App SDK 1.7 或更高版本，`SystemBackdropElement` 需要 1.6.3 或更高版本，Mica 在 Windows 10 上必须回退为可读的纯色主题表面。任何第三方控件还要记录版本、许可证、维护状态、主题、高对比度、UI Automation、键盘、虚拟化和退出方案。
|
||||||
|
|
||||||
|
- 遵循项目既有 MVVM 或代码隐藏约定，不为一个页面引入第二套架构。
|
||||||
|
- 用可复用命令统一按钮、菜单、上下文菜单和快捷键；异步命令需防重复提交。
|
||||||
|
- 在资源字典中集中管理语义颜色、文本、间距、圆角、图标与动效；运行时主题值使用 `ThemeResource`。
|
||||||
|
- 优先使用样式与组合。替换完整控件模板意味着同时承担视觉状态、输入、焦点和无障碍责任。
|
||||||
|
- 使用 `Grid` 与弹性尺寸构造响应式布局；避免深层嵌套和无法承受本地化、文本缩放的固定尺寸。
|
||||||
|
- 保持集合虚拟化，不在 UI 线程执行同步文件、网络、数据库或昂贵序列化工作。
|
||||||
|
- 长任务支持取消；导航、查询变化或窗口关闭后忽略过期结果，只把必要的最终状态更新封送回 UI 线程。
|
||||||
|
|
||||||
|
标题栏必须保留系统标题按钮、系统菜单和有效拖动区域，并验证最大化、还原、调整大小、Snap Layouts、活动/非活动、高对比度及右键系统菜单。多窗口必须明确所有者、激活、持久化位置、共享数据生命周期和对话框的 `XamlRoot`。
|
||||||
|
|
||||||
|
## 9. 多 Tab 数据工作台映射
|
||||||
|
|
||||||
|
对“顶部前置操作—中部表格—底部完成任务”的页面，使用统一页面骨架：
|
||||||
|
|
||||||
|
```text
|
||||||
|
Grid Rows="Auto,Auto,*,Auto,Auto"
|
||||||
|
页面标题/说明
|
||||||
|
CommandBar：导入、配置、刷新、筛选
|
||||||
|
状态区：InfoBar、来源摘要、校验结果
|
||||||
|
数据区：虚拟化列表/表格、加载/空/错误覆盖层
|
||||||
|
底部操作区：选择摘要、次要操作、主要生成/更新/提交
|
||||||
|
```
|
||||||
|
|
||||||
|
静态功能切换使用 `SelectorBar` 或适合内容的选择器；可关闭、可重排、具有独立工作状态的文档工作区使用 `TabView`。每个标签以稳定 ID 保存数据来源、筛选、排序、选择、勾选、滚动、验证、任务和未保存状态，不能以可见标题作为身份。
|
||||||
|
|
||||||
|
文件选择使用与项目打包模型和 Windows App SDK 版本相符的文件选择器，并在编码前验证窗口初始化要求。进行中状态优先在页面内显示；可恢复错误用 `InfoBar`；只有不可安全自动决定、不可逆或代价高的操作才使用 `ContentDialog`。普通成功以内联状态、状态栏或非阻塞通知反馈，避免统一弹出成功对话框。
|
||||||
|
|
||||||
|
## 10. 发布验证与评审
|
||||||
|
|
||||||
|
- [ ] 每个控件都匹配用户意图并公开正确语义。
|
||||||
|
- [ ] 所有 API 和依赖项都存在于项目使用的版本中。
|
||||||
|
- [ ] 已定义导航、选择、焦点和后退行为。
|
||||||
|
- [ ] 上下文命令具有无需悬停的访问路径。
|
||||||
|
- [ ] 集合虚拟化和键盘行为得到保留。
|
||||||
|
- [ ] 表单保留输入并提供可操作的验证信息。
|
||||||
|
- [ ] 对话框仅用于真正需要阻塞的决策。
|
||||||
|
- [ ] 已处理加载、空、错误、超时、取消和撤销状态。
|
||||||
|
- [ ] 主题资源可运行时更新，并覆盖浅色、深色和高对比度。
|
||||||
|
- [ ] 标题按钮、拖动区域、窗口所有权和对话框 `XamlRoot` 正确。
|
||||||
|
- [ ] 生产规模数据下的虚拟化、回收、取消和过期结果处理有效。
|
||||||
|
|
||||||
|
至少验证最低支持 Windows 与当前 Windows 11、紧凑/中等/宽窗口、贴靠和最大化、100%/125%/150%/200% 缩放、默认与增大文本、浅色/深色/高对比度、透明效果开关、键盘/鼠标及声明支持的触控、Narrator、真实与超大数据、空/错误/权限拒绝，以及辅助窗口关闭和恢复。自动测试不能替代焦点、播报、动效、文案和感知响应速度的人工评审。
|
||||||
|
|
||||||
|
按以下优先级报告问题：阻断（主要任务、数据、安全或无障碍不可用）、严重（频繁错误或主要性能/响应式问题）、中等（效率和平台一致性下降）、轻微（低影响视觉润色）。每项必须指出触发条件、用户影响和最小稳健修正。
|
||||||
|
|
||||||
|
## 11. 官方资料
|
||||||
|
|
||||||
|
- [Windows 应用控件](https://learn.microsoft.com/windows/apps/develop/ui/controls/)
|
||||||
|
- [NavigationView](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview)
|
||||||
|
- [TabView](https://learn.microsoft.com/windows/apps/develop/ui/controls/tab-view)
|
||||||
|
- [ItemsView](https://learn.microsoft.com/windows/apps/develop/ui/controls/itemsview)
|
||||||
|
- [命令系统](https://learn.microsoft.com/windows/apps/develop/ui/controls/commanding)
|
||||||
|
- [对话框与浮出控件](https://learn.microsoft.com/windows/apps/design/controls/dialogs-and-flyouts/)
|
||||||
|
- [应用设置指南](https://learn.microsoft.com/windows/apps/design/app-settings/guidelines-for-app-settings)
|
||||||
|
- [已归档 WCT DataGrid 状态](https://learn.microsoft.com/dotnet/communitytoolkit/archive/windows/datagrid)
|
||||||
|
- [WinUI 3 概述](https://learn.microsoft.com/windows/apps/winui/winui3/)
|
||||||
|
- [标题栏自定义](https://learn.microsoft.com/windows/apps/develop/title-bar?tabs=winui3)
|
||||||
|
- [使用 XAML 的响应式布局](https://learn.microsoft.com/windows/apps/develop/ui/layouts-with-xaml)
|
||||||
|
- [Windows 应用中的材质](https://learn.microsoft.com/windows/apps/develop/ui/materials)
|
||||||
|
- [无障碍检查清单](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)
|
||||||
@@ -1,163 +0,0 @@
|
|||||||
# WinUI controls and desktop patterns
|
|
||||||
|
|
||||||
## Contents
|
|
||||||
|
|
||||||
1. Selection method
|
|
||||||
2. Navigation and window shell
|
|
||||||
3. Collections and structured data
|
|
||||||
4. Input controls and forms
|
|
||||||
5. Commands and menus
|
|
||||||
6. Feedback and transient surfaces
|
|
||||||
7. Common page patterns
|
|
||||||
8. Control review checklist
|
|
||||||
9. Official sources
|
|
||||||
|
|
||||||
## 1. Selection method
|
|
||||||
|
|
||||||
Choose controls by semantics and built-in behavior:
|
|
||||||
|
|
||||||
1. Identify whether the user is navigating, selecting, invoking, editing, comparing, or inspecting.
|
|
||||||
2. Prefer the control that already implements the expected keyboard, focus, selection, automation, and theme behavior.
|
|
||||||
3. Check availability against the exact Windows App SDK or Toolkit version.
|
|
||||||
4. Customize styles before templates; replace the control only if its interaction model is wrong.
|
|
||||||
5. Record accessibility, localization, performance, maintenance, and licensing costs for third-party controls.
|
|
||||||
|
|
||||||
Do not choose a control from a screenshot alone. Two controls can look similar while exposing different semantics to keyboard and assistive technology.
|
|
||||||
|
|
||||||
## 2. Navigation and window shell
|
|
||||||
|
|
||||||
| Intent | Use | Avoid |
|
|
||||||
|---|---|---|
|
|
||||||
| Top-level app destinations | `NavigationView` | custom sidebar without Windows navigation behavior |
|
|
||||||
| Small set of static peer views | `SelectorBar` or a simple selector appropriate to content | document-style tabs for unrelated destinations |
|
|
||||||
| Open documents or closeable workspaces | `TabView` | `NavigationView` items masquerading as documents |
|
|
||||||
| Hierarchical location path | `BreadcrumbBar` | concatenated text and separators |
|
|
||||||
| Hierarchical data | `TreeView` | recursively nested `ListView` controls |
|
|
||||||
| List and selected item | list/details pattern | forcing every detail into a modal |
|
|
||||||
|
|
||||||
Keep top-level navigation shallow, stable, and labeled. Select top or left `NavigationView` by content breadth, localization, growth, window width, and command density—not a universal item-count rule. Let `PaneDisplayMode="Auto"` and control thresholds handle common adaptive behavior unless the experience requires deliberate states.
|
|
||||||
|
|
||||||
Use `Frame` only when page navigation and a back stack match the experience. Preserve selection, filter, scroll, and unsaved state when navigating back. Do not show a back button if there is nowhere meaningful to go.
|
|
||||||
|
|
||||||
For Windows App SDK 1.7 or later, prefer the WinUI `TitleBar` control for a customized title bar and coordinate it with `NavigationView`. On earlier versions, use the supported `Window.ExtendsContentIntoTitleBar` and `Window.SetTitleBar` path. Preserve caption buttons, drag regions, system menu access, active/inactive appearance, and resize behavior.
|
|
||||||
|
|
||||||
Use additional windows for genuinely parallel or detachable work, not as a replacement for information hierarchy. Define owner, activation, placement, close behavior, and state synchronization.
|
|
||||||
|
|
||||||
## 3. Collections and structured data
|
|
||||||
|
|
||||||
| Need | Preferred option | Notes |
|
|
||||||
|---|---|---|
|
|
||||||
| Text-heavy selectable collection | `ListView` | mature selection, grouping, reorder, and virtualization behavior |
|
|
||||||
| Uniform visual tiles | `GridView` | use a virtualizing items panel |
|
|
||||||
| Flexible list/grid/custom layouts | `ItemsView` | modern composition with layout switching and built-in selection/accessibility |
|
|
||||||
| Low-level custom virtualized layout | `ItemsRepeater` | selection, invocation, focus, and automation may need extra engineering |
|
|
||||||
| Hierarchy | `TreeView` | supports single and multiple selection |
|
|
||||||
| Simple read-only rows and columns | templated `ListView`/`ItemsView` | provide headers and accessible relationships |
|
|
||||||
| Full spreadsheet-like editing | verified maintained table component | validate keyboard, UI Automation, virtualization, sorting, resize, and editing |
|
|
||||||
|
|
||||||
Do not decide `ListView` versus a data table from a fixed threshold such as 20 rows. Base the choice on column relationships, comparison, sorting, editing, selection, virtualization, and keyboard navigation.
|
|
||||||
|
|
||||||
The Windows Community Toolkit `DataGrid` documentation is archived; it is not a current WCT 8+ WinUI 3 control. For new work, evaluate currently maintained options such as Toolkit Labs `DataTable` or the community `WinUI.TableView`, and explicitly verify their maturity and requirements. Do not silently introduce one.
|
|
||||||
|
|
||||||
Keep virtualization enabled for large or unbounded collections. Never replace a virtualizing panel with a generic panel without measuring the result. Provide loading, empty, filtered-empty, partial-data, stale, and load-failure states.
|
|
||||||
|
|
||||||
For selection, support Windows conventions: click/tap for a single item, Ctrl for independent selection, Shift for ranges, Space for focused selection where the control supports it, and visible selection independent from keyboard focus.
|
|
||||||
|
|
||||||
## 4. Input controls and forms
|
|
||||||
|
|
||||||
| Intent | Use | Important distinction |
|
|
||||||
|---|---|---|
|
|
||||||
| Short or multiline plain text | `TextBox` | use `AcceptsReturn` and suitable wrapping for multiline |
|
|
||||||
| Rich formatted editing | `RichEditBox` | do not use for plain multiline text |
|
|
||||||
| Numeric value | `NumberBox` | still validate range and domain constraints |
|
|
||||||
| Date | `DatePicker` or `CalendarDatePicker` | choose persistent picker versus compact calendar entry |
|
|
||||||
| Time | `TimePicker` | respect locale formatting |
|
|
||||||
| Immediate on/off setting | `ToggleSwitch` | label the state clearly |
|
|
||||||
| Selection in a form or batch list | `CheckBox` | supports checked, unchecked, and optional indeterminate semantics |
|
|
||||||
| One visible option from a small set | grouped `RadioButton` controls | use `ComboBox` when space or option count makes scanning worse |
|
|
||||||
| One option from a compact list | `ComboBox` | it does not support multiple selection |
|
|
||||||
| Multiple options | `ListView`, `ItemsView`, checked list, or purpose-built flyout | keep selected values reviewable |
|
|
||||||
| Bounded continuous value | `Slider` | show current value and allow precise keyboard entry when needed |
|
|
||||||
| Rating | `RatingControl` | use only for genuine rating semantics |
|
|
||||||
|
|
||||||
Place labels where scan order remains clear under narrow widths, text scaling, and localization. Use `AutomationProperties.LabeledBy` when a separate label must be associated with a field. Mark required fields in text, not color alone. Provide constraints before entry, validate at a useful boundary such as blur or submit, and state both the problem and recovery.
|
|
||||||
|
|
||||||
Do not disable the primary action without explaining unmet requirements. Preserve user input on validation or network failure. For long forms, define draft, cancel, close, and unsaved-change behavior.
|
|
||||||
|
|
||||||
## 5. Commands and menus
|
|
||||||
|
|
||||||
Model a command once and expose it through suitable surfaces using `StandardUICommand`, `XamlUICommand`, or the project's `ICommand` pattern.
|
|
||||||
|
|
||||||
| Surface | Use |
|
|
||||||
|---|---|
|
|
||||||
| Primary page command | visible `Button` or `CommandBar` command |
|
|
||||||
| Document-centric application menus | `MenuBar` |
|
|
||||||
| Object-specific commands | `ContextFlyout`, preferably `CommandBarFlyout` when rich commands help |
|
|
||||||
| Extra or low-frequency commands | secondary `CommandBar` commands or overflow menu |
|
|
||||||
| Split default/alternate action | `SplitButton` |
|
|
||||||
| Menu-only action set | `DropDownButton` or `MenuFlyout` |
|
|
||||||
| Power-user path | `KeyboardAccelerator` plus tooltip/menu shortcut text |
|
|
||||||
|
|
||||||
Keep critical commands discoverable without hover or gestures. Include relevant contextual commands in a context menu so pointer, keyboard, touch, and assistive technology users have a common route. Use access keys for efficient Alt navigation and accelerators for repeated actions.
|
|
||||||
|
|
||||||
Use specific action labels such as “Delete 3 files” rather than “OK”. Keep destructive commands spatially separated and show consequence. Offer undo when the action is common and reversible.
|
|
||||||
|
|
||||||
## 6. Feedback and transient surfaces
|
|
||||||
|
|
||||||
| Need | Use | Guidance |
|
|
||||||
|---|---|---|
|
|
||||||
| Inline status, warning, or recoverable error | `InfoBar` | keep visible while action is required; do not assume automatic dismissal |
|
|
||||||
| First-use education anchored to UI | `TeachingTip` | show sparingly and never for routine status |
|
|
||||||
| Blocking decision or irreversible consequence | `ContentDialog` | ask only when the app cannot safely choose or offer undo |
|
|
||||||
| Contextual options or detail | `Flyout` | dismissible and connected to its source |
|
|
||||||
| Determinate work | `ProgressBar` | report meaningful progress |
|
|
||||||
| Indeterminate short wait | `ProgressRing` | keep surrounding context stable |
|
|
||||||
| Long/background work | in-page progress plus cancel/background affordance | do not trap users in a spinner |
|
|
||||||
|
|
||||||
For frequent destructive actions, prefer immediate completion plus undo over repeated confirmation. For truly destructive dialogs, make the title state the decision and use explicit button verbs.
|
|
||||||
|
|
||||||
Every async surface needs a success, failure, timeout, retry or alternate path, and cancellation strategy when cancellation is meaningful. Avoid white screens and layout jumps; retain the previous content or use a shape-matched placeholder.
|
|
||||||
|
|
||||||
## 7. Common page patterns
|
|
||||||
|
|
||||||
### Application shell
|
|
||||||
|
|
||||||
Use title bar, top-level navigation, page header, contextual commands, and a content frame or presenter. Keep title-bar drag regions separate from interactive navigation and search controls.
|
|
||||||
|
|
||||||
### Settings
|
|
||||||
|
|
||||||
Use Windows Community Toolkit `SettingsCard` and `SettingsExpander` only after verifying the installed Toolkit package. Group by user intent, add descriptions for non-obvious consequences, and make reversible preferences apply immediately. Use Apply, restart, or confirmation only when a change is expensive, delayed, security-sensitive, or not safely reversible.
|
|
||||||
|
|
||||||
### List/details
|
|
||||||
|
|
||||||
At wide widths, show list and details together. At compact widths, navigate between them while preserving list selection, scroll, filter, and keyboard focus. Define what happens when the selected item is deleted, filtered out, or fails to load.
|
|
||||||
|
|
||||||
### Form or editor
|
|
||||||
|
|
||||||
Use a predictable scan path, keep related controls together, align actions consistently, and reserve space for validation. Make save state explicit: saved, saving, unsaved, conflict, offline, or failed. Provide undo/redo for document-like work.
|
|
||||||
|
|
||||||
### Empty and error states
|
|
||||||
|
|
||||||
State what happened, why when known, and what the user can do next. Tailor empty states: first-use empty, filtered empty, permission denied, disconnected, and failed loading are different problems.
|
|
||||||
|
|
||||||
## 8. Control review checklist
|
|
||||||
|
|
||||||
- [ ] Each control matches the user's intent and exposes correct semantics.
|
|
||||||
- [ ] All APIs and dependencies exist in the project's versions.
|
|
||||||
- [ ] Navigation, selection, focus, and back behavior are defined.
|
|
||||||
- [ ] Contextual commands have a non-hover route.
|
|
||||||
- [ ] Collection virtualization and keyboard behavior are preserved.
|
|
||||||
- [ ] Forms retain input and provide actionable validation.
|
|
||||||
- [ ] Dialogs are limited to genuinely blocking decisions.
|
|
||||||
- [ ] Loading, empty, error, timeout, cancellation, and undo states are handled.
|
|
||||||
|
|
||||||
## 9. Official sources
|
|
||||||
|
|
||||||
- [Controls for Windows apps](https://learn.microsoft.com/windows/apps/develop/ui/controls/)
|
|
||||||
- [NavigationView](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview)
|
|
||||||
- [TabView](https://learn.microsoft.com/windows/apps/develop/ui/controls/tab-view)
|
|
||||||
- [ItemsView](https://learn.microsoft.com/windows/apps/develop/ui/controls/itemsview)
|
|
||||||
- [Commanding](https://learn.microsoft.com/windows/apps/develop/ui/controls/commanding)
|
|
||||||
- [Dialogs and flyouts](https://learn.microsoft.com/windows/apps/design/controls/dialogs-and-flyouts/)
|
|
||||||
- [App settings guidelines](https://learn.microsoft.com/windows/apps/design/app-settings/guidelines-for-app-settings)
|
|
||||||
- [Archived WCT DataGrid status](https://learn.microsoft.com/dotnet/communitytoolkit/archive/windows/datagrid)
|
|
||||||
@@ -0,0 +1,198 @@
|
|||||||
|
# 桌面数据表格交互规范
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
1. 适用范围与交互契约
|
||||||
|
2. 状态模型
|
||||||
|
3. 指针事件与优先级
|
||||||
|
4. 筛选、排序与搜索
|
||||||
|
5. 勾选、多选与批量操作
|
||||||
|
6. 键盘与无障碍
|
||||||
|
7. 数据变化、分页与虚拟化
|
||||||
|
8. 视觉与反馈
|
||||||
|
9. 测试矩阵
|
||||||
|
10. 交付检查清单
|
||||||
|
|
||||||
|
## 1. 适用范围与交互契约
|
||||||
|
|
||||||
|
为展示结构化多列数据且支持选择、筛选、操作或编辑的表格、网格和高密度列表使用本规范。只读报表也要定义排序、复制、焦点和空状态；可编辑数据网格还要定义验证、提交和撤销。
|
||||||
|
|
||||||
|
在设计或编码前写出交互契约，至少回答：
|
||||||
|
|
||||||
|
- 选择单位是整行、单元格还是列；支持单选、连续多选还是非连续多选；
|
||||||
|
- 复选框代表“批量选择”还是一个真实业务字段；
|
||||||
|
- 单击行只选择，还是还会导航、展开或编辑；
|
||||||
|
- 双击行执行默认命令、进入编辑，还是禁用；
|
||||||
|
- 右键未选中行与已选中行时，命令作用于哪一组对象；
|
||||||
|
- 筛选作用于本地数据、当前页、已加载数据还是服务端完整结果；
|
||||||
|
- 排序、筛选、刷新、分页后是否保留选择和勾选；
|
||||||
|
- 主键、权限和数据变化如何使已有选择失效；
|
||||||
|
- 每个鼠标操作对应什么键盘和无障碍操作。
|
||||||
|
|
||||||
|
若产品未指定，采用本规范的推荐默认值。不要把框架初始属性当作已经确认的产品行为。
|
||||||
|
|
||||||
|
## 2. 状态模型
|
||||||
|
|
||||||
|
### 分离四类状态
|
||||||
|
|
||||||
|
| 状态 | 含义 | 推荐规则 |
|
||||||
|
|---|---|---|
|
||||||
|
| 当前行/当前单元格 | 后续键盘命令的目标和导航位置 | 同一表格通常只有一个；刷新后尽量保持稳定主键 |
|
||||||
|
| 键盘焦点 | 当前接收键盘输入的元素 | 必须始终可见；可能在单元格内按钮或编辑器上 |
|
||||||
|
| 选择集 | 详情、上下文命令或批量操作的对象 | 使用稳定记录 ID，不使用视图行号 |
|
||||||
|
| 勾选集 | 选择复选框或业务布尔字段的值 | 先确定语义；不得默认等同选择集 |
|
||||||
|
|
||||||
|
### 选择复选框与业务复选框
|
||||||
|
|
||||||
|
- **选择复选框：** 复选框只是多选的可见入口，勾选集与选择集是同一状态；表头复选框控制明确范围内的选择。
|
||||||
|
- **业务复选框：** 复选框表示“启用”“已审核”等领域字段，与行选择完全独立；列标题必须表达业务含义，不使用无标签的选择列样式。
|
||||||
|
- 同一表格同时需要两者时使用不同列、不同标题/工具提示和不同视觉反馈，并在规格中分别命名。
|
||||||
|
- 不要让整行单击切换业务复选框。不要维护两个看似相同但可能不同步的选择数组。
|
||||||
|
|
||||||
|
### 状态不变量
|
||||||
|
|
||||||
|
- 排序和筛选改变视图顺序，不改变记录 ID。
|
||||||
|
- 当前行可以未被多选；选中行也不一定拥有单元格焦点。
|
||||||
|
- 失效、无权限或被删除的记录必须从操作集合移除并告知用户。
|
||||||
|
- 行号只用于展示位置，不能作为选择、缓存、编辑或命令参数。
|
||||||
|
- 视觉上区分 hover、当前、焦点、选中、勾选、编辑、错误和禁用状态。
|
||||||
|
|
||||||
|
## 3. 指针事件与优先级
|
||||||
|
|
||||||
|
### 推荐交互矩阵
|
||||||
|
|
||||||
|
| 输入 | 目标 | 推荐结果 |
|
||||||
|
|---|---|---|
|
||||||
|
| 左键单击 | 行的非交互区域 | 将该行设为当前行；无修饰键时单选，Ctrl 切换，Shift 从锚点范围选择 |
|
||||||
|
| 左键单击 | 选择复选框 | 切换该行选择状态；更新当前行，但不触发行默认操作 |
|
||||||
|
| 左键单击 | 业务复选框 | 仅切换/提交该字段；不触发行默认操作，选择是否变化须显式规定 |
|
||||||
|
| 左键单击 | 按钮、链接、菜单或编辑器 | 仅执行该控件行为；事件不得冒泡成行操作 |
|
||||||
|
| 左键双击 | 行的非交互区域 | 执行唯一的非破坏性默认命令，或按契约进入编辑 |
|
||||||
|
| 右键/长按 | 未选中行 | 将其设为当前且唯一选中行，再打开针对该行的上下文菜单 |
|
||||||
|
| 右键/长按 | 已选中行 | 保留现有多选，打开针对整个选择集的菜单 |
|
||||||
|
| 右键 | 空白区域/表头 | 不借用旧行上下文；显示表格级/列级菜单或不显示菜单 |
|
||||||
|
|
||||||
|
### 事件优先级
|
||||||
|
|
||||||
|
按“单元格内控件 → 编辑器 → 行 → 表格空白区域”处理命中目标，内层处理后阻止外层重复执行。不得使用任意延时猜测单击还是双击。
|
||||||
|
|
||||||
|
单击行只负责当前项和选择，不执行打开、删除、提交等业务副作用。这样双击产生的两次单击不会重复执行业务命令。双击仅在同一有效记录的非交互区域触发；滚动条、复选框、按钮、链接、输入框和空白区不得触发。
|
||||||
|
|
||||||
|
双击默认命令必须满足：
|
||||||
|
|
||||||
|
- 非破坏性，通常是打开详情、预览或开始编辑；
|
||||||
|
- 同时提供 Enter、显式按钮或菜单入口；
|
||||||
|
- 与内联编辑的双击触发二选一，不同时绑定；
|
||||||
|
- 数据变化后按稳定 ID 再次确认目标仍存在且允许操作。
|
||||||
|
|
||||||
|
上下文菜单打开前先解析命中行和有效选择集。命令文案、启用状态和作用对象数量必须一致；菜单关闭不清除选择。提供 Shift+F10、菜单键或可见命令入口。
|
||||||
|
|
||||||
|
## 4. 筛选、排序与搜索
|
||||||
|
|
||||||
|
### 筛选模型
|
||||||
|
|
||||||
|
- 明确全局搜索、列筛选、固定范围筛选和高级条件之间是 AND 还是 OR。
|
||||||
|
- 按字段类型提供合适运算：文本包含/等于，数字和日期范围，枚举多选，布尔三态，空值/非空。
|
||||||
|
- 显示每个活动筛选、结果数量和“清除全部”；仅靠输入框内容或列标题颜色不足以表达状态。
|
||||||
|
- 区分“无数据”与“筛选后无结果”，后者保留条件并提供清除入口。
|
||||||
|
- 定义大小写、重音、全半角、区域设置、时区、空白和无效输入规则。
|
||||||
|
- 本地筛选保持界面即时；服务端筛选使用防抖、取消或请求 ID，忽略过期响应并显示加载/错误状态。
|
||||||
|
- 筛选条件变化通常返回第一页或合适的首个结果，同时避免让焦点跳回页面顶部。
|
||||||
|
|
||||||
|
### 排序
|
||||||
|
|
||||||
|
- 表头明确未排序、升序和降序；向无障碍 API 暴露排序状态。
|
||||||
|
- 多列排序必须显示优先级；不支持时只保留一个排序键。
|
||||||
|
- 使用稳定排序，定义空值位置和区域感知比较。
|
||||||
|
- 排序后按记录 ID 保持当前项、选择和未提交编辑，不按旧行号恢复。
|
||||||
|
|
||||||
|
### 筛选与选择的关系
|
||||||
|
|
||||||
|
默认保留被筛选隐藏的已选记录，并在批量工具栏显示“已选 N 项，其中 M 项当前不可见”，同时提供仅清除隐藏选择或清除全部。若业务要求筛选即清除选择，必须在操作发生前明确提示并保持一致。
|
||||||
|
|
||||||
|
表头全选必须标明范围：当前可见页、当前已加载结果，或所有符合筛选的结果。跨服务端完整结果选择时使用“筛选条件 + 排除 ID”或后端选择令牌等模型，不要假装客户端已持有所有 ID。
|
||||||
|
|
||||||
|
## 5. 勾选、多选与批量操作
|
||||||
|
|
||||||
|
- 选择复选框列固定在行首，表头使用三态：无、部分、全部；状态以已声明的全选范围计算。
|
||||||
|
- 点击表头全选前后都应让范围可理解，例如“选择本页 50 项”或“已选择全部 2,418 个匹配项”。
|
||||||
|
- Ctrl 支持独立增减选择，Shift 使用上次选择锚点扩展范围；筛选、排序后锚点无效时安全重置。
|
||||||
|
- 批量工具栏显示选择数量，只提供所有选中记录共同允许的命令。
|
||||||
|
- 对危险批量操作显示准确对象数和影响；可恢复操作优先支持撤销。
|
||||||
|
- 处理部分成功：列出成功、失败、跳过和权限不足的数量，允许重试失败项。
|
||||||
|
- 选择数很大时不要为每个 ID 创建 Widget 或重复复制完整对象；存储 ID/选择表达式。
|
||||||
|
- 禁用行仍可按需求查看，但不可勾选或执行命令；说明禁用原因。
|
||||||
|
|
||||||
|
## 6. 键盘与无障碍
|
||||||
|
|
||||||
|
### 键盘基线
|
||||||
|
|
||||||
|
| 按键 | 推荐行为 |
|
||||||
|
|---|---|
|
||||||
|
| 上/下方向键 | 移动当前行；是否同时改变选择取决于选定的选择模式 |
|
||||||
|
| 左/右方向键 | 单元格导航，或在行模式下滚动/进入单元格控件 |
|
||||||
|
| Ctrl+Space | 切换当前行的多选状态 |
|
||||||
|
| Shift+方向键/单击 | 从选择锚点扩展连续范围 |
|
||||||
|
| Ctrl+A | 选择明确定义的当前范围；大规模/服务端数据需二次表达全量范围 |
|
||||||
|
| Space | 当前焦点为复选框时切换它；不得同时触发行默认操作 |
|
||||||
|
| Enter | 执行与双击相同的默认命令，或提交当前编辑 |
|
||||||
|
| F2 | 进入可编辑单元格；与双击编辑契约保持一致 |
|
||||||
|
| Escape | 取消菜单/编辑；再次按键是否清除选择须明确规定 |
|
||||||
|
| Shift+F10/菜单键 | 为当前行或选择集打开上下文菜单 |
|
||||||
|
|
||||||
|
### 无障碍
|
||||||
|
|
||||||
|
- 为表格提供可感知名称、列标题、行/列关系、排序状态、选择状态、复选状态和总数/可见数。
|
||||||
|
- 焦点与选择使用不同视觉信号，不只依赖颜色。
|
||||||
|
- 复选框、按钮和链接使用其真实控件语义与名称；不要让整个数据行伪装成多个按钮。
|
||||||
|
- HTML 静态数据优先使用原生 `<table>`。只有实现完整二维键盘导航时才使用交互式 `grid` 语义，并采用 roving tabindex 或 `aria-activedescendant`。
|
||||||
|
- 表格发生筛选、批量完成或错误时，以不过度打扰的方式播报结果数量和状态变化。
|
||||||
|
- 高对比度、200% 缩放和长文本下仍能辨认当前行、选中、勾选、编辑和错误状态。
|
||||||
|
|
||||||
|
## 7. 数据变化、分页与虚拟化
|
||||||
|
|
||||||
|
- 所有交互状态关联稳定记录 ID；代理模型、排序、筛选和虚拟化层必须能映射回源记录。
|
||||||
|
- 刷新时保留仍存在且仍有权限的当前项与选择；不存在的项从集合移除并反馈。
|
||||||
|
- 编辑期间收到远程更新时定义覆盖、合并、冲突或刷新策略，不得静默丢失输入。
|
||||||
|
- 分页、增量加载和虚拟滚动不得导致复选状态闪烁、重复触发命令或焦点落到另一条记录。
|
||||||
|
- 服务端操作携带筛选、排序、页游标和请求 ID；只应用最新有效响应。
|
||||||
|
- 行命令启动后防止重复提交，显示行级或批量进度，并支持合理取消。
|
||||||
|
- 大型表格保持虚拟化；不要在每个单元格嵌入常驻复杂控件。
|
||||||
|
|
||||||
|
## 8. 视觉与反馈
|
||||||
|
|
||||||
|
- 表头固定或滚动时保持列对应关系；列宽、截断、换行和水平滚动策略必须明确。
|
||||||
|
- 当前行、选择、勾选与焦点各有可区分状态，但避免叠加过多高饱和背景。
|
||||||
|
- 可排序列显示方向；可筛选列显示入口和活动状态；不要只在 hover 时显示关键筛选信息。
|
||||||
|
- 批量操作栏出现时不遮挡表头、分页或最后几行，并保持选择数量可见。
|
||||||
|
- 行内错误靠近相关单元格，同时提供行级摘要；不要仅用红色边框。
|
||||||
|
- 加载骨架不得伪装成可选行；刷新时避免清空整个表格造成焦点和滚动跳动。
|
||||||
|
- 空状态区分首次无数据、筛选无结果、权限不足、加载失败和离线缓存。
|
||||||
|
|
||||||
|
## 9. 测试矩阵
|
||||||
|
|
||||||
|
至少验证：
|
||||||
|
|
||||||
|
1. 单选、多选、Ctrl、Shift、表头全选和三态复选框；
|
||||||
|
2. 单击、双击、右键、长按以及单元格内复选框/按钮/链接/编辑器；
|
||||||
|
3. 右键未选中行、已选中行、空白区和表头；
|
||||||
|
4. Enter、F2、Space、Ctrl+Space、Ctrl+A、Shift+F10、Escape 和方向键；
|
||||||
|
5. 筛选后无结果、多个条件、清除全部、服务端延迟、失败和过期响应；
|
||||||
|
6. 排序、筛选、刷新、分页和虚拟滚动后的当前项、选择、勾选及焦点；
|
||||||
|
7. 删除选中项、权限变化、部分成功、重复提交和窗口提前关闭；
|
||||||
|
8. 0、1、少量、大量和超大数据，长文本、空值、重复显示值和稳定 ID；
|
||||||
|
9. 浅色、深色、高对比度、100%–200% 缩放、键盘和屏幕阅读器；
|
||||||
|
10. 原型与最终桌面实现使用同一交互契约的对照验收。
|
||||||
|
|
||||||
|
## 10. 交付检查清单
|
||||||
|
|
||||||
|
- [ ] 已定义行/单元格选择模式及当前项、焦点、选择集、勾选集的关系。
|
||||||
|
- [ ] 已明确复选框是选择入口还是业务字段。
|
||||||
|
- [ ] 单击、双击、右键和单元格内控件不会重复触发行默认命令。
|
||||||
|
- [ ] 右键目标、多选保留和键盘上下文菜单行为明确。
|
||||||
|
- [ ] 筛选运算、服务端/本地范围、空值、结果数和清除入口完整。
|
||||||
|
- [ ] 表头全选范围、隐藏选择、三态和大规模全选模型明确。
|
||||||
|
- [ ] 排序、筛选、刷新、分页和虚拟化均使用稳定 ID 保持状态。
|
||||||
|
- [ ] 鼠标功能具有键盘、触控和无障碍等价路径。
|
||||||
|
- [ ] 原型与最终桌面实现已按测试矩阵验证，而非只检查静态视觉。
|
||||||
|
- [ ] 组件/API 已按项目准确版本验证。
|
||||||
@@ -0,0 +1,285 @@
|
|||||||
|
# 桌面多 Tab 数据工作台布局与命令分区规范
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
1. 适用范围与设计目标
|
||||||
|
2. 先验证 Tab 模型
|
||||||
|
3. 统一页面骨架
|
||||||
|
4. 命令分类与放置
|
||||||
|
5. 跨 Tab 一致性
|
||||||
|
6. 文件导入与前置条件
|
||||||
|
7. 表格主工作区
|
||||||
|
8. 底部完成任务区
|
||||||
|
9. 执行前确认策略
|
||||||
|
10. 执行中与完成反馈
|
||||||
|
11. 状态与生命周期
|
||||||
|
12. 响应式、键盘与无障碍
|
||||||
|
13. 测试矩阵与交付检查清单
|
||||||
|
|
||||||
|
## 1. 适用范围与设计目标
|
||||||
|
|
||||||
|
当 Windows 桌面应用包含多个标签页，并且多个标签页共享“准备数据或导入文件 → 检查/筛选表格 → 生成、更新或提交结果”的任务结构时，使用本规范统一页面布局、命令语义和反馈位置。
|
||||||
|
|
||||||
|
统一的目标是让用户学会一个标签页后能够预测其他标签页，而不是让所有页面机械地拥有相同控件。保持以下心智模型稳定：
|
||||||
|
|
||||||
|
> 准备数据 → 检查数据 → 完成任务 → 获得结果与恢复入口
|
||||||
|
|
||||||
|
设计前记录每个标签页的任务、数据源、前置条件、表格对象、主命令、影响范围和恢复方式。没有表格或没有完成阶段的标签页可以省略对应区域，不得为了视觉对齐保留无意义的空按钮或禁用占位。
|
||||||
|
|
||||||
|
本规范只负责页面级组合。标签身份、关闭和状态恢复遵循 `core-navigation-tabs.md`；表格选择、筛选和行事件遵循 `core-data-table.md`；确认、进度和完成反馈遵循 `core-dialogs-tasks.md`；字段与文件选择遵循 `core-form-input.md`。
|
||||||
|
|
||||||
|
## 2. 先验证 Tab 模型
|
||||||
|
|
||||||
|
- 少量、固定、同一工作对象的同级任务可以使用静态标签。
|
||||||
|
- 可创建、关闭、重排且具有独立脏状态的文档使用文档标签。
|
||||||
|
- 彼此无关的业务模块优先使用顶级导航，不要仅因页面外观相似就放进同一标签条。
|
||||||
|
- 标签过多且用户需要搜索目的地时，改用导航、溢出列表或分组，不把标签压缩到无法识别。
|
||||||
|
- 标签文本使用稳定名词或任务名；不要在不同运行阶段反复改变标签名称来表达状态。
|
||||||
|
|
||||||
|
在编码前确定标签是静态任务还是文档实例，并为每个标签使用稳定 ID。不要用显示索引绑定数据源、保存目标或任务状态。
|
||||||
|
|
||||||
|
## 3. 统一页面骨架
|
||||||
|
|
||||||
|
默认使用以下垂直区域。`Auto` 区域按内容占用空间，表格区使用剩余空间；反馈区和完成区不得覆盖表头、分页或最后一行。
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌──────────────── 标签栏 ────────────────┐
|
||||||
|
│ 页面标题 / 数据源摘要 / 页面状态 │ 可选，Auto
|
||||||
|
├─────────────────────────────────────────┤
|
||||||
|
│ 导入文件 前置参数 校验 刷新 更多命令 │ 数据准备区，Auto
|
||||||
|
├─────────────────────────────────────────┤
|
||||||
|
│ 搜索 筛选 结果数 清除条件 视图命令 │ 表格命令区，Auto
|
||||||
|
├─────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ 数据表格 │ 主工作区，*
|
||||||
|
│ │
|
||||||
|
├─────────────────────────────────────────┤
|
||||||
|
│ 已选 N 项 / 进度 / 错误 / 最后更新时间 │ 状态反馈区，按需 Auto
|
||||||
|
├─────────────────────────────────────────┤
|
||||||
|
│ 取消 更新数据 生成 │ 完成任务区，按需 Auto
|
||||||
|
└─────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 布局规则
|
||||||
|
|
||||||
|
- 各标签页复用同一页面外壳组件、内容边距、区域间距、命令高度、主按钮位置和反馈位置。
|
||||||
|
- 页面标题仅在标签名不足以说明当前对象或范围时出现；不要无意义重复标签文本。
|
||||||
|
- 数据准备区与表格命令区可在内容简单时合并，但命令顺序仍按“来源/前置 → 查看/筛选”排列。
|
||||||
|
- 表格是主要工作区时必须获得剩余高度，不用固定高度让窗口下方产生大片空白。
|
||||||
|
- 状态反馈区采用稳定插入位置。出现错误、进度或选择工具栏时避免让表格和底部按钮剧烈跳动。
|
||||||
|
- 完成任务区仅在页面存在明确提交阶段时显示；只读、浏览或仅刷新页面可以省略。
|
||||||
|
|
||||||
|
## 4. 命令分类与放置
|
||||||
|
|
||||||
|
先为命令确定作用域，再决定位置。相同命令跨菜单、工具栏、上下文菜单和快捷键复用同一命令状态，不复制业务逻辑。
|
||||||
|
|
||||||
|
| 命令类型 | 典型命令 | 首选位置 |
|
||||||
|
|---|---|---|
|
||||||
|
| 应用/窗口级 | 新建窗口、全局设置、帮助 | 应用外壳、菜单或全局工具栏 |
|
||||||
|
| 数据来源 | 选择文件、导入、重新导入、连接数据源 | 页面上方的数据准备区 |
|
||||||
|
| 前置配置 | 输出目录、模板、规则、日期范围 | 数据准备区；复杂时使用侧面板或任务页 |
|
||||||
|
| 表格视图 | 搜索、筛选、排序、列设置、刷新列表 | 紧邻表格上方 |
|
||||||
|
| 行对象 | 打开详情、预览、编辑单行 | 行内可见入口、上下文菜单或表格命令区 |
|
||||||
|
| 选择集/批量 | 删除所选、批量修改、导出所选 | 选择后出现的批量工具栏，显示对象数量 |
|
||||||
|
| 工作流完成 | 生成、应用全部更新、提交、发布 | 页面底部完成任务区 |
|
||||||
|
| 低频辅助 | 查看日志、导入历史、高级设置 | 更多/溢出菜单或辅助面板 |
|
||||||
|
|
||||||
|
### 命令语义
|
||||||
|
|
||||||
|
- 使用具体动词和对象，如“刷新列表”“更新 28 条记录”“生成报告”，不要让“更新”同时表示重新加载和写入数据。
|
||||||
|
- 每个局部任务区域最多使用一个视觉主按钮。底部完成区通常只突出当前工作流的最终安全操作。
|
||||||
|
- 相同位置保持相同语义；不要让一个标签页底部的“更新”保存数据，另一个标签页同位置的“更新”仅刷新视图。
|
||||||
|
- 破坏性命令与常规主操作分开，不把“永久删除”紧邻“生成”且使用相同样式。
|
||||||
|
- 高频命令保持可见；右键、悬停、拖放和手势只能作为加速路径。
|
||||||
|
- 不适用的命令直接省略。因权限、缺少前置条件或任务运行而禁用时，提供可发现的原因。
|
||||||
|
|
||||||
|
为每个命令定义以下契约：
|
||||||
|
|
||||||
|
```text
|
||||||
|
command_id
|
||||||
|
label_and_object
|
||||||
|
scope: app | page | table | selection | row
|
||||||
|
target_ids_or_query
|
||||||
|
prerequisites
|
||||||
|
placement
|
||||||
|
enabled_reason / disabled_reason
|
||||||
|
reversible
|
||||||
|
confirmation_policy
|
||||||
|
task_mode: immediate | foreground | background
|
||||||
|
completion_feedback
|
||||||
|
shortcut_or_access_key
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. 跨 Tab 一致性
|
||||||
|
|
||||||
|
统一以下内容：
|
||||||
|
|
||||||
|
- 页面区域顺序、外边距、间距 Token、控件高度、图标语言和按钮层级；
|
||||||
|
- 同类命令的名称、图标、相对顺序、快捷键、启用条件和进度表达；
|
||||||
|
- 表格的表头、选择、焦点、勾选、筛选活动态、空状态和错误状态；
|
||||||
|
- 主操作靠右或项目既定位置，状态与对象数量位于稳定的次要区域；
|
||||||
|
- 加载、取消、成功、失败和部分成功的反馈层级；
|
||||||
|
- 标签切换后的状态保留和焦点恢复。
|
||||||
|
|
||||||
|
允许以下差异：
|
||||||
|
|
||||||
|
- 不同任务需要的前置字段、表格列和次要命令；
|
||||||
|
- 由风险、可逆性和影响范围决定的确认策略；
|
||||||
|
- 由数据量和任务时长决定的分页、虚拟化和进度形式。
|
||||||
|
|
||||||
|
不要用固定按钮宽度强行容纳所有本地化文本。使用最小尺寸、内容自适应和一致的内边距；只在同一命令组确有比较价值时对齐宽度。
|
||||||
|
|
||||||
|
## 6. 文件导入与前置条件
|
||||||
|
|
||||||
|
### 导入状态
|
||||||
|
|
||||||
|
至少区分 `empty`、`selecting`、`validating`、`ready`、`importing`、`imported`、`invalid`、`failed`、`cancelled` 和适用时的 `stale/conflict`。
|
||||||
|
|
||||||
|
- 使用平台文件/文件夹选择器；显示最终文件名或路径，以及有助于判断的格式、大小、修改时间或记录数。
|
||||||
|
- 用户取消选择器是正常取消，不显示错误。
|
||||||
|
- 明确“选择文件”只是选择，还是选择后立即导入。高成本或可能覆盖当前数据时不要隐式开始。
|
||||||
|
- “追加导入”“替换当前数据”和“重新导入”使用不同文案，并在执行前说明对筛选、选择、编辑和未提交结果的影响。
|
||||||
|
- 文件校验在数据准备区附近显示；错误指出文件、原因和修复办法，不用模态框逐条报告。
|
||||||
|
- 拖放可以加速导入，但必须保留可见的选择/导入按钮和键盘路径。
|
||||||
|
- 同一标签页再次选择文件时，只有会丢失不可恢复工作才确认；可安全撤销或未产生修改时直接替换并反馈。
|
||||||
|
- 导入、解析和校验不得阻塞 GUI 线程。任务运行时防止重复导入，并定义取消后保留或清理哪些结果。
|
||||||
|
|
||||||
|
完成任务按钮的可用性由明确前置条件决定，例如：文件有效、必填参数完整、表格无阻断错误、当前选择范围有效且无冲突。禁用按钮附近显示尚缺条件，不仅依靠灰色状态。
|
||||||
|
|
||||||
|
## 7. 表格主工作区
|
||||||
|
|
||||||
|
- 搜索、筛选、结果数量和清除入口紧邻表格，不能散落到页面底部。
|
||||||
|
- 刷新列表属于视图/数据获取命令；写入业务数据的命令命名为“保存更改”“应用更新”等，避免混淆。
|
||||||
|
- 当前行、键盘焦点、选择集和勾选集保持独立；批量工具栏显示准确选择数量和隐藏选择数量。
|
||||||
|
- 行级命令作用于命中行；批量命令作用于已声明选择集；页面完成命令作用于整个已声明数据范围。执行前再次解析稳定 ID 或筛选表达式。
|
||||||
|
- 空、筛选无结果、加载、离线、权限不足、失败和部分数据状态使用不同内容与恢复入口。
|
||||||
|
- 切换标签后返回时，按产品价值保留筛选、排序、分页、滚动、当前行、选择和未提交编辑，不默认重置整个表格。
|
||||||
|
|
||||||
|
## 8. 底部完成任务区
|
||||||
|
|
||||||
|
底部区域用于结束当前页面工作流的命令，不是所有按钮的收纳区。
|
||||||
|
|
||||||
|
### 可以放在底部
|
||||||
|
|
||||||
|
- 生成最终文件、报告或构建产物；
|
||||||
|
- 将已检查的数据应用到业务系统；
|
||||||
|
- 提交、发布或完成当前步骤；
|
||||||
|
- 与上述主操作直接相关的取消、返回、保存草稿或预览。
|
||||||
|
|
||||||
|
### 不应放在底部
|
||||||
|
|
||||||
|
- 选择/导入文件、刷新列表、清除筛选和列设置；
|
||||||
|
- 只作用于单行的打开、编辑和删除；
|
||||||
|
- 只作用于当前选择集的高频批量命令；
|
||||||
|
- 与当前任务无关的设置、帮助和日志入口。
|
||||||
|
|
||||||
|
### 布局与状态
|
||||||
|
|
||||||
|
- 保持主操作位置稳定，通常位于完成区末端；次操作在其前，危险操作分组或移入明确菜单。
|
||||||
|
- 左侧可显示数据范围、脏状态、阻断原因、进度或最后完成时间，但不要重复上方已有信息。
|
||||||
|
- 固定/粘性完成区只能固定在标签页内容边界内，不遮挡表格滚动条、分页或最后一行。
|
||||||
|
- 窗口变窄时先让次要命令进入溢出或分行，再保证主操作和取消入口可见。
|
||||||
|
- 任务开始后禁用重复提交；主按钮可以显示当前阶段，但宽度变化不能造成明显位移。
|
||||||
|
- 切换标签、关闭标签或窗口时，明确任务继续后台、取消还是阻止离开，并与未保存协议一致。
|
||||||
|
|
||||||
|
## 9. 执行前确认策略
|
||||||
|
|
||||||
|
不得为所有完成命令统一弹出确认框。频繁、无风险的确认会形成自动点击习惯，降低真正高风险确认的价值。
|
||||||
|
|
||||||
|
| 策略 | 使用条件 | 示例 |
|
||||||
|
|---|---|---|
|
||||||
|
| `none` | 可逆、幂等、影响清晰或只是生成预览 | 刷新、重新计算、生成不覆盖的新文件 |
|
||||||
|
| `destructive` | 永久删除、覆盖、丢弃不可恢复数据 | 覆盖已有文件、永久删除记录 |
|
||||||
|
| `high_impact` | 大批量、外部副作用、成本高或影响难以预见 | 更新数千条记录、发送到外部系统 |
|
||||||
|
| `always_required` | 法规、安全、支付、发布或业务明确要求人工决策 | 支付、正式发布、提交审批 |
|
||||||
|
|
||||||
|
确认框必须显示动作、对象/范围、数量、不可逆后果和必要条件，按钮使用具体动词。例如使用“取消 / 更新 428 条”，不用“否 / 是”或“取消 / 确定”。不可逆操作默认聚焦安全选项。
|
||||||
|
|
||||||
|
可恢复的频繁操作优先直接执行并提供撤销。能在页面内提供预览、差异或范围摘要时，先让用户自然审阅，不再叠加无信息量的确认框。
|
||||||
|
|
||||||
|
## 10. 执行中与完成反馈
|
||||||
|
|
||||||
|
### 执行中
|
||||||
|
|
||||||
|
- 立即提供按下/忙碌反馈，防止双击生成重复任务。
|
||||||
|
- 已知总量时显示可信进度和当前阶段；未知时使用不确定进度并说明正在做什么。
|
||||||
|
- 只有任务支持安全取消时显示取消。点击后进入“正在取消”，不要立即谎称已取消。
|
||||||
|
- 可后台运行的长任务放入稳定任务区；切换标签不应丢失任务所有权或状态。
|
||||||
|
|
||||||
|
### 完成后
|
||||||
|
|
||||||
|
| 完成情况 | 推荐反馈 |
|
||||||
|
|---|---|
|
||||||
|
| 页面结果已明显变化 | 不额外弹窗；更新表格、状态或时间 |
|
||||||
|
| 保存、复制、导出等结果不明显 | 非模态状态/提示，并提供位置或下一步 |
|
||||||
|
| 生成文件 | “已生成 N 个文件 · 打开文件夹/打开结果” |
|
||||||
|
| 可撤销操作 | 持久到足以操作的撤销反馈 |
|
||||||
|
| 页面级失败或需要恢复 | 持久信息条，提供重试或修复入口 |
|
||||||
|
| 部分成功 | 显示成功、失败、跳过数量和“查看/重试失败项” |
|
||||||
|
| 用户必须立即决策才能继续 | 结果对话框或任务页 |
|
||||||
|
|
||||||
|
不要为普通成功统一弹出模态框。成功对话框会打断连续工作，也会迫使用户执行没有业务价值的“确定”。临时提示不得承载唯一的撤销、错误详情或结果入口。
|
||||||
|
|
||||||
|
## 11. 状态与生命周期
|
||||||
|
|
||||||
|
每个标签页至少按稳定标签/文档 ID 保存：
|
||||||
|
|
||||||
|
```text
|
||||||
|
data_source
|
||||||
|
prerequisite_values_and_validation
|
||||||
|
filter_sort_page
|
||||||
|
current_row_id
|
||||||
|
selected_ids_or_selection_expression
|
||||||
|
scroll_and_focus_target
|
||||||
|
dirty_or_conflict_state
|
||||||
|
task_id_and_task_state
|
||||||
|
last_result_and_recovery_action
|
||||||
|
```
|
||||||
|
|
||||||
|
- 业务数据、任务状态和临时视图状态分层，不把所有状态塞进页面控件。
|
||||||
|
- 标签切换不取消任务、不清空筛选、不覆盖未提交数据；确需重置时由显式命令触发。
|
||||||
|
- 异步回调核对任务 ID、标签 ID、数据版本和对象生命周期，过期结果不得写入新标签或新数据源。
|
||||||
|
- 文件路径、凭据和敏感数据仅按产品需要持久化，不写入日志、HTML 原型 URL 或不受保护的设置。
|
||||||
|
- 权限或数据变化导致目标失效时，停止相应命令、移除无效选择并解释影响。
|
||||||
|
|
||||||
|
## 12. 响应式、键盘与无障碍
|
||||||
|
|
||||||
|
- Tab 顺序遵循“标签栏 → 数据准备区 → 表格命令区 → 表格 → 状态/完成区”；复杂工作区支持 `F6` 在主要区域间移动。
|
||||||
|
- 标签条和表格内部使用方向键；Enter/Space 保持平台控件语义。常用导入、查找、保存和刷新命令可使用 `Ctrl+O`、`Ctrl+F`、`Ctrl+S` 和 `F5`，但仅在语义准确时采用。
|
||||||
|
- 仅图标命令提供名称和工具提示；同名按钮在不同标签中增加足够上下文供屏幕阅读器区分。
|
||||||
|
- 进度、错误、选择数量和完成结果通过标准无障碍状态播报，不抢夺用户当前焦点。
|
||||||
|
- 确认框关闭后将焦点返回调用按钮；完成后焦点保留在稳定区域，除非移动焦点能直接帮助修复错误。
|
||||||
|
- 在紧凑宽度下允许命令换行、折叠筛选或进入溢出，但主任务不能变成仅右键或悬停可用。
|
||||||
|
- 在浅色、深色、高对比度、100%–200% 缩放、长本地化文本和 Windows 贴靠宽度下验证；表格始终保留可用高度。
|
||||||
|
|
||||||
|
## 13. 测试矩阵与交付检查清单
|
||||||
|
|
||||||
|
### 测试矩阵
|
||||||
|
|
||||||
|
至少验证：
|
||||||
|
|
||||||
|
1. 学会第一个标签后，用户能否在其他标签找到数据来源、筛选、批量和完成命令；
|
||||||
|
2. 各标签的命令名称、图标、顺序、主次层级和相同位置语义是否一致；
|
||||||
|
3. 无文件、取消选择、格式无效、校验失败、重新导入、追加与替换；
|
||||||
|
4. 无数据、筛选无结果、单选、多选、隐藏选择、刷新和数据冲突；
|
||||||
|
5. 完成命令前置条件缺失、重复点击、快速完成、长任务、取消和迟到响应；
|
||||||
|
6. 无需确认、覆盖文件、批量高影响、不可逆操作及确认取消后的焦点恢复；
|
||||||
|
7. 明显成功、不可见成功、失败、部分成功、撤销和打开结果；
|
||||||
|
8. 任务运行、存在脏状态或显示错误时切换/关闭标签和窗口；
|
||||||
|
9. 紧凑、中等、宽、贴靠、最大化、100%–200% DPI、浅色、深色和高对比度；
|
||||||
|
10. 纯键盘、屏幕阅读器、长文案和原型到最终桌面实现的契约对照。
|
||||||
|
|
||||||
|
### 交付检查清单
|
||||||
|
|
||||||
|
- [ ] 已证明标签模型适合任务，而不是用标签代替顶级导航。
|
||||||
|
- [ ] 所有标签使用同一页面骨架和 Token，按语义省略不适用区域。
|
||||||
|
- [ ] 每个命令的作用域、目标、前置条件、位置、风险、反馈和快捷入口明确。
|
||||||
|
- [ ] 数据来源、表格视图、行、选择集和工作流完成命令没有混区。
|
||||||
|
- [ ] “刷新”“更新”“生成”“提交”等名称准确区分读取与写入副作用。
|
||||||
|
- [ ] 每个任务区域最多一个视觉主操作；危险操作与常规操作分离。
|
||||||
|
- [ ] 导入状态、取消、校验、追加/替换、重新导入和错误恢复完整。
|
||||||
|
- [ ] 底部完成区不遮挡表格，窄窗口下主操作仍可见。
|
||||||
|
- [ ] 确认只用于不可逆、高成本、外部副作用或强制决策，不对普通操作滥用。
|
||||||
|
- [ ] 普通成功不使用模态弹窗；结果不可见、失败和部分成功具有合适反馈与下一步。
|
||||||
|
- [ ] 切换标签保留有价值的筛选、选择、滚动、脏状态和任务状态。
|
||||||
|
- [ ] 原型与最终桌面实现使用同一页面、命令、确认和任务状态契约。
|
||||||
@@ -0,0 +1,212 @@
|
|||||||
|
# 桌面对话框、反馈与长任务交互规范
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
1. 选择反馈层级
|
||||||
|
2. 对话框交互契约
|
||||||
|
3. 焦点、按钮与关闭
|
||||||
|
4. 确认、删除与未保存决策
|
||||||
|
5. 进度、取消与后台任务
|
||||||
|
6. 错误、重试与部分成功
|
||||||
|
7. 通知、信息条与临时反馈
|
||||||
|
8. 异步与生命周期
|
||||||
|
9. 测试矩阵
|
||||||
|
10. 交付检查清单
|
||||||
|
|
||||||
|
## 1. 选择反馈层级
|
||||||
|
|
||||||
|
使用能解决问题的最低干扰层级：
|
||||||
|
|
||||||
|
| 场景 | 优先形式 | 不应使用 |
|
||||||
|
|---|---|---|
|
||||||
|
| 字段格式或局部操作错误 | 字段附近/组件内联反馈 | 应用级模态错误框 |
|
||||||
|
| 页面加载失败、离线、权限或可恢复警告 | 页面内信息条/Banner，带操作 | 自动消失 Toast |
|
||||||
|
| 简短、可忽略、无需立即操作的完成状态 | 非模态临时通知或状态区 | 阻塞对话框 |
|
||||||
|
| 与当前对象相关的附加选择/详情 | Flyout/Popover/非模态面板 | 无原因的全窗口模态 |
|
||||||
|
| 应用无法安全替用户决定 | 窗口级模态对话框 | 隐藏在状态栏的提示 |
|
||||||
|
| 永久破坏贵重资产、安全/支付等高风险决策 | 明确后果的确认对话框 | 含糊“确定/取消” |
|
||||||
|
| 长时间但可继续其他工作的任务 | 页面/任务中心进度，可后台化 | 锁住整个应用的旋转圈 |
|
||||||
|
| 短暂阻塞且必须完成才能继续 | 局部遮罩或模态进度，支持取消时提供取消 | 假装确定进度的百分比 |
|
||||||
|
|
||||||
|
同类、重复或持续状态应占据稳定界面位置，不要每次弹出。对常见可恢复操作优先直接完成并提供撤销，而不是反复确认。
|
||||||
|
|
||||||
|
## 2. 对话框交互契约
|
||||||
|
|
||||||
|
创建对话框前定义：
|
||||||
|
|
||||||
|
- 为什么必须阻塞，以及阻塞当前窗口还是整个应用；
|
||||||
|
- 标题、简短说明、影响对象和所需决策；
|
||||||
|
- 主操作、次操作、取消/关闭、默认按钮与危险按钮；
|
||||||
|
- 初始焦点、Tab 循环、Enter、Escape 和窗口关闭按钮行为；
|
||||||
|
- 验证、提交中、失败、重试和成功后的关闭条件；
|
||||||
|
- 所有者窗口、重复打开防护和对话框生命周期；
|
||||||
|
- 屏幕阅读器名称、描述和状态播报。
|
||||||
|
|
||||||
|
### 内容与动作
|
||||||
|
|
||||||
|
- 标题直接说明决策，如“删除 3 个项目？”或“保存更改后关闭？”。
|
||||||
|
- 正文说明不可见后果和影响范围，不重复标题或堆叠技术错误。
|
||||||
|
- 按钮使用具体动词：“删除”“覆盖”“保存并关闭”，不要让危险操作叫“确定”。
|
||||||
|
- 常用安全操作是视觉主按钮；不可恢复操作与其他按钮分离，并使用一致的危险样式。
|
||||||
|
- 超过三项复杂选择通常应改成任务页面或向导，不把应用页面塞进对话框。
|
||||||
|
- 对话框内只有完成决策所需内容；帮助和详细日志使用可展开区或外部入口。
|
||||||
|
|
||||||
|
## 3. 焦点、按钮与关闭
|
||||||
|
|
||||||
|
### 打开
|
||||||
|
|
||||||
|
- 将焦点移入对话框。短对话框聚焦最安全且最可能的操作；复杂内容先聚焦标题/说明或第一个字段。
|
||||||
|
- 不可逆决策默认聚焦取消或最安全操作，除非平台和业务有充分理由。
|
||||||
|
- 记录调用者；关闭后将焦点返回调用者，调用者消失时返回逻辑后继。
|
||||||
|
- 模态界面必须让背景在视觉和交互上都不可用；不能只添加 `aria-modal` 或半透明遮罩。
|
||||||
|
|
||||||
|
### 操作
|
||||||
|
|
||||||
|
- Tab/Shift+Tab 留在模态对话框内部；非模态面板允许按明确规则离开。
|
||||||
|
- Enter 只触发当前有效的默认按钮；多行输入中默认换行。
|
||||||
|
- Escape 执行取消/关闭，不提交或丢失输入；无法取消时解释原因并提供可见关闭路径。
|
||||||
|
- 右上角关闭、Alt+F4、Escape 和取消按钮使用同一取消协议。
|
||||||
|
- 提交中防重复操作；若可取消，取消请求与关闭 UI 是两个阶段，等待任务确认停止或忽略结果。
|
||||||
|
|
||||||
|
### 关闭
|
||||||
|
|
||||||
|
- 成功、取消、失败和窗口关闭返回可区分结果，调用方不能把所有关闭都当成功。
|
||||||
|
- 验证失败或提交失败时保持对话框打开并保留输入。
|
||||||
|
- 对话框关闭时清理订阅、计时器和任务回调，防止访问已销毁界面。
|
||||||
|
- 避免同时打开多个相同对话框；重复请求应激活已有实例或排队。
|
||||||
|
|
||||||
|
## 4. 确认、删除与未保存决策
|
||||||
|
|
||||||
|
### 何时确认
|
||||||
|
|
||||||
|
仅当操作不可逆、代价高、影响范围难以预见、涉及安全/支付，或应用无法安全提供撤销时确认。频繁删除草稿、移除可恢复项等优先立即执行并提供撤销。
|
||||||
|
|
||||||
|
确认内容必须包含：动作、对象、数量、不可逆后果和必要条件。不要使用双重否定或“是否确定？”作为全部说明。
|
||||||
|
|
||||||
|
### 未保存内容
|
||||||
|
|
||||||
|
- 使用“保存 / 不保存 / 取消”而不是模糊的“是 / 否”。
|
||||||
|
- 多文档退出列出受影响文档，并支持安全的“全部保存”与失败项处理。
|
||||||
|
- 保存失败保持窗口/标签打开，提供重试、另存或恢复内容出口。
|
||||||
|
- 不保存仅放弃明确列出的本地更改，不删除远程数据或其他自动保存版本。
|
||||||
|
- 关闭、后退、切换账户和应用退出共享同一未保存协调器。
|
||||||
|
|
||||||
|
### 覆盖与冲突
|
||||||
|
|
||||||
|
- 文件或数据已变化时显示来源、时间和可理解差异，提供保留本地、重新加载、另存/复制或合并。
|
||||||
|
- 默认操作选择数据损失最小的方案。
|
||||||
|
- 不把版本冲突伪装成普通“保存失败”，也不要静默覆盖。
|
||||||
|
|
||||||
|
## 5. 进度、取消与后台任务
|
||||||
|
|
||||||
|
### 任务状态模型
|
||||||
|
|
||||||
|
至少定义 `queued`、`running`、`pausing/paused`（适用时）、`cancelling`、`cancelled`、`succeeded`、`failed` 和 `partially-succeeded`。完成、失败与取消是终态，不能仅靠进度条是否消失判断。
|
||||||
|
|
||||||
|
### 进度选择
|
||||||
|
|
||||||
|
- 已知总量且进度可信时使用确定进度，显示完成量/总量或百分比及当前阶段。
|
||||||
|
- 总量未知时使用不确定进度，并用具体文本说明正在做什么。
|
||||||
|
- 先不确定、后可计算时允许切换为确定进度，但进度不能倒退或长期停在 99%。
|
||||||
|
- 极短操作避免闪烁；稍长操作先显示局部忙碌状态，达到明显时长后升级为进度界面。
|
||||||
|
- 后台任务显示在稳定任务中心/状态区，可重新找到；通知只作为补充。
|
||||||
|
- 多文件/多阶段任务同时显示总体进度和当前项，不用每行一个永久旋转圈。
|
||||||
|
|
||||||
|
### 取消
|
||||||
|
|
||||||
|
- 只有任务真实支持安全取消时显示取消按钮。
|
||||||
|
- 点击后进入 `cancelling`，禁用重复取消，并说明正在停止；不能立即谎称已取消。
|
||||||
|
- 定义取消点、已完成工作的保留/回滚、临时文件清理和后端请求撤销。
|
||||||
|
- 窗口关闭时明确任务取消、后台继续或转移到任务中心，不能让工作静默中断。
|
||||||
|
- 取消后的迟到结果必须被请求 ID/任务状态拒绝，不能重新把 UI 改成成功。
|
||||||
|
|
||||||
|
### 响应速度
|
||||||
|
|
||||||
|
- 所有 I/O、计算和批处理离开 GUI 线程；通过线程安全消息更新进度。
|
||||||
|
- 节流高频进度更新，避免每个字节/记录都刷新 UI。
|
||||||
|
- 不使用 `processEvents()` 或嵌套事件循环掩盖阻塞。
|
||||||
|
- 任务命令具有幂等/去重策略，双击按钮不能创建重复任务。
|
||||||
|
|
||||||
|
## 6. 错误、重试与部分成功
|
||||||
|
|
||||||
|
错误反馈回答：发生了什么、影响什么、用户能做什么、工作是否保留。
|
||||||
|
|
||||||
|
### 错误分类
|
||||||
|
|
||||||
|
- **用户可修复：** 指向字段、权限申请、文件位置或设置。
|
||||||
|
- **暂时故障：** 提供重试、稍后处理、离线或切换服务。
|
||||||
|
- **冲突：** 提供刷新、比较、合并、另存或放弃本地更改。
|
||||||
|
- **不可恢复：** 保留诊断 ID/日志出口和安全返回路径，不暴露内部堆栈。
|
||||||
|
|
||||||
|
### 重试
|
||||||
|
|
||||||
|
- 重试只重复失败且安全的部分，保留已完成结果。
|
||||||
|
- 不可幂等操作重试前查询实际状态或使用幂等键，避免重复付款、创建或删除。
|
||||||
|
- 连续失败不无限弹窗；提供持久错误区和诊断入口。
|
||||||
|
- 网络恢复自动重试时显示状态并限制退避；用户手动重试仍可用。
|
||||||
|
|
||||||
|
### 部分成功
|
||||||
|
|
||||||
|
- 显示成功、失败、跳过、取消的数量和对象范围。
|
||||||
|
- 允许查看/导出失败详情、重试失败项或撤销成功项（可行时）。
|
||||||
|
- 不用绿色“成功”覆盖失败项，也不因少量失败否认全部已完成工作。
|
||||||
|
- 批量操作结束后刷新受影响数据，同时保持仍有效的选择和上下文。
|
||||||
|
|
||||||
|
## 7. 通知、信息条与临时反馈
|
||||||
|
|
||||||
|
### 信息条/Banner
|
||||||
|
|
||||||
|
- 用于页面级可恢复问题、离线、权限、过期数据和需要操作的警告。
|
||||||
|
- 保持到问题解决、用户关闭或上下文消失；关闭后是否再次出现由状态而非计时器决定。
|
||||||
|
- 包含严重程度、简短文本、主要恢复动作和必要时的详情。
|
||||||
|
- 出现时不抢焦点，但重要状态通过无障碍实时区域/平台事件播报。
|
||||||
|
|
||||||
|
### 临时通知/Toast
|
||||||
|
|
||||||
|
- 仅用于无需立即响应且不会因错过而阻塞任务的信息。
|
||||||
|
- 不承载唯一的撤销入口、关键错误或复杂决策；重要历史可在任务/通知中心找到。
|
||||||
|
- 避免连续堆叠相同通知，合并重复事件并限制频率。
|
||||||
|
- 自动消失前给足阅读时间；键盘和屏幕阅读器用户能访问需要的操作。
|
||||||
|
|
||||||
|
### 成功反馈
|
||||||
|
|
||||||
|
- 页面内变化明显时无需额外“成功”弹窗。
|
||||||
|
- 保存、复制、导出等结果不明显时提供简短状态，并包含位置或下一步。
|
||||||
|
- 撤销反馈说明对象与时限；时限结束后命令状态一致，不留下失效按钮。
|
||||||
|
|
||||||
|
## 8. 异步与生命周期
|
||||||
|
|
||||||
|
- 每个对话框/任务有唯一实例或任务 ID、所有者和取消源。
|
||||||
|
- 异步完成前核对窗口、页面和对象仍存在，且结果仍属于当前请求。
|
||||||
|
- 关闭 UI 不等于工作已停止；分开管理可见状态和任务状态。
|
||||||
|
- 应用挂起、退出、网络断开、凭据过期和权限变化时定义持久化/恢复。
|
||||||
|
- 错误处理不能在后台线程直接操作 GUI；通过队列信号/调度器返回 UI 线程。
|
||||||
|
- 记录必要诊断信息但过滤密码、令牌、个人数据和完整文件内容。
|
||||||
|
- 任务完成通知不抢夺用户当前窗口或焦点；需要时提供“打开结果”。
|
||||||
|
|
||||||
|
## 9. 测试矩阵
|
||||||
|
|
||||||
|
至少验证：
|
||||||
|
|
||||||
|
1. 内联、页面级、临时通知、Flyout 和模态层级选择是否正确；
|
||||||
|
2. Enter、Escape、Alt+F4、关闭按钮、Tab 循环和焦点返回；
|
||||||
|
3. 危险操作、可撤销删除、未保存和版本冲突；
|
||||||
|
4. 确定/不确定进度、快速完成、长时间停顿和多阶段任务；
|
||||||
|
5. 取消请求、取消中关闭、迟到成功、重复提交和应用退出；
|
||||||
|
6. 网络失败、权限、超时、部分成功、重试失败和离线恢复；
|
||||||
|
7. 多窗口所有者、父窗口关闭和重复打开同一对话框；
|
||||||
|
8. 100%–200% 缩放、长文案、高对比度、减少动画、键盘和屏幕阅读器；
|
||||||
|
9. 原型与最终桌面实现的按钮、结果、任务状态和错误恢复对照。
|
||||||
|
|
||||||
|
## 10. 交付检查清单
|
||||||
|
|
||||||
|
- [ ] 已使用最低干扰层级，不把所有反馈都放进对话框。
|
||||||
|
- [ ] 对话框的阻塞范围、所有者、按钮、默认/取消和结果明确。
|
||||||
|
- [ ] 焦点进入、循环、Escape、关闭和返回调用者符合平台行为。
|
||||||
|
- [ ] 危险操作说明对象与后果，可恢复操作优先撤销。
|
||||||
|
- [ ] 任务具有完整状态、可信进度、取消协议和重复提交防护。
|
||||||
|
- [ ] 错误区分可修复、暂时故障、冲突和不可恢复，并保留用户工作。
|
||||||
|
- [ ] 部分成功显示准确数量并支持失败项恢复。
|
||||||
|
- [ ] 后台线程不操作 GUI，关闭后迟到回调安全忽略。
|
||||||
|
- [ ] 键盘、缩放、高对比度和屏幕阅读器已验证。
|
||||||
|
- [ ] 原型与桌面实现使用同一决策和任务状态契约。
|
||||||
@@ -0,0 +1,186 @@
|
|||||||
|
# 桌面表单与输入交互规范
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
1. 表单模式与交互契约
|
||||||
|
2. 字段状态模型
|
||||||
|
3. 控件选择与字段语义
|
||||||
|
4. 验证时机与错误恢复
|
||||||
|
5. 保存、取消与未保存状态
|
||||||
|
6. 键盘、输入法与无障碍
|
||||||
|
7. 异步、依赖字段与敏感数据
|
||||||
|
8. 测试矩阵
|
||||||
|
9. 交付检查清单
|
||||||
|
|
||||||
|
## 1. 表单模式与交互契约
|
||||||
|
|
||||||
|
设计前选择一种主提交模式，不要让同一表单中的字段随机采用不同规则：
|
||||||
|
|
||||||
|
| 模式 | 适用场景 | 提交与失败行为 |
|
||||||
|
|---|---|---|
|
||||||
|
| 即时生效 | 可快速撤销的偏好、显示设置 | 值改变后提交；失败时恢复旧值或显示未应用状态 |
|
||||||
|
| 显式提交 | 创建、编辑、支付、权限等成组数据 | 用户选择“保存/创建/应用”；失败时保留全部输入 |
|
||||||
|
| 分步向导 | 内容多、存在顺序依赖或需分阶段确认 | 每步验证本步；返回不丢值；最终提交前汇总检查 |
|
||||||
|
| 自动保存 | 长文档、草稿和持续编辑 | 显示保存中/已保存/失败/离线；保留本地可恢复副本 |
|
||||||
|
|
||||||
|
在编码前定义：初始值来源、必填与可选、格式和领域约束、验证时机、提交范围、默认按钮、取消语义、脏状态、关闭策略、离线行为、权限和敏感字段处理。
|
||||||
|
|
||||||
|
表单状态至少包括 `pristine`、`dirty`、`validating`、`valid`、`invalid`、`submitting`、`saved`、`save-failed` 和适用时的 `offline/conflict`。不要只维护一个 `isValid` 布尔值。
|
||||||
|
|
||||||
|
## 2. 字段状态模型
|
||||||
|
|
||||||
|
每个字段分别维护：
|
||||||
|
|
||||||
|
- 原始值、编辑值和规范化后的提交值；
|
||||||
|
- 是否访问、是否修改、是否正在组合输入、是否正在异步验证；
|
||||||
|
- 本地格式错误、领域错误、服务端错误和警告；
|
||||||
|
- 是否可编辑、只读、禁用、依赖项不可用或权限不足；
|
||||||
|
- 最近一次有效验证所对应的值或请求 ID。
|
||||||
|
|
||||||
|
### 状态规则
|
||||||
|
|
||||||
|
- `disabled` 表示用户当前不能操作且通常不参与提交；`read-only` 表示值可读取、聚焦和复制但不可修改。不要互换。
|
||||||
|
- 占位符不是标签，也不保存输入格式说明。标签、必填标记、帮助文本和错误信息各有独立位置。
|
||||||
|
- 字段变脏后又恢复到原始规范值时清除脏状态，不能只比较显示字符串。
|
||||||
|
- 外部数据刷新不得静默覆盖脏字段；显示冲突并让用户选择保留、重新加载或合并。
|
||||||
|
- 控件被条件隐藏时明确其值是保留、清空还是不提交；不要留下不可见但生效的旧值。
|
||||||
|
- 错误状态不能永久黏附在已修正值上，也不能因界面刷新而消失。
|
||||||
|
|
||||||
|
## 3. 控件选择与字段语义
|
||||||
|
|
||||||
|
| 数据意图 | 优先控件 | 关键规则 |
|
||||||
|
|---|---|---|
|
||||||
|
| 单行/多行自由文本 | 标准单行/多行文本控件 | 设置长度、换行、粘贴和空白规范 |
|
||||||
|
| 密码或密钥 | 标准密码输入控件 | 默认遮蔽；不记录日志；明确显示/隐藏和复制策略 |
|
||||||
|
| 有界整数/小数 | 标准数字输入控件 | 定义范围、步长、精度、单位、区域格式和空值 |
|
||||||
|
| 二元立即设置 | 开关控件 | 标签表达状态或结果，不使用含糊的“开启” |
|
||||||
|
| 独立布尔选择 | 复选框 | 定义未选、已选和确有语义时的不确定态 |
|
||||||
|
| 少量互斥选项 | 单选按钮组 | 组名清晰；方向键切换；不要默认危险选项 |
|
||||||
|
| 紧凑单选 | 下拉单选控件 | 区分自由输入与仅可选择；不要用作多选 |
|
||||||
|
| 建议但允许自由输入 | 自动建议输入控件 | 区分输入文本、突出建议和已提交值 |
|
||||||
|
| 日期/时间 | 平台日期时间控件 | 使用区域设置；明确时区、范围和是否允许空值 |
|
||||||
|
| 文件/文件夹 | 平台选择器 | 显示最终路径/名称；处理取消、权限和不存在 |
|
||||||
|
|
||||||
|
不要用自由文本复刻已有的日期、数字、枚举或文件选择控件。不要仅因视觉统一而移除平台输入法、撤销、剪贴板和辅助技术支持。
|
||||||
|
|
||||||
|
## 4. 验证时机与错误恢复
|
||||||
|
|
||||||
|
### 分层验证
|
||||||
|
|
||||||
|
1. **输入约束：** 长度、字符集合和明显不可能的值；仅阻止真正无意义的输入。
|
||||||
|
2. **字段验证：** 格式、范围、必填和单字段领域规则。
|
||||||
|
3. **跨字段验证：** 开始/结束日期、密码确认、条件必填和互斥规则。
|
||||||
|
4. **服务端验证：** 唯一性、权限、库存、版本冲突和最终业务规则。
|
||||||
|
|
||||||
|
允许用户处于合理的中间输入状态，例如负号、小数点、未完成日期或输入法组合文本。不得在每次按键后强行格式化、移动光标或弹出错误。
|
||||||
|
|
||||||
|
### 推荐时机
|
||||||
|
|
||||||
|
- 输入前显示格式、单位、范围和示例等约束。
|
||||||
|
- 首次失焦或提交时显示一般字段错误；字段已报错后可在修改时及时更新。
|
||||||
|
- 跨字段规则在相关字段都可判断时验证，并把错误放在最能指导修复的位置。
|
||||||
|
- 服务端验证使用防抖、取消或请求 ID；只应用与当前值匹配的最新结果。
|
||||||
|
- 提交时重新运行所有适用规则；客户端验证不能替代服务端验证。
|
||||||
|
|
||||||
|
### 错误呈现
|
||||||
|
|
||||||
|
- 使用具体文案回答“哪里不对、为什么、怎样修复”，不要只写“输入无效”。
|
||||||
|
- 错误紧邻字段并与字段建立无障碍关系；长表单在提交失败后提供错误摘要。
|
||||||
|
- 聚焦第一个无效字段仅发生在用户提交后；输入过程中不要抢夺焦点。
|
||||||
|
- 不只用颜色表达错误；保留输入、选择范围和滚动位置。
|
||||||
|
- 网络失败与字段值无效是不同状态。网络失败提供重试或离线方案，不要把字段标红。
|
||||||
|
- 警告允许继续时明确后果；错误阻止提交时明确所需修复。
|
||||||
|
|
||||||
|
不要仅通过禁用提交按钮隐藏问题。若按钮禁用，附近要说明缺少什么；提交时仍必须验证，以覆盖键盘、程序调用和竞态。
|
||||||
|
|
||||||
|
## 5. 保存、取消与未保存状态
|
||||||
|
|
||||||
|
### 显式提交
|
||||||
|
|
||||||
|
- 默认按钮使用具体动词，如“创建项目”“保存更改”，而不是泛化的“确定”。
|
||||||
|
- 提交开始后防止重复请求，保留可阅读内容，并显示任务范围内的进度。
|
||||||
|
- 成功后更新原始快照、清除脏状态并给出持久到足以感知的反馈。
|
||||||
|
- 失败后保留输入；将字段错误映射到字段，将全局错误放在表单级反馈区。
|
||||||
|
- 服务端只接受部分字段时明确成功与失败，不要假装整体保存成功。
|
||||||
|
|
||||||
|
### 取消与关闭
|
||||||
|
|
||||||
|
- “取消”撤销本次未提交编辑并返回稳定位置；不应撤销提交前已明确即时生效的其他设置。
|
||||||
|
- 无修改时直接关闭。有未保存修改时优先自动保存草稿或提供“保存 / 不保存 / 取消关闭”。
|
||||||
|
- 不可恢复且代价高的更改才要求确认；频繁、可恢复的小修改优先撤销。
|
||||||
|
- 关闭确认必须基于领域脏状态，而不是仅监听是否发生过按键。
|
||||||
|
- 应用退出、标签关闭、页面导航和窗口关闭使用同一未保存策略。
|
||||||
|
|
||||||
|
### 即时生效与自动保存
|
||||||
|
|
||||||
|
- 乐观更新失败时恢复旧值或把字段标为未同步；不得显示已应用但实际未保存。
|
||||||
|
- 连续变化使用合并、防抖或串行队列，保证旧响应不能覆盖新值。
|
||||||
|
- 自动保存显示最近保存状态；离线时保留本地草稿并说明同步状态。
|
||||||
|
- 取消自动保存任务时不得删除最后一个已确认版本。
|
||||||
|
|
||||||
|
## 6. 键盘、输入法与无障碍
|
||||||
|
|
||||||
|
- Tab/Shift+Tab 按视觉和任务顺序移动；复合控件内部使用平台标准方向键。
|
||||||
|
- Enter 在单行字段中执行明确的默认提交，在多行编辑器中默认换行；需要 Ctrl+Enter 提交时显示提示。
|
||||||
|
- Escape 关闭建议、日期弹层或临时模式；不得无提示清空整份表单。
|
||||||
|
- 使用访问键和标准快捷键；不要覆盖输入法、屏幕阅读器或文本编辑快捷键。
|
||||||
|
- 标签与字段、帮助与描述、错误与字段建立程序化关系；必填和无效状态可被屏幕阅读器感知。
|
||||||
|
- 单选组、复选组和相关字段具有组名；错误摘要中的项目可将焦点移到对应字段。
|
||||||
|
- 在 200% 文本/显示缩放、中文输入法、屏幕键盘和高对比度下验证。
|
||||||
|
|
||||||
|
### 输入法组合
|
||||||
|
|
||||||
|
中文、日文、韩文等输入法组合期间，不执行最终格式化、远程搜索、自动提交或破坏性的字段重写。组合完成后再触发需要完整文本的验证。粘贴、撤销、重做、语音输入和自动填充必须经过同一规范化与验证流程。
|
||||||
|
|
||||||
|
不要在用户输入过程中反复替换整个字符串。格式化数字、电话或证件号时保持光标、选择范围和输入法状态，并允许复制未经装饰的领域值。
|
||||||
|
|
||||||
|
## 7. 异步、依赖字段与敏感数据
|
||||||
|
|
||||||
|
### 异步验证
|
||||||
|
|
||||||
|
- 为每次请求关联字段值、记录版本和请求 ID；只接受仍匹配当前编辑值的结果。
|
||||||
|
- 显示 `validating`，但避免阻止用户继续填写无关字段。
|
||||||
|
- 提交与验证竞态时等待最新必要验证或在服务端统一裁决。
|
||||||
|
- 取消窗口或离开页面时取消请求或忽略回调，不能访问已销毁 UI。
|
||||||
|
- 缓存结果时包含影响有效性的上下文，如租户、权限和相关字段。
|
||||||
|
|
||||||
|
### 依赖字段
|
||||||
|
|
||||||
|
- 父字段变化导致子选项失效时，明确清空、重新选择或保留不可用值。
|
||||||
|
- 加载子选项时保持标签和布局稳定，显示加载/失败/重试。
|
||||||
|
- 条件必填规则同步更新标签、帮助、验证和无障碍状态。
|
||||||
|
- 自动计算字段默认只读；允许覆盖时明确“自动/手动”来源和恢复方式。
|
||||||
|
|
||||||
|
### 敏感数据
|
||||||
|
|
||||||
|
- 不把密码、令牌、支付数据或个人信息写入日志、URL、分析事件和普通崩溃上下文。
|
||||||
|
- 明确剪贴板、显示/隐藏、超时清除和截屏风险；不要默认禁止所有粘贴或密码管理器。
|
||||||
|
- 错误消息不泄露账户是否存在、权限细节或服务端内部信息。
|
||||||
|
- HTML 原型只使用虚构数据，不模拟采集真实敏感信息。
|
||||||
|
|
||||||
|
## 8. 测试矩阵
|
||||||
|
|
||||||
|
至少验证：
|
||||||
|
|
||||||
|
1. 初始、修改、恢复原值、只读、禁用、条件隐藏和权限变化；
|
||||||
|
2. 空值、边界值、超长值、空白、非法字符、区域数字、日期和时区；
|
||||||
|
3. 首次失焦、重复编辑、提交失败、修复后重提和服务器字段错误；
|
||||||
|
4. 中文输入法组合、粘贴、撤销/重做、自动填充和屏幕键盘；
|
||||||
|
5. 异步验证乱序、取消、超时、离线和字段依赖变化；
|
||||||
|
6. 双击提交、连续即时更新和旧响应覆盖新值；
|
||||||
|
7. 页面导航、标签关闭、窗口关闭和应用退出时的未保存决策；
|
||||||
|
8. 100%–200% 缩放、窄窗口、长翻译、高对比度、键盘和屏幕阅读器；
|
||||||
|
9. 原型与最终桌面实现的字段、规则、错误和提交状态对照。
|
||||||
|
|
||||||
|
## 9. 交付检查清单
|
||||||
|
|
||||||
|
- [ ] 已选择即时生效、显式提交、分步或自动保存模式。
|
||||||
|
- [ ] 每个字段的原始值、编辑值、脏状态和验证状态明确。
|
||||||
|
- [ ] 控件与数据类型匹配，标签、帮助、必填和错误语义完整。
|
||||||
|
- [ ] 允许合理中间输入和输入法组合，不在每次按键后破坏文本。
|
||||||
|
- [ ] 本地、跨字段和服务端验证时机及错误位置明确。
|
||||||
|
- [ ] 保存失败保留输入，取消和关闭使用统一未保存策略。
|
||||||
|
- [ ] 异步请求具有取消/过期保护，旧响应不能覆盖新值。
|
||||||
|
- [ ] 敏感信息不进入日志、URL、原型真实数据或普通分析事件。
|
||||||
|
- [ ] 键盘、缩放、高对比度和屏幕阅读器已验证。
|
||||||
|
- [ ] 原型与桌面实现使用同一字段和状态契约。
|
||||||
@@ -0,0 +1,141 @@
|
|||||||
|
# 桌面 HTML 原型评审与实现交接
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
1. 适用范围与目标
|
||||||
|
2. 原型前的设计冻结条件
|
||||||
|
3. 原型技术与目录约束
|
||||||
|
4. 必须覆盖的内容与状态
|
||||||
|
5. 客户评审与验收边界
|
||||||
|
6. 从 HTML 交接到目标桌面适配器
|
||||||
|
7. 变更管理与完成标准
|
||||||
|
8. 常见反模式
|
||||||
|
|
||||||
|
## 1. 适用范围与目标
|
||||||
|
|
||||||
|
HTML 原型用于低成本验证信息架构、内容层级、视觉 Token、窗口断点、关键流程和状态反馈。它是设计规格的可交互表达，不是最终产品的 Web 版本。
|
||||||
|
|
||||||
|
以下情况默认制作原型：
|
||||||
|
|
||||||
|
- 新产品、主要窗口、关键业务流程或显著视觉改版；
|
||||||
|
- 客户需要在原生开发前确认范围、流程或视觉；
|
||||||
|
- 多角色、多状态或跨页面交互仅靠静态图难以说明；
|
||||||
|
- 多种桌面框架团队需要统一实现基准。
|
||||||
|
|
||||||
|
仅修正文案、颜色、间距或单个明确控件时，可以说明理由后跳过。跳过不等于省略状态、无障碍和验收要求。
|
||||||
|
|
||||||
|
## 2. 原型前的设计冻结条件
|
||||||
|
|
||||||
|
开始写 HTML 前至少确定：
|
||||||
|
|
||||||
|
- 目标用户、核心任务和主流程；
|
||||||
|
- 页面/窗口清单、导航模型和命令层级；
|
||||||
|
- 目标桌面框架与控件映射方向；
|
||||||
|
- 字体、颜色、间距、圆角、层级和动效 Token；
|
||||||
|
- 紧凑、中等、宽窗口的布局策略；
|
||||||
|
- 加载、空、错误、离线、禁用、成功、取消和撤销状态；
|
||||||
|
- 原型要确认的决策、审批人和反馈截止方式。
|
||||||
|
|
||||||
|
仍有未知项时在原型内显式标注假设，不要用精致视觉掩盖未完成的产品决策。
|
||||||
|
|
||||||
|
## 3. 原型技术与目录约束
|
||||||
|
|
||||||
|
默认创建独立的 `prototype/` 目录，至少包含入口 HTML、样式、交互脚本和本地资源。项目已有前端原型栈时遵循现有结构；没有时优先使用简单、可直接打开或通过轻量本地服务器运行的 HTML/CSS/JavaScript。
|
||||||
|
|
||||||
|
- 默认不引入前端框架、构建链或组件库；只有复杂状态确有收益且团队能维护时才使用。
|
||||||
|
- 不依赖外部 CDN、在线字体、远程图片或只有开发机可用的绝对路径。
|
||||||
|
- 使用语义化 HTML、CSS 自定义属性和少量模块化 JavaScript，保持客户环境可重复运行。
|
||||||
|
- 将设计 Token 集中定义，避免在各页面复制颜色、间距和字号。
|
||||||
|
- 使用本地模拟数据或可重置 fixture；需要模拟接口时明确 schema、延迟、空数据和失败响应。
|
||||||
|
- 不包含生产凭据、真实个人数据、生产数据库连接、遥测或不可逆操作。
|
||||||
|
- 提供清晰的启动入口；不得要求客户先理解桌面工程的构建环境。
|
||||||
|
|
||||||
|
原型不是生产 Web 应用，不要提前建设路由框架、认证、完整后端、SEO、服务端渲染或发布基础设施，除非这些本身就是待确认体验的一部分。
|
||||||
|
|
||||||
|
## 4. 必须覆盖的内容与状态
|
||||||
|
|
||||||
|
至少实现：
|
||||||
|
|
||||||
|
- 主导航、页面层级和主要任务的端到端可点击路径；
|
||||||
|
- 关键命令、菜单、对话框、表单验证、选择和反馈；
|
||||||
|
- 默认、悬停、按下、焦点、选中和禁用状态；
|
||||||
|
- 加载、空、错误、成功、取消、超时和过期结果；
|
||||||
|
- 紧凑、中等、宽窗口的重排、折叠和滚动行为；
|
||||||
|
- 浅色、深色，以及适用时的高对比度近似方案；
|
||||||
|
- 键盘焦点顺序、Enter/Escape、常用快捷键和不依赖悬停的操作入口；
|
||||||
|
- 真实长度的中文、数字、日期、错误文案和高密度示例数据。
|
||||||
|
|
||||||
|
避免只有首页和理想数据的“演示动画”。客户需要看到业务完成条件、失败后的恢复方式以及删除等高风险操作的后果。
|
||||||
|
|
||||||
|
## 5. 客户评审与验收边界
|
||||||
|
|
||||||
|
评审前提供场景脚本，而不是只给一个 URL 或目录。按用户任务引导客户检查并记录：
|
||||||
|
|
||||||
|
1. 信息架构和功能范围；
|
||||||
|
2. 页面布局、密度和窗口断点；
|
||||||
|
3. 品牌、颜色、字体、图标和动效方向；
|
||||||
|
4. 文案、术语、数据字段和默认值；
|
||||||
|
5. 主流程、异常流程、权限和不可用状态；
|
||||||
|
6. 哪些内容已确认、需修改、暂缓或超出范围。
|
||||||
|
|
||||||
|
必须声明以下内容不能仅靠 HTML 验收：
|
||||||
|
|
||||||
|
- 原生标题栏、系统菜单、Snap Layouts、多窗口和任务栏行为；
|
||||||
|
- 原生控件的精确尺寸、字体栅格化和系统主题差异；
|
||||||
|
- Mica/Acrylic、原生弹出层、输入法和多显示器 DPI 行为；
|
||||||
|
- 屏幕阅读器和目标框架无障碍 API 的最终语义；
|
||||||
|
- 启动速度、内存、虚拟化、线程、打包、升级和生产数据性能。
|
||||||
|
|
||||||
|
验收记录至少包含原型版本或提交、日期、审批人、确认项、遗留项和明确排除项。未回复不能自动视为确认。
|
||||||
|
|
||||||
|
## 6. 从 HTML 交接到目标桌面适配器
|
||||||
|
|
||||||
|
确认后冻结原型版本，并建立追踪表：
|
||||||
|
|
||||||
|
| 原型项 | 设计 Token/状态 | 目标框架意图 | 适配器验证 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| 导航 | 层级、选中、折叠 | 平台导航、标签或页面容器 | 键盘、窗口断点、状态恢复 |
|
||||||
|
| 共享命令 | 文本、图标、启用状态 | 可复用命令对象或集中 action | 快捷键、上下文和权限 |
|
||||||
|
| 数据集合 | 空、加载、选择、分页 | 虚拟化列表/表格与稳定数据模型 | 大数据性能和选择保持 |
|
||||||
|
| 对话与反馈 | 模态性、默认操作 | 平台对话框、页面信息条和任务反馈 | 焦点、Escape、所有者和生命周期 |
|
||||||
|
|
||||||
|
原型中的组件语义保持集中：
|
||||||
|
|
||||||
|
- 表单优先使用原生 `form`、`label`、`input`、`select`、`textarea` 和 `button`，模拟字段、异步和提交错误。
|
||||||
|
- 静态数据优先使用 `<table>`；只有实现完整二维键盘模型时才使用交互式 `grid` 语义。
|
||||||
|
- 标签使用 `tablist`、`tab`、`tabpanel` 关系，隐藏面板不得保留可聚焦子元素。
|
||||||
|
- 模态界面优先使用原生 `<dialog>` 或经验证实现，并管理背景 inert、焦点循环、Escape 和焦点返回。
|
||||||
|
- 使用稳定 ID 和事件委托区分单击、双击、上下文菜单及单元格内控件；不要依赖 DOM 索引作为业务身份。
|
||||||
|
- 使用可访问状态文本或实时区域模拟进度、错误和部分成功，但不抢夺焦点或重复播报。
|
||||||
|
|
||||||
|
交接时遵循以下规则：
|
||||||
|
|
||||||
|
- 复用设计 Token 和状态名称，不复用 DOM 结构或逐字翻译 CSS。
|
||||||
|
- 把模拟数据 schema 转成明确的领域模型、接口契约和错误类型。
|
||||||
|
- 将 JavaScript 交互意图映射到桌面命令、信号/事件和状态管理。
|
||||||
|
- 选择目标框架的标准控件；原型视觉与原生行为冲突时优先保证任务、可用性和平台约定。
|
||||||
|
- 对无法一比一实现的材质、布局或动效给出差异说明，并在桌面端验收中重新确认。
|
||||||
|
- 桌面实现完成后执行视觉对照，也必须单独完成原生键盘、无障碍、DPI、性能和打包测试。
|
||||||
|
|
||||||
|
## 7. 变更管理与完成标准
|
||||||
|
|
||||||
|
客户确认后的需求变化先回到原型和验收记录。评估它对页面、状态、数据契约、桌面控件、开发量和测试范围的影响，再更新原生实现。
|
||||||
|
|
||||||
|
HTML 原型阶段完成必须同时满足：
|
||||||
|
|
||||||
|
- 评审范围内流程和关键状态可操作；
|
||||||
|
- 指定窗口宽度、主题和键盘路径已检查；
|
||||||
|
- 不含真实凭据和生产副作用；
|
||||||
|
- 客户能按说明独立运行；
|
||||||
|
- 已形成书面确认、遗留项和排除项；
|
||||||
|
- 已建立到所选桌面适配器的控件与状态映射。
|
||||||
|
|
||||||
|
## 8. 常见反模式
|
||||||
|
|
||||||
|
- 先写完整 HTML，再补用户流程、状态和验收目标。
|
||||||
|
- 为一次性原型引入复杂前端框架、后端和部署平台。
|
||||||
|
- 只实现理想路径，使用 `alert()` 代替真实错误、确认和恢复体验。
|
||||||
|
- 用浏览器窗口模拟原生标题栏后承诺 Snap、系统菜单或窗口拖拽效果。
|
||||||
|
- 把浏览器像素截图作为所有 DPI、主题和字体环境的最终标准。
|
||||||
|
- 客户口头说“差不多”便开始开发，没有版本化确认和遗留项。
|
||||||
|
- 桌面端直接复制 HTML 的控件结构、CSS 数值或 JavaScript 状态管理。
|
||||||
@@ -0,0 +1,178 @@
|
|||||||
|
# 桌面导航、标签页与窗口交互规范
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
1. 选择导航模型
|
||||||
|
2. 目的地、路由与状态模型
|
||||||
|
3. 导航、后退与焦点恢复
|
||||||
|
4. 自适应导航与应用外壳
|
||||||
|
5. 静态标签与文档标签
|
||||||
|
6. 未保存内容与关闭协议
|
||||||
|
7. 多窗口与窗口生命周期
|
||||||
|
8. 键盘与无障碍
|
||||||
|
9. 测试矩阵
|
||||||
|
10. 交付检查清单
|
||||||
|
|
||||||
|
## 1. 选择导航模型
|
||||||
|
|
||||||
|
先根据用户心智模型选择，不按视觉偏好混用：
|
||||||
|
|
||||||
|
| 模型 | 表达含义 | 典型呈现 |
|
||||||
|
|---|---|---|
|
||||||
|
| 顶级导航 | 在应用主要目的地之间切换 | 带标签的侧边或顶部导航 + 页面容器 |
|
||||||
|
| 层级导航 | 进入对象或任务的下一级，并允许后退 | 路由栈、主从页面或显式导航控制器 |
|
||||||
|
| 静态标签 | 在少量、固定、同一对象的同级属性页之间切换 | 不可关闭的标签或分段选择器 |
|
||||||
|
| 文档标签 | 管理可创建、关闭、重排和可能移动到窗口的工作文档 | 可关闭、移动和溢出的文档标签 |
|
||||||
|
| 多窗口 | 并行展示独立任务、文档或工具 | 具有独立状态容器的顶层窗口 |
|
||||||
|
| 辅助面板 | 补充当前任务，不成为新的顶级目的地 | 侧面板、检查器或可停靠面板 |
|
||||||
|
|
||||||
|
不要使用标签页表示彼此无关的应用目的地，也不要用顶级导航伪装可关闭文档。层级导航、文档历史和编辑撤销是三种独立历史，不共用一个“后退”命令。
|
||||||
|
|
||||||
|
在编码前定义：目的地清单、稳定 ID、层级关系、可深链参数、进入/离开条件、后退语义、状态保留、加载策略、权限、未保存行为、多窗口所有权和恢复策略。
|
||||||
|
|
||||||
|
## 2. 目的地、路由与状态模型
|
||||||
|
|
||||||
|
### 稳定身份
|
||||||
|
|
||||||
|
- 使用路由/目的地 ID、文档 ID 和窗口 ID 标识状态，不使用导航项索引或当前标签位置。
|
||||||
|
- 路由参数只包含可序列化的最小身份；大型对象和敏感数据放在应用状态/服务中。
|
||||||
|
- 同一文档重复打开时明确激活现有标签、创建只读副本，还是允许多个编辑会话。
|
||||||
|
- 权限变化或对象删除后，历史记录不得导航到可操作的幽灵页面；显示可恢复状态或移除记录。
|
||||||
|
|
||||||
|
### 每个页面保存什么
|
||||||
|
|
||||||
|
按产品价值决定保留：滚动位置、选中对象、筛选、展开节点、输入草稿、焦点目标、分页和子视图。持久业务数据与临时视图状态分开。
|
||||||
|
|
||||||
|
- 前进/后退通常恢复页面上下文，不重新创建空白页面。
|
||||||
|
- 刷新数据不应默认清空用户位置；无法恢复时将焦点放到语义最近的位置。
|
||||||
|
- 导航缓存需要容量和失效策略，不能无限保留页面、订阅、线程和敏感数据。
|
||||||
|
- 恢复失败时安全回到有效目的地并说明原因，不崩溃或显示空壳。
|
||||||
|
|
||||||
|
## 3. 导航、后退与焦点恢复
|
||||||
|
|
||||||
|
### 进入目的地
|
||||||
|
|
||||||
|
- 点击当前已激活的顶级导航项默认不重复压栈；需要“回到顶部/刷新”时显式定义。
|
||||||
|
- 导航启动后防止重复触发。异步加载显示当前目的地的骨架/进度，并忽略过期结果。
|
||||||
|
- 先确认离开条件，再切换选中导航项；被未保存状态阻止时恢复原导航视觉。
|
||||||
|
- 失败时保留上一页或显示可操作错误，不短暂显示目标页后再弹回。
|
||||||
|
|
||||||
|
### 后退与前进
|
||||||
|
|
||||||
|
- 仅在有有效历史时启用后退；不要显示一个永远禁用的装饰按钮。
|
||||||
|
- `Alt+Left`/鼠标后退键按应用导航历史返回；不要撤销编辑或关闭文档。
|
||||||
|
- 后退前运行与直接导航相同的未保存协调器。
|
||||||
|
- 从详情返回列表时恢复筛选、选择、滚动和焦点；目标已删除时选择相邻项或列表容器。
|
||||||
|
- 深链首次进入没有应用内上一页时，后退回到合理的应用起点或关闭该任务窗口，规则必须明确。
|
||||||
|
|
||||||
|
### 焦点
|
||||||
|
|
||||||
|
- 导航完成后把焦点放到页面标题、主内容或恢复的任务位置，而不是留在不可见导航项。
|
||||||
|
- 用户通过键盘选择导航项时保持可预测焦点；指针导航不应无必要抢走当前输入焦点。
|
||||||
|
- 弹层、对话框和辅助面板关闭后将焦点返回调用者或逻辑后继。
|
||||||
|
- 加载完成不自动把焦点从用户正在操作的其他控件抢走。
|
||||||
|
|
||||||
|
## 4. 自适应导航与应用外壳
|
||||||
|
|
||||||
|
- 紧凑、中等、宽布局使用同一目的地和选择状态，只改变呈现方式。
|
||||||
|
- 导航面板折叠/展开不重建页面、不清空历史、不丢焦点。
|
||||||
|
- 紧凑模式保留可发现的打开导航入口；图标必须有文本/工具提示和无障碍名称。
|
||||||
|
- 顶级项保持稳定顺序。权限或功能开关改变时，移除无权项并处理当前目的地回退。
|
||||||
|
- 标题栏拖动区域不能覆盖导航按钮、搜索、标签关闭或窗口命令。
|
||||||
|
- 设置、账户和帮助等固定项与主要业务目的地分组，但仍参与明确的焦点顺序。
|
||||||
|
- 窗口变窄时优先折叠次要面板、重排主从内容，再隐藏低频命令；不把关键任务变成仅菜单可用。
|
||||||
|
|
||||||
|
## 5. 静态标签与文档标签
|
||||||
|
|
||||||
|
### 静态标签
|
||||||
|
|
||||||
|
- 用于少量固定同级页面，不提供新建、关闭、拖动或未保存标记。
|
||||||
|
- 标签切换应快速。内容加载有明显延迟时使用手动激活：方向键移动焦点，Enter/Space 激活。
|
||||||
|
- 标签名称简短且稳定；不要用仅图标标签承载关键分类。
|
||||||
|
- 切换后保留每页内部状态，除非数据刷新是明确操作。
|
||||||
|
|
||||||
|
### 文档标签
|
||||||
|
|
||||||
|
每个文档标签维护稳定文档 ID、标题、脏状态、加载/错误、只读/冲突、固定状态和所属窗口。标签位置只是显示顺序。
|
||||||
|
|
||||||
|
- 单击激活文档；关闭按钮只关闭命中标签，不先意外切换并触发其他副作用。
|
||||||
|
- 支持关闭当前、关闭其他、关闭右侧等命令时准确处理固定标签和未保存标签。
|
||||||
|
- 关闭后优先激活最近使用或邻近标签，并将焦点放到合理位置。
|
||||||
|
- 重排不改变文档身份、保存目标、撤销栈或后台任务所有权。
|
||||||
|
- 标签太多时提供滚动、溢出列表或搜索；不能把标签压缩到无法识别。
|
||||||
|
- 标签标题变化保持关闭按钮位置稳定；脏状态使用符号并提供无障碍文本，不只变颜色。
|
||||||
|
- 双击标签、双击空白区和中键关闭仅作为加速路径，必须有显式按钮/菜单/键盘入口。
|
||||||
|
- 拖出新窗口是高级能力；需定义取消拖动、跨 DPI、失败回退和最后标签行为。
|
||||||
|
|
||||||
|
### 标签键盘
|
||||||
|
|
||||||
|
- Ctrl+Tab/Ctrl+Shift+Tab 在文档标签间切换；是否按显示顺序或最近使用顺序要保持一致。
|
||||||
|
- Ctrl+W 关闭当前可关闭文档；不会绕过未保存检查。
|
||||||
|
- 标签条聚焦后使用方向键移动，Enter/Space 激活；Delete 关闭仅在产品明确采用时启用。
|
||||||
|
- 关闭后焦点移动到新激活标签或逻辑后继，不落到已删除对象。
|
||||||
|
|
||||||
|
## 6. 未保存内容与关闭协议
|
||||||
|
|
||||||
|
所有离开路径调用同一关闭协调器：导航离开、后退、关闭标签、关闭窗口、退出应用、切换账户和外部打开另一文档。
|
||||||
|
|
||||||
|
推荐协议：
|
||||||
|
|
||||||
|
1. 收集受影响的脏文档/表单和正在提交的任务；
|
||||||
|
2. 无修改则直接继续；可自动保存则先安全保存；
|
||||||
|
3. 需要决策时显示具体对象和“保存 / 不保存 / 取消”；
|
||||||
|
4. 多文档退出支持逐项或“全部保存”，并报告失败项；
|
||||||
|
5. 只有全部必要保存成功或用户明确放弃后才完成关闭；
|
||||||
|
6. 取消关闭恢复原窗口、标签、导航选择和焦点。
|
||||||
|
|
||||||
|
- 保存失败不得关闭；保留内容并提供重试、另存或复制恢复数据。
|
||||||
|
- 后台任务与文档绑定时定义关闭后取消、继续后台或转移所有权。
|
||||||
|
- 进程崩溃恢复与正常未保存提示分开；恢复草稿不能覆盖较新的服务端版本。
|
||||||
|
- 不用“是否发生过键盘输入”判断脏状态，应比较规范化领域快照或命令状态。
|
||||||
|
|
||||||
|
## 7. 多窗口与窗口生命周期
|
||||||
|
|
||||||
|
- 每个窗口具有明确任务、所有者和状态容器；不要依赖全局“当前窗口”。
|
||||||
|
- 应用级服务可以共享，页面选择、导航历史、焦点、文档视图状态通常按窗口隔离。
|
||||||
|
- 辅助窗口定义模态性、任务栏显示、始终置顶、最小化/恢复和父窗口关闭行为。
|
||||||
|
- 同一文档在多窗口编辑时定义单写者、协同、只读副本或冲突策略。
|
||||||
|
- 关闭父窗口前处理其拥有的对话框、弹层、未保存内容和后台任务。
|
||||||
|
- 保存窗口位置/尺寸/最大化/停靠布局；恢复时限制到当前显示器可用区域。
|
||||||
|
- 显示器移除、DPI 改变或窗口恢复失败时使用安全默认位置和最小可用尺寸。
|
||||||
|
- 最后一个窗口关闭是退出、留在托盘还是保留后台服务必须明确，不让任务静默终止。
|
||||||
|
|
||||||
|
## 8. 键盘与无障碍
|
||||||
|
|
||||||
|
- 顶级导航、标签条和页面内容是不同复合区域；Tab 在区域间移动，方向键在区域内移动。
|
||||||
|
- 当前导航目的地与键盘焦点分别可见，并向无障碍 API 暴露选中/激活状态。
|
||||||
|
- 后退、关闭、新建标签、切换标签和窗口命令具有标准快捷键及菜单说明。
|
||||||
|
- 标签关闭按钮、仅图标导航项和窗口按钮提供准确名称；重复标签增加可区分上下文。
|
||||||
|
- 页面标题使用可导航语义；导航完成和错误加载时播报目的地变化，但不重复朗读整页。
|
||||||
|
- 高对比度、200% 缩放和长翻译下仍能识别活动目的地、活动标签、脏状态和关闭入口。
|
||||||
|
- 动效尊重系统减少动画设置；转场不延迟输入或导致前庭不适。
|
||||||
|
|
||||||
|
## 9. 测试矩阵
|
||||||
|
|
||||||
|
至少验证：
|
||||||
|
|
||||||
|
1. 当前目的地重复点击、快速连续导航、加载失败和过期响应；
|
||||||
|
2. 后退/前进、深链首次进入、对象删除和权限变化；
|
||||||
|
3. 紧凑/宽导航切换、贴靠、标题栏命中和焦点保持；
|
||||||
|
4. 静态标签、文档新建/关闭/重排/溢出和重复打开；
|
||||||
|
5. 单个/多个脏文档的保存、不保存、取消和保存失败；
|
||||||
|
6. Ctrl+Tab、Ctrl+W、Alt+Left、方向键、Enter、Space、Delete 和 Shift+F10；
|
||||||
|
7. 多窗口共享文档、关闭父窗口、最后窗口和后台任务；
|
||||||
|
8. 窗口位置恢复、显示器移除、100%–200% DPI 和高对比度；
|
||||||
|
9. 屏幕阅读器对目的地、活动标签、脏状态、标签数量和加载结果的播报；
|
||||||
|
10. 原型与最终桌面实现的路由、关闭和恢复契约对照。
|
||||||
|
|
||||||
|
## 10. 交付检查清单
|
||||||
|
|
||||||
|
- [ ] 已区分顶级导航、层级导航、静态标签、文档标签和多窗口。
|
||||||
|
- [ ] 所有目的地、文档和窗口使用稳定 ID，不依赖显示索引。
|
||||||
|
- [ ] 后退、刷新和导航失败能够保留或安全恢复用户上下文。
|
||||||
|
- [ ] 标签关闭、重排、溢出、快捷键和焦点后继明确。
|
||||||
|
- [ ] 所有离开路径共享未保存协调器，保存失败不会丢失内容。
|
||||||
|
- [ ] 多窗口的所有权、共享状态、关闭和最后窗口行为明确。
|
||||||
|
- [ ] 自适应布局不会重建状态或破坏标题栏命中。
|
||||||
|
- [ ] 键盘、缩放、高对比度和屏幕阅读器已验证。
|
||||||
|
- [ ] 原型与桌面实现使用同一路由和文档状态契约。
|
||||||
@@ -1,143 +0,0 @@
|
|||||||
# WinUI engineering and validation
|
|
||||||
|
|
||||||
## Contents
|
|
||||||
|
|
||||||
1. Version and dependency gates
|
|
||||||
2. XAML and state architecture
|
|
||||||
3. Windowing and responsive implementation
|
|
||||||
4. Performance and async behavior
|
|
||||||
5. Implementation review
|
|
||||||
6. Release test matrix
|
|
||||||
7. Severity model
|
|
||||||
8. Official sources
|
|
||||||
|
|
||||||
## 1. Version and dependency gates
|
|
||||||
|
|
||||||
Before generating XAML or C#:
|
|
||||||
|
|
||||||
1. Read the project file, central package props, target framework, target/min Windows versions, and installed packages.
|
|
||||||
2. Identify the Windows App SDK and Windows Community Toolkit versions exactly.
|
|
||||||
3. Check whether the project is packaged or unpackaged and whether it uses single-project MSIX.
|
|
||||||
4. Verify the proposed API in current Microsoft documentation and, for controls, the WinUI 3 Gallery.
|
|
||||||
5. Record minimum-version and fallback behavior in the recommendation.
|
|
||||||
|
|
||||||
Use `Microsoft.UI.Xaml` for WinUI 3. Treat examples using `Windows.UI.Xaml`, WinUI 2 Gallery, or UWP-specific APIs as migration inputs, not copy-ready code.
|
|
||||||
|
|
||||||
Examples of version-sensitive guidance:
|
|
||||||
|
|
||||||
- the WinUI `TitleBar` control requires Windows App SDK 1.7 or later;
|
|
||||||
- `SystemBackdropElement` requires Windows App SDK 1.6.3 or later;
|
|
||||||
- Mica requires Windows 11 and falls back to a solid theme surface on Windows 10;
|
|
||||||
- Windows Community Toolkit `DataGrid` is archived and not a WCT 8+ WinUI 3 control.
|
|
||||||
|
|
||||||
For any third-party control, document package, version, license, maintenance status, supported Windows versions, theme/high-contrast behavior, UI Automation support, keyboard model, localization, virtualization, and escape plan.
|
|
||||||
|
|
||||||
## 2. XAML and state architecture
|
|
||||||
|
|
||||||
- Follow the project's MVVM or code-behind conventions; do not introduce a second architecture for one screen.
|
|
||||||
- Represent user actions as reusable commands when the same action appears in buttons, menus, context menus, and accelerators.
|
|
||||||
- Keep view state explicit: idle, loading, content, empty, filtered empty, error, offline/stale, permission denied, and partial result as applicable.
|
|
||||||
- Centralize semantic colors, type styles, spacing, geometry, icon sizes, and motion in resource dictionaries.
|
|
||||||
- Use `ThemeResource` for values that must change while the app is running and `StaticResource` only when runtime theme updates are not required.
|
|
||||||
- Put light, dark, and high-contrast mappings in theme dictionaries when custom tokens are necessary.
|
|
||||||
- Prefer styles and composition over copying full control templates. A custom template inherits responsibility for every visual and accessibility state.
|
|
||||||
- Use `x:Bind` or the project's established binding approach consistently. Make binding mode and update timing explicit for editable values.
|
|
||||||
- Use Grid and flexible sizing for structured layouts; avoid deep nested panels and fixed sizes that break localization or text scaling.
|
|
||||||
- Keep visual order aligned with reading and tab order.
|
|
||||||
|
|
||||||
Do not write UI-thread dispatching as a substitute for sound async ownership. Marshal only the final state update that truly requires the UI thread and ensure the view is still alive.
|
|
||||||
|
|
||||||
## 3. Windowing and responsive implementation
|
|
||||||
|
|
||||||
### Title bar
|
|
||||||
|
|
||||||
Keep system caption buttons and the system menu. Define a drag region along the top edge, exclude interactive children from drag regions, and test active/inactive appearance. Verify maximize, restore, resize, Snap Layouts, touch, right-click system menu, and high contrast.
|
|
||||||
|
|
||||||
Prefer the platform `TitleBar` control when the project version supports it. When using `NavigationView` with that control, let one component own back and pane-toggle behavior rather than showing duplicate buttons.
|
|
||||||
|
|
||||||
### Responsive layout
|
|
||||||
|
|
||||||
Start with a safe compact layout and add wider visual states. Use effective window/content width. Test each transition in both directions and preserve:
|
|
||||||
|
|
||||||
- selection and keyboard focus;
|
|
||||||
- scroll position and expanded state;
|
|
||||||
- input and validation state;
|
|
||||||
- command availability;
|
|
||||||
- accessible reading order.
|
|
||||||
|
|
||||||
Avoid replacing the whole visual tree on every resize if a reflow or reposition is sufficient. Debounce expensive resize-driven work and never rebuild data collections solely because the window crossed a breakpoint.
|
|
||||||
|
|
||||||
### Multi-window
|
|
||||||
|
|
||||||
Define ownership, activation, persisted placement, minimum size, close confirmation, and shared data lifetime. Ensure commands act on the active document/window context and that dialogs have the correct XamlRoot/owner.
|
|
||||||
|
|
||||||
## 4. Performance and async behavior
|
|
||||||
|
|
||||||
- Keep collection virtualization enabled and measure with realistic data, images, templates, and grouping.
|
|
||||||
- Prefer `ListView`, `GridView`, or `ItemsView` behavior before low-level `ItemsRepeater` customization.
|
|
||||||
- Decode images near their rendered size, avoid loading full-resolution assets for thumbnails, and cancel work for recycled items.
|
|
||||||
- Avoid synchronous file, network, database, or expensive serialization work on the UI thread.
|
|
||||||
- Make async commands idempotent or prevent duplicate invocation while work is active.
|
|
||||||
- Support cancellation for long operations and ignore stale results after navigation, search-query changes, or window close.
|
|
||||||
- Show immediate command feedback. Delay large skeleton/progress transitions just enough to avoid flicker for near-instant work, while never leaving the UI apparently frozen.
|
|
||||||
- Keep previous usable content visible during refresh when safe; distinguish refresh from first load.
|
|
||||||
- Animate opacity and transforms where possible; avoid layout-heavy animation across large trees.
|
|
||||||
- Defer expensive secondary content until requested, but do not lazy-load controls required for keyboard order or core task comprehension without a plan.
|
|
||||||
- Measure startup, navigation, resize, input latency, scroll smoothness, memory growth, and recovery from device/theme changes.
|
|
||||||
|
|
||||||
## 5. Implementation review
|
|
||||||
|
|
||||||
Check correctness before visual polish:
|
|
||||||
|
|
||||||
- [ ] Namespace, APIs, package versions, and minimum OS are valid.
|
|
||||||
- [ ] The project builds without introducing warnings in the changed scope.
|
|
||||||
- [ ] Commands cannot double-submit and failures preserve user work.
|
|
||||||
- [ ] Every data surface has loading, empty, error, and retry behavior as needed.
|
|
||||||
- [ ] Virtualization, recycling, and cancellation work with production-scale data.
|
|
||||||
- [ ] Theme resources update at runtime and custom tokens cover high contrast.
|
|
||||||
- [ ] Layout survives compact width, long strings, text scaling, and display scaling.
|
|
||||||
- [ ] Focus, selection, accessible names, roles, states, and announcements are correct.
|
|
||||||
- [ ] Caption controls, drag regions, dialogs, and multi-window ownership behave correctly.
|
|
||||||
- [ ] Destructive actions use undo or confirmation proportional to consequence.
|
|
||||||
|
|
||||||
## 6. Release test matrix
|
|
||||||
|
|
||||||
Test representative combinations rather than one happy-path machine:
|
|
||||||
|
|
||||||
| Dimension | Minimum coverage |
|
|
||||||
|---|---|
|
|
||||||
| Windows | minimum supported OS plus current Windows 11 |
|
|
||||||
| Window | supported minimum, small `<=640` epx, medium `641–1007`, large `>=1008`, snapped, maximized |
|
|
||||||
| Scale | common 100%, 125%, 150%, 200% display scales and monitor transitions |
|
|
||||||
| Text | default and increased Windows text size |
|
|
||||||
| Theme | light, dark, high contrast; transparency on and off |
|
|
||||||
| Input | keyboard only, mouse, touch/pen when claimed |
|
|
||||||
| Assistive tech | Narrator, Magnifier, Accessibility Insights/Inspect |
|
|
||||||
| Content | empty, one item, realistic data, very large data, long localized strings, failures |
|
|
||||||
| Environment | slow storage/network, offline, permission denied, RDP or material fallback where relevant |
|
|
||||||
| Lifecycle | suspend/close if applicable, reopen, upgrade, secondary-window close, crash-safe data recovery |
|
|
||||||
|
|
||||||
Automate stable checks, but keep human review for Narrator flow, focus visibility, touch comfort, motion, wording, hierarchy, and perceived responsiveness.
|
|
||||||
|
|
||||||
## 7. Severity model
|
|
||||||
|
|
||||||
Use this order when reviewing a design or implementation:
|
|
||||||
|
|
||||||
| Severity | Definition | Examples |
|
|
||||||
|---|---|---|
|
|
||||||
| Blocker | Prevents a primary task, excludes an input/accessibility mode, loses data, or uses an unavailable API | keyboard trap, clipped save button, archived control assumed present |
|
|
||||||
| Major | Causes frequent error, disorientation, inaccessible content, or severe responsive/performance failure | broken focus return, nonvirtualized large list, unreadable dark mode |
|
|
||||||
| Moderate | Slows tasks or creates inconsistent Windows behavior with a workaround | hidden contextual command, weak empty state, inconsistent selection |
|
|
||||||
| Minor | Polish issue with little task impact | spacing drift, inconsistent icon weight, unnecessary shadow |
|
|
||||||
|
|
||||||
For each finding, cite the screen/control, trigger condition, user impact, and smallest robust correction. Avoid vague feedback such as “make it more modern.”
|
|
||||||
|
|
||||||
## 8. Official sources
|
|
||||||
|
|
||||||
- [WinUI 3 overview](https://learn.microsoft.com/windows/apps/winui/winui3/)
|
|
||||||
- [Title bar customization](https://learn.microsoft.com/windows/apps/develop/title-bar?tabs=winui3)
|
|
||||||
- [NavigationView title bar integration](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview)
|
|
||||||
- [Responsive layouts with XAML](https://learn.microsoft.com/windows/apps/develop/ui/layouts-with-xaml)
|
|
||||||
- [ListView and GridView](https://learn.microsoft.com/windows/apps/develop/ui/controls/listview-and-gridview)
|
|
||||||
- [Materials in Windows apps](https://learn.microsoft.com/windows/apps/develop/ui/materials)
|
|
||||||
- [Accessibility checklist](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)
|
|
||||||
@@ -1,142 +0,0 @@
|
|||||||
# Windows input and accessibility baseline
|
|
||||||
|
|
||||||
## Contents
|
|
||||||
|
|
||||||
1. Input parity
|
|
||||||
2. Keyboard and focus
|
|
||||||
3. Mouse, touch, pen, and drag
|
|
||||||
4. UI Automation semantics
|
|
||||||
5. Visual and cognitive accessibility
|
|
||||||
6. Status, errors, and timing
|
|
||||||
7. Accessibility test matrix
|
|
||||||
8. Official sources
|
|
||||||
|
|
||||||
## 1. Input parity
|
|
||||||
|
|
||||||
Make every primary scenario possible with keyboard alone. Pointer hover, right-click, touch swipe, pen barrel button, drag-and-drop, and gestures may accelerate a task but must not be the only way to complete it.
|
|
||||||
|
|
||||||
Use standard controls first because they already implement much of the focus, keyboard, pointer, touch, and UI Automation behavior. For every custom control, define:
|
|
||||||
|
|
||||||
- automation role, name, value, state, and supported patterns;
|
|
||||||
- tab-stop and inner arrow-key behavior;
|
|
||||||
- keyboard activation and Escape behavior;
|
|
||||||
- pointer cursor, hover, press, and context menu behavior;
|
|
||||||
- touch target, manipulation threshold, and gesture alternative;
|
|
||||||
- focus visuals, selected visuals, and high-contrast rendering.
|
|
||||||
|
|
||||||
## 2. Keyboard and focus
|
|
||||||
|
|
||||||
- Put actionable elements in the tab sequence; keep labels and decorative elements out.
|
|
||||||
- Match tab order to visual and reading order. Prefer natural XAML order and use `TabIndex` only to correct a demonstrated issue.
|
|
||||||
- Use arrow keys inside composite controls such as lists, menus, radio groups, tabs, and grids.
|
|
||||||
- Set initial focus to the most useful safe element when a window, page, dialog, or task surface opens.
|
|
||||||
- Return focus to the invoker when a flyout or dialog closes. After deletion, move focus to a predictable adjacent item or stable container.
|
|
||||||
- Keep the platform focus visual visible. Do not encode focus only through a subtle color change.
|
|
||||||
- Use access keys for visible commands and form navigation; use keyboard accelerators for frequent or standard actions.
|
|
||||||
- Show accelerators in menus and tooltips where users learn commands.
|
|
||||||
- Allow Escape to close dismissible UI or cancel the current transient mode. Do not discard unsaved work silently.
|
|
||||||
- Ensure Enter and Space activate controls according to standard control behavior; do not invent conflicting key semantics.
|
|
||||||
|
|
||||||
Use familiar shortcuts only when the command truly has the familiar meaning:
|
|
||||||
|
|
||||||
| Shortcut | Expected meaning |
|
|
||||||
|---|---|
|
|
||||||
| `Ctrl+N` | new item/document/window as appropriate |
|
|
||||||
| `Ctrl+O` | open |
|
|
||||||
| `Ctrl+S` | save |
|
|
||||||
| `Ctrl+Z` / `Ctrl+Y` or `Ctrl+Shift+Z` | undo / redo, consistent with the app domain |
|
|
||||||
| `Ctrl+F` | search or find |
|
|
||||||
| `F5` | refresh when refresh is meaningful |
|
|
||||||
| `Delete` | delete selected item, with undo or confirmation based on consequence |
|
|
||||||
| `Alt+Left` | back when the app has navigation history |
|
|
||||||
| `F6` | move between major panes in complex workspaces |
|
|
||||||
|
|
||||||
Do not override operating-system or assistive-technology shortcuts.
|
|
||||||
|
|
||||||
## 3. Mouse, touch, pen, and drag
|
|
||||||
|
|
||||||
### Mouse and pointer
|
|
||||||
|
|
||||||
- Use hover to preview or accelerate, never to hide the only route to a command.
|
|
||||||
- Provide a context menu for object-specific commands; expose frequent commands visibly as well.
|
|
||||||
- Use tooltips for unfamiliar icons, truncated content, and shortcut education—not for essential instructions.
|
|
||||||
- Keep selection and focus visually distinct in dense lists and grids.
|
|
||||||
- Preserve target position during hover and press; avoid geometry changes that make the pointer chase a control.
|
|
||||||
|
|
||||||
### Touch and pen
|
|
||||||
|
|
||||||
Use platform controls at their default size where possible. For custom targets, meet the Windows touch baseline:
|
|
||||||
|
|
||||||
- target at least 40 × 40 epx, even if the visible glyph is smaller;
|
|
||||||
- a 32 epx-tall target can be acceptable when it is at least 120 epx wide;
|
|
||||||
- for touch-optimized experiences, prefer 44 × 44 epx with at least 4 epx visible separation;
|
|
||||||
- enlarge frequent or high-consequence targets beyond the minimum;
|
|
||||||
- do not place destructive targets tightly beside routine actions.
|
|
||||||
|
|
||||||
Support mouse precision without making touch impossible. Make scrolling, zoom, selection, and pen input coexist without gesture conflicts.
|
|
||||||
|
|
||||||
### Drag and drop
|
|
||||||
|
|
||||||
Show a clear drag affordance, valid targets, insertion position, forbidden states, and completion feedback. Use a movement threshold to prevent accidental drags. Always provide keyboard and menu commands such as Move up/down, Move to, Attach, or Import for critical drag operations.
|
|
||||||
|
|
||||||
## 4. UI Automation semantics
|
|
||||||
|
|
||||||
Accessible names must be concise, unique enough in context, and action-oriented for commands.
|
|
||||||
|
|
||||||
- Let standard controls promote visible text when that produces the correct name.
|
|
||||||
- Set `AutomationProperties.Name` explicitly for icon-only buttons, meaningful images, custom-drawn content, ambiguous repeated controls, or controls whose visible text does not describe the action.
|
|
||||||
- Associate form labels with fields through `AutomationProperties.LabeledBy` where applicable.
|
|
||||||
- Put supplemental instructions in help text or accessible descriptions; do not stuff them into the name.
|
|
||||||
- Expose selection, checked, expanded, pressed, read-only, required, invalid, busy, and disabled states through the correct control or automation peer.
|
|
||||||
- Mark decorative images and duplicate glyphs so they do not create noise.
|
|
||||||
- Implement the appropriate UI Automation patterns for custom controls; an accessible name alone is insufficient.
|
|
||||||
|
|
||||||
Do not add an explicit name to every control mechanically. Duplicate or stale names can make the screen-reader experience worse.
|
|
||||||
|
|
||||||
## 5. Visual and cognitive accessibility
|
|
||||||
|
|
||||||
- Maintain at least 4.5:1 text contrast in the normal light and dark themes.
|
|
||||||
- Test high contrast; do not use a high-contrast theme as a substitute for adequate normal-theme contrast.
|
|
||||||
- Pair color with text, shape, icon, position, or pattern for errors, selection, and status.
|
|
||||||
- Preserve visible focus, current selection, and input validation at all theme states.
|
|
||||||
- Support Windows text-size settings and display scaling without clipped text, inaccessible controls, or lost commands.
|
|
||||||
- Prefer wrapping and adaptive height to truncation. Test long localized strings, narrow windows, and right-to-left layout when the product supports such locales.
|
|
||||||
- Use plain, specific writing. Put the decision or recovery action first; avoid blame and error codes without explanation.
|
|
||||||
- Avoid flashing and nonessential repetitive animation. Respect system animation preferences and keep interaction possible while motion runs.
|
|
||||||
- Provide captions or transcripts for meaningful audio/video and text alternatives for informative graphics.
|
|
||||||
|
|
||||||
## 6. Status, errors, and timing
|
|
||||||
|
|
||||||
Announce important asynchronous state changes without stealing focus. Use a suitable live-region or standard control behavior for loading completion, errors, and background status.
|
|
||||||
|
|
||||||
Error feedback must answer:
|
|
||||||
|
|
||||||
1. What failed?
|
|
||||||
2. What user work was preserved?
|
|
||||||
3. What can the user do now?
|
|
||||||
|
|
||||||
Place field errors near the field and summarize multiple errors at the task level when useful. Move focus only when it helps recovery, such as focusing the first invalid field after submit.
|
|
||||||
|
|
||||||
Do not auto-dismiss critical errors. Give users enough time to read transient status, pause time limits when feasible, and provide a persistent history for important background operations or notifications.
|
|
||||||
|
|
||||||
## 7. Accessibility test matrix
|
|
||||||
|
|
||||||
- [ ] Complete primary flows with keyboard only.
|
|
||||||
- [ ] Verify logical Tab, Shift+Tab, arrow, Enter, Space, Escape, access-key, and accelerator behavior.
|
|
||||||
- [ ] Test Narrator reading order, names, roles, values, states, and live announcements.
|
|
||||||
- [ ] Inspect the UI Automation tree with Accessibility Insights for Windows or Inspect.
|
|
||||||
- [ ] Test light, dark, and at least one high-contrast theme.
|
|
||||||
- [ ] Measure text contrast and verify that color is not the only cue.
|
|
||||||
- [ ] Test Windows text-size changes, display scale changes, Magnifier, and narrow windows.
|
|
||||||
- [ ] Test mouse, touch when supported, context menus, and alternatives to drag/hover.
|
|
||||||
- [ ] Check long strings, localization expansion, and any supported right-to-left language.
|
|
||||||
- [ ] Add automated accessibility checks for critical screens and flows where the test stack supports them.
|
|
||||||
|
|
||||||
## 8. Official sources
|
|
||||||
|
|
||||||
- [Accessibility checklist for Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)
|
|
||||||
- [Keyboard interactions](https://learn.microsoft.com/windows/apps/develop/input/keyboard-interactions)
|
|
||||||
- [Guidelines for touch targets](https://learn.microsoft.com/windows/apps/develop/input/guidelines-for-targeting)
|
|
||||||
- [Touch interactions](https://learn.microsoft.com/windows/apps/develop/input/touch-interactions)
|
|
||||||
- [Accessible text requirements](https://learn.microsoft.com/windows/apps/design/accessibility/accessible-text-requirements)
|
|
||||||
- [Accessibility testing](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-testing)
|
|
||||||
@@ -1,129 +1,129 @@
|
|||||||
# Windows visual and layout foundations
|
# Windows 视觉与布局基础
|
||||||
|
|
||||||
## Contents
|
## 目录
|
||||||
|
|
||||||
1. Design principles
|
1. 设计原则
|
||||||
2. Visual foundations
|
2. 视觉基础
|
||||||
3. Layout and responsive behavior
|
3. 布局与响应式行为
|
||||||
4. Color and themes
|
4. 颜色与主题
|
||||||
5. Materials and elevation
|
5. 材质与层级
|
||||||
6. Typography, icons, and motion
|
6. 字体、图标与动效
|
||||||
7. Foundation review checklist
|
7. 基础规范检查清单
|
||||||
8. Official sources
|
8. 官方资料
|
||||||
|
|
||||||
## 1. Design principles
|
## 1. 设计原则
|
||||||
|
|
||||||
Use the current Windows 11 principles as evaluation questions:
|
将当前 Windows 11 设计原则作为评估问题：
|
||||||
|
|
||||||
| Principle | Ask |
|
| 原则 | 评估问题 |
|
||||||
|---|---|
|
|---|---|
|
||||||
| Effortless | Can users complete the primary task with focus, precision, and little interpretation? |
|
| Effortless（轻松） | 用户能否专注、准确且无需过多理解就完成主要任务？ |
|
||||||
| Calm | Is secondary chrome quiet enough for content and current work to dominate? |
|
| Calm（平静） | 次要界面元素是否足够克制，让内容和当前工作占据主导？ |
|
||||||
| Personal | Does the app respect theme, accent, text size, input, and user preferences? |
|
| Personal（个性化） | 应用是否尊重主题、强调色、文本大小、输入方式和用户偏好？ |
|
||||||
| Familiar | Do navigation, commands, selection, windowing, and feedback behave like Windows? |
|
| Familiar（熟悉） | 导航、命令、选择、窗口化和反馈是否符合 Windows 行为？ |
|
||||||
| Complete + Coherent | Do screens, windows, states, and input modes feel like one system? |
|
| Complete + Coherent（完整且一致） | 界面、窗口、状态和输入方式是否形成统一系统？ |
|
||||||
|
|
||||||
Do not substitute the older Fluent vocabulary of light, depth, motion, material, and scale for these five product principles. Treat color, elevation, iconography, materials, geometry, typography, and motion as visual foundations.
|
不要用早期 Fluent 中的 Light、Depth、Motion、Material 和 Scale 词汇替代这五项产品原则。将颜色、层级、图标、材质、几何、字体和动效视为视觉基础。
|
||||||
|
|
||||||
## 2. Visual foundations
|
## 2. 视觉基础
|
||||||
|
|
||||||
Build a semantic token layer instead of styling each screen independently:
|
建立语义化 Token 层，不要单独设置每个界面的样式：
|
||||||
|
|
||||||
- `surface.base`, `surface.layer`, `surface.overlay`;
|
- `surface.base`、`surface.layer`、`surface.overlay`；
|
||||||
- `text.primary`, `text.secondary`, `text.disabled`;
|
- `text.primary`、`text.secondary`、`text.disabled`；
|
||||||
- `accent.default`, `accent.hover`, `accent.pressed`, `accent.disabled`;
|
- `accent.default`、`accent.hover`、`accent.pressed`、`accent.disabled`；
|
||||||
- `status.success`, `status.caution`, `status.critical`, `status.informational`;
|
- `status.success`、`status.caution`、`status.critical`、`status.informational`；
|
||||||
- `stroke.control`, `stroke.divider`, `focus.stroke`;
|
- `stroke.control`、`stroke.divider`、`focus.stroke`；
|
||||||
- `space.1` through `space.n`, `radius.control`, `radius.overlay`;
|
- `space.1` 到 `space.n`、`radius.control`、`radius.overlay`；
|
||||||
- `motion.fast`, `motion.normal`, and shared easing tokens.
|
- `motion.fast`、`motion.normal` 和共享缓动 Token。
|
||||||
|
|
||||||
Map these semantics to WinUI theme resources where available. Keep brand tokens above platform tokens so light, dark, and high-contrast mappings remain explicit.
|
在目标框架有对应能力时，将这些语义映射到主题、调色板或样式资源。让品牌 Token 位于 Windows 平台 Token 之上，明确浅色、深色和高对比度映射。
|
||||||
|
|
||||||
Use one primary accent action per local task area. Use size, spacing, alignment, and weight before adding more colors or surfaces.
|
每个局部任务区域只使用一个主要强调操作。先通过尺寸、间距、对齐和字重建立层级，再增加颜色或表面。
|
||||||
|
|
||||||
## 3. Layout and responsive behavior
|
## 3. 布局与响应式行为
|
||||||
|
|
||||||
Design in effective pixels (epx). Use multiples of 4 epx for sizes, margins, and positions when practical; text size is not restricted to this grid.
|
使用有效像素（epx）进行设计。尺寸、边距和位置在可行时使用 4 epx 的倍数；文本大小不受该网格限制。
|
||||||
|
|
||||||
Use the current Windows width classes as starting points, then adjust only when content demonstrates a real need:
|
以当前 Windows 宽度类别为起点，仅在内容证明有实际需要时调整：
|
||||||
|
|
||||||
| Class | Effective width | Typical response |
|
| 类别 | 有效宽度 | 典型响应方式 |
|
||||||
|---|---:|---|
|
|---|---:|---|
|
||||||
| Small | `<= 640` | single pane, collapsed or minimal navigation, stacked form, deferred secondary content |
|
| 小 | `<= 640` | 单窗格、折叠或最小化导航、堆叠表单、延后显示次要内容 |
|
||||||
| Medium | `641–1007` | compact navigation, list/detail may switch between one and two panes |
|
| 中 | `641–1007` | 紧凑导航、列表/详情可在单窗格和双窗格间切换 |
|
||||||
| Large | `>= 1008` | persistent navigation or multi-pane workspace when it improves the task |
|
| 大 | `>= 1008` | 在有助于任务时使用常驻导航或多窗格工作区 |
|
||||||
|
|
||||||
Use the actual content region or window width, not monitor resolution. Validate at the app's supported minimum size, Windows Snap widths, restored windows, maximized windows, and across display scaling changes.
|
使用实际内容区域或窗口宽度，而不是显示器分辨率。在应用支持的最小尺寸、Windows 贴靠宽度、还原窗口、最大化窗口以及跨显示缩放变化时进行验证。
|
||||||
|
|
||||||
Apply responsive techniques deliberately:
|
有意识地应用响应式技术：
|
||||||
|
|
||||||
- **Reflow:** wrap or stack content without changing meaning.
|
- **重排（Reflow）：** 在不改变含义的情况下换行或堆叠内容。
|
||||||
- **Resize:** let flexible regions absorb space; constrain readable text measure.
|
- **调整大小（Resize）：** 让弹性区域吸收空间，并限制文本的可读行宽。
|
||||||
- **Reposition:** move secondary panels or commands while preserving order.
|
- **重新定位（Reposition）：** 移动次要面板或命令，同时保持顺序。
|
||||||
- **Reveal:** progressively expose low-priority content as room grows.
|
- **显示（Reveal）：** 随可用空间增加，逐步展示低优先级内容。
|
||||||
- **Replace:** switch to a more suitable navigation or presentation control.
|
- **替换（Replace）：** 切换为更适合的导航或展示控件。
|
||||||
- **Re-architect:** use a different workflow only when a compact window cannot support the same structure.
|
- **重构（Re-architect）：** 仅当紧凑窗口无法支持相同结构时改用不同工作流。
|
||||||
|
|
||||||
Define the narrow state as the safe default, then use `VisualStateManager` and `AdaptiveTrigger` for wider states. Prefer control-provided thresholds such as `NavigationView` compact/open pane widths when those express the intended behavior. Avoid fixed widths for content that must localize or scale.
|
将窄屏状态定义为安全默认状态，再使用 `VisualStateManager` 和 `AdaptiveTrigger` 添加宽屏状态。当 `NavigationView` 的紧凑/展开窗格宽度等控件阈值能表达预期行为时，优先使用这些阈值。避免给需要本地化或缩放的内容设置固定宽度。
|
||||||
|
|
||||||
## 4. Color and themes
|
## 4. 颜色与主题
|
||||||
|
|
||||||
- Use `{ThemeResource ...}` for colors and brushes that must update when the theme changes.
|
- 对必须随主题运行时更新的颜色和画刷使用 `{ThemeResource ...}`。
|
||||||
- Test light, dark, and high contrast independently; do not generate dark mode by inversion.
|
- 分别测试浅色、深色和高对比度；不要通过反相生成深色模式。
|
||||||
- Respect the system accent color unless product identity or domain semantics justify a controlled brand accent.
|
- 尊重系统强调色，除非产品标识或领域语义足以证明需要受控的品牌强调色。
|
||||||
- Maintain at least 4.5:1 contrast for normal text. Use icons, text, or patterns in addition to semantic color.
|
- 普通文本至少保持 4.5:1 对比度。除语义色外，同时使用图标、文本或图案。
|
||||||
- Do not encode state only through reduced opacity. Preserve recognizable text, focus, selection, and disabled semantics.
|
- 不要只通过降低不透明度表达状态。保持文本、焦点、选择和禁用语义可辨认。
|
||||||
- Never place critical text over a material or image without a deterministic readable fallback.
|
- 不要把关键文本放在无法确定可读性的材质或图像上，必须提供明确可读的回退方案。
|
||||||
|
|
||||||
Prefer system resources such as text fill, control fill, stroke, accent fill, and system status brushes. Verify resource names against the project's Windows App SDK version before emitting code.
|
优先使用文本填充、控件填充、描边、强调色填充和系统状态画刷等系统资源。生成代码前，根据目标框架、版本和平台能力验证资源名称。
|
||||||
|
|
||||||
## 5. Materials and elevation
|
## 5. 材质与层级
|
||||||
|
|
||||||
Use material to clarify layers, not to decorate every container:
|
使用材质来明确层级，不要装饰每个容器：
|
||||||
|
|
||||||
| Need | Preferred mechanism | Notes |
|
| 需求 | 首选材质 | 说明 |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| Main window background | `MicaBackdrop` | Windows 11; solid fallback on Windows 10 |
|
| 主窗口背景 | Mica | 用于 Windows 11；在 Windows 10 或框架不支持时回退为纯色 |
|
||||||
| Desktop-see-through window | `DesktopAcrylicBackdrop` | More visually active; use only when the experience benefits |
|
| 可透视桌面的窗口 | Desktop Acrylic | 视觉更活跃；仅在体验确有收益且框架安全支持时使用 |
|
||||||
| Material on a specific region | `SystemBackdropElement` | Requires Windows App SDK 1.6.3 or later |
|
| 临时菜单和浮层 | Acrylic 或主题浮层色 | 用于表达临时层级，并准备不透明回退 |
|
||||||
| Blur content inside the window | in-app `AcrylicBrush` | Does not show the desktop behind the app |
|
| 模糊窗口内部内容 | 应用内模糊材质 | 不应误导用户以为能透视应用后的桌面 |
|
||||||
| Simple content surface | theme solid color | Often the clearest and cheapest choice |
|
| 简单内容表面 | 主题纯色 | 通常是最清晰且成本最低的选择 |
|
||||||
|
|
||||||
Do not use UWP `HostBackdrop` patterns in WinUI 3. Allow system fallback when transparency is disabled, hardware is insufficient, Battery Saver suppresses Acrylic, Remote Desktop is active, or high contrast is enabled. Ensure the fallback color preserves hierarchy and contrast.
|
透明效果关闭、硬件不足、节电模式抑制 Acrylic、使用远程桌面或启用高对比度时，允许系统或适配器回退。确保回退颜色仍能维持层级和对比度；具体 API、版本门槛和禁用条件由所选框架适配文档定义。
|
||||||
|
|
||||||
Use elevation only to communicate overlap, focus, or transient UI. Prefer system shadows and overlay behavior. Do not introduce an external shadow control merely to make cards look raised.
|
仅用层级表达重叠、焦点或临时 UI。优先使用系统阴影和覆盖层行为。不要仅为了让卡片显得凸起而引入外部阴影控件。
|
||||||
|
|
||||||
## 6. Typography, icons, and motion
|
## 6. 字体、图标与动效
|
||||||
|
|
||||||
Use Segoe UI Variable and the WinUI type ramp by default. Reuse platform text styles rather than copying numeric sizes throughout XAML. Use regular body weight, stronger titles or labels, tabular figures for aligned numeric data, and wrapping before truncation. When truncation is unavoidable, expose the full value through an accessible tooltip or detail surface.
|
Windows 11 优先使用 Segoe UI Variable；不具备该字体或平台映射时回退到 Segoe UI 或目标框架的 Windows 系统字体。复用平台文本层级，不要在各页面重复数值字号。正文使用常规字重，标题或标签使用更强字重，对齐的数字数据使用等宽数字，并优先换行而不是截断。无法避免截断时，通过无障碍工具提示或详情界面公开完整值。
|
||||||
|
|
||||||
Use `SymbolIcon`, `FontIcon` with Segoe Fluent Icons, or a consistent vector asset set. Keep icon metaphor, size, stroke/fill style, and alignment consistent. Give unfamiliar or icon-only commands an accessible name and tooltip. Do not use emoji as navigation or command icons.
|
使用 Segoe Fluent Icons 能力或一致、授权明确的矢量资源集；目标系统缺少字体字形时必须回退。保持图标隐喻、大小、描边/填充风格和对齐一致。为不熟悉或仅有图标的命令提供无障碍名称和工具提示。不要使用 Emoji 作为导航或命令图标。
|
||||||
|
|
||||||
Use motion to explain causality, hierarchy, and continuity:
|
使用动效解释因果关系、层级和连续性：
|
||||||
|
|
||||||
- give immediate pointer/press feedback;
|
- 立即提供指针/按下反馈；
|
||||||
- prefer platform transitions and connected animations where they clarify movement;
|
- 在有助于解释移动时，优先使用平台过渡和连接动画；
|
||||||
- animate compositor-friendly properties such as opacity and transforms;
|
- 为不透明度和变换等适合合成器的属性设置动画；
|
||||||
- keep motion interruptible and never use it to delay input;
|
- 保持动画可中断，绝不使用动画延迟输入；
|
||||||
- reduce or remove nonessential motion when system animation settings request it;
|
- 当系统动画设置要求时，减少或移除非必要动效；
|
||||||
- avoid perpetual decorative movement in productivity surfaces.
|
- 避免在生产力界面中使用持续循环的装饰性动效。
|
||||||
|
|
||||||
## 7. Foundation review checklist
|
## 7. 基础规范检查清单
|
||||||
|
|
||||||
- [ ] The UI reflects Effortless, Calm, Personal, Familiar, and Complete + Coherent.
|
- [ ] UI 体现 Effortless、Calm、Personal、Familiar 和 Complete + Coherent。
|
||||||
- [ ] Semantic tokens cover themes and all interaction states.
|
- [ ] 语义 Token 覆盖主题和所有交互状态。
|
||||||
- [ ] Layout is proven at compact, medium, wide, snapped, and scaled conditions.
|
- [ ] 布局已在紧凑、中等、宽、贴靠和缩放条件下验证。
|
||||||
- [ ] Spacing and geometry follow a coherent 4 epx rhythm.
|
- [ ] 间距和几何遵循一致的 4 epx 节奏。
|
||||||
- [ ] Material choice communicates a layer and has a solid fallback.
|
- [ ] 材质选择能表达层级并具有纯色回退方案。
|
||||||
- [ ] Typography remains readable under text scaling and localization.
|
- [ ] 字体在文本缩放和本地化后仍可读。
|
||||||
- [ ] Icons use one language and are not emoji.
|
- [ ] 图标采用统一语言且不使用 Emoji。
|
||||||
- [ ] Motion communicates change and respects user settings.
|
- [ ] 动效能传达变化并尊重用户设置。
|
||||||
|
|
||||||
## 8. Official sources
|
## 8. 官方资料
|
||||||
|
|
||||||
- [Windows design principles](https://learn.microsoft.com/windows/apps/design/design-principles)
|
- [Windows 设计原则](https://learn.microsoft.com/windows/apps/design/design-principles)
|
||||||
- [Windows design guidelines](https://learn.microsoft.com/windows/apps/design/guidelines-overview)
|
- [Windows 设计指南](https://learn.microsoft.com/windows/apps/design/guidelines-overview)
|
||||||
- [Screen sizes and breakpoints](https://learn.microsoft.com/windows/apps/design/layout/screen-sizes-and-breakpoints-for-responsive-design)
|
- [屏幕尺寸与断点](https://learn.microsoft.com/windows/apps/design/layout/screen-sizes-and-breakpoints-for-responsive-design)
|
||||||
- [Content layout and spacing](https://learn.microsoft.com/windows/apps/design/basics/content-basics)
|
- [内容布局与间距](https://learn.microsoft.com/windows/apps/design/basics/content-basics)
|
||||||
- [Materials in Windows apps](https://learn.microsoft.com/windows/apps/develop/ui/materials)
|
- [Windows 应用中的材质](https://learn.microsoft.com/windows/apps/develop/ui/materials)
|
||||||
- [Accessible text requirements](https://learn.microsoft.com/windows/apps/design/accessibility/accessible-text-requirements)
|
- [无障碍文本要求](https://learn.microsoft.com/windows/apps/design/accessibility/accessible-text-requirements)
|
||||||
|
|||||||
@@ -0,0 +1,142 @@
|
|||||||
|
# Windows 输入与无障碍基线
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
1. 输入等价性
|
||||||
|
2. 键盘与焦点
|
||||||
|
3. 鼠标、触控、笔与拖拽
|
||||||
|
4. UI Automation 语义
|
||||||
|
5. 视觉与认知无障碍
|
||||||
|
6. 状态、错误与计时
|
||||||
|
7. 无障碍测试矩阵
|
||||||
|
8. 官方资料
|
||||||
|
|
||||||
|
## 1. 输入等价性
|
||||||
|
|
||||||
|
确保所有主要场景都能只用键盘完成。指针悬停、右键、触控轻扫、笔桶形按钮、拖放和手势可以加速任务，但不得成为完成任务的唯一方式。
|
||||||
|
|
||||||
|
优先使用标准控件，因为它们已经实现大量焦点、键盘、指针、触控和 UI Automation 行为。为每个自定义控件定义：
|
||||||
|
|
||||||
|
- 自动化角色、名称、值、状态和支持的模式；
|
||||||
|
- Tab 停靠点和内部方向键行为；
|
||||||
|
- 键盘激活和 Escape 行为；
|
||||||
|
- 指针光标、悬停、按下和上下文菜单行为；
|
||||||
|
- 触控目标、操作阈值和手势替代方式；
|
||||||
|
- 焦点视觉、选中视觉和高对比度渲染。
|
||||||
|
|
||||||
|
## 2. 键盘与焦点
|
||||||
|
|
||||||
|
- 将可操作元素放入 Tab 顺序；让标签和装饰元素退出该顺序。
|
||||||
|
- 让 Tab 顺序与视觉和阅读顺序一致。优先使用自然布局/声明顺序，仅在纠正确认存在的问题时显式覆盖焦点顺序。
|
||||||
|
- 在列表、菜单、单选组、标签页和网格等复合控件内部使用方向键。
|
||||||
|
- 窗口、页面、对话框或任务界面打开时，将初始焦点设置到最有用且安全的元素。
|
||||||
|
- 浮出控件或对话框关闭时将焦点返回调用者。删除后，将焦点移动到可预测的相邻项或稳定容器。
|
||||||
|
- 保持平台焦点视觉可见。不要只用轻微颜色变化表达焦点。
|
||||||
|
- 为可见命令和表单导航使用访问键；为频繁或标准操作使用键盘快捷键。
|
||||||
|
- 在菜单和工具提示中显示快捷键，帮助用户学习命令。
|
||||||
|
- 允许 Escape 关闭可解除界面或取消当前临时模式。不得静默丢弃未保存工作。
|
||||||
|
- 确保 Enter 和 Space 按标准控件行为激活控件；不要发明冲突的按键语义。
|
||||||
|
|
||||||
|
仅当命令真正具有熟悉含义时使用常见快捷键：
|
||||||
|
|
||||||
|
| 快捷键 | 预期含义 |
|
||||||
|
|---|---|
|
||||||
|
| `Ctrl+N` | 根据场景新建项目/文档/窗口 |
|
||||||
|
| `Ctrl+O` | 打开 |
|
||||||
|
| `Ctrl+S` | 保存 |
|
||||||
|
| `Ctrl+Z` / `Ctrl+Y` 或 `Ctrl+Shift+Z` | 撤销/重做，并与应用领域保持一致 |
|
||||||
|
| `Ctrl+F` | 搜索或查找 |
|
||||||
|
| `F5` | 在刷新有意义时刷新 |
|
||||||
|
| `Delete` | 删除选中项，并根据后果提供撤销或确认 |
|
||||||
|
| `Alt+Left` | 应用存在导航历史时后退 |
|
||||||
|
| `F6` | 在复杂工作区的主要窗格间移动 |
|
||||||
|
|
||||||
|
不要覆盖操作系统或辅助技术快捷键。
|
||||||
|
|
||||||
|
## 3. 鼠标、触控、笔与拖拽
|
||||||
|
|
||||||
|
### 鼠标与指针
|
||||||
|
|
||||||
|
- 使用悬停进行预览或加速，但不要把命令的唯一入口隐藏在悬停中。
|
||||||
|
- 为对象特定命令提供上下文菜单，同时让频繁命令保持可见。
|
||||||
|
- 将工具提示用于不熟悉的图标、截断内容和快捷键教学，不要用于关键说明。
|
||||||
|
- 在高密度列表和网格中，让选择与焦点在视觉上可区分。
|
||||||
|
- 悬停和按下时保持目标位置稳定；避免几何变化迫使指针追逐控件。
|
||||||
|
|
||||||
|
### 触控与笔
|
||||||
|
|
||||||
|
尽可能使用平台控件的默认尺寸。自定义目标应满足 Windows 触控基线：
|
||||||
|
|
||||||
|
- 目标至少为 40 × 40 epx，即使可见字形更小；
|
||||||
|
- 高度为 32 epx 的目标，在宽度至少 120 epx 时可以接受；
|
||||||
|
- 针对触控优化的体验，优先使用 44 × 44 epx，并保持至少 4 epx 可见间距；
|
||||||
|
- 让频繁使用或误操作后果严重的目标大于最低尺寸；
|
||||||
|
- 不要让破坏性目标紧邻常规操作。
|
||||||
|
|
||||||
|
在支持鼠标精确操作的同时保证触控可用。让滚动、缩放、选择和笔输入共存且不产生手势冲突。
|
||||||
|
|
||||||
|
### 拖放
|
||||||
|
|
||||||
|
显示清晰的拖动提示、有效目标、插入位置、禁止状态和完成反馈。使用移动阈值避免误拖。对于关键拖动操作，始终提供“上移/下移”“移动到”“附加”或“导入”等键盘和菜单命令。
|
||||||
|
|
||||||
|
## 4. UI Automation 语义
|
||||||
|
|
||||||
|
无障碍名称必须简洁，在上下文中足以区分，并对命令使用操作导向的表述。
|
||||||
|
|
||||||
|
- 当标准控件根据可见文本生成的名称正确时，使用该默认名称。
|
||||||
|
- 对仅有图标的按钮、有意义的图像、自定义绘制内容、含义不清的重复控件，或可见文本无法描述操作的控件，通过目标框架的无障碍 API 显式设置名称。
|
||||||
|
- 适用时，通过目标框架的标签关系把表单标签与字段关联。
|
||||||
|
- 将补充说明放在帮助文本或无障碍描述中；不要把所有内容塞进名称。
|
||||||
|
- 通过正确的控件或 AutomationPeer 公开选择、选中、展开、按下、只读、必填、无效、忙碌和禁用状态。
|
||||||
|
- 标记装饰性图像和重复字形，避免产生噪音。
|
||||||
|
- 为自定义控件实现合适的 UI Automation 模式；只有无障碍名称并不充分。
|
||||||
|
|
||||||
|
不要机械地为每个控件添加显式名称。重复或过期的名称会使屏幕阅读器体验更差。
|
||||||
|
|
||||||
|
## 5. 视觉与认知无障碍
|
||||||
|
|
||||||
|
- 在普通浅色和深色主题中保持至少 4.5:1 的文本对比度。
|
||||||
|
- 测试高对比度；不要把高对比度主题当作普通主题对比度不足的补救方法。
|
||||||
|
- 对错误、选择和状态，除颜色外同时使用文本、形状、图标、位置或图案。
|
||||||
|
- 在所有主题状态中保持焦点、当前选择和输入验证清晰可见。
|
||||||
|
- 支持 Windows 文本大小设置和显示缩放，不能出现文本裁切、控件不可访问或命令丢失。
|
||||||
|
- 优先使用换行和自适应高度而不是截断。产品支持相关区域时，测试长本地化字符串、窄窗口和从右到左布局。
|
||||||
|
- 使用平实、具体的文案。先给出决策或恢复操作；避免指责用户，也不要只显示错误代码而不解释。
|
||||||
|
- 避免闪烁和非必要的重复动画。尊重系统动画偏好，并在动效运行时保持可交互。
|
||||||
|
- 为有意义的音频/视频提供字幕或文字稿，为信息性图形提供文本替代内容。
|
||||||
|
|
||||||
|
## 6. 状态、错误与计时
|
||||||
|
|
||||||
|
播报重要的异步状态变化，但不要抢夺焦点。为加载完成、错误和后台状态使用合适的实时区域或标准控件行为。
|
||||||
|
|
||||||
|
错误反馈必须回答：
|
||||||
|
|
||||||
|
1. 什么失败了？
|
||||||
|
2. 用户的哪些工作已保留？
|
||||||
|
3. 用户现在可以做什么？
|
||||||
|
|
||||||
|
将字段错误放在字段附近；有多个错误时，根据需要在任务层级汇总。仅在有助于恢复时移动焦点，例如提交后聚焦第一个无效字段。
|
||||||
|
|
||||||
|
不要自动关闭关键错误。给用户足够时间阅读临时状态；可行时暂停时间限制，并为重要后台操作或通知提供持久历史记录。
|
||||||
|
|
||||||
|
## 7. 无障碍测试矩阵
|
||||||
|
|
||||||
|
- [ ] 只使用键盘完成主要流程。
|
||||||
|
- [ ] 验证合理的 Tab、Shift+Tab、方向键、Enter、Space、Escape、访问键和快捷键行为。
|
||||||
|
- [ ] 测试 Narrator 阅读顺序、名称、角色、值、状态和实时播报。
|
||||||
|
- [ ] 使用 Accessibility Insights for Windows 或 Inspect 检查 UI Automation 树。
|
||||||
|
- [ ] 测试浅色、深色和至少一种高对比度主题。
|
||||||
|
- [ ] 测量文本对比度，并确认颜色不是唯一提示。
|
||||||
|
- [ ] 测试 Windows 文本大小变化、显示缩放变化、放大镜和窄窗口。
|
||||||
|
- [ ] 测试鼠标、支持时的触控、上下文菜单，以及拖拽/悬停的替代方式。
|
||||||
|
- [ ] 检查长字符串、本地化扩展和任何受支持的从右到左语言。
|
||||||
|
- [ ] 在测试技术栈支持时，为关键界面和流程添加自动化无障碍检查。
|
||||||
|
|
||||||
|
## 8. 官方资料
|
||||||
|
|
||||||
|
- [Windows 应用无障碍检查清单](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)
|
||||||
|
- [键盘交互](https://learn.microsoft.com/windows/apps/develop/input/keyboard-interactions)
|
||||||
|
- [触控目标指南](https://learn.microsoft.com/windows/apps/develop/input/guidelines-for-targeting)
|
||||||
|
- [触控交互](https://learn.microsoft.com/windows/apps/develop/input/touch-interactions)
|
||||||
|
- [无障碍文本要求](https://learn.microsoft.com/windows/apps/design/accessibility/accessible-text-requirements)
|
||||||
|
- [无障碍测试](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-testing)
|
||||||
Reference in New Issue
Block a user