176 lines
6.0 KiB
Markdown
176 lines
6.0 KiB
Markdown
以下是为提供的代码编写的 **Markdown 格式技术文档**，清晰地描述了代码的功能、结构、类与函数说明，并对 `uitype` 类型进行了归纳。
|
||
|
||
---
|
||
|
||
# 技术文档：UI 类型视图系统（View System）
|
||
|
||
## 概述
|
||
|
||
本模块实现了一个基于 JavaScript 的轻量级 UI 视图渲染系统，用于根据不同的字段类型（`uitype`）生成对应的显示组件。系统支持多种数据类型的可视化展示，如字符串、密码、数字、邮箱等，并通过注册机制将特定 `uitype` 映射到对应的视图类。
|
||
|
||
该系统适用于表单字段、数据展示界面或低代码平台中的动态 UI 渲染场景。
|
||
|
||
---
|
||
|
||
## 支持的 uitype 类型
|
||
|
||
以下为系统预定义并可扩展的字段类型（`uitype`），用于控制如何渲染数据：
|
||
|
||
| uitype | 说明 |
|
||
|--------------|------|
|
||
| `str` | 普通字符串，直接显示文本内容 |
|
||
| `password` | 密码字段，显示为 `****` 隐藏实际值 |
|
||
| `int` | 整数类型（暂未实现具体视图） |
|
||
| `float` | 浮点数类型（暂未实现具体视图） |
|
||
| `tel` | 电话号码（暂未实现具体视图） |
|
||
| `email` | 邮箱地址（暂未实现具体视图） |
|
||
| `file` | 文件上传/链接（暂未实现具体视图） |
|
||
| `'check` | 布尔检查框（可能为拼写错误，应为 `check` 或 `checkbox`）|
|
||
| `checkbox` | 复选框（布尔值）|
|
||
| `date` | 日期类型（暂未实现具体视图） |
|
||
| `text` | 多行文本（暂未实现具体视图） |
|
||
| `code` | 代码块显示（暂未实现具体视图） |
|
||
| `video` | 视频媒体（暂未实现具体视图） |
|
||
| `audio` | 音频媒体（暂未实现具体视图） |
|
||
|
||
> 注：当前仅实现了 `str` 和 `password` 两种类型的视图组件。
|
||
|
||
---
|
||
|
||
## 核心 API 说明
|
||
|
||
### `ViewStr(desc) → Widget`
|
||
|
||
创建一个用于显示字符串字段的文本组件。
|
||
|
||
#### 参数
|
||
- `desc` (Object): 字段描述对象，包含以下属性：
|
||
- `value` (string): 要显示的字符串值。
|
||
- `row_data` (optional, any): 关联的原始行数据（可用于后续交互）。
|
||
|
||
#### 返回值
|
||
- `Widget`: 一个 `Text` 类型的 UI 组件，左对齐显示文本。
|
||
|
||
#### 示例
|
||
```js
|
||
var widget = ViewStr({ value: "Hello World", row_data: { id: 1 } });
|
||
// 渲染出显示 "Hello World" 的文本组件
|
||
```
|
||
|
||
#### 内部逻辑
|
||
- 使用 `Text({ text: ..., halign: 'left' })` 创建文本控件。
|
||
- 若 `desc.row_data` 存在，则将其附加到返回组件的 `data` 属性上，便于后续操作。
|
||
|
||
> ⚠️ 注意：当前版本中 `w.desc_object = desc;` 在 `ViewStr` 中设置的是 `desc_object`，而在 `ViewPassword` 中是 `data`，建议统一命名以避免混淆。
|
||
|
||
---
|
||
|
||
### `ViewPassword(desc) → Widget`
|
||
|
||
创建一个用于显示密码字段的安全文本组件，隐藏真实值。
|
||
|
||
#### 参数
|
||
- `desc` (Object): 字段描述对象，包含以下属性：
|
||
- `value` (string): 实际密码值（不会显示）。
|
||
- `row_data` (optional, any): 关联的原始行数据（可用于点击后查看明文或其他行为）。
|
||
|
||
#### 返回值
|
||
- `Widget`: 一个显示 `"****"` 的 `Text` 组件，左对齐。
|
||
|
||
#### 示例
|
||
```js
|
||
var widget = ViewPassword({ value: "secret123", row_data: userRecord });
|
||
// 显示为 "****"，保护隐私
|
||
```
|
||
|
||
#### 内部逻辑
|
||
- 文本固定显示为 `"****"`，防止泄露密码。
|
||
- 若存在 `row_data`，则挂载至组件 `data` 属性，可用于事件回调。
|
||
|
||
---
|
||
|
||
### `uitypesdef.setViewKlass(uitype, viewClass)`
|
||
|
||
注册指定 `uitype` 对应的视图构造函数。
|
||
|
||
#### 示例用法
|
||
```js
|
||
uitypesdef.setViewKlass('str', ViewStr);
|
||
```
|
||
将 `str` 类型字段的视图类设置为 `ViewStr`。
|
||
|
||
> 此方法属于外部依赖 `uitypesdef` 对象，需确保其已全局可用。
|
||
|
||
---
|
||
|
||
## 类定义
|
||
|
||
### `class ViewType extends JsWidget`
|
||
|
||
所有视图类的基类，继承自 `JsWidget`。
|
||
|
||
#### 构造函数
|
||
```js
|
||
constructor(opts)
|
||
```
|
||
调用父类构造函数，初始化基础组件选项。
|
||
|
||
> 当前无额外逻辑，作为扩展基类使用。
|
||
|
||
---
|
||
|
||
### `class ViewStr extends ViewType`
|
||
|
||
`str` 类型字段的具体视图类（目前为空实现，功能由工厂函数完成）。
|
||
|
||
> ⚠️ 当前存在不一致：`ViewStr` 同时以函数和类的形式出现，可能导致命名冲突或维护困难。
|
||
|
||
#### 建议改进
|
||
- 移除 `ViewStr` 函数，完全使用类构造；
|
||
- 或重命名函数为 `createViewStr`，保持类名唯一性。
|
||
|
||
---
|
||
|
||
## 设计问题与改进建议
|
||
|
||
| 问题 | 描述 | 建议 |
|
||
|------|------|-------|
|
||
| 1. 工厂函数与类同名 | `ViewStr` 既是函数又是类，易造成混淆 | 区分命名，例如函数改为 `createViewStr()` |
|
||
| 2. 属性命名不一致 | `ViewStr` 设置 `desc_object`，`ViewPassword` 设置 `data` | 统一为 `data` 或 `sourceDesc` |
|
||
| 3. `'check` 类型异常 | 类型名以单引号开头，可能是笔误 | 应修正为 `check` 或 `switch` |
|
||
| 4. 缺乏事件处理 | 所有视图均为静态显示 | 可添加点击显示密码等功能 |
|
||
| 5. 未实现多数 uitype | 列出 13 种类型但仅实现 2 种 | 应逐步补全或标记为“待实现” |
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
```js
|
||
// 显示用户名
|
||
const nameField = { value: "Alice", row_data: userData };
|
||
const nameLabel = ViewStr(nameField);
|
||
|
||
// 显示密码（隐藏）
|
||
const pwdField = { value: "p@ssw0rd", row_data: userData };
|
||
const pwdLabel = ViewPassword(pwdField);
|
||
|
||
// 注册到系统
|
||
uitypesdef.setViewKlass('str', ViewStr);
|
||
uitypesdef.setViewKlass('password', ViewPassword);
|
||
```
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
本模块构建了一个灵活的 UI 视图映射框架，允许根据不同字段类型动态渲染合适的显示组件。尽管目前仅实现了部分功能，但其设计具备良好的扩展性，适合进一步发展为完整的低代码前端渲染引擎。
|
||
|
||
---
|
||
|
||
> ✅ **状态**：原型阶段，核心机制可行，需优化命名一致性与完整性。
|
||
> 📦 **适用场景**：表单预览、后台管理系统、配置面板等需要动态 UI 渲染的场合。
|
||
|
||
---
|
||
|
||
*文档版本：1.0*
|
||
*最后更新：2025-04-05* |