mirror of
https://github.com/Tencent/tmagic-editor.git
synced 2026-05-08 17:48:47 +00:00
3eb8cc0614
补全方法的参数类型、返回值类型与详情说明，规范字段编辑器/字段配置/运行时 API 等文档。 Co-authored-by: Cursor <cursoragent@cursor.com>
231 lines
5.1 KiB
Markdown
231 lines
5.1 KiB
Markdown
# DataSource（基础数据源）
|
||
|
||
`DataSource` 是 `@tmagic/data-source` 的基础数据源类，用于静态数据管理。
|
||
|
||
## 构造函数
|
||
|
||
```typescript
|
||
new DataSource(options: DataSourceOptions)
|
||
```
|
||
|
||
### DataSourceOptions
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `schema` | `DataSourceSchema` | 数据源配置 |
|
||
| `app` | `TMagicApp` | 应用实例 |
|
||
| `initialData` | `Record<string, any>` | 初始数据（可选） |
|
||
| `useMock` | `boolean` | 使用 Mock 数据（可选） |
|
||
| `request` | `RequestFunction` | 请求函数（可选） |
|
||
| `ObservedDataClass` | `ObservedDataClass` | 观察者数据类（可选） |
|
||
|
||
### DataSourceSchema
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | `string` | 数据源 ID |
|
||
| `type` | `'base'` | 数据源类型 |
|
||
| `title` | `string` | 数据源标题（可选） |
|
||
| `description` | `string` | 数据源描述（可选） |
|
||
| `fields` | `DataSchema[]` | 字段配置 |
|
||
| `methods` | `CodeBlockContent[]` | 自定义方法配置（可选） |
|
||
| `mocks` | `MockSchema` | Mock 数据配置（可选） |
|
||
| `events` | `EventConfig[]` | 事件配置（可选） |
|
||
|
||
## 属性
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | `string` | 数据源 ID（只读） |
|
||
| `type` | `string` | 数据源类型，值为 `'base'` |
|
||
| `schema` | `DataSourceSchema` | 配置 schema |
|
||
| `fields` | `DataSchema[]` | 字段配置 |
|
||
| `methods` | `CodeBlockContent[]` | 自定义方法配置 |
|
||
| `data` | `any` | 当前数据 |
|
||
| `isInit` | `boolean` | 是否已初始化 |
|
||
|
||
## 实例方法
|
||
|
||
### setData
|
||
|
||
- **参数：**
|
||
- `{any} data` 数据
|
||
- `{string} path` 数据路径（可选）
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
设置数据源数据。如果指定路径，则只更新该路径的数据。
|
||
|
||
- **示例：**
|
||
|
||
```typescript
|
||
// 设置整个数据
|
||
ds.setData({ name: 'test', count: 10 });
|
||
|
||
// 设置特定路径的数据
|
||
ds.setData('newValue', 'user.name');
|
||
```
|
||
|
||
### setValue
|
||
|
||
- **参数：**
|
||
- `{string} path` 数据路径
|
||
- `{any} data` 数据
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
按路径设置数据，等同于 `setData(data, path)`。
|
||
|
||
- **示例：**
|
||
|
||
```typescript
|
||
ds.setValue('user.age', 25);
|
||
```
|
||
|
||
### setFields
|
||
|
||
- **参数：**
|
||
- `{DataSchema[]} fields` 字段配置
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
设置数据源的字段配置 `fields`。一般在初始化或 schema 更新后调用。
|
||
|
||
### setMethods
|
||
|
||
- **参数：**
|
||
- `{CodeBlockContent[]} methods` 自定义方法配置
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
设置数据源的自定义方法配置 `methods`。
|
||
|
||
### onDataChange
|
||
|
||
- **参数：**
|
||
- `{string} path` 数据路径
|
||
- `{(payload: any) => void} callback` 回调函数
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
监听指定路径的数据变化。
|
||
|
||
::: warning callback 入参取决于 `ObservedData` 实现
|
||
- `SimpleObservedData`（默认）：路径监听触发时，回调收到的是 `{ updateData, path }` 形式的 `ChangeEvent`，**不是**纯粹的 newVal。仅在 `options.immediate` 分支会以「当前路径值」回调一次。
|
||
- `DeepObservedData`（基于 `deep-state-observer`）：回调入参贴近「值」的语义。
|
||
|
||
如需统一拿到「最新值」，可在回调里用 `ds.getData(path)` 主动读取。
|
||
:::
|
||
|
||
- **示例：**
|
||
|
||
```typescript
|
||
ds.onDataChange('user.name', (payload) => {
|
||
// SimpleObservedData 下 payload 形如 { updateData, path }
|
||
console.log('user.name 变更，最新值:', ds.getData('user.name'));
|
||
});
|
||
```
|
||
|
||
### offDataChange
|
||
|
||
- **参数：**
|
||
- `{string} path` 数据路径
|
||
- `{(payload: any) => void} callback` 回调函数（与 `onDataChange` 相同的引用）
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
取消监听数据变化。
|
||
|
||
### getDefaultData
|
||
|
||
- **返回：**
|
||
- `{any}` 默认数据
|
||
|
||
- **详情：**
|
||
|
||
根据字段配置获取默认数据。
|
||
|
||
### init
|
||
|
||
- **返回：**
|
||
- `{Promise<void>}`
|
||
|
||
- **详情：**
|
||
|
||
初始化数据源。
|
||
|
||
### destroy
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
销毁数据源，清理资源。
|
||
|
||
## 事件
|
||
|
||
DataSource 继承自 EventEmitter，支持以下事件：
|
||
|
||
| 事件名 | 说明 | 回调参数 |
|
||
|--------|------|----------|
|
||
| `change` | 数据变化时触发 | `(changeEvent: ChangeEvent)`，`ChangeEvent` 形如 `{ updateData, path? }` |
|
||
|
||
### 示例
|
||
|
||
```typescript
|
||
ds.on('change', (changeEvent) => {
|
||
console.log('数据已变化', changeEvent.updateData, changeEvent.path);
|
||
});
|
||
```
|
||
|
||
## 字段配置 (DataSchema)
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `name` | `string` | 字段名 |
|
||
| `type` | `string` | 字段类型 |
|
||
| `title` | `string` | 字段标题（可选） |
|
||
| `description` | `string` | 字段描述（可选） |
|
||
| `defaultValue` | `any` | 默认值（可选） |
|
||
| `fields` | `DataSchema[]` | 子字段（对象类型时）（可选） |
|
||
|
||
### 字段配置示例
|
||
|
||
```typescript
|
||
const schema = {
|
||
id: 'user_ds',
|
||
type: 'base',
|
||
fields: [
|
||
{ name: 'id', type: 'number', defaultValue: 0 },
|
||
{ name: 'name', type: 'string', defaultValue: '' },
|
||
{
|
||
name: 'profile',
|
||
type: 'object',
|
||
fields: [
|
||
{ name: 'avatar', type: 'string' },
|
||
{ name: 'bio', type: 'string' }
|
||
]
|
||
}
|
||
]
|
||
};
|
||
```
|