# NyouOS UI 开发指南

[简体中文](fluent-ui-guide.md) | [English](fluent-ui-guide-en.md)

本文说明 NyouOS-On-Web 2.0 的视觉基础、 组件工厂与  应用框架。所有接口均来自当前的 、 和对应 CSS。

架构与应用注册流程见[开发者指南](DEVELOPER_GUIDE.md)。

## 设计原则

- 优先复用系统令牌和组件，不在应用内复制一套按钮、输入框或模态框。
- 组件构造函数返回真实 DOM 节点，而不是 HTML 字符串或虚拟 DOM。
- 用户内容使用 ；只有受信任模板才写入 。
- 所有交互在浅色、深色、关闭模糊和关闭动画时都应清晰可用。
- 图标从  读取；常规态用 ，激活态可用 。
- 布局要适应窗口缩放，而不是只适配全屏桌面。

## CSS 令牌与主题

基础令牌定义在  的 ，深色主题由  覆盖。应用样式应使用变量：



### 常用令牌

| 分类 | 变量 |
| --- | --- |
| 背景 | , ,  |
| 文本 | , ,  |
| 强调色 | , , ,  |
| 边框/阴影 | ,  |
| 圆角 |  8px、 12px、 16px、 20px |
| 模糊 |  8px、 12px、 16px |
| 动画 | , , ,  |

不要把浅色模式的  或固定蓝色写进业务组件。强调色可由用户或壁纸动态改变， 会更新相关变量。

### 材质开关

系统通过  类和变量控制模糊、窗口材质、动画及 NyouOS V2 外观。应用不应直接更改这些全局类。需要响应设置时监听：



动画关闭时 CSS 和窗口管理器会缩短或移除过渡。不要用无法取消的固定  作为业务状态的唯一来源。

## 图标

 的图标名称对应不带扩展名的 SVG 文件：



新增图标前先检查  与 。文件名区分空格和大小写；引用不存在的 fill 图标时不会自动回退。

## FluentUI 基础

 是全局 DOM 工厂。大多数组件接受 、，并立即返回一个 ：



组件不会自动挂载，也不会形成响应式数据绑定。状态变化后由调用方更新 DOM 或重新渲染。

## 按钮

### Button



设置  时按钮自动禁用并显示 spinner。异步操作若要恢复状态，通常应重建按钮或直接同步其属性和内容。

### IconButton



纯图标按钮必须提供有意义的 ，必要时由调用方补充 。

## 输入与选择

### Input / SearchBox



返回值是 wrapper；原生输入框位于 。如需 、selection 或额外 ARIA 属性，先查询内部 input。

### Select

这是自定义下拉菜单，不是原生 ：



### Toggle



Toggle 会维护  和 。

### Slider



回调值是数值。高频拖动中避免同步执行昂贵网络或大 DOM 重绘。

### SegmentedControl



## 导航组件

### NavigationBar



 和  可传字符串或 DOM 节点。外部/用户字符串不要直接作为 HTML 传入。

### ToolBar



### Breadcrumb



### TabBar



## 内容与反馈

### Card



 可传字符串或 DOM 节点； 当前只接受 HTML 字符串。字符串会作为受信任 HTML 处理，因此动态数据应先转义或改为给  传节点。需要交互式页脚时，可自行创建卡片结构或在卡片生成后挂载节点。

### List



### Progress / Spinner



### Empty



### SettingItem



### ScrollArea



它提供自定义滚动条。普通应用页面若已放入  的 ，通常不需要再嵌套 ScrollArea。

## 菜单和对话框

### ContextMenu



菜单项通过各自的  执行动作。组件提供  与 ；挂载、点击外部关闭和生命周期仍由调用方处理。

### Dialog

用于系统提示、警告和错误：



按钮最多取前三个。

### InputDialog



 返回  表示通过，返回字符串会显示为错误消息。

### Modal

 适合自定义标题、内容与按钮的通用覆盖层：



### Toast 与通知中心



Toast 是瞬时 UI，不持久化。需要出现在通知中心时使用：



## FluentWindow 应用框架

 不是系统窗口管理器。它负责“窗口内部”的侧栏、导航、高亮、页面区域、响应式折叠、侧栏搜索和滚动位置；外层窗口仍由  创建。



 在初次挂载和后续切页时调用。渲染应只操作给定 ：



### 侧栏搜索



### 实例 API

| 方法/属性 | 用途 |
| --- | --- |
|  | 切换页面； 可重置滚动 |
|  |  的简写 |
|  | 重新调用当前页渲染器 |
|  | 断开 observer、监听和宿主样式；关闭应用时必须调用 |
|  /  | 手动管理当前页滚动位置 |
|  | 启用或隐藏侧栏搜索 |
|  | 手动设置搜索结果 |
|  /  | 清空或聚焦搜索框 |
|  | 获取当前查询文本 |
| , , ,  | 当前状态和关键 DOM 节点 |

应用关闭时：



## 可访问性与键盘

- 可点击元素优先使用 ，不要只给  绑定 click。
- 图标装饰可用空 ；传达含义的图标必须有文本、 或 。
- 模态框打开后应把焦点移入，关闭后恢复触发元素焦点。
- 自定义组件若扩展键盘行为，应支持 /，并正确设置 role 和状态属性。
- 不覆盖系统级  快捷键；文本编辑区也不要拦截无关按键。
- 文本和关键边界不能只依靠半透明材质，在纯色/高亮背景上也要保持对比度。

## 响应式与性能

- 应用的最小尺寸在  中声明，并在该尺寸实测。
- 使用 grid/flex、、 和容器宽度，不依赖屏幕绝对坐标。
- 远程图片提供加载与失败状态；大图和媒体使用 Blob/IndexedDB，及时释放 。
- 重复初始化前清理 document/window 监听、interval、observer、媒体流和未完成请求。
- 、slider、resize 等高频事件中进行节流，避免反复整体渲染。
- 背景窗口实现 /，暂停动画、媒体和轮询。

## 组件选择速查

| 需求 | 首选 |
| --- | --- |
| 普通操作/主操作 |  |
| 无文本工具操作 |  /  |
| 布尔设置 |  +  |
| 少量互斥视图 |  |
| 多文档切换 |  |
| 应用分区导航 |  |
| 短暂操作反馈 |  |
| 可追溯系统消息 |  |
| 危险操作确认 |  |
| 获取单个短文本 |  |
| 空列表提示 |  |
| 非确定等待 |  |
| 确定进度 |  |

新增组件前先搜索现有应用。这个项目的视觉一致性主要来自复用，而不是继续增加近似但不兼容的控件。