339 lines
14 KiB
Markdown
339 lines
14 KiB
Markdown
# API接口字段中文注释设计文档
|
||
|
||
## 1. 概述
|
||
|
||
本文档旨在为项目中所有API接口的字段添加中文注释，以提高代码的可读性和可维护性。通过对SDK、服务层、事件系统等模块中的接口定义进行中文注释，使开发人员能够更快速地理解和使用这些接口。
|
||
|
||
## 2. 设计原则
|
||
|
||
- 保持原有代码结构不变，仅添加中文注释
|
||
- 注释内容准确描述字段的含义和用途
|
||
- 统一注释风格，确保文档一致性
|
||
- 重点注释复杂或容易误解的字段
|
||
|
||
## 3. 接口字段注释规范
|
||
|
||
### 3.1 基本注释格式
|
||
|
||
```typescript
|
||
/**
|
||
* 字段中文描述
|
||
*/
|
||
fieldName: fieldType
|
||
```
|
||
|
||
### 3.2 枚举类型注释格式
|
||
|
||
```typescript
|
||
/**
|
||
* 枚举类型中文描述
|
||
*/
|
||
export enum EnumName {
|
||
/**
|
||
* 枚举值中文描述
|
||
*/
|
||
VALUE1 = 'value1',
|
||
|
||
/**
|
||
* 枚举值中文描述
|
||
*/
|
||
VALUE2 = 'value2',
|
||
}
|
||
```
|
||
|
||
## 4. SDK接口字段注释
|
||
|
||
### 4.1 核心类型定义
|
||
|
||
#### SDKConfig接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ----------- | -------------- | ---------------- |
|
||
| appId | string | 应用唯一标识符 |
|
||
| appName | string | 应用名称 |
|
||
| version | string | 应用版本号 |
|
||
| permissions | string[] | 应用所需权限列表 |
|
||
| debug | boolean (可选) | 是否开启调试模式 |
|
||
|
||
#### APIResponse接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ------- | ------------- | -------------- |
|
||
| success | boolean | 请求是否成功 |
|
||
| data | T (可选) | 返回的数据内容 |
|
||
| error | string (可选) | 错误信息 |
|
||
| code | number (可选) | 错误码 |
|
||
|
||
### 4.2 窗体SDK接口字段注释
|
||
|
||
#### WindowState枚举
|
||
|
||
| 枚举值 | 中文注释 |
|
||
| ---------- | ---------- |
|
||
| NORMAL | 正常状态 |
|
||
| MINIMIZED | 最小化状态 |
|
||
| MAXIMIZED | 最大化状态 |
|
||
| FULLSCREEN | 全屏状态 |
|
||
|
||
#### WindowEvents接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ------------- | --------------------------------------- | -------------------- |
|
||
| onResize | (width: number, height: number) => void | 窗体尺寸变化事件回调 |
|
||
| onMove | (x: number, y: number) => void | 窗体位置移动事件回调 |
|
||
| onStateChange | (state: WindowState) => void | 窗体状态变化事件回调 |
|
||
| onFocus | () => void | 窗体获得焦点事件回调 |
|
||
| onBlur | () => void | 窗体失去焦点事件回调 |
|
||
| onClose | () => void | 窗体关闭事件回调 |
|
||
|
||
### 4.3 存储SDK接口字段注释
|
||
|
||
#### StorageStats接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ------------ | ------ | ------------------ |
|
||
| usedSpace | number | 已使用存储空间(MB) |
|
||
| maxSpace | number | 最大存储空间(MB) |
|
||
| keysCount | number | 存储键数量 |
|
||
| lastAccessed | Date | 最后访问时间 |
|
||
|
||
### 4.4 网络SDK接口字段注释
|
||
|
||
#### NetworkRequestConfig接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ------------ | -------------------------------------------------- | ------------------ |
|
||
| method | HTTPMethod (可选) | HTTP请求方法 |
|
||
| headers | Record<string, string> (可选) | 请求头信息 |
|
||
| body | any (可选) | 请求体数据 |
|
||
| timeout | number (可选) | 请求超时时间(毫秒) |
|
||
| responseType | 'json' \| 'text' \| 'blob' \| 'arrayBuffer' (可选) | 响应数据类型 |
|
||
|
||
#### NetworkResponse接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ---------- | ---------------------- | ------------ |
|
||
| data | T | 响应数据内容 |
|
||
| status | number | HTTP状态码 |
|
||
| statusText | string | HTTP状态文本 |
|
||
| headers | Record<string, string> | 响应头信息 |
|
||
| url | string | 请求URL |
|
||
|
||
### 4.5 事件SDK接口字段注释
|
||
|
||
#### EventMessage接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| --------- | ------ | -------------- |
|
||
| id | string | 消息唯一标识符 |
|
||
| channel | string | 事件频道名称 |
|
||
| data | T | 消息数据内容 |
|
||
| senderId | string | 发送方标识符 |
|
||
| timestamp | Date | 消息发送时间戳 |
|
||
|
||
#### EventSubscriptionConfig接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ------ | ----------------------------------------- | -------------- |
|
||
| filter | (message: EventMessage) => boolean (可选) | 消息过滤器函数 |
|
||
| once | boolean (可选) | 是否只监听一次 |
|
||
|
||
### 4.6 UI SDK接口字段注释
|
||
|
||
#### DialogOptions接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ------------- | ----------------- | ------------------ |
|
||
| title | string (可选) | 对话框标题 |
|
||
| message | string | 对话框消息内容 |
|
||
| type | DialogType (可选) | 对话框类型 |
|
||
| buttons | string[] (可选) | 自定义按钮文本数组 |
|
||
| defaultButton | number (可选) | 默认按钮索引 |
|
||
| cancelButton | number (可选) | 取消按钮索引 |
|
||
|
||
#### NotificationOptions接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| -------- | ----------------------------------------------- | -------------- |
|
||
| title | string | 通知标题 |
|
||
| body | string | 通知正文内容 |
|
||
| icon | string (可选) | 通知图标URL |
|
||
| duration | number (可选) | 显示时长(毫秒) |
|
||
| actions | Array<{ title: string; action: string }> (可选) | 通知操作按钮 |
|
||
|
||
### 4.7 系统SDK接口字段注释
|
||
|
||
#### SystemInfo接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ---------------- | --------------------------------- | -------------- |
|
||
| platform | string | 运行平台信息 |
|
||
| userAgent | string | 用户代理字符串 |
|
||
| language | string | 系统语言设置 |
|
||
| timezone | string | 时区信息 |
|
||
| screenResolution | { width: number; height: number } | 屏幕分辨率 |
|
||
| colorDepth | number | 颜色深度 |
|
||
| pixelRatio | number | 像素比率 |
|
||
|
||
#### AppInfo接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ------------ | -------- | ---------------- |
|
||
| id | string | 应用唯一标识符 |
|
||
| name | string | 应用名称 |
|
||
| version | string | 应用版本号 |
|
||
| permissions | string[] | 应用权限列表 |
|
||
| createdAt | Date | 应用创建时间 |
|
||
| lastActiveAt | Date | 应用最后活跃时间 |
|
||
|
||
## 5. 服务层接口字段注释
|
||
|
||
### 5.1 窗体服务接口字段注释
|
||
|
||
#### WindowConfig接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ----------- | -------------- | ------------------ |
|
||
| title | string | 窗体标题 |
|
||
| width | number | 窗体宽度(像素) |
|
||
| height | number | 窗体高度(像素) |
|
||
| minWidth | number (可选) | 窗体最小宽度(像素) |
|
||
| minHeight | number (可选) | 窗体最小高度(像素) |
|
||
| maxWidth | number (可选) | 窗体最大宽度(像素) |
|
||
| maxHeight | number (可选) | 窗体最大高度(像素) |
|
||
| resizable | boolean (可选) | 是否可调整大小 |
|
||
| movable | boolean (可选) | 是否可移动 |
|
||
| closable | boolean (可选) | 是否可关闭 |
|
||
| minimizable | boolean (可选) | 是否可最小化 |
|
||
| maximizable | boolean (可选) | 是否可最大化 |
|
||
| modal | boolean (可选) | 是否为模态窗体 |
|
||
| alwaysOnTop | boolean (可选) | 是否始终置顶 |
|
||
| x | number (可选) | 窗体X坐标位置 |
|
||
| y | number (可选) | 窗体Y坐标位置 |
|
||
|
||
#### WindowInstance接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| --------- | ------------------------ | ------------------ |
|
||
| id | string | 窗体唯一标识符 |
|
||
| appId | string | 关联应用标识符 |
|
||
| config | WindowConfig | 窗体配置信息 |
|
||
| state | WindowState | 窗体当前状态 |
|
||
| element | HTMLElement (可选) | 窗体DOM元素 |
|
||
| iframe | HTMLIFrameElement (可选) | 窗体内嵌iframe元素 |
|
||
| zIndex | number | 窗体层级索引 |
|
||
| createdAt | Date | 窗体创建时间 |
|
||
| updatedAt | Date | 窗体更新时间 |
|
||
|
||
## 6. 事件系统接口字段注释
|
||
|
||
### 6.1 事件管理器接口字段注释
|
||
|
||
#### IEventMap接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ------------- | ------------------------ | ---------------- |
|
||
| [key: string] | (...args: any[]) => void | 事件处理函数映射 |
|
||
|
||
#### IEventBuilder接口
|
||
|
||
该接口定义了事件管理器的基本方法，无需额外字段注释。
|
||
|
||
### 6.2 窗口事件接口字段注释
|
||
|
||
#### IWindowFormEvent接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| -------------------- | ------------------------------------------- | ---------------- |
|
||
| windowFormMinimize | (id: string) => void | 窗口最小化事件 |
|
||
| windowFormMaximize | (id: string) => void | 窗口最大化事件 |
|
||
| windowFormRestore | (id: string) => void | 窗口还原事件 |
|
||
| windowFormClose | (id: string) => void | 窗口关闭事件 |
|
||
| windowFormFocus | (id: string) => void | 窗口聚焦事件 |
|
||
| windowFormDataUpdate | (data: IWindowFormDataUpdateParams) => void | 窗口数据更新事件 |
|
||
| windowFormCreated | () => void | 窗口创建完成事件 |
|
||
|
||
#### IWindowFormDataUpdateParams接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ------ | ---------------- | ----------------- |
|
||
| id | string | 窗口唯一标识符 |
|
||
| state | TWindowFormState | 窗口状态 |
|
||
| width | number | 窗口宽度 |
|
||
| height | number | 窗口高度 |
|
||
| x | number | 窗口X坐标(左上角) |
|
||
| y | number | 窗口Y坐标(左上角) |
|
||
|
||
## 7. 应用管理接口字段注释
|
||
|
||
### 7.1 应用清单接口字段注释
|
||
|
||
#### InternalAppManifest接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ----------- | -------------------------------------- | ---------------- |
|
||
| id | string | 应用唯一标识符 |
|
||
| name | string | 应用名称 |
|
||
| version | string | 应用版本号 |
|
||
| description | string | 应用描述信息 |
|
||
| author | string | 应用作者 |
|
||
| icon | string | 应用图标 |
|
||
| permissions | string[] | 应用所需权限列表 |
|
||
| window | { width: number; height: number; ... } | 窗体配置信息 |
|
||
| category | string (可选) | 应用分类 |
|
||
| keywords | string[] (可选) | 应用关键字列表 |
|
||
|
||
#### AppRegistration接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| --------- | ------------------- | -------------- |
|
||
| manifest | InternalAppManifest | 应用清单信息 |
|
||
| component | any | Vue组件 |
|
||
| isBuiltIn | boolean | 是否为内置应用 |
|
||
|
||
## 8. UI组件接口字段注释
|
||
|
||
### 8.1 桌面图标接口字段注释
|
||
|
||
#### IDesktopAppIcon接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ------ | ------ | -------------------- |
|
||
| name | string | 图标名称 |
|
||
| icon | string | 图标内容 |
|
||
| path | string | 图标路径 |
|
||
| x | number | 图标在grid布局中的列 |
|
||
| y | number | 图标在grid布局中的行 |
|
||
|
||
### 8.2 网格模板参数接口字段注释
|
||
|
||
#### IGridTemplateParams接口
|
||
|
||
| 字段名 | 类型 | 中文注释 |
|
||
| ---------------- | ------ | -------------- |
|
||
| cellExpectWidth | number | 单元格预设宽度 |
|
||
| cellExpectHeight | number | 单元格预设高度 |
|
||
| cellRealWidth | number | 单元格实际宽度 |
|
||
| cellRealHeight | number | 单元格实际高度 |
|
||
| gapX | number | 列间距 |
|
||
| gapY | number | 行间距 |
|
||
| colCount | number | 总列数 |
|
||
| rowCount | number | 总行数 |
|
||
|
||
## 9. 实施计划
|
||
|
||
1. 对SDK模块中的所有接口字段添加中文注释
|
||
2. 对服务层模块中的接口字段添加中文注释
|
||
3. 对事件系统模块中的接口字段添加中文注释
|
||
4. 对应用管理模块中的接口字段添加中文注释
|
||
5. 对UI组件模块中的接口字段添加中文注释
|
||
6. 审查和验证所有注释的准确性和完整性
|
||
|
||
## 10. 注意事项
|
||
|
||
1. 保持原有代码逻辑不变，仅添加注释
|
||
2. 确保注释内容准确反映字段的实际用途
|
||
3. 统一注释风格，避免表述不一致
|
||
4. 对于已有注释的字段，检查并完善注释内容
|
||
5. 在添加注释时注意不要影响代码的可读性
|