# 可访问性设计

<cite>
**本文引用的文件**
- `README.md`
- `src/index.html`
- `src/main.ts`
- `src/app/app.config.ts`
- `src/app/app.component.html`
- `src/app/app.component.ts`
- `src/app/globalstyle.scss`
- `src/app/gxapp-sidebar/gxapp-sidebar.component.html`
- `src/app/gxapp-footer/gxapp-footer.component.html`
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向 GSDJGXApp 的可访问性设计，围绕键盘导航、屏幕阅读器支持、色彩对比度、内容可读性、表单可访问性、多媒体替代方案、可访问性测试与自动化检测、以及 WCAG 2.1 符合性检查清单进行系统化梳理与改进建议。文档同时结合项目现有实现（如 HTML 语言声明、全局样式、菜单与侧边栏交互、通知 Toast 等）进行逐项分析，并给出落地建议与可视化图示，帮助开发者在不破坏既有架构的前提下提升应用的可访问性水平。

## 项目结构
GSDJGXApp 采用 Angular 22 + Tauri 2 + Rust 的跨平台桌面应用架构，前端通过路由与组件化组织界面，全局样式集中管理，部分第三方 UI 组件库（Syncfusion）用于构建菜单、分割器、通知等控件。整体结构如下：

```mermaid
graph TB
A["浏览器/桌面窗口<br/>src/index.html"] --> B["Angular 引导<br/>src/main.ts"]
B --> C["应用配置<br/>src/app/app.config.ts"]
C --> D["根组件模板<br/>src/app/app.component.html"]
D --> E["根组件逻辑<br/>src/app/app.component.ts"]
E --> F["全局样式<br/>src/app/globalstyle.scss"]
D --> G["侧边栏组件<br/>src/app/gxapp-sidebar/gxapp-sidebar.component.html"]
D --> H["页脚组件<br/>src/app/gxapp-footer/gxapp-footer.component.html"]
```

图表来源
- `src/index.html#L1-L14`
- `src/main.ts#L1-L23`
- `src/app/app.config.ts#L1-L13`
- `src/app/app.component.html#L1-L101`
- `src/app/app.component.ts#L1-L800`
- `src/app/globalstyle.scss#L1-L286`
- `src/app/gxapp-sidebar/gxapp-sidebar.component.html#L1-L26`
- `src/app/gxapp-footer/gxapp-footer.component.html#L1-L104`

章节来源
- `README.md#L1-L118`
- `src/index.html#L1-L14`
- `src/main.ts#L1-L23`
- `src/app/app.config.ts#L1-L13`

## 核心组件
- 根组件与布局：负责菜单、分割器、左右面板、页脚与通知等核心 UI 容器。
- 侧边栏：提供导航图标按钮与用户/设置入口，具备点击交互与活动态样式。
- 页脚：展示工作区路径、估值日、授权状态、服务状态与版本信息。
- 全局样式：统一字体、行高、间距、颜色系统与状态徽章样式，为可访问性提供基础。

章节来源
- `src/app/app.component.html#L1-L101`
- `src/app/app.component.ts#L1-L800`
- `src/app/gxapp-sidebar/gxapp-sidebar.component.html#L1-L26`
- `src/app/gxapp-footer/gxapp-footer.component.html#L1-L104`
- `src/app/globalstyle.scss#L1-L286`

## 架构总览
下图展示了可访问性相关的交互路径与关键节点（键盘焦点、屏幕阅读器、通知与状态呈现）：

```mermaid
sequenceDiagram
participant U as "用户"
participant M as "菜单/侧边栏<br/>gxapp-sidebar"
participant R as "路由/面板容器<br/>app.component"
participant F as "页脚状态<br/>gxapp-footer"
participant T as "通知Toast<br/>app.component"
U->>M : 键盘 Tab/Enter 导航至图标按钮
M-->>R : 触发点击事件并更新 currentId
R->>R : 切换左侧面板/主面板内容
R-->>U : 展示新视图焦点保持在可交互元素
U->>F : 查看授权/服务/版本状态
T-->>U : 以视觉样式区分错误/警告/成功/信息
```

图表来源
- `src/app/app.component.html#L1-L101`
- `src/app/app.component.ts#L304-L384`
- `src/app/gxapp-sidebar/gxapp-sidebar.component.html#L1-L26`
- `src/app/gxapp-footer/gxapp-footer.component.html#L1-L104`

## 详细组件分析

### 键盘导航与焦点管理
- Tab 顺序与焦点可见性
  - 当前实现：菜单与图标按钮通过点击事件驱动导航；未见显式键盘事件绑定与焦点管理代码。
  - 建议：为图标按钮添加可聚焦属性与键盘事件（如 Enter/Space），并在活动项上提供明确的焦点样式与 ARIA 状态。
- 快捷键绑定
  - 当前实现：未发现全局快捷键绑定。
  - 建议：为常用操作（如打开设置、最小化/最大化/关闭窗口）提供可配置的快捷键，并在页脚或帮助中展示。
- 分割器与面板
  - 当前实现：Splitter 控件用于左右面板，但未见键盘可访问性配置。
  - 建议：为分割器添加可调节尺寸的键盘交互（如方向键微调），并确保面板内内容可被键盘完整遍历。

```mermaid
flowchart TD
Start(["用户按下 Tab"]) --> CheckFocus["检查当前焦点元素"]
CheckFocus --> IsButton{"是否为可聚焦按钮？"}
IsButton --> |是| FocusStyle["应用焦点样式"]
IsButton --> |否| NextElement["移动到下一个可聚焦元素"]
FocusStyle --> Action["触发点击/键盘动作"]
NextElement --> CheckFocus
Action --> UpdateUI["更新面板/路由"]
UpdateUI --> End(["完成"])
```

章节来源
- `src/app/app.component.html#L1-L101`
- `src/app/app.component.ts#L304-L384`
- `src/app/gxapp-sidebar/gxapp-sidebar.component.html#L1-L26`

### 屏幕阅读器支持
- HTML 语言与字符集
  - 页面已设置语言为 zh-CN，字符集为 UTF-8，有助于屏幕阅读器正确发音与解析。
- ARIA 标签与角色
  - 当前实现：标题按钮组使用 aria-label 描述“Minimize/Maximize/Close”，有助于识别。
  - 建议：为菜单项、图标按钮、状态徽章、Toast 等添加 aria-label 或 aria-labelledby，明确其语义与状态变化。
- 语义化结构
  - 当前实现：使用 ejs-menu、ejs-splitter 等第三方组件，建议确认其是否输出语义化 HTML 结构（如 nav、ul/li、section 等）。
  - 建议：在自定义区域补充语义标签（如 role="navigation"、aria-live="polite"），并为动态内容提供更新提示。

章节来源
- `src/index.html#L1-L14`
- `src/app/app.component.html#L1-L101`
- `src/app/gxapp-sidebar/gxapp-sidebar.component.html#L1-L26`

### 色彩对比度与色盲友好设计
- 当前实现：全局样式定义了颜色变量（如 primary-blue、warning-yellow、success-green、error-red 等），但未见显式的对比度校验或动态对比度支持。
- 建议：
  - 使用对比度检测工具（如 WebAIM Contrast Checker）验证文本与背景的对比度（至少 4.5:1 用于普通文本，3:1 用于大文本）。
  - 提供色盲友好模式（如 deuteranopia、protanopia、Tritanopia 变体），并通过系统偏好或用户设置启用。
  - 为状态徽章与图标提供非颜色的额外标识（如形状、文字说明）。

章节来源
- `src/app/globalstyle.scss#L33-L93`

### 内容可读性优化
- 字体与行高：全局样式设置了基础字体族与行高，有助于可读性。
- 行间距与段落结构：建议在表单、表格与详情页中统一使用一致的行间距与段落间距，避免密集排版。
- 动态内容：为 Toast、状态徽章与表格内容提供 aria-live 区域，确保屏幕阅读器及时播报。

章节来源
- `src/app/globalstyle.scss#L8-L21`
- `src/app/app.component.ts#L493-L536`

### 表单可访问性
- 标签关联：建议为所有输入控件提供显式 label 关联（for/id 或包裹结构），并为必填字段与禁用状态提供清晰提示。
- 错误提示：当前 Toast 已按类型区分样式，建议为错误信息提供 aria-invalid 与 aria-describedby，引导用户定位问题。
- 输入验证反馈：在提交前与提交后均提供即时反馈，确保键盘用户可感知。

章节来源
- `src/app/app.component.ts#L493-L536`

### 多媒体内容的替代方案
- 图片：为图标与状态徽章提供 alt 文本或 aria-label，确保无图像时仍可理解含义。
- 视频/音频：当前未发现多媒体播放器组件，若后续引入，需提供字幕与音频描述。
- 图表：对于 ECharts/Syncfusion 图表，建议提供可读的标题、数据表与键盘缩放/平移能力。

章节来源
- `src/app/app.component.html#L38-L79`

### 可访问性测试与自动化检测
- 自动化工具
  - Lighthouse：检查对比度、标签完整性、键盘可达性等。
  - axe-core：集成到 CI，对关键页面进行可访问性扫描。
  - Pa11y、Deque Axe：批量检测链接、表单、多媒体等。
- 手动测试
  - 键盘独行：仅使用 Tab/Shift+Tab 遍历，Enter/Space 触发。
  - 屏幕阅读器：NVDA/JAWS/VoiceOver 下浏览菜单、面板与状态。
  - 高对比度模式：Windows 高对比度主题与 macOS 黑白模式。
- 回归测试：在每次重大 UI 变更后执行可访问性回归。

（本节为通用实践指导，无需特定文件来源）

### WCAG 2.1 符合性检查清单
- 可感知（Perceivable）
  - 文本与图标提供替代文本与标签；对比度满足要求；多媒体提供字幕/音频描述。
- 可操作（Operable）
  - 键盘可达；时间限制合理；交互元素可聚焦且有焦点样式。
- 可理解（Understandable）
  - 语言与字符集正确；表单标签与错误提示清晰；状态变化可被感知。
- 强健（Robust）
  - 使用语义化标记；兼容多种辅助技术；错误处理不破坏可访问性。

（本节为通用实践指导，无需特定文件来源）

## 依赖关系分析
- 应用启动与路由
  - 启动入口注册本地化与第三方组件许可证，路由使用 HashLocationStrategy。
- 根组件依赖
  - 依赖菜单、分割器、通知等第三方组件，需关注其可访问性实现与可配置项。
- 全局样式
  - 统一的颜色与间距变量为可访问性提供基础，但需配合对比度与语义化结构使用。

```mermaid
graph LR
Main["main.ts"] --> Config["app.config.ts"]
Config --> Routes["路由配置"]
Main --> Root["app.component.ts"]
Root --> Styles["globalstyle.scss"]
Root --> Sidebar["gxapp-sidebar.html"]
Root --> Footer["gxapp-footer.html"]
```

图表来源
- `src/main.ts#L1-L23`
- `src/app/app.config.ts#L1-L13`
- `src/app/app.component.ts#L1-L800`
- `src/app/globalstyle.scss#L1-L286`
- `src/app/gxapp-sidebar/gxapp-sidebar.component.html#L1-L26`
- `src/app/gxapp-footer/gxapp-footer.component.html#L1-L104`

章节来源
- `src/main.ts#L1-L23`
- `src/app/app.config.ts#L1-L13`
- `src/app/app.component.ts#L1-L800`

## 性能考虑
- 可访问性优化不应显著增加渲染开销；优先使用语义化结构与 CSS 变量，减少不必要的 DOM 层级。
- Toast 与状态提示应避免频繁闪烁，以免影响视觉敏感用户的体验。

（本节为通用指导，无需特定文件来源）

## 故障排查指南
- 焦点丢失
  - 症状：键盘导航中断、焦点跳转异常。
  - 排查：检查路由切换是否重置焦点；为活动项提供明确的焦点样式。
- 屏幕阅读器无法读取动态内容
  - 症状：Toast/状态变化未被播报。
  - 排查：为动态区域添加 aria-live；确保内容更新后可被辅助技术捕获。
- 对比度过低
  - 症状：文本难以辨识。
  - 排查：使用对比度检测工具验证；必要时调整颜色变量或提供高对比度主题。

章节来源
- `src/app/app.component.ts#L493-L536`
- `src/app/globalstyle.scss#L33-L93`

## 结论
GSDJGXApp 在语言与字符集、全局样式与第三方组件方面已具备一定可访问性基础。为进一步提升，建议在键盘导航、ARIA 标签、对比度与色盲友好设计、表单反馈与多媒体替代方案等方面进行系统化改进，并建立自动化与手动相结合的可访问性测试流程，确保符合 WCAG 2.1 标准。

## 附录
- 快速对照要点
  - HTML 语言与字符集：已设置 zh-CN 与 UTF-8。
  - ARIA 标签：标题按钮已使用 aria-label，建议扩展到更多交互元素。
  - 对比度：建议使用工具验证并提供高对比度模式。
  - 键盘可达：为图标按钮添加键盘事件与焦点样式。
  - 动态内容播报：为 Toast 与状态区域添加 aria-live。

章节来源
- `src/index.html#L1-L14`
- `src/app/gxapp-sidebar/gxapp-sidebar.component.html#L1-L26`
- `src/app/app.component.ts#L493-L536`
- `src/app/globalstyle.scss#L33-L93`