qt-ui-design

Qt UI 设计

在输出 UI 之前，请确认你了解：目标平台、屏幕几何尺寸、设计系统、内容优先级、观看距离、区域设置和输入方式。对照对话内容和项目状态，检查以下七项；只询问确实缺失的信息。如果用户无法回答某一项，请选择合理的 Qt 默认值，并在回复中说明，以便用户更正。

对现有设计进行小幅修改——例如 “将确定按钮移到右侧”、“更改此标签”、“将其设为红色”——无需执行检查清单。静默应用第 1 节中的内容，并在相关时检查第 2 节（对比度、点击目标）。

0. 上下文检查（设计前）

使用以下七项判断哪些信息已明确，以及需要询问什么。如果对话或代码库中已经说明某项信息，就不要再次询问。

1. 目标平台 — 桌面、Web 浏览器、移动设备，还是特定硬件（MCU、Raspberry Pi 或其他嵌入式开发板）？
   • 如果是特定开发板：询问是否有该开发板专用的技能；如果有，请加载。
2. 屏幕形状 — 矩形（默认）、正方形还是圆形？
3. 分辨率和 DPI — 是否知道屏幕分辨率和 DPI？（大致值即可。）
4. 设计系统 — 检查项目是否已使用设计系统或 Qt Quick Controls 样式。如果有，请遵循并复用其设计令牌。如果没有，请推荐一种 Qt Quick Controls 样式：Basic、Fusion、Imagine、Material、Universal、iOS 或 FluentWinUI3（iOS 和 FluentWinUI3 样式需要 Qt 6.7 或更高版本）。如果项目遵循第三方设计语言（Material Design 3、Apple Human Interface Guidelines、Fluent 2），请将其令牌映射到相应的 Qt Quick Controls 样式，而不要另行引入一套令牌。
5. 内容优先级 — 此屏幕上哪些信息最重要（主要）、次要和次次要？
6. 观看距离 — 用户距离屏幕多远？（例如，手持约 30 cm、桌面约 60 cm、面板约 1.5 m、墙面约 3 m）
7. 区域设置和输入 — 主要区域设置/语言是什么？是否需要支持 RTL（阿拉伯语、希伯来语、波斯语、乌尔都语）？必须支持哪些输入方式（触控、键盘、鼠标/指针、硬件按钮、语音）？ 如果目标是嵌入式或 MCU 设备，请在做出任何设计决策前完整阅读第 4 节——该节会覆盖多项桌面默认设置。

如果用户要求审核现有设计，请跳至第 5 节（审核）。

---

1. 适用的设计原则（所有目标）

设计时请遵循以下原则。不要逐条询问——请自行参考这些原则做出决策。

内容与布局：

• 黄金比例 + 三分法： 将主要元素放置在视觉交点上。
• 渐进式呈现： 仅显示当前步骤所需的内容。
• 倒金字塔： 先呈现关键信息，再补充细节。
• 模块化： 将复杂流程拆分为更小、独立的屏幕。
• 奥卡姆剃刀： 两种设计效果相同时，选择更简单的一种。
• 性能负载： 步骤越少，任务完成率越高。
• 五类组织法： 按类别、时间、地点、字母顺序或连续性组织内容。 感知与交互：
• 雅各布定律： 符合用户熟悉的模式。
• 示能性： 控件的外观应体现其功能。
• 希克定律： 选项越多，决策越慢。限制每个屏幕上的选项数量。
• 米勒定律： 工作记忆可容纳约 7 项内容。请据此分组。
• 识别优于回忆： 展示选项，而不是要求用户记忆。
• 邻近性 + 相似性： 在视觉上将相关元素分组。
• 统一连通性： 共用边框或颜色的元素属于同一组。
• 冯·雷斯托夫效应： 一个视觉上突出的元素会吸引注意——请谨慎使用。
• 峰终定律： 用户会记住体验的高潮时刻和结尾。设计完成状态（例如安装程序的完成屏幕）时，应让人感到圆满，而非戛然而止。
• 多尔蒂阈值： 在 400 ms 内提供系统反馈，否则显示进度指示器。
• 审美易用性效应： 精致的设计会让人觉得更易用。
• 寻路： 用户必须始终清楚自己当前的位置、来过哪里以及可以前往哪里。 阅读模式（用于指导信息布局）：
• F 型： 适用于文字密集的内容——顶部栏、较短的次级栏，以及沿左侧边缘浏览。
• Z 型： 适用于内容稀疏的页面——从左上角到右上角，再沿对角线移动，最后到右下角。
• 层蛋糕型： 用户会浏览标题并跳过正文。
• 斑点型： 用户会跳转到关键位置——链接、大写字母、列表项。 按钮与 CTA：
• 限制每组中的 CTA 按钮数量。确定 + 取消 = 一组；其他操作必须在视觉上弱化。
• 使用邻近性和相似性来区分主要、次要和第三级控件。 错误预防：
• 设计具有引导性的示能性，帮助用户正确操作。
• 在技术可行的情况下，允许撤销。
• 在执行破坏性或不可逆操作前进行确认。
• 在危险状态下添加警报或提示。 响应式设计（仅限桌面端／Web——嵌入式场景请参见第 4 节）：
• 优先针对主要目标的分辨率进行设计——带浏览器界面的桌面环境、固定分辨率的嵌入式环境，或应用常见的窗口大小调整范围。对于较窄的宽度，将次要内容堆叠、折叠或隐藏。
• 最小布局宽度：240 px。低于此宽度时，将元素堆叠或折叠。
• 空间紧张时，将次要功能隐藏在菜单或下拉列表中。

1.1 动效与动画（桌面端/网页端 — 嵌入式：参见第 4 节）

动效用于传达状态、关系和因果。每个动画都必须具有实际功能，而非仅作装饰。

• **进入动画：**使用减速缓动（快速开始，缓慢结束）。元素应呈现出到达的感觉，而不是突然出现。
• **退出动画：**使用加速缓动（缓慢开始，快速结束）。元素应呈现出离开的感觉，而不是突然消失。
• **直接操作反馈：**在 100 ms 内响应。耗时 > 1 s 的操作必须显示进度指示器；耗时 > 10 s 的操作必须显示预计时间。
• **时长预算：**小元素（图标、徽章）：100–150 ms。中等元素（卡片、面板）：200–300 ms。全屏过渡：300–400 ms。任何 UI 动画都不得超过 500 ms——过慢会让人觉得界面坏了。
• 限制同时播放的动画为一到两个元素。整个屏幕同时动画会让人迷失方向。
• 在 QML/CSS 中只为 transform 和 opacity 添加动画——这两者由 GPU 合成。为几何属性（宽度、高度、锚点）添加动画会触发布局重新计算，导致卡顿。
• **尊重用户对减少动态效果的偏好。**在网页上，将非必要动画置于 prefers-reduced-motion CSS 媒体查询的控制之下。Qt 6.x 没有内置的等效功能：请提供项目级设置（例如绑定到 QSettings 或运行时辅助功能选项的单例属性），并据此控制动画。用户选择关闭动画时，应改为即时过渡——不要只是减慢动画速度。
• **空间一致性：**在屏幕间移动的元素，其动画方向应与目的地相符（对于从左到右布局，前进 = 向左滑动，返回 = 向右滑动）。

1.2 字体排印比例（桌面端/网页端）

嵌入式字体排印参见第 4.4 节。本小节仅适用于桌面端和网页端。

**使用模块化比例推导所有字号。**模块化比例是一组按固定比率关联的数值——每个字号之间都具有数学上的比例关系，从而形成和谐而非随意的字号体系。比率如下；另请参见 https://www.modularscale.com/，其中提供交互式生成器。

如何构建比例

1. 选择基准字号——即在目标观看距离下，正文显示效果最佳的字号。对于约 60 cm 的桌面观看距离，16 px 是可靠的起始值。基准字号即 ms(0)。

2. 选择比率——将基准字号乘以该比率，得到下一个更大的字号；除以该比率，得到下一个更小的字号。根据产品的特性选择： | 比率 | 名称 | 系数 | 特性 | |---|---|---|---| | 8:9 | 大二度 | 1.125 | 紧凑、密集——适用于数据密集型 UI、安装流程 | | 5:6 | 小三度 | 1.200 | 适中——适用于通用桌面应用 | | 4:5 | 大三度 | 1.250 | 开阔、舒适——适用于营销、引导流程 | | 3:4 | 纯四度 | 1.333 | 对比鲜明——适用于仪表板、强调层级 | | 1:1.618 | 黄金分割 | 1.618 | 对比强烈——谨慎使用；各级字号间距较大 |

3. 将比例级映射到用途——为每种字体排印用途分配一个级数。不得添加不在比例体系中的用途；如果需要某个字号，请选择最接近的级数。

示例（基准字号 16 px，纯四度 1.333）

ms()	数值（px，四舍五入）	用途
ms(3)	37.9 → 38 px	展示文本 / 主视觉文本
ms(2)	28.4 → 28 px	页面标题 / H1
ms(1)	21.3 → 21 px	章节标题 / H2
ms(0)	16 px	正文 — 基准字号
ms(-1)	12.0 → 12 px	说明文字 / 标签 / 元数据

每个屏幕最多使用其中的 三个到四个级数。启用超过四种字号会产生视觉噪声。

适用于所有模块化比例尺的规则

• 正文（ms(0)）的最小字号为 16 px（桌面端观看距离约为 60 cm）。主要阅读内容绝不要使用 ms(-1) 或更小的字号。
• **行高：**正文为 1.4–1.6×，标题为 1.1–1.2×（标题所需的行距较小）。
• **行长：**每行 45–75 个字符，阅读体验更舒适。对文本容器使用 max-width，不要让正文横跨整个视口。
• **字重搭配：**正文和说明文字使用常规字重（400），标题使用中等字重（500）。正文中绝不要使用粗体（700）。
• **优先使用系统字体。**默认使用操作系统／平台的系统字体（Windows 上为 Segoe UI Variable，macOS 上为 SF Pro，Android／Linux 上为 Roboto）。只有在品牌有要求且存在 Figma 令牌时，才引入自定义字体。
• **在系统大字体设置下验证。**不要硬编码会忽略操作系统字体缩放的像素值。在 Qt 中，正文优先使用 font.pointSize（它会遵循平台 DPI 缩放），而非 font.pixelSize；也可以使用由 Screen.pixelDensity 驱动的单例来推算字号。在 Web 上使用相对单位（rem）。

Qt/QML 实现

在 QML 中，将比例尺定义为单例（例如 TypeScale.qml），这样引用字号时使用的是角色名称，而非硬编码值：

// TypeScale.qml — generated from modular scale, base 16, ratio 1.333
pragma Singleton
import QtQuick

QtObject {
    readonly property real base:    16   // ms(0)
    readonly property real h2:      21   // ms(1)
    readonly property real h1:      28   // ms(2)
    readonly property real display: 38   // ms(3)
    readonly property real caption: 12   // ms(-1)
}

在组件中通过 TypeScale.h1 引用。基础字号或比例发生变化时，重新计算整个单例——绝不要单独修补某个值。

在 QML 模块中注册该单例，以便导入。使用 qmldir 文件：

module MyApp.Theme
singleton TypeScale 1.0 TypeScale.qml

在 CMake 中使用 qt_add_qml_module：

qt_add_qml_module(myapp_theme
    URI MyApp.Theme
    VERSION 1.0
    QML_FILES TypeScale.qml
)
set_source_files_properties(TypeScale.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)

1.3 多输入方式与键盘导航（桌面端／Web）

每个桌面端和 Web 界面都必须支持多种输入方式。不要只针对指针设备进行设计。

• **必须支持完整的键盘导航。**Tab 顺序必须遵循视觉阅读顺序（从左上到右下，适用于 LTR）。始终显示可见的焦点指示器——在 QML 中，让它由 activeFocus 驱动（例如，边框或缩放绑定到 activeFocus 的 Rectangle），或使用 Control 的样式专属焦点视觉效果。在 Web 上，不要移除焦点环，除非提供经过样式设计的替代效果。
• **不要设置键盘陷阱。**使用键盘导航的用户必须始终能够通过 Escape 或键盘可访问的关闭控件，退出任何模态框、弹出框或叠加层。
• 每个交互元素都必须能通过指针、键盘以及——在 Qt 的无障碍 API 支持的情况下——屏幕阅读器访问。这是硬性要求，而非建议。
• **悬停状态是增强功能，不是主要的信息呈现方式。**悬停时显示的任何信息，也必须能在不使用指针的情况下访问（例如，通过可见标签、专用信息按钮或由键盘触发的工具提示）。
• **触控与指针输入可以共存。**在同时支持触控笔或指针的触控设备上，不要在检测到指针时移除触控目标。

1.4 语义化颜色

颜色应在整个界面中始终如一地传达含义。避免随意选择颜色。

• 使用基于角色的令牌，而非原始十六进制值。 令牌名称应描述颜色所起的作用（交互、表面、表面内容、错误、轮廓），而非颜色的外观（蓝色、深蓝色、灰色 2）。上述角色词汇与 Material Design 3 一致；如果项目采用 Fluent 2 或 Apple Human Interface Guidelines 的设计语言，请映射到这些系统中的对应角色名称，而不要混用不同词汇。如果项目附带 Figma 令牌集，请先手动将令牌复制到单例中，待有提取工具后再使用工具提取。
• QML 中“表面内容”颜色的命名注意事项。 将令牌转换为 QML 属性时，以 on + 大写字母开头的名称（onSurface、onPrimary）会与 QML 的信号处理程序语法冲突，并在加载时出错（“Cannot assign a value to a signal”）；只要同一对象中声明了配对的基础令牌（surface、primary），就会出现此问题——而这正是 Material 对“表面内容”颜色的要求。请重命名 QML 属性（例如 textOnSurface、surfaceForeground）。
• 区分交互颜色与装饰颜色。 按钮上用于表示“此处可点击”的颜色，不应同时用作不会引导用户交互的背景强调色。将交互颜色用于装饰，会让用户误以为不可点击的元素可以点击。
• 状态不能只通过颜色传达。 第 2 节（WCAG）已对此进行说明，但这同样适用于非禁用状态：成功、警告和错误状态都必须同时配有图标或文字标签。
• 深色模式： 从一开始就针对浅色和深色主题进行设计。基于令牌的颜色系统会自动处理这点；如果使用硬编码颜色，则必须明确定义深色变体。
• 颜色含义因文化而异（另见 §1.5）：在西方语境中，红色代表危险，但在一些东亚语境中代表好运。在西方语境中，白色代表纯洁，但在一些东亚语境中代表哀悼。对于安全关键型产品或面向国际市场发布的产品，不要只依靠颜色传达关键信息——务必同时配上文字或通用图标。

1.5 本地化与 RTL 布局

在信息收集环节询问第 7 个问题，并根据回答在此处采取相应措施。

• 日期、时间和数字格式必须适应区域设置。不要硬编码 DD/MM/YYYY 之类的格式字符串。请使用 Qt 的 QLocale 或平台区域设置 API。
• RTL 布局镜像： 对于阿拉伯语、希伯来语、波斯语和乌尔都语，整个布局都要水平镜像。导航方向从右向左。返回按钮指向右侧。表示方向的图标（箭头、尖括号、播放控件）必须翻转。在场景根部附近启用 LayoutMirroring.enabled，并设置 LayoutMirroring.childrenInherit: true；这会处理锚点和 Qt Quick 布局。即使启用了 LayoutMirroring，以下项目仍需特别处理：Text.horizontalAlignment 的默认值、Image 内容（在方向性图标上使用 mirror: true）、自定义 Canvas 绘制，以及任何手动设置的 x 坐标。
• 文本扩展： 翻译后的字符串通常比英文原文长 30–40%。设计容器和按钮时应留出扩展空间，避免为任何面向用户的字符串使用固定宽度容器。
• 图标： 避免使用具有特定文化属性或在不同地区含义不同的图标（例如竖起大拇指、某些手势）。优先使用通用符号（成功用勾号，关闭用 X，搜索用放大镜）。
• 避免将文字嵌入图片或图标。 本地化要求所有文字都存放在字符串资源中——烘焙在素材中的文字无法翻译。

---

2. 无障碍（WCAG 2.2）

交付前，请依据以下要求检查每项设计：

• 可感知： 所有信息都有非视觉形式的对应内容（替代文本、标签）。文本对比度 ≥ 4.5:1，大号文本和 UI 组件的对比度 ≥ 3:1。
• 可操作： 支持完整的键盘导航，且不存在焦点陷阱。无需指针即可触达所有交互目标。
• 易理解： 标签、说明和错误消息应使用浅显易懂的语言。
• 健壮： 标记和结构应能与屏幕阅读器及辅助工具配合使用。
• 传达状态时，绝不能只依赖颜色——始终搭配形状、图标或文字。
• 将操作系统字体大小设为“大”进行测试——验证布局可适应文本缩放，不会出现文本截断或溢出。
• 使用色盲模拟进行测试（最常见的是绿色盲）——确认所有状态变化即使不依赖颜色也能区分。
• 验证焦点顺序——逐个 Tab 浏览所有交互元素，并确认顺序合理。焦点必须始终可见——Qt 侧的焦点指示器模式见 §1.3。

---

3. AI 专属 UX

设计涉及 AI 功能的屏幕时：

• 用户控制： 用户必须能够启动、停止和修改 AI 操作。始终提供“撤销”或“重新生成”功能。
• 透明度： AI 的决策会影响用户时，应说明做出该决策的原因。
• 平稳应对失败： AI 失败时，提供明确的手动替代方案。
• 价值优先于新奇： AI 功能必须解决实际问题，而不是只用于演示。
• 传达不确定性： AI 输出具有概率性。置信度较低或结果可能不准确时，应明确说明——使用审慎措辞（“建议”“大约”“使用前请核查”）、视觉置信度指示器或明确标注。绝不能将概率性输出当作权威事实呈现。对于 Qt AI Assistant 等类似功能，只要答案会影响重大决策，就应提供“显示来源”或“为什么？”入口。
• 延迟处理模式： AI 操作通常需要 1–15 秒。不要显示通用的加载动画——用户无法据此估算时长，等待约 3 秒后会开始焦虑。
  • 流式输出（文本生成）：立即开始呈现部分结果。生成期间，在插入点显示闪烁光标或脉动指示器。
  • 长时间操作（代码生成、图像处理）：显示与预期结果形状相符的骨架屏或占位符，以此吸引用户注意并设定预期。
  • 后台操作（索引、分析）：显示为不显眼且持续存在的状态指示器（状态栏中的进度条、工具栏中的动画图标），而非阻塞式模态窗口。
  • 等待 AI 响应时，绝不要将整个屏幕留白。
• 操作前征得同意： 如果 AI 功能会读取、发送或修改用户数据（文件、代码、设置），应在执行操作前明确告知。提供一行确认语（“此操作将读取您的项目文件以生成建议”）即可——无需使用模态对话框。

---

4. 嵌入式和 MCU 目标

本节覆盖桌面端默认规则。为任何嵌入式、MCU 或硬件受限目标进行设计前，请通读本节。

影响每项决策的硬件信息（如果尚未回答，请在上方的需求收集步骤中收集）：

• 物理像素尺寸和 DPI
• 是否配备 GPU？如果不确定，请假设没有。
• UI 资源可用的 RAM 和闪存空间
• 输入方式：触摸屏、硬件按钮、旋转编码器、指针
• 是否存在特定于开发板的技能

4.1 无 GPU 时的渲染

软件光栅化意味着每种视觉效果都会消耗 CPU 时间。

允许	不允许
扁平纯色填充	渐变
1 px 实线描边	投影
位图（PNG）图标和字体	模糊或透明图层
仅透明度变化的过渡效果	同时移动和淡出的动画
固定像素布局	Flexbox 或流式布局

优先使用位图图标，而非矢量路径——光栅化成本在编译时产生，而非运行时。只有确认有 GPU 时，才放宽这些限制。 例外。 上述限制适用于运行时软件光栅化。Qt Quick Ultralite 通过其静态渲染管线支持编译时烘焙的渐变。一些 MCU 配备了 2D blitter 或小型 GPU，可以放宽禁止模糊和透明度的限制。在将表格视为严格禁令之前，请先核实硬件数据手册和所用的 Qt 工具链。

4.2 布局

• 固定像素布局。不使用流式网格或断点。按照屏幕的精确尺寸进行设计。
• 每个屏幕只处理一项任务。不使用重叠面板。
• 扁平导航：在屏幕之间切换，而非在屏幕内导航。最多 2 层。
• 系统状态（已连接、错误、活动模式）必须始终可见——不使用工具提示或悬停状态。

4.3 交互

• 不使用悬停状态。将悬停触发的内容显示改为明确的按钮或专用屏幕。
• 触控目标最小尺寸：默认 48 px。在某些受控环境（固定握持的医疗仪器、受保护的工业面板）中，经过明确的安全审查后，可以使用更小的目标。需要戴手套的环境（工业、户外）：60–72 px。
• 每项操作都必须提供硬件按钮作为备用方案。不允许仅通过触控操作。
• 除非硬件确认支持，否则不使用拖动、滚动惯性或多点触控。
• 控制物理执行器的任何操作之前都必须进行确认。

4.4 排版

嵌入式字体是位图——大小在构建时固定。请从一开始就设置正确。

观看距离	最小字号
~50 cm（手持设备、家电）	最小 14 px，推荐 16 px
~1.0–1.5 m（HMI、仪表盘）	最小 20 px
~2–3 m（墙面面板、公共显示屏）	最小 28 px

所有文本的对比度均须 ≥ 4.5:1。嵌入式屏幕的可视角度往往较差，且环境光较强——对比度越高越好。

4.5 错误与安全

• 执行不可逆的物理执行器命令之前必须进行确认——这是安全要求。
• 错误状态指示必须保持显示：由应用状态驱动，而非瞬态 UI 状态。屏幕重绘后也必须保留。
• 警报需要三种相互独立的提示：颜色 + 形状 + 文本。
• 定义一个安全默认屏幕，以便应用崩溃或失去通信时，UI 返回该屏幕。
• 不允许静默失败——未确认的硬件命令必须以可见方式显示。

4.6 桌面端 → MCU 快速参考

规则	桌面端 / Web	MCU / 嵌入式
响应式设计	Flexbox、流式布局	固定像素布局
动画	缓动曲线，≤ 400 ms	仅透明度变化，< 200 ms
渐进式披露	工具提示、悬停	仅使用明确的按钮
触控目标	推荐 44 px	默认 48 px（仅在经过明确的安全审查后放宽）
字体渲染	矢量、由 OS 缩放	位图、在构建时固定
状态提示	颜色 + 基于令牌	颜色 + 形状 + 文本
错误恢复	撤销	操作前确认
状态可见性	状态栏 / 工具提示	始终显示在屏幕上
导航层级	不限	最多 2 层
本地化	QLocale、RTL 镜像	仅 QLocale（RTL 很少适用）

---

5. 审核说明

审核现有设计时，请为每项发现分类：

1. Critical — 违反核心 UX 定律或 WCAG 无障碍规则。必须修复。
2. Warning — 可能造成使用阻力或增加认知负荷。应该修复。
3. Opportunity — 改进或由 AI 驱动的优化。可以考虑。 如果目标是嵌入式环境，请先应用第 4 节中的约束。

桌面端/网页端目标的扩展审核清单：

• 动效：动画是否 ≤ 400 ms、具备实际功能，并提供减少动态效果的方案？
• 字体排版：正文是否 ≥ 16 px，且每个屏幕使用的字号不超过三种？
• 键盘：所有交互元素是否都能仅使用键盘访问和操作？
• 颜色：所有颜色是否都基于设计令牌或采用语义化命名？所有状态变化是否都同时使用另一种提示？
• 本地化：所有用户可见文本是否都采用符合区域设置的格式？容器是否能为译文扩展 30–40% 的空间？
• AI 功能：是否按照第 3 节的要求处理延迟模式、不确定性和用户同意？

---

6. 参考资料

• Nielsen Norman Group — 10 条可用性启发式： https://www.nngroup.com/articles/ten-usability-heuristics/
• UX 定律： https://lawsofux.com/
• WCAG 2.2： https://www.w3.org/TR/WCAG22/
• Modular Scale 计算器： https://www.modularscale.com/
• Apple 人机界面指南： https://developer.apple.com/design/human-interface-guidelines
• Microsoft Fluent 2 设计原则： https://fluent2.microsoft.design/design-principles
• Google Material Design 3 基础： https://m3.material.io/foundations
• Qt QLocale（本地化 API）： https://doc.qt.io/qt-6/qlocale.html
• Qt LayoutMirroring（RTL）： https://doc.qt.io/qt-6/qml-qtquick-layoutmirroring.html