tmagic-editor/docs/runtime-api/data-source/dataSource.md

DataSource（基础数据源）

DataSource 是 @tmagic/data-source 的基础数据源类，用于静态数据管理。

构造函数

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}

• 详情：

  设置数据源数据。如果指定路径，则只更新该路径的数据。

• 示例：

// 设置整个数据
ds.setData({ name: 'test', count: 10 });

// 设置特定路径的数据
ds.setData('newValue', 'user.name');

setValue

• 参数：

  • {string} path 数据路径
  • {any} data 数据

• 返回：

  • {void}

• 详情：

  按路径设置数据，等同于 setData(data, path)。

• 示例：

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) 主动读取。 :::

• 示例：

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? }

示例

ds.on('change', (changeEvent) => {
  console.log('数据已变化', changeEvent.updateData, changeEvent.path);
});

字段配置 (DataSchema)

参数	类型	说明
name	string	字段名
type	string	字段类型
title	string	字段标题（可选）
description	string	字段描述（可选）
defaultValue	any	默认值（可选）
fields	DataSchema[]	子字段（对象类型时）（可选）

字段配置示例

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' }
      ]
    }
  ]
};