opc/win_ui_ux_design_skill
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Chinese localization

Browse Source
This commit is contained in:
QiuSW
2026-07-18 17:40:25 +08:00
parent 07c63cb565
commit 2ed513bc25
6 changed files with 465 additions and 465 deletions
Download Patch File Download Diff File Expand all files Collapse all files
references/controls-and-patterns.md
+109 -109
View File
@@ -1,163 +1,163 @@
# WinUI controls and desktop patterns
# WinUI 控件与桌面端模式
## 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. 选择方法
2. 导航与窗口外壳
3. 集合与结构化数据
4. 输入控件与表单
5. 命令与菜单
6. 反馈与临时界面
7. 常见页面模式
8. 控件评审检查清单
9. 官方资料
## 1. Selection method
## 1. 选择方法
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.
1. 确定用户是在导航、选择、调用、编辑、比较还是检查。
2. 优先选择已经实现预期键盘、焦点、选择、自动化和主题行为的控件。
3. 根据准确的 Windows App SDK 或 Toolkit 版本检查可用性。
4. 先自定义样式，再考虑模板；仅当交互模型不正确时才替换控件。
5. 记录第三方控件的无障碍、本地化、性能、维护和许可成本。
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
## 2. 导航与窗口外壳
| 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 |
| 应用顶级目标位置 | `NavigationView` | 缺少 Windows 导航行为的自定义侧栏 |
| 少量静态同级视图 | `SelectorBar` 或适合内容的简单选择器 | 用文档式标签页表示无关目标位置 |
| 打开的文档或可关闭工作区 | `TabView` | 让 `NavigationView` 项目伪装成文档 |
| 分层位置路径 | `BreadcrumbBar` | 拼接文本和分隔符 |
| 分层数据 | `TreeView` | 递归嵌套 `ListView` 控件 |
| 列表与选中项 | 列表/详情模式 | 强制在模态窗口中显示所有详情 |
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.
保持顶级导航浅、稳定且带标签。根据内容宽度、本地化、增长空间、窗口宽度和命令密度选择顶部或左侧 `NavigationView`，不要使用统一的项目数量规则。除非体验需要明确的自定义状态，否则让 `PaneDisplayMode="Auto"` 和控件阈值处理常见自适应行为。
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.
仅当页面导航和后退堆栈符合体验时使用 `Frame`。后退导航时保留选择、筛选、滚动和未保存状态。没有可返回位置时不要显示后退按钮。
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.
对于 Windows App SDK 1.7 或更高版本，优先使用 WinUI `TitleBar` 控件自定义标题栏，并与 `NavigationView` 协调。对于更早版本，使用受支持的 `Window.ExtendsContentIntoTitleBar` 和 `Window.SetTitleBar` 方案。保留标题按钮、拖动区域、系统菜单访问、活动/非活动外观和调整大小行为。
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
## 3. 集合与结构化数据
| 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 |
| 以文本为主的可选择集合 | `ListView` | 具有成熟的选择、分组、重排和虚拟化行为 |
| 统一的视觉磁贴 | `GridView` | 使用支持虚拟化的项目面板 |
| 灵活的列表/网格/自定义布局 | `ItemsView` | 支持布局切换并内置选择和无障碍的现代组合方式 |
| 底层自定义虚拟化布局 | `ItemsRepeater` | 选择、调用、焦点和自动化可能需要额外工程工作 |
| 层级 | `TreeView` | 支持单选和多选 |
| 简单只读行列 | 模板化 `ListView`/`ItemsView` | 提供表头和无障碍关系 |
| 完整的电子表格式编辑 | 经验证且持续维护的表格组件 | 验证键盘、UI Automation、虚拟化、排序、调整大小和编辑 |
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.
不要用“20 行”等固定阈值决定使用 `ListView` 还是数据表格。应根据列关系、比较、排序、编辑、选择、虚拟化和键盘导航来选择。
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.
Windows Community Toolkit `DataGrid` 文档已归档；它不是当前 WCT 8+ 的 WinUI 3 控件。对于新项目，评估当前仍在维护的方案，例如 Toolkit Labs `DataTable` 或社区 `WinUI.TableView`，并明确验证其成熟度和要求。不得静默引入依赖。
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.
选择行为应支持 Windows 约定：单击/点击选择单项，Ctrl 独立选择，Shift 范围选择，控件支持时用 Space 选择焦点项，并让可见选择状态与键盘焦点相互独立。
## 4. Input controls and forms
## 4. 输入控件与表单
| 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 |
| 短文本或多行纯文本 | `TextBox` | 多行使用 `AcceptsReturn` 和合适的换行方式 |
| 富格式编辑 | `RichEditBox` | 不要用于普通多行文本 |
| 数值 | `NumberBox` | 仍需验证范围和领域约束 |
| 日期 | `DatePicker` 或 `CalendarDatePicker` | 在常驻选择器和紧凑日历输入间选择 |
| 时间 | `TimePicker` | 尊重区域格式 |
| 立即生效的开/关设置 | `ToggleSwitch` | 清楚标记状态 |
| 表单或批量列表中的选择 | `CheckBox` | 支持选中、未选中和可选的不确定语义 |
| 从少量可见选项中单选 | 分组的 `RadioButton` 控件 | 当空间或选项数量降低扫描效率时使用 `ComboBox` |
| 从紧凑列表中单选 | `ComboBox` | 不支持多选 |
| 多选 | `ListView`、`ItemsView`、复选列表或专用浮出控件 | 让用户能够复查已选值 |
| 有界连续值 | `Slider` | 显示当前值，并在需要时允许精确键盘输入 |
| 评分 | `RatingControl` | 仅用于真实的评分语义 |
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.
将标签放在窄宽度、文本缩放和本地化后仍能保持清晰扫描顺序的位置。需要把独立标签关联到字段时，使用 `AutomationProperties.LabeledBy`。用文字而不是仅用颜色标记必填字段。输入前提供约束，在失焦或提交等合适边界验证，并同时说明问题和恢复方式。
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
## 5. 命令与菜单
Model a command once and expose it through suitable surfaces using `StandardUICommand`, `XamlUICommand`, or the project's `ICommand` pattern.
使用 `StandardUICommand`、`XamlUICommand` 或项目的 `ICommand` 模式，只建模一次命令，再通过合适的界面公开。
| 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 |
| 主要页面命令 | 可见的 `Button` 或 `CommandBar` 命令 |
| 以文档为中心的应用菜单 | `MenuBar` |
| 对象特定命令 | `ContextFlyout`；富命令有帮助时优先 `CommandBarFlyout` |
| 额外或低频命令 | 次要 `CommandBar` 命令或溢出菜单 |
| 拆分默认/备选操作 | `SplitButton` |
| 仅菜单操作集 | `DropDownButton` 或 `MenuFlyout` |
| 高级用户路径 | `KeyboardAccelerator` 加工具提示/菜单快捷键文本 |
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.
让关键命令无需悬停或手势即可发现。在上下文菜单中包含相关上下文命令，使指针、键盘、触控和辅助技术用户都有通用路径。使用访问键实现高效的 Alt 导航，使用快捷键执行重复操作。
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.
使用“删除 3 个文件”等具体操作标签，不要只写“确定”。让破坏性命令在空间上分离并显示后果。操作常见且可恢复时提供撤销。
## 6. Feedback and transient surfaces
## 6. 反馈与临时界面
| 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 |
| 内联状态、警告或可恢复错误 | `InfoBar` | 需要操作时保持可见；不要假设会自动消失 |
| 锚定到 UI 的首次使用教学 | `TeachingTip` | 谨慎展示，不要用于常规状态 |
| 阻塞式决策或不可逆后果 | `ContentDialog` | 仅当应用无法安全选择或无法提供撤销时询问 |
| 上下文选项或详情 | `Flyout` | 可解除，并与来源建立连接 |
| 确定性工作 | `ProgressBar` | 报告有意义的进度 |
| 不确定的短时等待 | `ProgressRing` | 保持周围上下文稳定 |
| 长时间/后台工作 | 页面内进度加取消/后台处理入口 | 不要让用户困在旋转指示器中 |
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
## 7. 常见页面模式
### 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.
使用标题栏、顶级导航、页面标题、上下文命令和内容 Frame 或 Presenter。让标题栏拖动区域与交互式导航和搜索控件分离。
### 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.
仅在验证已安装 Toolkit 软件包后使用 Windows Community Toolkit `SettingsCard` 和 `SettingsExpander`。按用户意图分组，为不明显的后果添加说明，并让可恢复偏好立即生效。仅当更改代价高、延迟生效、涉及安全或无法安全恢复时使用“应用”、重启或确认。
### 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
## 8. 控件评审检查清单
- [ ] 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.
- [ ] 每个控件都匹配用户意图并公开正确语义。
- [ ] 所有 API 和依赖项都存在于项目使用的版本中。
- [ ] 已定义导航、选择、焦点和后退行为。
- [ ] 上下文命令具有无需悬停的访问路径。
- [ ] 集合虚拟化和键盘行为得到保留。
- [ ] 表单保留输入并提供可操作的验证信息。
- [ ] 对话框仅用于真正需要阻塞的决策。
- [ ] 已处理加载、空、错误、超时、取消和撤销状态。
## 9. Official sources
## 9. 官方资料
- [Controls for Windows apps](https://learn.microsoft.com/windows/apps/develop/ui/controls/)
- [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)
- [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)
- [命令系统](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)