mirror of
https://github.com/Tencent/tmagic-editor.git
synced 2026-05-31 12:48:05 +00:00
8dae67769c
- dataSourceService / codeBlockService 新增 undo / redo / canUndo / canRedo 方法 - undo/redo 内部复用 add / update / remove / setCodeDslByIdSync / deleteCodeDslByIds 写回， 并强制 doNotPushHistory，借此自动驱动 initService 中的依赖收集链路 （DepTargetType.DATA_SOURCE / DATA_SOURCE_COND / DATA_SOURCE_METHOD / CODE_BLOCK） - 更新场景下若 step 带 changeRecords，按 propPath 局部 patch，不冲掉同节点其它无关变更； 缺省退化为整 schema / 整内容替换 - 补充对应单测与 API 文档
649 lines
13 KiB
Markdown
649 lines
13 KiB
Markdown
# dataSourceService方法
|
||
|
||
## get
|
||
|
||
- **参数：**
|
||
- `{StateKey}` name 状态键名
|
||
|
||
- **返回：**
|
||
- `{any}` 对应的状态值
|
||
|
||
- **详情：**
|
||
|
||
获取数据源服务的内部状态
|
||
|
||
可用的状态键：
|
||
- `datasourceTypeList`: 数据源类型列表
|
||
- `dataSources`: 当前数据源列表
|
||
- `editable`: 是否可编辑
|
||
- `configs`: 数据源表单配置
|
||
- `values`: 数据源默认值
|
||
- `events`: 数据源事件列表
|
||
- `methods`: 数据源方法列表
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
const dataSources = dataSourceService.get("dataSources");
|
||
console.log(dataSources);
|
||
```
|
||
|
||
## set
|
||
|
||
- **参数：**
|
||
- `{StateKey}` name 状态键名
|
||
- `{any}` value 状态值
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
设置数据源服务的内部状态
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
dataSourceService.set("editable", false);
|
||
```
|
||
|
||
## getFormConfig
|
||
|
||
- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是
|
||
|
||
- **参数：**
|
||
- `{string}` type 数据源类型，默认为 'base'
|
||
|
||
- **返回：**
|
||
- {`FormConfig`} 表单配置
|
||
|
||
::: details 查看 FormConfig 及关联类型定义
|
||
<<< @/../packages/form-schema/src/base.ts#FormConfig{ts}
|
||
|
||
<<< @/../packages/form-schema/src/base.ts#FormItemConfig{ts}
|
||
|
||
<<< @/../packages/form-schema/src/base.ts#ChildConfig{ts}
|
||
|
||
<<< @/../packages/form-schema/src/base.ts#DynamicTypeConfig{ts}
|
||
|
||
<<< @/../packages/form-schema/src/base.ts#FormItem{ts}
|
||
:::
|
||
|
||
- **详情：**
|
||
|
||
获取指定类型数据源的表单配置
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
const config = dataSourceService.getFormConfig("http");
|
||
console.log(config);
|
||
```
|
||
|
||
## setFormConfig
|
||
|
||
- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是
|
||
|
||
- **参数：**
|
||
- `{string}` type 数据源类型
|
||
- {`FormConfig`} config 表单配置
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
设置指定类型数据源的表单配置
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
dataSourceService.setFormConfig("http", [
|
||
{
|
||
name: "url",
|
||
text: "请求地址",
|
||
type: "text",
|
||
},
|
||
{
|
||
name: "method",
|
||
text: "请求方法",
|
||
type: "select",
|
||
options: [
|
||
{ text: "GET", value: "GET" },
|
||
{ text: "POST", value: "POST" },
|
||
],
|
||
},
|
||
]);
|
||
```
|
||
|
||
## getFormValue
|
||
|
||
- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是
|
||
|
||
- **参数：**
|
||
- `{string}` type 数据源类型，默认为 'base'
|
||
|
||
- **返回：**
|
||
- {Partial<`DataSourceSchema`>} 数据源默认值
|
||
|
||
::: details 查看 DataSourceSchema 及关联类型定义
|
||
<<< @/../packages/schema/src/index.ts#DataSourceSchema{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#DataSchema{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#MockSchema{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#CodeBlockContent{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#CodeParam{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#EventConfig{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#JsEngine{ts}
|
||
:::
|
||
|
||
- **详情：**
|
||
|
||
获取指定类型数据源的默认值
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
const defaultValue = dataSourceService.getFormValue("http");
|
||
console.log(defaultValue);
|
||
```
|
||
|
||
## setFormValue
|
||
|
||
- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是
|
||
|
||
- **参数：**
|
||
- `{string}` type 数据源类型
|
||
- {Partial<`DataSourceSchema`>} value 数据源默认值
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
设置指定类型数据源的默认值
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
dataSourceService.setFormValue("http", {
|
||
type: "http",
|
||
method: "GET",
|
||
url: "",
|
||
});
|
||
```
|
||
|
||
## getFormEvent
|
||
|
||
- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是
|
||
|
||
- **参数：**
|
||
- `{string}` type 数据源类型，默认为 'base'
|
||
|
||
- **返回：**
|
||
- {`EventOption`[]} 事件列表
|
||
|
||
::: details 查看 EventOption 类型定义
|
||
<<< @/../packages/core/src/utils.ts#EventOption{ts}
|
||
:::
|
||
|
||
- **详情：**
|
||
|
||
获取指定类型数据源的事件列表
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
const events = dataSourceService.getFormEvent("http");
|
||
console.log(events);
|
||
```
|
||
|
||
## setFormEvent
|
||
|
||
- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是
|
||
|
||
- **参数：**
|
||
- `{string}` type 数据源类型
|
||
- {`EventOption`[]} value 事件列表
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
设置指定类型数据源的事件列表
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
dataSourceService.setFormEvent("http", [
|
||
{ label: "请求成功", value: "success" },
|
||
{ label: "请求失败", value: "error" },
|
||
]);
|
||
```
|
||
|
||
## getFormMethod
|
||
|
||
- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是
|
||
|
||
- **参数：**
|
||
- `{string}` type 数据源类型，默认为 'base'
|
||
|
||
- **返回：**
|
||
- {`EventOption`[]} 方法列表
|
||
|
||
- **详情：**
|
||
|
||
获取指定类型数据源的方法列表
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
const methods = dataSourceService.getFormMethod("http");
|
||
console.log(methods);
|
||
```
|
||
|
||
## setFormMethod
|
||
|
||
- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是
|
||
|
||
- **参数：**
|
||
- `{string}` type 数据源类型
|
||
- {`EventOption`[]} value 方法列表
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
设置指定类型数据源的方法列表
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
dataSourceService.setFormMethod("http", [
|
||
{ label: "发起请求", value: "request" },
|
||
{ label: "重试", value: "retry" },
|
||
]);
|
||
```
|
||
|
||
## add
|
||
|
||
- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是
|
||
|
||
- **参数：**
|
||
- {`DataSourceSchema`} config 数据源配置
|
||
- `{Object}` options 可选配置
|
||
- `{boolean}` doNotPushHistory 是否不写入历史记录（默认 false）
|
||
|
||
- **返回：**
|
||
- {`DataSourceSchema`} 添加后的数据源配置
|
||
|
||
- **详情：**
|
||
|
||
添加一个数据源，如果配置中没有id或id已存在，会自动生成新的id
|
||
|
||
::: tip
|
||
添加成功会自动调用 `historyService.pushDataSource` 入栈一条 `oldSchema=null` 的新增记录，
|
||
参见 [historyService.pushDataSource](./historyServiceMethods.md#pushdatasource)。
|
||
传入 `doNotPushHistory: true` 可跳过写入历史栈，常用于批量导入、外部同步等非用户操作场景。
|
||
:::
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
const newDs = dataSourceService.add({
|
||
type: "http",
|
||
title: "用户信息",
|
||
url: "/api/user",
|
||
method: "GET",
|
||
});
|
||
|
||
console.log(newDs.id); // 自动生成的id
|
||
```
|
||
|
||
## update
|
||
|
||
- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是
|
||
|
||
- **参数：**
|
||
- {`DataSourceSchema`} config 数据源配置
|
||
- `{Object}` options 可选配置
|
||
- {`ChangeRecord`[]} changeRecords 变更记录
|
||
- `{boolean}` doNotPushHistory 是否不写入历史记录（默认 false）
|
||
|
||
::: details 查看 ChangeRecord 类型定义
|
||
<<< @/../packages/form-schema/src/base.ts#ChangeRecord{ts}
|
||
:::
|
||
|
||
- **返回：**
|
||
- {`DataSourceSchema`} 更新后的数据源配置
|
||
|
||
- **详情：**
|
||
|
||
更新数据源
|
||
|
||
::: tip
|
||
更新成功会自动调用 `historyService.pushDataSource` 入栈一条 `oldSchema` / `newSchema`
|
||
均为对应 schema 的更新记录，传入的 `changeRecords` 也会一并写进 step；撤销/重做时调用方可据此按
|
||
`propPath` 局部回放，缺省才退化为整 schema 替换。传入 `doNotPushHistory: true` 可跳过写入历史栈。
|
||
:::
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
const updatedDs = dataSourceService.update({
|
||
id: "ds_123",
|
||
type: "http",
|
||
title: "用户详情",
|
||
url: "/api/user/detail",
|
||
});
|
||
|
||
console.log(updatedDs);
|
||
```
|
||
|
||
## remove
|
||
|
||
- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是
|
||
|
||
- **参数：**
|
||
- `{string}` id 数据源id
|
||
- `{Object}` options 可选配置
|
||
- `{boolean}` doNotPushHistory 是否不写入历史记录（默认 false）
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
删除指定id的数据源
|
||
|
||
::: tip
|
||
对实际存在的数据源会自动调用 `historyService.pushDataSource` 入栈一条 `newSchema=null`
|
||
的删除记录；不存在的 id 不会入历史。传入 `doNotPushHistory: true` 也可显式跳过写入历史栈。
|
||
:::
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
dataSourceService.remove("ds_123");
|
||
```
|
||
|
||
## createId
|
||
|
||
- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是
|
||
|
||
- **参数：** 无
|
||
|
||
- **返回：**
|
||
- `{string}` 生成的唯一id
|
||
|
||
- **详情：**
|
||
|
||
生成一个唯一的数据源id，格式为 `ds_` + guid
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
const id = dataSourceService.createId();
|
||
console.log(id); // 'ds_xxx-xxx-xxx'
|
||
```
|
||
|
||
## getDataSourceById
|
||
|
||
- **参数：**
|
||
- `{string}` id 数据源id
|
||
|
||
- **返回：**
|
||
- {`DataSourceSchema` | undefined} 数据源配置
|
||
|
||
- **详情：**
|
||
|
||
根据id获取数据源配置
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
const ds = dataSourceService.getDataSourceById("ds_123");
|
||
console.log(ds);
|
||
```
|
||
|
||
## undo
|
||
|
||
- **参数：**
|
||
- `{Id}` id 数据源id
|
||
|
||
- **返回：**
|
||
- {`DataSourceStepValue` | null} 撤销的 step；栈不存在或已无可撤销时返回 `null`
|
||
|
||
- **详情：**
|
||
|
||
撤销指定数据源的最近一次变更。内部根据 [historyService](./historyServiceMethods.md) 取出 step 后，
|
||
复用 [add](#add) / [update](#update) / [remove](#remove) 写回，并自动带上 `doNotPushHistory: true`，
|
||
确保不会再次入栈。
|
||
|
||
写回会触发对应的 `add` / `update` / `remove` 事件，编辑器内部据此重新维护数据源相关的依赖收集
|
||
（`DepTargetType.DATA_SOURCE` / `DATA_SOURCE_COND` / `DATA_SOURCE_METHOD`），无需调用方额外处理。
|
||
|
||
对于带有 `changeRecords` 的更新 step，会按 `propPath` 局部 patch 当前数据源；缺省才退化为整 schema 替换，
|
||
避免冲掉同节点上的其它无关变更。
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
if (dataSourceService.canUndo("ds_123")) {
|
||
dataSourceService.undo("ds_123");
|
||
}
|
||
```
|
||
|
||
## redo
|
||
|
||
- **参数：**
|
||
- `{Id}` id 数据源id
|
||
|
||
- **返回：**
|
||
- {`DataSourceStepValue` | null} 重做的 step；栈不存在或已无可重做时返回 `null`
|
||
|
||
- **详情：**
|
||
|
||
重做指定数据源的下一次变更。其它行为同 [undo](#undo)。
|
||
|
||
## canUndo
|
||
|
||
- **参数：**
|
||
- `{Id}` id 数据源id
|
||
|
||
- **返回：**
|
||
- `{boolean}`
|
||
|
||
- **详情：**
|
||
|
||
当前指定数据源是否可撤销，等价于 `historyService.canUndoDataSource(id)`。
|
||
|
||
## canRedo
|
||
|
||
- **参数：**
|
||
- `{Id}` id 数据源id
|
||
|
||
- **返回：**
|
||
- `{boolean}`
|
||
|
||
- **详情：**
|
||
|
||
当前指定数据源是否可重做，等价于 `historyService.canRedoDataSource(id)`。
|
||
|
||
## copyWithRelated
|
||
|
||
- **参数：**
|
||
- {`MNode` | `MNode`[]} config 组件节点配置
|
||
- `{TargetOptions}` collectorOptions 可选的收集器配置
|
||
|
||
::: details 查看 MNode 及关联类型定义
|
||
<<< @/../packages/schema/src/index.ts#MNode{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#MComponent{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#MContainer{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#MIteratorContainer{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#MPage{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#MApp{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#MPageFragment{ts}
|
||
:::
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
复制组件时会带上组件关联的数据源，将关联的数据源存储到 localStorage
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService, editorService } from "@tmagic/editor";
|
||
|
||
const node = editorService.get("node");
|
||
dataSourceService.copyWithRelated(node);
|
||
```
|
||
|
||
## paste
|
||
|
||
- **参数：** 无
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
粘贴数据源，从 localStorage 中读取复制的数据源并添加到当前页面
|
||
|
||
如果数据源id已存在，则不会覆盖
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
dataSourceService.paste();
|
||
```
|
||
|
||
## resetState
|
||
|
||
- **参数：** 无
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
重置数据源服务状态，清空所有数据源
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
dataSourceService.resetState();
|
||
```
|
||
|
||
## destroy
|
||
|
||
- **参数：** 无
|
||
|
||
- **返回：**
|
||
- `{void}`
|
||
|
||
- **详情：**
|
||
|
||
销毁 dataSourceService，移除所有事件监听并重置状态
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
dataSourceService.destroy();
|
||
```
|
||
|
||
## usePlugin
|
||
|
||
- **详情：**
|
||
|
||
usePlugin支持更加灵活更加细致的扩展， 上述方法中标记有`扩展支持： 是`的方法都支持使用usePlugin扩展
|
||
|
||
每个支持扩展的方法都支持定制before、after两个hook来干预原有方法的行为，before可以用于修改传入参数，after可以用于修改返回的值
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
dataSourceService.usePlugin({
|
||
beforeAdd(config) {
|
||
console.log("添加前:", config);
|
||
return [config];
|
||
},
|
||
|
||
afterAdd(result, config) {
|
||
console.log("添加后:", result);
|
||
return result;
|
||
},
|
||
});
|
||
```
|
||
|
||
## removeAllPlugins
|
||
|
||
- **详情：**
|
||
|
||
删掉当前设置的所有扩展
|
||
|
||
- **示例：**
|
||
|
||
```js
|
||
import { dataSourceService } from "@tmagic/editor";
|
||
|
||
dataSourceService.removeAllPlugins();
|
||
```
|
||
|