From 3eb8cc061445a9a37c2c47d26dd9bca3fdf7434e Mon Sep 17 00:00:00 2001 From: roymondchen Date: Thu, 7 May 2026 17:33:58 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20editor/form/runtim?= =?UTF-8?q?e/stage=20=E7=AD=89=20API=20=E6=96=87=E6=A1=A3=E5=8F=82?= =?UTF-8?q?=E6=95=B0=E4=B8=8E=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补全方法的参数类型、返回值类型与详情说明，规范字段编辑器/字段配置/运行时 API 等文档。 Co-authored-by: Cursor --- docs/api/editor/codeBlockServiceMethods.md | 321 +++++++----------- docs/api/editor/dataSourceServiceMethods.md | 166 ++++----- docs/api/editor/editorServiceEvents.md | 37 +- docs/api/editor/editorServiceMethods.md | 264 +++++++------- docs/api/editor/events.md | 28 +- docs/api/editor/eventsServiceMethods.md | 46 +-- docs/api/editor/historyServiceEvents.md | 7 +- docs/api/editor/historyServiceMethods.md | 28 +- docs/api/editor/props.md | 2 +- docs/api/editor/propsServiceEvents.md | 2 +- docs/api/editor/propsServiceMethods.md | 129 ++++--- docs/api/editor/slots.md | 2 +- docs/api/editor/uiServiceMethods.md | 1 + docs/api/form/form-dialog-events.md | 30 +- docs/api/form/form-dialog-methods.md | 36 +- docs/api/form/form-dialog-props.md | 129 +++++-- docs/api/form/form-events.md | 44 ++- docs/api/form/form-methods.md | 60 +++- docs/api/form/form-props.md | 114 ++++--- docs/api/stage/coreEvents.md | 89 ++++- docs/api/stage/coreMethods.md | 108 +++++- docs/api/table/events.md | 25 +- docs/api/table/props.md | 32 +- docs/form-config/editor-fields/code-link.md | 17 +- .../editor-fields/code-select-col.md | 15 +- docs/form-config/editor-fields/code-select.md | 16 +- docs/form-config/editor-fields/code.md | 39 ++- .../editor-fields/cond-op-select.md | 19 +- .../editor-fields/data-source-field-select.md | 24 +- .../editor-fields/data-source-fields.md | 13 +- .../editor-fields/data-source-input.md | 13 +- .../data-source-method-select.md | 15 +- .../editor-fields/data-source-methods.md | 13 +- .../editor-fields/data-source-mocks.md | 13 +- .../editor-fields/data-source-select.md | 22 +- .../editor-fields/display-conds.md | 17 +- .../form-config/editor-fields/event-select.md | 30 +- docs/form-config/editor-fields/key-value.md | 15 +- .../editor-fields/page-fragment-select.md | 13 +- docs/form-config/editor-fields/ui-select.md | 13 +- docs/form-config/fields/date-picker.md | 103 +++--- docs/form-config/fields/daterange-picker.md | 45 +-- docs/form-config/fields/datetime-picker.md | 102 +++--- docs/form-config/fields/display.md | 25 +- docs/form-config/fields/dynamic-field.md | 4 +- docs/form-config/fields/hidden.md | 22 +- docs/form-config/fields/link.md | 35 +- docs/form-config/fields/number-range.md | 26 +- docs/form-config/fields/number.md | 57 ++-- docs/form-config/fields/radio.md | 56 +-- docs/form-config/fields/select.md | 121 ++++--- docs/form-config/fields/switch.md | 33 +- docs/form-config/fields/text.md | 120 ++++--- docs/form-config/fields/textarea.md | 43 +-- docs/form-config/fields/time-picker.md | 36 +- docs/form-config/fields/timerange-picker.md | 43 +-- docs/form-config/relate.md | 6 +- docs/guide/advanced/code-block.md | 10 +- docs/guide/advanced/coupling.md | 19 +- docs/guide/advanced/data-source.md | 2 +- docs/guide/advanced/tmagic-form.md | 6 +- docs/guide/advanced/tmagic-ui.md | 8 +- docs/guide/component.md | 2 +- docs/guide/editor-expand.md | 8 +- docs/guide/index.md | 5 +- docs/guide/introduction.md | 2 +- docs/guide/migration.md | 2 +- docs/guide/publish.md | 6 +- docs/guide/runtime.md | 2 +- docs/guide/tutorial/hello-world.md | 8 +- docs/guide/tutorial/render.md | 12 +- docs/guide/tutorial/runtime.md | 4 +- docs/runtime-api/core/app.md | 80 ++++- docs/runtime-api/core/devtoolApi.md | 91 +++-- docs/runtime-api/core/env.md | 13 +- docs/runtime-api/core/eventHelper.md | 13 +- docs/runtime-api/core/iteratorContainer.md | 19 +- docs/runtime-api/core/node.md | 37 +- docs/runtime-api/core/page.md | 25 +- docs/runtime-api/core/utils.md | 12 +- docs/runtime-api/data-source/dataSource.md | 50 ++- .../data-source/dataSourceManager.md | 86 ++--- .../runtime-api/data-source/httpDataSource.md | 49 ++- docs/runtime-api/data-source/observedData.md | 26 +- docs/runtime-api/data-source/utils.md | 42 +-- 85 files changed, 2061 insertions(+), 1462 deletions(-) diff --git a/docs/api/editor/codeBlockServiceMethods.md b/docs/api/editor/codeBlockServiceMethods.md index 75960e3d..5ac13dc6 100644 --- a/docs/api/editor/codeBlockServiceMethods.md +++ b/docs/api/editor/codeBlockServiceMethods.md @@ -1,355 +1,269 @@ # codeBlockService方法 - - ## setCodeDsl - **参数：** - - - + - {[CodeBlockDSL](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/schema/src/index.ts#L75)} codeDsl 代码块DSL - **返回：** - - `{Promise}` - **详情：** + 设置活动的代码块dsl数据源，并触发 `code-dsl-change` 事件 + ## getCodeDsl -- **参数：** - - - - - **返回：** - - - `{Promise}` + - {[CodeBlockDSL](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/schema/src/index.ts#L75) | null} - **详情：** + 获取活动的代码块dsl数据源（默认从dsl中的codeBlocks字段读取） + ## getCodeContentById -- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - - **参数：** - - - + - `{string | number}` id 代码块id - **返回：** - - - `{Promise}` + - {[CodeBlockContent](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/schema/src/index.ts#L79) | null} - **详情：** + 根据代码块id获取代码块内容 + ## setCodeDslById - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - + - `{string | number}` id 代码块id + - {Partial<[CodeBlockContent](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/schema/src/index.ts#L79)>} codeConfig 代码块内容配置信息 - **返回：** - - `{Promise}` - **详情：** + 设置代码块ID和代码内容到源dsl，强制写入；底层调用 [setCodeDslByIdSync](#setcodedslbyidsync) + +## setCodeDslByIdSync + +- **参数：** + - `{string | number}` id 代码块id + - {Partial<[CodeBlockContent](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/schema/src/index.ts#L79)>} codeConfig 代码块内容配置信息 + - `{boolean}` force 是否强制写入，默认 `true`；为 `false` 时若同 id 已存在则跳过 + +- **返回：** + - `{void}` + +- **详情：** + + 同步版本的 [setCodeDslById](#setcodedslbyid)，并会触发 `addOrUpdate` 事件 + ## getCodeDslByIds -- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - - **参数：** - - - + - `{string[]}` ids 代码块id数组 - **返回：** - - - `{Promise}` + - {[CodeBlockDSL](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/schema/src/index.ts#L75)} 命中的代码块dsl - **详情：** -## setCodeEditorShowStatus - -- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - -- **参数：** - - - - -- **返回：** - - - `{Promise}` - -- **详情：** - -## getCodeEditorShowStatus - -- **参数：** - - - - -- **返回：** - - - `{Promise}` - -- **详情：** - -## setCodeEditorContent - -- **参数：** - - - - -- **返回：** - - - `{Promise}` - -- **详情：** - -## getCurrentDsl - -- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - -- **参数：** - - - - -- **返回：** - - - `{Promise}` - -- **详情：** + 根据代码块id数组获取代码dsl ## getEditStatus -- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 +- **返回：** + - `{boolean}` 是否可编辑 + +- **详情：** + + 获取当前编辑状态 ## setEditStatus -- **参数：** - - - - -- **返回：** - - - `{Promise}` - -- **详情：** - -## setId - -- **参数：** - - - - -- **返回：** - - - `{Promise}` - -- **详情：** - -## getId - -- **参数：** - - - - -- **返回：** - - - `{Promise}` - -- **详情：** - -## getMode - - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - + - `{boolean}` status 是否可编辑 - **返回：** - - `{Promise}` - **详情：** -## setMode - -- **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - -- **参数：** - - - - -- **返回：** - - - `{Promise}` - -- **详情：** + 设置代码块编辑状态 ## setCombineIds - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - + - `{string[]}` ids 代码块id数组 - **返回：** - - `{Promise}` - **详情：** + 设置当前选中组件已关联绑定的代码块id数组 + ## getCombineIds -- **参数：** - - - - - **返回：** - - - `{Promise}` + - `{string[]}` 代码块id数组 - **详情：** -## refreshAllRelations - -- **参数：** - - - - -- **返回：** - - - `{Promise}` - -- **详情：** - -## getCombineInfo - -- **参数：** - - - - -- **返回：** - - - `{Promise}` - -- **详情：** + 获取当前选中组件已关联绑定的代码块id数组 ## getUndeletableList -- **参数：** - - - - - **返回：** - - - `{Promise}` + - `{(string | number)[]}` 代码块id数组 - **详情：** + 获取不可删除列表 + ## setUndeleteableList - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - + - `{(string | number)[]}` codeIds 代码块id数组 - **返回：** - - `{Promise}` - **详情：** + 设置不可删除列表：为业务逻辑预留的不可删除的代码块列表，由业务逻辑维护（如代码块上线后不可删除） + ## setCodeDraft - **参数：** - - - + - `{string | number}` codeId 代码块id + - `{string}` content 代码草稿内容 - **返回：** - - - `{Promise}` + - `{void}` - **详情：** + 将代码草稿写入 localStorage + ## getCodeDraft - **参数：** - - - + - `{string | number}` codeId 代码块id - **返回：** - - - `{Promise}` + - `{string | null}` 代码草稿内容 - **详情：** + 从 localStorage 读取代码草稿 + ## removeCodeDraft - **参数：** - - - + - `{string | number}` codeId 代码块id - **返回：** - - - `{Promise}` + - `{void}` - **详情：** + 删除 localStorage 中的代码草稿 + ## deleteCodeDslByIds - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - + - `{(string | number)[]}` codeIds 需要删除的代码块id数组 - **返回：** - - `{Promise}` - **详情：** + 在dsl数据源中删除指定id的代码块，每删除一个会触发一次 `remove` 事件 + +## setParamsColConfig + +- **参数：** + - `{TableColumnConfig}` config 参数列配置 + +- **返回：** + - `{void}` + +- **详情：** + + 设置代码块入参表格列配置 + +## getParamsColConfig + +- **返回：** + - `{TableColumnConfig | undefined}` 参数列配置 + +- **详情：** + + 获取代码块入参表格列配置 + ## getUniqueId -- **参数：** - - - - - **返回：** - - - `{Promise}` + - `{Promise}` 代码块唯一id - **详情：** -## deleteCompsInRelation + 生成代码块唯一id（格式为 `code_xxxx`），与已有id冲突时会递归重试 + +## copyWithRelated - **参数：** - - - + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]} config 组件节点配置 + - `{TargetOptions}` collectorOptions 可选的依赖收集器配置 - **返回：** - - - `{Promise}` + - `{void}` - **详情：** + 复制组件时会带上组件关联的代码块，将关联的代码块dsl存储到 localStorage + +## paste + +- **返回：** + - `{void}` + +- **详情：** + + 粘贴代码块。从 localStorage 读取已复制的代码块dsl并写入当前dsl，已存在同id的代码块不会被覆盖 + +## resetState + +- **返回：** + - `{void}` + +- **详情：** + + 重置 codeBlockService 状态 + ## destroy -- **参数：** - - - - - **返回：** - - - `{Promise}` + - `{void}` - **详情：** + 销毁 codeBlockService，重置状态并移除所有事件监听和插件 + ## use 使用中间件的方式扩展方法，上述方法中标记有`扩展支持： 是`的方法都支持使用use扩展 @@ -367,4 +281,3 @@ - **详情：** 删掉当前设置的所有扩展 - diff --git a/docs/api/editor/dataSourceServiceMethods.md b/docs/api/editor/dataSourceServiceMethods.md index 38c365c8..8f7d9c4c 100644 --- a/docs/api/editor/dataSourceServiceMethods.md +++ b/docs/api/editor/dataSourceServiceMethods.md @@ -3,11 +3,9 @@ ## get - **参数：** - - `{StateKey}` name 状态键名 - **返回：** - - `{any}` 对应的状态值 - **详情：** @@ -26,21 +24,19 @@ - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; -const dataSources = dataSourceService.get('dataSources'); +const dataSources = dataSourceService.get("dataSources"); console.log(dataSources); ``` ## set - **参数：** - - `{StateKey}` name 状态键名 - `{any}` value 状态值 - **返回：** - - `{void}` - **详情：** @@ -50,9 +46,9 @@ console.log(dataSources); - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; -dataSourceService.set('editable', false); +dataSourceService.set("editable", false); ``` ## getFormConfig @@ -60,12 +56,10 @@ dataSourceService.set('editable', false); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{string}` type 数据源类型，默认为 'base' - **返回：** - - - {[FormConfig](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/form/src/schema.ts#L706)} 表单配置 + - {[FormConfig](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L864)} 表单配置 - **详情：** @@ -74,9 +68,9 @@ dataSourceService.set('editable', false); - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; -const config = dataSourceService.getFormConfig('http'); +const config = dataSourceService.getFormConfig("http"); console.log(config); ``` @@ -85,12 +79,10 @@ console.log(config); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{string}` type 数据源类型 - - {[FormConfig](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/form/src/schema.ts#L706)} config 表单配置 + - {[FormConfig](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L864)} config 表单配置 - **返回：** - - `{void}` - **详情：** @@ -100,21 +92,21 @@ console.log(config); - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; -dataSourceService.setFormConfig('http', [ +dataSourceService.setFormConfig("http", [ { - name: 'url', - text: '请求地址', - type: 'text', + name: "url", + text: "请求地址", + type: "text", }, { - name: 'method', - text: '请求方法', - type: 'select', + name: "method", + text: "请求方法", + type: "select", options: [ - { text: 'GET', value: 'GET' }, - { text: 'POST', value: 'POST' }, + { text: "GET", value: "GET" }, + { text: "POST", value: "POST" }, ], }, ]); @@ -125,11 +117,9 @@ dataSourceService.setFormConfig('http', [ - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{string}` type 数据源类型，默认为 'base' - **返回：** - - {Partial<[DataSourceSchema](https://github.com/Tencent/tmagic-editor/blob/5880dfbe15fcead63e9dc7c91900f8c4e7a574d8/packages/schema/src/index.ts#L221)>} 数据源默认值 - **详情：** @@ -139,9 +129,9 @@ dataSourceService.setFormConfig('http', [ - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; -const defaultValue = dataSourceService.getFormValue('http'); +const defaultValue = dataSourceService.getFormValue("http"); console.log(defaultValue); ``` @@ -150,12 +140,10 @@ console.log(defaultValue); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{string}` type 数据源类型 - {Partial<[DataSourceSchema](https://github.com/Tencent/tmagic-editor/blob/5880dfbe15fcead63e9dc7c91900f8c4e7a574d8/packages/schema/src/index.ts#L221)>} value 数据源默认值 - **返回：** - - `{void}` - **详情：** @@ -165,12 +153,12 @@ console.log(defaultValue); - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; -dataSourceService.setFormValue('http', { - type: 'http', - method: 'GET', - url: '', +dataSourceService.setFormValue("http", { + type: "http", + method: "GET", + url: "", }); ``` @@ -179,11 +167,9 @@ dataSourceService.setFormValue('http', { - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{string}` type 数据源类型，默认为 'base' - **返回：** - - {[EventOption](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/core/src/events.ts#L26-L29)[]} 事件列表 - **详情：** @@ -193,9 +179,9 @@ dataSourceService.setFormValue('http', { - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; -const events = dataSourceService.getFormEvent('http'); +const events = dataSourceService.getFormEvent("http"); console.log(events); ``` @@ -204,12 +190,10 @@ console.log(events); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{string}` type 数据源类型 - {[EventOption](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/core/src/events.ts#L26-L29)[]} value 事件列表 - **返回：** - - `{void}` - **详情：** @@ -219,11 +203,11 @@ console.log(events); - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; -dataSourceService.setFormEvent('http', [ - { label: '请求成功', value: 'success' }, - { label: '请求失败', value: 'error' }, +dataSourceService.setFormEvent("http", [ + { label: "请求成功", value: "success" }, + { label: "请求失败", value: "error" }, ]); ``` @@ -232,11 +216,9 @@ dataSourceService.setFormEvent('http', [ - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{string}` type 数据源类型，默认为 'base' - **返回：** - - {[EventOption](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/core/src/events.ts#L26-L29)[]} 方法列表 - **详情：** @@ -246,9 +228,9 @@ dataSourceService.setFormEvent('http', [ - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; -const methods = dataSourceService.getFormMethod('http'); +const methods = dataSourceService.getFormMethod("http"); console.log(methods); ``` @@ -257,12 +239,10 @@ console.log(methods); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{string}` type 数据源类型 - {[EventOption](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/core/src/events.ts#L26-L29)[]} value 方法列表 - **返回：** - - `{void}` - **详情：** @@ -272,11 +252,11 @@ console.log(methods); - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; -dataSourceService.setFormMethod('http', [ - { label: '发起请求', value: 'request' }, - { label: '重试', value: 'retry' }, +dataSourceService.setFormMethod("http", [ + { label: "发起请求", value: "request" }, + { label: "重试", value: "retry" }, ]); ``` @@ -285,11 +265,9 @@ dataSourceService.setFormMethod('http', [ - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - {[DataSourceSchema](https://github.com/Tencent/tmagic-editor/blob/5880dfbe15fcead63e9dc7c91900f8c4e7a574d8/packages/schema/src/index.ts#L221)} config 数据源配置 - **返回：** - - {[DataSourceSchema](https://github.com/Tencent/tmagic-editor/blob/5880dfbe15fcead63e9dc7c91900f8c4e7a574d8/packages/schema/src/index.ts#L221)} 添加后的数据源配置 - **详情：** @@ -299,13 +277,13 @@ dataSourceService.setFormMethod('http', [ - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; const newDs = dataSourceService.add({ - type: 'http', - title: '用户信息', - url: '/api/user', - method: 'GET', + type: "http", + title: "用户信息", + url: "/api/user", + method: "GET", }); console.log(newDs.id); // 自动生成的id @@ -316,13 +294,11 @@ console.log(newDs.id); // 自动生成的id - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - {[DataSourceSchema](https://github.com/Tencent/tmagic-editor/blob/5880dfbe15fcead63e9dc7c91900f8c4e7a574d8/packages/schema/src/index.ts#L221)} config 数据源配置 - `{Object}` options 可选配置 - {[ChangeRecord](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/form/src/schema.ts#L27-L39)[]} changeRecords 变更记录 - **返回：** - - {[DataSourceSchema](https://github.com/Tencent/tmagic-editor/blob/5880dfbe15fcead63e9dc7c91900f8c4e7a574d8/packages/schema/src/index.ts#L221)} 更新后的数据源配置 - **详情：** @@ -332,13 +308,13 @@ console.log(newDs.id); // 自动生成的id - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; const updatedDs = dataSourceService.update({ - id: 'ds_123', - type: 'http', - title: '用户详情', - url: '/api/user/detail', + id: "ds_123", + type: "http", + title: "用户详情", + url: "/api/user/detail", }); console.log(updatedDs); @@ -349,11 +325,9 @@ console.log(updatedDs); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{string}` id 数据源id - **返回：** - - `{void}` - **详情：** @@ -363,9 +337,9 @@ console.log(updatedDs); - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; -dataSourceService.remove('ds_123'); +dataSourceService.remove("ds_123"); ``` ## createId @@ -375,7 +349,6 @@ dataSourceService.remove('ds_123'); - **参数：** 无 - **返回：** - - `{string}` 生成的唯一id - **详情：** @@ -385,7 +358,7 @@ dataSourceService.remove('ds_123'); - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; const id = dataSourceService.createId(); console.log(id); // 'ds_xxx-xxx-xxx' @@ -394,11 +367,9 @@ console.log(id); // 'ds_xxx-xxx-xxx' ## getDataSourceById - **参数：** - - `{string}` id 数据源id - **返回：** - - {[DataSourceSchema](https://github.com/Tencent/tmagic-editor/blob/5880dfbe15fcead63e9dc7c91900f8c4e7a574d8/packages/schema/src/index.ts#L221) | undefined} 数据源配置 - **详情：** @@ -408,21 +379,19 @@ console.log(id); // 'ds_xxx-xxx-xxx' - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; -const ds = dataSourceService.getDataSourceById('ds_123'); +const ds = dataSourceService.getDataSourceById("ds_123"); console.log(ds); ``` ## copyWithRelated - **参数：** - - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99) | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)[]} config 组件节点配置 + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]} config 组件节点配置 - `{TargetOptions}` collectorOptions 可选的收集器配置 - **返回：** - - `{void}` - **详情：** @@ -432,9 +401,9 @@ console.log(ds); - **示例：** ```js -import { dataSourceService, editorService } from '@tmagic/editor'; +import { dataSourceService, editorService } from "@tmagic/editor"; -const node = editorService.get('node'); +const node = editorService.get("node"); dataSourceService.copyWithRelated(node); ``` @@ -443,19 +412,18 @@ dataSourceService.copyWithRelated(node); - **参数：** 无 - **返回：** - - `{void}` - **详情：** 粘贴数据源，从 localStorage 中读取复制的数据源并添加到当前页面 - + 如果数据源id已存在，则不会覆盖 - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; dataSourceService.paste(); ``` @@ -465,7 +433,6 @@ dataSourceService.paste(); - **参数：** 无 - **返回：** - - `{void}` - **详情：** @@ -475,7 +442,7 @@ dataSourceService.paste(); - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; dataSourceService.resetState(); ``` @@ -485,7 +452,6 @@ dataSourceService.resetState(); - **参数：** 无 - **返回：** - - `{void}` - **详情：** @@ -495,7 +461,7 @@ dataSourceService.resetState(); - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; dataSourceService.destroy(); ``` @@ -504,23 +470,23 @@ dataSourceService.destroy(); - **详情：** -相对于[use](#use), usePlugin支持更加灵活更加细致的扩展， 上述方法中标记有`扩展支持： 是`的方法都支持使用usePlugin扩展 +usePlugin支持更加灵活更加细致的扩展， 上述方法中标记有`扩展支持： 是`的方法都支持使用usePlugin扩展 每个支持扩展的方法都支持定制before、after两个hook来干预原有方法的行为，before可以用于修改传入参数，after可以用于修改返回的值 - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; dataSourceService.usePlugin({ beforeAdd(config) { - console.log('添加前:', config); + console.log("添加前:", config); return [config]; }, - + afterAdd(result, config) { - console.log('添加后:', result); + console.log("添加后:", result); return result; }, }); @@ -535,7 +501,7 @@ dataSourceService.usePlugin({ - **示例：** ```js -import { dataSourceService } from '@tmagic/editor'; +import { dataSourceService } from "@tmagic/editor"; dataSourceService.removeAllPlugins(); -``` \ No newline at end of file +``` diff --git a/docs/api/editor/editorServiceEvents.md b/docs/api/editor/editorServiceEvents.md index 4a49e2ad..8cefa3f8 100644 --- a/docs/api/editor/editorServiceEvents.md +++ b/docs/api/editor/editorServiceEvents.md @@ -1,40 +1,51 @@ - # editorService事件 ## root-change - **详情：** dsl跟节点发生变化，[editorService.set('root', {})](./editorServiceMethods.md#set)后触发 -- **回调函数：** (value: [MApp](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/schema/src/index.ts?plain=1#L66-L73), preValue: [MApp](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/schema/src/index.ts?plain=1#L66-L73)) => void +- **事件回调函数：** (value: [MApp](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/schema/src/index.ts?plain=1#L66-L73), preValue?: [MApp](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/schema/src/index.ts?plain=1#L66-L73)) => void ## select - **详情：** 选中组件，[editorService.select()](./editorServiceMethods.md#select)后触发 -- **回调函数：** (node: [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)) => void +- **事件回调函数：** (node: [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)) => void ## add -- **详情：** 选中组件，[editorService.add()](./editorServiceMethods.md#add)后触发 - -- **回调函数：** (node: [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)[]) => void +- **详情：** 添加节点后触发，[editorService.add()](./editorServiceMethods.md#add)后触发 +- **事件回调函数：** (node: [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]) => void ## remove -- **详情：** 选中组件，[editorService.remove()](./editorServiceMethods.md#remove)后触发 - -- **回调函数：** (node: [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)[]) => void +- **详情：** 删除节点后触发，[editorService.remove()](./editorServiceMethods.md#remove)后触发 +- **事件回调函数：** (node: [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]) => void ## update -- **详情：** 选中组件，[editorService.update()](./editorServiceMethods.md#update)后触发 +- **详情：** 更新组件后触发，[editorService.update()](./editorServiceMethods.md#update)后触发 -- **回调函数：** (node: [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)[]) => void +- **事件回调函数：** (data: Array<{ newNode: [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210); oldNode: [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210); changeRecords?: [ChangeRecord](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/form/src/schema.ts#L27-L39)[] }>) => void +## move-layer + +- **详情：** 移动节点层级后触发，[editorService.moveLayer()](./editorServiceMethods.md#movelayer)后触发 + +- **事件回调函数：** (offset: number | [LayerOffset](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/type.ts)) => void + + 其中 `LayerOffset` 枚举值为 `'top'` / `'bottom'` + +## drag-to + +- **详情：** 拖拽节点到指定容器后触发，[editorService.dragTo()](./editorServiceMethods.md#dragto)后触发 + +- **事件回调函数：** (data: { targetIndex: number; configs: [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]; targetParent: [MContainer](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L54-L59) }) => void ## history-change -- **详情：** 历史记录改变，[editorService.redo()，editorService.undo()](./editorServiceMethods.html#undo)后触发 -- **回调函数：** (node: [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)) => void \ No newline at end of file +- **详情：** 历史记录改变，[editorService.redo()，editorService.undo()](./editorServiceMethods.md#undo)后触发 + +- **事件回调函数：** (data: [MPage](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L61) | [MPageFragment](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)) => void diff --git a/docs/api/editor/editorServiceMethods.md b/docs/api/editor/editorServiceMethods.md index 2a993081..924dcf3d 100644 --- a/docs/api/editor/editorServiceMethods.md +++ b/docs/api/editor/editorServiceMethods.md @@ -3,17 +3,15 @@ ## get - **参数：** - - - `{'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'modifiedNodeIds' | 'pageLength' | 'stage'} name` + - `{'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'modifiedNodeIds' | 'pageLength' | 'pageFragmentLength' | 'stage' | 'stageLoading' | 'disabledMultiSelect'} name` - **返回：** - - `{any} value` - + - **详情：** 获取当前指指定name的值 - + 'root': 当前整个配置，也就是当前编辑器的值 'page': 当前正在编辑的页面配置 @@ -30,19 +28,26 @@ 'pageLength': 所以页面个数 + 'pageFragmentLength': 页面片个数 + 'stage': [StageCore](../stage/coreMethods.md)实例 + 'stageLoading': 画布是否加载中 + + 'disabledMultiSelect': 是否禁用多选 + - **示例：** ```js -import { editorService } from '@tmagic/editor'; +import { editorService } from "@tmagic/editor"; -const node = editorService.get('node'); +const node = editorService.get("node"); ``` ## set - - `{'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'modifiedNodeIds' | 'pageLength' | 'stage'} name` - - `{any} value` + +- `{'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'modifiedNodeIds' | 'pageLength' | 'pageFragmentLength' | 'stage' | 'stageLoading' | 'disabledMultiSelect'} name` +- `{any} value` - **详情：** 参考[get](#get)方法 @@ -50,23 +55,20 @@ const node = editorService.get('node'); - **示例：** ```js -import { editorService } from '@tmagic/editor'; +import { editorService } from "@tmagic/editor"; -const node = editorService.get('node'); +const node = editorService.get("node"); -editorService.set('node', { +editorService.set("node", { ...node, - name: 'new name' + name: "new name", }); - ``` ## getNodeInfo - **参数：** - - `{number | string}` id 组件id - - `{boolean}` raw 是否使用toRaw，默认为true :::tip @@ -74,7 +76,6 @@ editorService.set('node', { ::: - **返回：** - - {[EditorNodeInfo](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/editor/src/type.ts#L139-L143)} - **详情：** @@ -84,9 +85,9 @@ editorService.set('node', { - **示例：** ```js -import { editorService } from '@tmagic/editor'; +import { editorService } from "@tmagic/editor"; -const info = editorService.getNodeInfo('text_123'); +const info = editorService.getNodeInfo("text_123"); console.log(info.node); console.log(info.parent); @@ -96,14 +97,11 @@ console.log(info.page); ## getNodeById - **参数：** - - `{number | string}` id - - `{boolean}` raw 是否使用toRaw，默认为true - **返回：** - - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)} 组件节点配置 + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} 组件节点配置 - **详情：** @@ -112,9 +110,9 @@ console.log(info.page); - **示例：** ```js -import { editorService } from '@tmagic/editor'; +import { editorService } from "@tmagic/editor"; -const node = editorService.getNodeById('text_123'); +const node = editorService.getNodeById("text_123"); console.log(node); ``` @@ -122,14 +120,11 @@ console.log(node); ## getParentById - **参数：** - - `{number | string}` id - - `{boolean}` raw 是否使用toRaw，默认为true - **返回：** - - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)} 指点组件的父节点配置 + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} 指点组件的父节点配置 - **详情：** @@ -138,9 +133,9 @@ console.log(node); - **示例：** ```js -import { editorService } from '@tmagic/editor'; +import { editorService } from "@tmagic/editor"; -const parent = editorService.getParentById('text_123'); +const parent = editorService.getParentById("text_123"); console.log(parent); ``` @@ -150,13 +145,10 @@ console.log(parent); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)} parent - - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)} node 可选 + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} parent + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} node 可选 - **返回：** - - {Promise<[Layout](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/editor/src/type.ts#L297-L302)>} 当前布局模式 - **详情：** @@ -172,9 +164,9 @@ console.log(parent); - **示例：** ```js -import { editorService } from '@tmagic/editor'; +import { editorService } from "@tmagic/editor"; -const parent = editorService.getParentById('text_123'); +const parent = editorService.getParentById("text_123"); editorService.getLayout(parent).then((layout) => { console.log(parent); }); @@ -185,12 +177,10 @@ editorService.getLayout(parent).then((layout) => { - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - {number | string | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)} config 需要选中的节点或节点ID + - {number | string | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} config 需要选中的节点或节点ID - **返回：** - - - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)>} 当前选中的节点配置 + - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)>} 当前选中的节点配置 - **详情：** @@ -203,20 +193,18 @@ editorService.getLayout(parent).then((layout) => { - **示例：** ```js -import { editorService } from '@tmagic/editor'; +import { editorService } from "@tmagic/editor"; -editorService.select('text_123'); -editorService.get('stage')?.select('text_123'); +editorService.select("text_123"); +editorService.get("stage")?.select("text_123"); ``` ## multiSelect - **参数：** - - {(number | string)[]} ids 需要选中的节点ID集合 - -- **返回：** +- **返回：** - `{Promise}` - **详情：** @@ -230,22 +218,47 @@ editorService.get('stage')?.select('text_123'); - **示例：** ```js -import { editorService } from '@tmagic/editor'; +import { editorService } from "@tmagic/editor"; -editorService.multiSelect(['text_123', 'button_123']); -editorService.get('stage')?.multiSelect(['text_123', 'button_123']); +editorService.multiSelect(["text_123", "button_123"]); +editorService.get("stage")?.multiSelect(["text_123", "button_123"]); ``` +## selectNextNode + +- **返回：** + - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | null>} 选中后的节点配置 + +- **详情：** + + 选中当前节点同层级（同一父节点）的下一个节点，已经是最后一个时回到第一个 + +## selectNextPage + +- **返回：** + - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)>} 选中后的页面配置 + +- **详情：** + + 选中下一页，已经是最后一页时回到第一页 + +## selectRoot + +- **返回：** + - `{void}` + +- **详情：** + + 选中根节点（root），同时清空当前选中的页面、父节点、画布及高亮节点 + ## highlight - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - {number | string | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)} config 需要高亮的节点或节点ID + - {number | string | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} config 需要高亮的节点或节点ID - **返回：** - - `{Promise}` - **详情：** @@ -255,9 +268,9 @@ editorService.get('stage')?.multiSelect(['text_123', 'button_123']); - **示例：** ```js -import { editorService } from '@tmagic/editor'; +import { editorService } from "@tmagic/editor"; -editorService.highlight('text_123'); +editorService.highlight("text_123"); ``` ## doAdd @@ -265,14 +278,12 @@ editorService.highlight('text_123'); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} node 新组件节点 - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)} node 新组件节点 - - - {[MContainer](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L54-L59)} parent 指定的容器节点 + - {[MContainer](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L139)} parent 指定的容器节点 - **返回：** - - - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)>} 新增的组件 + - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)>} 新增的组件 - **详情：** @@ -283,14 +294,12 @@ editorService.highlight('text_123'); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]} node 新组件节点配置或多个节点集合 - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99) | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)[]} node 新组件节点配置或多个节点集合 - - - {[MContainer](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L54-L59)} parent 指定的容器组件节点配置，如果不设置，默认为当前选中的组件的父节点 + - {[MContainer](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L139)} parent 指定的容器组件节点配置，如果不设置，默认为当前选中的组件的父节点 - **返回：** - - - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99) | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)[]>} 新增的组件或组件集合 + - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]>} 新增的组件或组件集合 - **详情：** @@ -307,30 +316,24 @@ editorService.highlight('text_123'); ## doRemove - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - - **参数：** - - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)} node 要删除的节点 + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} node 要删除的节点 - **返回：** - - `{Promise}` - **详情：** 删除指定的组件或者页面 - ## remove - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[])} node 要删除的节点或节点集合 - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99) | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)[])} node 要删除的节点或节点集合 - - **返回：** - - `{Promise}` - **详情：** @@ -350,12 +353,13 @@ editorService.highlight('text_123'); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99) | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99))} node 新的节点 + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} config 新的节点 + - `{Object}` data 可选配置 + - {[ChangeRecord](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form/src/schema.ts#L8)[]} changeRecords 变更记录 + - `{boolean}` selectedAfterUpdate 更新后是否将新节点同步到当前选中节点列表 - **返回：** - - - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99) | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)>} 新的节点 + - `{Promise<{ newNode: MNode; oldNode: MNode; changeRecords?: ChangeRecord[] }>}` 更新前后的节点信息 - **详情：** @@ -370,13 +374,13 @@ editorService.highlight('text_123'); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99) | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)[]>} node 新的节点或节点集合 - + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]} config 新的节点或节点集合 + - `{Object}` data 可选配置 + - {[ChangeRecord](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/form/src/schema.ts#L27-L39)[]} changeRecords 变更记录 + - `{boolean}` selectedAfterUpdate 更新后是否同步到当前选中节点列表 - **返回：** - - - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99) | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)[]>} 新的节点或节点集合 + - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]>} 新的节点或节点集合 - **详情：** @@ -395,12 +399,10 @@ editorService.highlight('text_123'); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{ string | number }` id1 - `{ string | number }` id2 - **返回：** - - `{Promise}` - **详情：** @@ -414,29 +416,37 @@ editorService.highlight('text_123'); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99) | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)[]>} node 需要复制的节点或节点集合 + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]} config 需要复制的节点或节点集合 - **返回：** - - - `{Promise}` + - `{void}` - **详情：** - + 复制组件节点或节点集合 -通过[storageService.setItem](./storageServiceMethods.md#setitem),将组将节点配置转化成string，然后存储到localStorage中 +通过[storageService.setItem](./storageServiceMethods.md#setitem),将组件节点配置存储到localStorage中 + +## copyWithRelated + +- **参数：** + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]} config 需要复制的节点或节点集合 + - `{TargetOptions}` collectorOptions 可选的依赖收集器配置 + +- **返回：** + - `{void}` + +- **详情：** + + 复制节点时会同时收集组件关联的依赖（如 dataSource、codeBlock 等），并一起存储到 localStorage 中，便于粘贴时一起带入 ## doPaste - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 -- **参数：** - - - +- ## **参数：** - **返回：** - - `{Promise}` - **详情：** @@ -448,31 +458,26 @@ editorService.highlight('text_123'); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - {[PastePosition](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/type.ts#L152-L163)} position 粘贴的坐标 - **返回：** - - - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99) | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)[]>} 添加后的组件节点配置 + - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]>} 添加后的组件节点配置 - **详情：** 粘贴组件节点或节点集合 -通过[storageService.getItem](./storageServiceMethods.md#setitem),从localStorage中获取节点，然后添加到当前容器中 - +通过[storageService.getItem](./storageServiceMethods.md#getItem),从localStorage中获取节点，然后添加到当前容器中 ## doAlignCenter - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)} config 需要居中的组件 + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} config 需要居中的组件 - **返回：** - - - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)>} + - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)>} - **详情：** @@ -487,13 +492,10 @@ editorService.highlight('text_123'); - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99) | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)[]>} config 需要居中的组件或者组件集合 + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]} config 需要居中的组件或者组件集合 - **返回：** - - - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99) | [MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)[]>} - + - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]>} - **详情：** @@ -504,16 +506,15 @@ editorService.highlight('text_123'); alignCenter可以支持一次水平居中多个组件，alignCenter是通过调用[doAlignCenter](#doaligncentere)来获取到已设置好水平居中的位置信息的节点，然后调用update更新。 ::: + ## moveLayer - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{number | 'top' | 'bottom'}` offset - **返回：** - - `{Promise}` - **详情：** @@ -522,30 +523,40 @@ alignCenter可以支持一次水平居中多个组件，alignCenter是通过调 用于实现上移一层、下移一层、置顶、置底 - ## moveToContainer - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)} config 需要移动的节点 + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} config 需要移动的节点 - `{string | number}` targetId 容器ID - **返回：** - - - Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99) | undefined> + - Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | undefined> - **详情：** 移动到指定容器中 +## dragTo + +- **参数：** + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | [MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]} config 需要拖拽的节点或节点集合 + - {[MContainer](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L139)} targetParent 目标父容器 + - `{number}` targetIndex 目标位置索引 + +- **返回：** + - `{Promise}` + +- **详情：** + + 将节点（支持多选）拖拽到目标容器的指定位置，会自动处理跨容器布局切换并记录历史 + ## undo - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **返回：** - - {Promise<[StepValue](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/type.ts#L400-L404) | null>} - **详情：** @@ -557,7 +568,6 @@ alignCenter可以支持一次水平居中多个组件，alignCenter是通过调 - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **返回：** - - {Promise<[StepValue](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/type.ts#L400-L404) | null>} - **详情：** @@ -569,12 +579,10 @@ alignCenter可以支持一次水平居中多个组件，alignCenter是通过调 - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{number}` left - `{number}` top - **返回：** - - `{Promise}` - **详情：** @@ -608,16 +616,16 @@ alignCenter可以支持一次水平居中多个组件，alignCenter是通过调 - **示例：** ```js -import { editorService, getAddParent } from '@tmagic/editor'; -import { ElMessageBox } from 'element-plus'; +import { editorService, getAddParent } from "@tmagic/editor"; +import { ElMessageBox } from "element-plus"; editorService.use({ // 添加是否删除节点确认提示 async remove(node, next) { - await ElMessageBox.confirm('是否删除', '提示', { - confirmButtonText: '确定', - cancelButtonText: '取消', - type: 'warning', + await ElMessageBox.confirm("是否删除", "提示", { + confirmButtonText: "确定", + cancelButtonText: "取消", + type: "warning", }); next(); @@ -626,7 +634,7 @@ editorService.use({ add(node, next) { // text组件只能添加到container中 const parentNode = getAddParent(node); - if (node.type === 'text' && parentNode?.type !== 'container') { + if (node.type === "text" && parentNode?.type !== "container") { return; } @@ -646,7 +654,7 @@ editorService.use({ - **示例：** ```js -import { editorService } from '@tmagic/editor'; +import { editorService } from "@tmagic/editor"; editorService.usePlugin({ // 添加组件的时候设置一个添加时间 diff --git a/docs/api/editor/events.md b/docs/api/editor/events.md index ffdf9515..45277004 100644 --- a/docs/api/editor/events.md +++ b/docs/api/editor/events.md @@ -4,4 +4,30 @@ - **详情：** 编辑器右侧组件属性配置加载完毕后触发 -- **回调函数：** (formState: [FomState](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/form/src/schema.ts#L27-L39)) => void +- **事件回调函数：** (instance: InstanceType) => void + +## props-panel-unmounted + +- **详情：** 编辑器右侧组件属性配置卸载时触发 + +- **事件回调函数：** () => void + +## update:modelValue + +- **详情：** 当 [modelValue](./props.md#modelvalue-v-model)(DSL) 变化时触发，配合 `v-model` 使用 + +- **事件回调函数：** (value: [MApp](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/schema/src/index.ts?plain=1#L66-L73) | null) => void + +## props-form-error + +- **详情：** 属性表单校验失败时触发 + +- **事件回调函数：** (e: any) => void + +## props-submit-error + +- **详情：** 属性表单提交失败时触发 + +- **事件回调函数：** (e: any) => void + + 注意：`Editor.vue` 中该 emit 的类型签名为 `[e: any]`，运行时通常为 `Error` 实例（来自 `submitForm` 抛错），但也可能是 element-plus 校验返回的 `invalidFields` 结构，业务侧消费时建议先做类型判断 diff --git a/docs/api/editor/eventsServiceMethods.md b/docs/api/editor/eventsServiceMethods.md index e740dc91..43ef9ef5 100644 --- a/docs/api/editor/eventsServiceMethods.md +++ b/docs/api/editor/eventsServiceMethods.md @@ -1,48 +1,5 @@ # eventsService方法 -## init - -- **参数：** - - - {Record} eventMethodList 事件方法列表配置 - -- **返回：** - - - `{void}` - -- **详情：** - - 初始化事件服务，设置所有组件的事件和方法列表 - - :::tip - 该方法通常由编辑器内部调用，开发者可以通过 [m-editor 的 eventMethodList prop](./props.md#eventmethodlist) 来配置 - ::: - -- **示例：** - -```js -import { eventsService } from '@tmagic/editor'; - -eventsService.init({ - page: { - events: [ - { label: '页面加载', value: 'load' }, - { label: '页面卸载', value: 'unload' }, - ], - methods: [ - { label: '刷新', value: 'refresh' }, - { label: '返回', value: 'back' }, - ], - }, - button: { - events: [ - { label: '点击', value: 'click' }, - ], - methods: [], - }, -}); -``` - ## setEvents - **参数：** @@ -185,6 +142,7 @@ eventsService.setMethod('video', [ - **参数：** - `{string}` type 组件类型 + - `{string | number}` _targetId 目标节点id（保留参数，便于扩展时按节点定制） - **返回：** @@ -199,7 +157,7 @@ eventsService.setMethod('video', [ ```js import { eventsService } from '@tmagic/editor'; -const methods = eventsService.getMethod('video'); +const methods = eventsService.getMethod('video', 'video_123'); console.log(methods); // [{ label: '播放', value: 'play' }, ...] ``` diff --git a/docs/api/editor/historyServiceEvents.md b/docs/api/editor/historyServiceEvents.md index c303a299..4793516f 100644 --- a/docs/api/editor/historyServiceEvents.md +++ b/docs/api/editor/historyServiceEvents.md @@ -4,11 +4,14 @@ - **详情：** 页面切换 -- **回调函数：** (undoRedo: [undoRedo](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/utils/undo-redo.ts)) => void +- **事件回调函数：** (undoRedo: [UndoRedo](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/utils/undo-redo.ts)) => void ## change - **详情：** 历史记录发生变化 -- **回调函数：** (state: [StepValue](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/type.ts#L400-L404)) => void +- **事件回调函数：** (state: [StepValue](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/type.ts#L400-L404) | null) => void + :::tip + 当游标处于历史栈边界（已经无法继续撤销或重做）时，`UndoRedo.undo()` / `redo()` 返回 `null`，对应 `change` 回调收到的 `state` 为 `null` + ::: diff --git a/docs/api/editor/historyServiceMethods.md b/docs/api/editor/historyServiceMethods.md index e01612a6..71b80229 100644 --- a/docs/api/editor/historyServiceMethods.md +++ b/docs/api/editor/historyServiceMethods.md @@ -6,29 +6,33 @@ 重置记录 +## resetPage + +- **详情：** + + 重置当前页面的历史记录状态（清空当前页面id，重置 canRedo/canUndo） + +## resetState + +- **详情：** + + 重置历史记录全部内部状态（清空 pageId、pageSteps、canRedo、canUndo） + ## changePage - **参数：** - - - {[MPage](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L61)} page + - {[MPage](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L157) | [MPageFragment](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L162)} page - **详情：** 按页面切换历史堆栈 -## empty - -- **详情：** - - 重置记录，同[reset](#reset) ## push - **参数：** - - {[StepValue](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/type.ts#L400-L404)} state - **返回：** - - {[StepValue](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/type.ts#L400-L404) | null} - **详情：** @@ -38,8 +42,7 @@ ## undo - **返回：** - - - {Promise<[StepValue](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/type.ts#L400-L404) | null>} + - {[StepValue](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/editor/src/type.ts#L554-L573) | null} - **详情：** @@ -48,8 +51,7 @@ ## redo - **返回：** - - - {Promise<[StepValue](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/type.ts#L400-L404) | null>} + - {[StepValue](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/editor/src/type.ts#L554-L573) | null} - **详情：** diff --git a/docs/api/editor/props.md b/docs/api/editor/props.md index 0438a2fa..4d205ed4 100644 --- a/docs/api/editor/props.md +++ b/docs/api/editor/props.md @@ -547,7 +547,7 @@ const propsValues = { 组件属性配置中事件tab中的事件名与动作的下拉选项列表 :::tip - 该属性最终会设置到[eventsService](./eventsServiceMethods.md)中，所以也可直接调用[eventsService.setEvents()](./eventsServiceMethods.md#setEvents)与[eventsService.setMethods()](./eventsServiceMethods#setMethods)方法来配置 + 该属性最终会设置到[eventsService](./eventsServiceMethods.md)中，所以也可直接调用[eventsService.setEvents()](./eventsServiceMethods.md#setEvents)与[eventsService.setMethods()](./eventsServiceMethods.md#setMethods)方法来配置 ::: - **默认值：** `{}` diff --git a/docs/api/editor/propsServiceEvents.md b/docs/api/editor/propsServiceEvents.md index f6aab430..cb123c42 100644 --- a/docs/api/editor/propsServiceEvents.md +++ b/docs/api/editor/propsServiceEvents.md @@ -4,4 +4,4 @@ - **详情：** [propsService.setPropsConfigs()](./propsServiceMethods.md#setPropsConfigs)后触发 -- **回调函数：** () => void +- **事件回调函数：** () => void diff --git a/docs/api/editor/propsServiceMethods.md b/docs/api/editor/propsServiceMethods.md index d496a6f8..decdccfe 100644 --- a/docs/api/editor/propsServiceMethods.md +++ b/docs/api/editor/propsServiceMethods.md @@ -1,16 +1,57 @@ # propsService方法 +## setDisabledDataSource + +- **参数：** + - `{boolean}` disabled 是否禁用数据源 + +- **返回：** + - `{void}` + +- **详情：** + + 设置是否禁用数据源（内部状态），影响 [fillConfig](#fillconfig) 注入的公共配置 + +## setDisabledCodeBlock + +- **参数：** + - `{boolean}` disabled 是否禁用代码块 + +- **返回：** + - `{void}` + +- **详情：** + + 设置是否禁用代码块（内部状态），影响 [fillConfig](#fillconfig) 注入的公共配置 + +## getDisabledDataSource + +- **返回：** + - `{boolean}` 是否禁用数据源 + +- **详情：** + + 获取是否禁用数据源的内部状态 + +## getDisabledCodeBlock + +- **返回：** + - `{boolean}` 是否禁用代码块 + +- **详情：** + + 获取是否禁用代码块的内部状态 + ## fillConfig - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - {[FormConfig](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/form/src/schema.ts#L706)} config + - {[FormConfig](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L864)} config + - `{string}` labelWidth 表单项 label 宽度，默认 `'80px'` - **返回：** - - - {Promise<[FormConfig](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/form/src/schema.ts#L706)>} + - {Promise<[FormConfig](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L864)>} - **详情：** @@ -19,11 +60,9 @@ ## setPropsConfigs - **参数：** - - - {Record} configs + - {Record} configs - **返回：** - - `{void}` - **详情：** @@ -35,12 +74,10 @@ - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{string}` type 组件类型 - - {[FormConfig](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/form/src/schema.ts#L706)} config 属性表单配置DSL + - {[FormConfig](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L864)} config 属性表单配置DSL - **返回：** - - `{Promise}` - **详情：** @@ -52,12 +89,12 @@ - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{string}` type 组件类型 + - `{Object}` data 可选参数 + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210) | null} node 当前节点 - **返回：** - - - {Promise<[FormConfig](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/form/src/schema.ts#L706)>} + - {Promise<[FormConfig](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L864)>} - **详情：** @@ -66,11 +103,9 @@ ## setPropsValues - **参数：** - - - {Record} values + - {Record} values - **返回：** - - `{void}` - **详情：** @@ -80,64 +115,55 @@ ## setPropsValue - **参数：** - - `{string}` type 组件类型 - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)} value 组件初始值 - + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} value 组件初始值 - **返回：** - - `{Promise}` - **详情：** 设置组件与属性表单默认值的对应关系 - ## getPropsValue - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{string}` type 组件类型 - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)} value 组件默认值，可选 - + - `{Object}` defaultValue 组件默认值，可选 - **返回：** - - - `{Promise}` + - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)>} 合并默认配置后的节点对象 - **详情：** - 获取指定类型的组件初始值 + 获取指定类型的组件初始值，会合并 [getDefaultPropsValue](#getdefaultpropsvalue) 与已注册的 propsValue，并自动生成 id ## createId - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - {string} type 组件列席 + - `{string | number}` type 组件类型 - **返回：** - - - `{Promise}` + - `{string}` 生成的组件id（格式为 `type_guid`） - **详情：** 生成组件id + ## setNewItemId - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - - {[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)} config + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} config + - `{boolean}` force 是否强制设置新ID，默认 `true` - **返回：** - - - {Promise<[MNode](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/schema/src/index.ts#L99)>} + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)} 处理后的节点 - **详情：** @@ -148,22 +174,47 @@ - **[扩展支持](../../guide/editor-expand#行为扩展)：** 是 - **参数：** - - `{string}` type 组件类型 - **返回：** - - - `{Promise}` + - `{Object}` 默认属性配置对象（包含 `type`、`style`、`name` 等基础字段，`page`/`container` 类型会额外包含 `layout`、`items`） - **详情：** 获取默认属性配置 +## replaceRelateId + +- **参数：** + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]} originConfigs 原始组件配置 + - {[MNode](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/schema/src/index.ts#L210)[]} targetConfigs 待替换的组件配置 + - `{TargetOptions}` collectorOptions 依赖收集器配置 + +- **返回：** + - `{void}` + +- **详情：** + + 根据 [setNewItemId](#setnewitemid) 收集到的新旧 id 映射，替换目标配置中关联引用的 id（用于复制粘贴时保持组件间的关联依赖） + +## clearRelateId + +- **返回：** + - `{void}` + +- **详情：** + + 清除 [setNewItemId](#setnewitemid) 维护的新旧 id 映射关系 + ## resetState - **详情：** -情况所有组件的属性配置与初始值 + 清空所有组件的属性配置 (`propsConfigMap`) 与初始值 (`propsValueMap`)。 + + ::: tip + 本方法**不会**重置 `disabledDataSource` / `disabledCodeBlock` 标记，也**不会**清空 `relateIdMap`；如需清理后两者，请分别调用 [setDisabledDataSource](#setdisableddatasource) / [setDisabledCodeBlock](#setdisabledcodeblock) 与 [clearRelateId](#clearrelateid)。 + ::: ## destroy diff --git a/docs/api/editor/slots.md b/docs/api/editor/slots.md index 3f0a1f4d..eaee7654 100644 --- a/docs/api/editor/slots.md +++ b/docs/api/editor/slots.md @@ -334,7 +334,7 @@ - **详情：** 编辑器右侧属性配置 -- **默认：** [PropsPanel.vue](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/layouts/PropsPanel.vue) +- **默认：** [PropsPanel.vue](https://github.com/Tencent/tmagic-editor/blob/master/packages/editor/src/layouts/props-panel/PropsPanel.vue) ## props-panel-header diff --git a/docs/api/editor/uiServiceMethods.md b/docs/api/editor/uiServiceMethods.md index 33871947..2b16761e 100644 --- a/docs/api/editor/uiServiceMethods.md +++ b/docs/api/editor/uiServiceMethods.md @@ -24,6 +24,7 @@ - `stageRect`: 画布尺寸 - `columnWidth`: 列宽度配置 - `showGuides`: 是否显示参考线 + - `hasGuides`: 画布上是否存在参考线 - `showRule`: 是否显示标尺 - `propsPanelSize`: 属性面板尺寸 - `showAddPageButton`: 是否显示添加页面按钮 diff --git a/docs/api/form/form-dialog-events.md b/docs/api/form/form-dialog-events.md index 141620f9..9c55a42e 100644 --- a/docs/api/form/form-dialog-events.md +++ b/docs/api/form/form-dialog-events.md @@ -4,24 +4,40 @@ - **详情：** 弹出关闭 -- **回调函数：** () => void - +- **事件回调函数：** `() => void` ## submit -- **详情：** 调用[save()](./form-dialog-methods.md#save) +- **详情：** 调用 [save()](./form-dialog-methods.md#save) 校验通过后触发 -- **回调函数：** (values: any) => void +- **事件回调函数：** `(values: any, eventData: { changeRecords: ChangeRecord[] }) => void` ## error -- **详情：** 表单校验不同 +- **详情：** 表单校验**不**通过时触发 -- **回调函数：** (error: any) => void +- **事件回调函数：** `(invalidFields: Record) => void` + + 注意：与 `Form` 的 `error` 事件一致，回调收到的是 element-plus `validate` 返回的 `invalidFields` 结构，**不是** `Error` 实例。 ## change - **详情：** 表单中任何值发生变化 -- **回调函数：** (values: any) => void +- **事件回调函数：** `(values: any, eventData: ContainerChangeEventData) => void` + 注意：第一个参数是**整张表单**的 `values`，并非单个字段的值。 + + 其中 `ContainerChangeEventData` 定义如下： + + ```ts + interface ChangeRecord { + propPath?: string; + value: any; + } + + interface ContainerChangeEventData { + modifyKey?: string; + changeRecords?: ChangeRecord[]; + } + ``` diff --git a/docs/api/form/form-dialog-methods.md b/docs/api/form/form-dialog-methods.md index 81e204a6..cb8bf494 100644 --- a/docs/api/form/form-dialog-methods.md +++ b/docs/api/form/form-dialog-methods.md @@ -6,8 +6,40 @@ ## save +- **签名：** `save(): Promise` + - **返回：** - - `{Promise}` + - `{Promise}` -- **详情：** 获取表单的值 +- **详情：** 调用内部 Form 的 `submitForm` 进行校验，校验通过后触发 `submit` 事件（参数为表单值与 `{ changeRecords }`）；若校验失败则触发 `error` 事件 + +## show + +- **签名：** `show(): void` + +- **详情：** 打开弹窗，等价于将内部 `dialogVisible` 置为 `true` + +## hide + +- **签名：** `hide(): void` + +- **详情：** 关闭弹窗，等价于将内部 `dialogVisible` 置为 `false` + +## form + +- **类型：** `Ref | undefined>` + +- **详情：** 内部 Form 组件的实例引用，可通过它访问 Form 上 `defineExpose` 暴露的方法与属性 + +## saveFetch + +- **类型：** `Ref` + +- **详情：** 保存按钮的 loading 状态 + +## dialogVisible + +- **类型：** `Ref` + +- **详情：** 弹窗的显示状态 diff --git a/docs/api/form/form-dialog-props.md b/docs/api/form/form-dialog-props.md index 94292890..f45816da 100644 --- a/docs/api/form/form-dialog-props.md +++ b/docs/api/form/form-dialog-props.md @@ -2,61 +2,67 @@ ## config -- **详情：** 表单配置 +- **详情：** 表单配置 - **默认值：** `[]` -- **类型：** [FormConfig](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/form/src/schema.ts#L706) +- **类型：** [FormConfig](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L864) - **示例：** - + ```html ``` ## values -- **详情：** 表单初始化值 +- **详情：** 表单初始化值 - **默认值：** `{}` - **类型：** `Object` - **示例：** - + ```html ``` +## parentValues + +- **详情：** 父级表单值，会透传给内部 Form 组件 + +- **类型：** `Object` + ## width - **详情：** 弹窗宽度 @@ -65,29 +71,46 @@ const values = ref([ ## labelWidth -- **详情：** +- **详情：** -表单域标签的宽度，例如 '50px'。 作为 Form 直接子元素的 form-item 会继承该值。 支持 auto +表单域标签的宽度，例如 '50px'。 作为 Form 直接子元素的 form-item 会继承该值。 支持 auto。 - **默认值：** `'200px'` -- **类型：** `string | number` +- **类型：** `string` ## fullscreen -- **详情：** 弹出是否全屏 - +- **详情：** 是否全屏。 - **默认值：** false -- **类型：** boolean +- **类型：** `boolean` ## disabled -- **详情：** 是否禁用该表单内的所有组件。 若设置为 true，则表单内组件上的 disabled 属性不再生效 +- **详情：** 是否禁用该表单内的所有组件。 若设置为 true，则表单内组件上的 disabled 属性不再生效。 - **默认值：** false -- **类型：** `boolean` +- **类型：** `boolean` + +## inline + +- **详情：** 行内表单模式 + +- **类型：** `boolean` + +## labelPosition + +- **详情：** 表单域标签的位置， 当设置为 left 或 right 时，则也需要设置 label-width 属性 + +- **类型：** `string` + +## zIndex + +- **详情：** 弹窗的 z-index + +- **类型：** `number` ## title @@ -108,3 +131,49 @@ const values = ref([ - **默认值：** `'确定'` - **类型：** `string` + +## preventSubmitDefault + +- **详情：** 是否阻止内部 Form 原生 submit 事件的默认行为 + +- **类型：** `boolean` + +## closeOnClickModal + +- **详情：** 是否可以通过点击 modal 关闭 Dialog + +- **默认值：** `false` + +- **类型：** `boolean` + +## closeOnPressEscape + +- **详情：** 是否可以通过按下 ESC 关闭 Dialog + +- **默认值：** `false` + +- **类型：** `boolean` + +## destroyOnClose + +- **详情：** 关闭时销毁 Dialog 中的元素 + +- **默认值：** `false` + +- **类型：** `boolean` + +## showClose + +- **详情：** 是否显示关闭按钮 + +- **默认值：** `true` + +- **类型：** `boolean` + +## showCancel + +- **详情：** 是否显示底部取消按钮 + +- **默认值：** `true` + +- **类型：** `boolean` diff --git a/docs/api/form/form-events.md b/docs/api/form/form-events.md index 6247cb2e..974352d0 100644 --- a/docs/api/form/form-events.md +++ b/docs/api/form/form-events.md @@ -4,4 +4,46 @@ - **详情：** 表单中任何值发生变化 -- **回调函数：** (values: any) => void +- **事件回调函数：** `(values: any, eventData: ContainerChangeEventData) => void` + + 其中 `ContainerChangeEventData` 定义如下： + + ```ts + interface ChangeRecord { + propPath?: string; + value: any; + } + + interface ContainerChangeEventData { + modifyKey?: string; + changeRecords?: ChangeRecord[]; + } + ``` + +## error + +- **详情：** 表单校验失败时触发。回调收到的是 element-plus `validate` 返回的 `invalidFields` 结构（按字段名分组的校验失败项），而**不是** `Error` 实例 + +- **事件回调函数：** `(invalidFields: Record) => void` + +## field-input + +- **详情：** 表单项 input 事件触发时由内部表单项向上派发，用于监听单个字段的输入 + +- **事件回调函数：** `(prop: string, value: any) => void` + +## field-change + +- **详情：** 表单项 change 事件触发时由内部表单项向上派发，用于监听单个字段的变更 + +- **事件回调函数：** 存在两种派发形式，监听时需注意区分： + - 大多数表单项（如 `Tabs`、`useImport` 等）派发的是 `(prop: string, value: any) => void`； + - 表格类容器（`useSortable`、`useTableColumns` 等）会**只派发整行/整批数据**：`(newData: any) => void`。 + + 如果只关心字段维度，可在回调里通过 `arguments.length === 1` 区分，或在表格类场景额外监听上层的 `change` 事件。 + +## update:stepActive + +- **详情：** 当内部 step 容器切换步骤时触发。`Step.vue` 在点击步骤时派发的是 `index + 1`（`number`），文档类型保留 `string | number` 兼容父级初始传入 + +- **事件回调函数：** `(active: string | number) => void` diff --git a/docs/api/form/form-methods.md b/docs/api/form/form-methods.md index 8d12af89..fd9c0488 100644 --- a/docs/api/form/form-methods.md +++ b/docs/api/form/form-methods.md @@ -6,8 +6,64 @@ ## submitForm +- **签名：** `async (native?: boolean) => Promise` + +- **参数：** + + - `native?: boolean` - 是否返回原始表单值。当 `native` 为 `true` 时返回内部 `values.value`（响应式原值）；否则返回 `cloneDeep(toRaw(values.value))`（深拷贝后的纯对象） + - **返回：** - - `{Promise}` + - `{Promise}` - 校验通过后返回当前表单值；校验失败时会触发 `error` 事件并 throw 一个包含错误信息的 `Error` -- **详情：** 提交表单，获取表单的值 +- **详情：** 提交表单，先执行校验，校验通过后清空 `changeRecords` 并返回当前表单值 + +## changeHandler + +- **签名：** `(prop: string, value: any, eventData?: ContainerChangeEventData) => void` + +- **详情：** 表单项值变更处理函数，会根据传入的 `propPath` 更新内部表单值，并向上 emit `change` 事件 + +## getTextByName + +- **签名：** `(name: string) => string | undefined` + +- **参数：** + + - `name: string` - 字段名，支持点分隔的路径格式，如 `'a.b.c'` + +- **返回：** + + - `{string | undefined}` - 找到的 `text` 值，如果未找到则返回 `undefined` + +- **详情：** 通过 `name` 从表单 `config` 中查找对应表单项的 `text` + +## values + +- **类型：** `Ref` + +- **详情：** 当前表单值的响应式引用 + +## lastValuesProcessed + +- **类型：** `Ref` + +- **详情：** 对比模式下，处理后的待对比表单值 + +## formState + +- **类型：** `FormState` + +- **详情：** 内部使用的 formState 对象（`reactive`），通过 `provide('mForm')` 注入给子组件 + +## initialized + +- **类型：** `Ref` + +- **详情：** 表单是否已经完成初始化 + +## changeRecords + +- **类型：** `ShallowRef` + +- **详情：** 表单变更记录列表，提交成功或重置后会被清空 diff --git a/docs/api/form/form-props.md b/docs/api/form/form-props.md index 5c3421d5..d98415c7 100644 --- a/docs/api/form/form-props.md +++ b/docs/api/form/form-props.md @@ -2,70 +2,94 @@ ## config -- **详情：** 表单配置 +- **详情：** 表单配置 - **默认值：** `[]` -- **类型：** [FormConfig](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/form/src/schema.ts#L706) +- **类型：** [FormConfig](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L864) - **示例：** - + ```html ``` ## initValues -- **详情：** 表单初始化值 +- **详情：** 表单初始化值 - **默认值：** `{}` - **类型：** `Object` - **示例：** - + ```html ``` +## lastValues + +- **详情：** 需对比的值（开启对比模式时传入） + +- **默认值：** `{}` + +- **类型：** `Object` + +## isCompare + +- **详情：** 是否开启对比模式 + +- **默认值：** `false` + +- **类型：** `boolean` + +## parentValues + +- **详情：** 父级表单值 + +- **默认值：** `{}` + +- **类型：** `Object` + ## labelWidth -- **详情：** +- **详情：** 表单域标签的宽度，例如 '50px'。 作为 Form 直接子元素的 form-item 会继承该值。 支持 auto - **默认值：** `'200px'` -- **类型：** `string | number` +- **类型：** `string` ## disabled @@ -73,31 +97,23 @@ const initValues = ref([ - **默认值：** false -- **类型：** `boolean` +- **类型：** `boolean` ## height -- **详情：** - - +- **详情：** 表单容器的高度，会作为内联样式 `height` 应用到表单根元素上 -- **默认值：** +- **默认值：** `'auto'` - - -- **类型：** +- **类型：** `string` ## stepActive -- **详情：** - - +- **详情：** 当表单包含 step 容器时，控制当前激活的步骤 -- **默认值：** +- **默认值：** `1` - - -- **类型：** +- **类型：** `string | number` ## size @@ -105,10 +121,9 @@ const initValues = ref([ - **类型：** `'small' | 'default' | 'large'` - ## inline -- **详情：** 行内表单模式 +- **详情：** 行内表单模式 - **默认值：** false @@ -117,10 +132,9 @@ const initValues = ref([ ## labelPosition - **详情：** 表单域标签的位置， 当设置为 left 或 right 时，则也需要设置 label-width 属性 - -- **默认值：** ’right' +- **默认值：** `'right'` -- **类型：** `'left' | 'right' | 'top` +- **类型：** `string` ## keyProp @@ -135,3 +149,15 @@ const initValues = ref([ - **详情：** tooltip弹出层的class - **类型：** `string` + +## preventSubmitDefault + +- **详情：** 是否阻止表单原生 submit 事件的默认行为 + +- **类型：** `boolean` + +## extendState + +- **详情：** 扩展 formState 的钩子函数，返回的对象会被合并到 formState 上 + +- **类型：** `(state: FormState) => Record | Promise>` diff --git a/docs/api/stage/coreEvents.md b/docs/api/stage/coreEvents.md index 6e8d6b98..1f3159e1 100644 --- a/docs/api/stage/coreEvents.md +++ b/docs/api/stage/coreEvents.md @@ -1,21 +1,96 @@ # stage事件 -## runtime-ready - ## mounted -## highlight +- **参数**：（无） +- **详情**：stage 挂载完成后触发 -## update +## runtime-ready + +- **参数**： + - `runtime: Runtime`：runtime 实例 +- **详情**：runtime 准备就绪时触发 + +## page-el-update + +- **参数**： + - `el: HTMLElement`：当前页面的根节点元素 +- **详情**：当前页面的根节点变化时触发，stage 会同步根节点和画布的大小 + +## change-guides + +- **参数**： + - `data: GuidesEventData`：参考线数据，包含 `type`（参考线方向）和 `guides`（参考线位置数组） +- **详情**：参考线变化时触发 ## select +- **参数**： + - `el: HTMLElement`：被选中的元素 + - `event: MouseEvent`：触发选中的鼠标事件 +- **详情**：单选选中元素时触发 + ## multi-select -## select-parent +- **参数**： + - `els: HTMLElement[]`：被选中的元素列表 + - `event: MouseEvent`：触发选中的鼠标事件 +- **详情**：多选选中元素时触发 -## sort +## dblclick + +- **参数**： + - `event: MouseEvent`：鼠标双击事件 +- **详情**：画布元素被双击时触发 ## update -## change-guides +- **参数**： + - `data: UpdateEventData`：更新事件数据，包含被更新的元素及其样式信息（`width`、`height`、`left`、`top`、`transform` 等）和 `parentEl` +- **详情**：拖拽/缩放等操作更新组件时触发 + +## sort + +- **参数**： + - `data: SortEventData`：排序数据，包含 `src`（源节点 id）、`dist`（目标节点 id）以及 `root` +- **详情**：组件排序变化时触发 + +## select-parent + +- **参数**：（无） +- **详情**：触发选中父级节点时抛出 + +## rerender + +- **参数**：（无） +- **详情**：需要重新渲染画布时触发 + +## remove + +- **参数**： + - `data: RemoveEventData`：被移除元素的数据 +- **详情**：从画布删除组件时触发 + +## highlight + +- **参数**： + - `el: HTMLElement`：被高亮的元素 +- **详情**：高亮元素时触发 + +## mousemove + +- **参数**： + - `event: MouseEvent`：鼠标移动事件 +- **详情**：鼠标在画布上移动**且命中带 magic id 的节点元素**时触发；若 `getElementFromPoint` 拿不到带 id 的节点（例如悬空在画布空白处），则不会派发该事件 + +## mouseleave + +- **参数**： + - `event: MouseEvent`：鼠标离开事件 +- **详情**：鼠标离开画布时触发 + +## drag-start + +- **参数**： + - `event: OnDragStart`：moveable 的拖拽开始事件 +- **详情**：开始拖拽元素时触发 diff --git a/docs/api/stage/coreMethods.md b/docs/api/stage/coreMethods.md index 3fa063b8..83469f9e 100644 --- a/docs/api/stage/coreMethods.md +++ b/docs/api/stage/coreMethods.md @@ -2,47 +2,78 @@ ## select -- **详情：** 单选选中元素 +- **类型**：`(id: Id, event?: MouseEvent) => Promise` +- **参数**： + - `id`：选中节点的 id + - `event`：触发选中的鼠标事件（可选） +- **详情**：单选选中元素 ## multiSelect -- **详情：** 多选选中多个元素 +- **类型**：`(ids: Id[]) => Promise` +- **参数**： + - `ids`：选中元素的 id 列表 +- **详情**：多选选中多个元素 ## highlight -- **详情：** 高亮选中元素 +- **类型**：`(id: Id) => void` +- **参数**： + - `id`：要高亮的节点 id +- **详情**：按 id 高亮节点 + +## clearHighlight + +- **类型**：`() => void` +- **详情**：清除高亮 ## update -- **详情：** 更新组件 +- **类型**：`(data: UpdateData) => Promise` +- **参数**： + - `data`：更新组件所需的数据，包含 `config`、`parent`、`parentId`、`root` 等字段 +- **详情**：更新组件 ## add -- **详情：** 往画布增加一个组件 +- **类型**：`(data: UpdateData) => Promise` +- **参数**： + - `data`：组件信息数据，包含要新增组件的 `config`、`parent`、`parentId`、`root` 等字段 +- **详情**：往画布增加一个组件 ## remove -- **详情：** 从画布删除一个组件 +- **类型**：`(data: RemoveData) => Promise` +- **参数**： + - `data`：组件信息数据，包含要删除组件的 `id`、`parentId`、`root` 等字段 +- **详情**：从画布删除一个组件 ## setZoom -- **详情：** +- **类型**：`(zoom?: number) => void` +- **参数**： + - `zoom`：缩放比例，缺省时使用 `DEFAULT_ZOOM` +- **详情**：设置画布缩放比例 ## mount -- **详情：** 挂载Dom节点 +- **类型**：`(el: HTMLDivElement) => Promise` +- **参数**： + - `el`：将 stage 挂载到该 Dom 节点上 +- **详情**：挂载 Dom 节点 ## clearGuides -- **详情：** 清空所有参考线 - -## clearGuides - -- **详情：** 清空所有参考线 +- **类型**：`() => void` +- **详情**：清空所有参考线 ## delayedMarkContainer -- **详情：** +- **类型**：`(event: MouseEvent, excludeElList?: Element[]) => NodeJS.Timeout | undefined` +- **参数**： + - `event`：鼠标事件 + - `excludeElList`：计算鼠标所在容器时要排除的元素列表 +- **详情**： 鼠标拖拽着元素，在容器上方悬停，延迟一段时间后，对容器进行标记，如果悬停时间够长将标记成功，悬停时间短，调用方通过返回的timeoutId取消标记 @@ -52,7 +83,54 @@ 2、释放鼠标后，通过标记的标志找到要加入的容器 +## getAddContainerHighlightClassNameTimeout + +- **类型**：`(event: MouseEvent, excludeElList?: Element[]) => NodeJS.Timeout | undefined` +- **参数**： + - `event`：鼠标事件 + - `excludeElList`：计算鼠标所在容器时要排除的元素列表 +- **详情**：@deprecated 废弃接口，建议用 [delayedMarkContainer](#delayedmarkcontainer) 代替 + +## getMoveableOption + +- **类型**：`(key: K) => MoveableOptions[K] | undefined` +- **参数**: + - `key`：要获取的 moveable 配置项名称 +- **详情**：获取 moveable 配置项的当前值 + +## getDragStatus + +- **类型**：`() => StageDragStatus | undefined` +- **详情**：获取当前画布的拖拽状态 + +## disableMultiSelect + +- **类型**：`() => void` +- **详情**：禁用多选能力 + +## enableMultiSelect + +- **类型**：`() => void` +- **详情**：启用多选能力 + +## reloadIframe + +- **类型**：`(url: string) => void` +- **参数**： + - `url`：重新加载的 runtime 地址 +- **详情**：重新加载 runtime iframe + +## getElementImage + +- **类型**：`(id: Id, type?: 'download' | 'raw' | 'svg' | 'canvas' | 'png' | 'jpeg' | 'webp' | 'blob', options?: SnapdomOptions) => Promise` +- **参数**： + - `id`：要截图的节点 id + - `type`：导出类型，默认为 `'png'` + - `options`：[snapdom](https://github.com/zumerlab/snapdom) 选项 +- **详情**：将指定 id 的 dom 元素生成为图片 + ## destroy -- **详情：** 销毁实例 +- **类型**：`() => void` +- **详情**：销毁实例 diff --git a/docs/api/table/events.md b/docs/api/table/events.md index c7c36df5..80bff895 100644 --- a/docs/api/table/events.md +++ b/docs/api/table/events.md @@ -20,15 +20,30 @@ ## after-action - **参数：** - - `action: string` - 操作类型 - - `data: any` - 操作相关数据 + - `payload: { index: number }` - 触发动作所在行的索引 -- **说明：** 表格操作完成后触发 +- **说明：** 表格行的编辑型动作（如 actions 中 `type: 'edit'` 的保存）执行结束后触发。 + + 注意：`ActionsColumn` 在 handler 返回值为「假值」（如 `undefined`/`null`/未返回）时同样会派发该事件；**仅当**返回值为对象且 `res.ret !== 0` 时才视为失败、不派发。如果业务需要严格在「业务接口成功」后再处理，应在 handler 内显式 `return { ret: 0 }` 并在监听处自行判断 `res.ret`。 - **示例：** ```js - const handleAfterAction = (action, data) => { - console.log('操作完成:', action, data); + const handleAfterAction = ({ index }) => { + console.log('操作完成，行索引:', index); + }; + ``` + +## after-action-cancel + +- **参数：** + - `payload: { index: number }` - 触发动作所在行的索引 + +- **说明：** 表格行的编辑型动作被取消后触发 + +- **示例：** + ```js + const handleAfterActionCancel = ({ index }) => { + console.log('操作取消，行索引:', index); }; ``` diff --git a/docs/api/table/props.md b/docs/api/table/props.md index 9bfcd046..3afc9c29 100644 --- a/docs/api/table/props.md +++ b/docs/api/table/props.md @@ -3,23 +3,22 @@ ## data - **详情：** 表格数据，数组格式 - -- **默认值：** `[]` + +- **必填：** 是 - **类型：** `Array` - **示例：** ```js [ - { id: 1, name: '张三', age: 20 }, - { id: 2, name: '李四', age: 25 } - ] + { id: 1, name: "张三", age: 20 }, + { id: 2, name: "李四", age: 25 }, + ]; ``` ## columns - **详情：** 表格列配置 - - **默认值：** `[]` - **类型：** `Array` @@ -27,22 +26,20 @@ - **示例：** ```js [ - { prop: 'name', label: '姓名', width: 120 }, - { prop: 'age', label: '年龄', width: 80 } - ] + { prop: "name", label: "姓名", width: 120 }, + { prop: "age", label: "年龄", width: 80 }, + ]; ``` ## spanMethod - **详情：** 合并行或列的计算方法 - - **默认值：** `undefined` - **类型：** `Function` - **参数：** - `{ row, column, rowIndex, columnIndex }` - - **返回值：** `[rowspan, colspan]` 或 `{ rowspan, colspan }` - **示例：** @@ -55,13 +52,12 @@ return [0, 0]; } } - } + }; ``` ## loading - **详情：** 是否显示加载状态 - - **默认值：** `false` - **类型：** `boolean` @@ -69,7 +65,6 @@ ## showHeader - **详情：** 是否显示表头 - - **默认值：** `true` - **类型：** `boolean` @@ -77,21 +72,19 @@ ## bodyHeight - **详情：** Table 的最大高度。合法的值为数字或者单位为 px 的高度 - - **默认值：** `undefined` - **类型：** `string | number` - **示例：** ```js - bodyHeight: 400 - bodyHeight: '400px' + bodyHeight: 400; + bodyHeight: "400px"; ``` ## emptyText - **详情：** 空数据时显示的文本内容 - - **默认值：** `'暂无数据'` - **类型：** `string` @@ -99,7 +92,6 @@ ## defaultExpandAll - **详情：** 是否默认展开所有行，当 Table 包含展开行存在或者为树形表格时有效 - - **默认值：** `false` - **类型：** `boolean` @@ -107,7 +99,6 @@ ## rowkeyName - **详情：** 行数据的 Key，用来优化 Table 的渲染 - - **默认值：** `'id'` - **类型：** `string` @@ -117,7 +108,6 @@ ## border - **详情：** 是否显示边框 - - **默认值：** `false` - **类型：** `boolean` diff --git a/docs/form-config/editor-fields/code-link.md b/docs/form-config/editor-fields/code-link.md index 498fb15b..14a225b2 100644 --- a/docs/form-config/editor-fields/code-link.md +++ b/docs/form-config/editor-fields/code-link.md @@ -28,11 +28,12 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| formTitle | 弹窗标题 | string | — | — | -| codeOptions | 代码编辑器配置项 | object | — | — | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ----------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| formTitle | 弹窗标题 | string | — | — | +| codeOptions | 代码编辑器配置项 | object | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/editor-fields/code-select-col.md b/docs/form-config/editor-fields/code-select-col.md index c0650eab..7f8cf831 100644 --- a/docs/form-config/editor-fields/code-select-col.md +++ b/docs/form-config/editor-fields/code-select-col.md @@ -28,10 +28,11 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| notEditable | 是否不可编辑代码块（disable控制是否可选择） | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ----------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| notEditable | 是否不可编辑代码块（disable控制是否可选择） | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/editor-fields/code-select.md b/docs/form-config/editor-fields/code-select.md index f6ca8be0..495dbd0c 100644 --- a/docs/form-config/editor-fields/code-select.md +++ b/docs/form-config/editor-fields/code-select.md @@ -19,15 +19,17 @@ ## 功能说明 CodeSelect 组件支持： + - 选择代码块 - 选择数据源方法 - 配置代码块参数 ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| className | 自定义类名 | string | — | — | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| --------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| className | 自定义类名 | string | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/editor-fields/code.md b/docs/form-config/editor-fields/code.md index 53782884..28bcc3a7 100644 --- a/docs/form-config/editor-fields/code.md +++ b/docs/form-config/editor-fields/code.md @@ -10,7 +10,7 @@ ```js { - type: 'code', + type: 'vs-code', name: 'code', text: '代码' } @@ -20,7 +20,7 @@ ```js { - type: 'code', + type: 'vs-code', name: 'code', text: '代码', language: 'javascript' @@ -31,7 +31,7 @@ ```js { - type: 'code', + type: 'vs-code', name: 'code', text: '代码', autosize: { @@ -42,20 +42,23 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| language | 代码语言 | string | javascript/typescript/json等 | — | -| height | 编辑器高度 | string | — | — | -| parse | 是否解析代码 | boolean | — | false | -| options | 编辑器配置项 | object | — | — | -| autosize | 自动调整大小配置 | object | — | — | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| language | 代码语言 | string | javascript/typescript/json等 | — | +| height | 编辑器高度 | string | — | — | +| parse | 是否解析代码 | boolean | — | false | +| options | 编辑器配置项 | object | — | — | +| autosize | 自动调整大小配置 | object | — | — | +| mFormItemType | 传入代码编辑器的自定义类型 | string | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | ## autosize Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| minRows | 最小行数 | number | — | — | -| maxRows | 最大行数 | number | — | — | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ------- | -------- | ------ | ------ | ------ | +| minRows | 最小行数 | number | — | — | +| maxRows | 最大行数 | number | — | — | diff --git a/docs/form-config/editor-fields/cond-op-select.md b/docs/form-config/editor-fields/cond-op-select.md index 8c87fb30..50b6767c 100644 --- a/docs/form-config/editor-fields/cond-op-select.md +++ b/docs/form-config/editor-fields/cond-op-select.md @@ -10,7 +10,7 @@ ```js { - type: 'cond-op', + type: 'cond-op-select', name: 'op', text: '操作符' } @@ -20,7 +20,7 @@ ```js { - type: 'cond-op', + type: 'cond-op-select', name: 'op', text: '操作符', parentFields: ['field1', 'field2'] @@ -28,10 +28,11 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| parentFields | 父级字段 | string[] | — | — | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| parentFields | 父级字段 | string[] | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/editor-fields/data-source-field-select.md b/docs/form-config/editor-fields/data-source-field-select.md index feee0ccb..d6647f12 100644 --- a/docs/form-config/editor-fields/data-source-field-select.md +++ b/docs/form-config/editor-fields/data-source-field-select.md @@ -50,18 +50,20 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| value | 返回值类型 | string | key/value | — | -| checkStrictly | 是否严格遵守父子节点不互相关联 | boolean / Function | — | — | -| dataSourceFieldType | 允许选择的字段类型 | DataSourceFieldType[] | — | — | -| fieldConfig | 自定义字段配置 | ChildConfig | — | — | -| notEditable | 是否不可编辑数据源（disable控制是否可选择） | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| value | 返回值类型 | string | key/value | — | +| checkStrictly | 是否严格遵守父子节点不互相关联 | boolean / Function | — | — | +| dataSourceFieldType | 允许选择的字段类型 | DataSourceFieldType[] | — | — | +| fieldConfig | 自定义字段配置 | ChildConfig | — | — | +| notEditable | 是否不可编辑数据源（disable控制是否可选择） | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | ## value说明 + - `key`: 不编译，返回数据源id和字段name - `value`: 编译后返回数据源data[field] diff --git a/docs/form-config/editor-fields/data-source-fields.md b/docs/form-config/editor-fields/data-source-fields.md index 33a848da..e727cdeb 100644 --- a/docs/form-config/editor-fields/data-source-fields.md +++ b/docs/form-config/editor-fields/data-source-fields.md @@ -17,9 +17,10 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| -------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/editor-fields/data-source-input.md b/docs/form-config/editor-fields/data-source-input.md index 95434083..98087f94 100644 --- a/docs/form-config/editor-fields/data-source-input.md +++ b/docs/form-config/editor-fields/data-source-input.md @@ -17,9 +17,10 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| -------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/editor-fields/data-source-method-select.md b/docs/form-config/editor-fields/data-source-method-select.md index d7fcba7a..c82ab128 100644 --- a/docs/form-config/editor-fields/data-source-method-select.md +++ b/docs/form-config/editor-fields/data-source-method-select.md @@ -28,10 +28,11 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| notEditable | 是否不可编辑数据源（disable控制是否可选择） | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ----------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| notEditable | 是否不可编辑数据源（disable控制是否可选择） | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/editor-fields/data-source-methods.md b/docs/form-config/editor-fields/data-source-methods.md index 73a2d804..1999d296 100644 --- a/docs/form-config/editor-fields/data-source-methods.md +++ b/docs/form-config/editor-fields/data-source-methods.md @@ -17,9 +17,10 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| -------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/editor-fields/data-source-mocks.md b/docs/form-config/editor-fields/data-source-mocks.md index fd095595..5657bda6 100644 --- a/docs/form-config/editor-fields/data-source-mocks.md +++ b/docs/form-config/editor-fields/data-source-mocks.md @@ -17,9 +17,10 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| -------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/editor-fields/data-source-select.md b/docs/form-config/editor-fields/data-source-select.md index 64c5bab7..2218b78b 100644 --- a/docs/form-config/editor-fields/data-source-select.md +++ b/docs/form-config/editor-fields/data-source-select.md @@ -39,17 +39,19 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| placeholder | 输入框占位文本 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| dataSourceType | 数据源类型过滤 | string | base/http等 | — | -| value | 返回值类型 | string | id/value | — | -| notEditable | 是否不可编辑数据源（disable控制是否可选择） | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| -------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| placeholder | 输入框占位文本 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| dataSourceType | 数据源类型过滤 | string | base/http等 | — | +| value | 返回值类型 | string | id/value | — | +| notEditable | 是否不可编辑数据源（disable控制是否可选择） | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | ## value说明 + - `id`: 不编译，返回数据源id - `value`: 编译后返回数据源data diff --git a/docs/form-config/editor-fields/display-conds.md b/docs/form-config/editor-fields/display-conds.md index 620c8373..15db7ae1 100644 --- a/docs/form-config/editor-fields/display-conds.md +++ b/docs/form-config/editor-fields/display-conds.md @@ -28,11 +28,12 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| titlePrefix | 标题前缀 | string | — | — | -| parentFields | 父级字段 | string[] / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | — | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| titlePrefix | 标题前缀 | string | — | — | +| parentFields | 父级字段 | string[] / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/editor-fields/event-select.md b/docs/form-config/editor-fields/event-select.md index 77a86b28..31e02f21 100644 --- a/docs/form-config/editor-fields/event-select.md +++ b/docs/form-config/editor-fields/event-select.md @@ -29,21 +29,23 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| src | 事件来源 | string | datasource/component | — | -| labelWidth | 标签宽度 | string | — | — | -| eventNameConfig | 事件名称表单配置 | FormItem | — | — | -| actionTypeConfig | 动作类型配置 | FormItem | — | — | -| targetCompConfig | 联动组件配置 | FormItem | — | — | -| compActionConfig | 联动组件动作配置 | FormItem | — | — | -| codeActionConfig | 联动代码配置 | FormItem | — | — | -| dataSourceActionConfig | 联动数据源配置 | FormItem | — | — | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ---------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| src | 事件来源 | string | datasource/component | — | +| labelWidth | 标签宽度 | string | — | — | +| eventNameConfig | 事件名称表单配置 | FormItem | — | — | +| actionTypeConfig | 动作类型配置 | FormItem | — | — | +| targetCompConfig | 联动组件配置 | FormItem | — | — | +| compActionConfig | 联动组件动作配置 | FormItem | — | — | +| codeActionConfig | 联动代码配置 | FormItem | — | — | +| dataSourceActionConfig | 联动数据源配置 | FormItem | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | ## src说明 + - `component`: 组件事件 - `datasource`: 数据源事件 diff --git a/docs/form-config/editor-fields/key-value.md b/docs/form-config/editor-fields/key-value.md index 54841fbc..27c24fad 100644 --- a/docs/form-config/editor-fields/key-value.md +++ b/docs/form-config/editor-fields/key-value.md @@ -30,10 +30,11 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| advanced | 是否支持高级模式（代码编辑） | boolean | — | false | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| -------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| advanced | 是否支持高级模式（代码编辑） | boolean | — | false | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/editor-fields/page-fragment-select.md b/docs/form-config/editor-fields/page-fragment-select.md index 3db1c170..261b0231 100644 --- a/docs/form-config/editor-fields/page-fragment-select.md +++ b/docs/form-config/editor-fields/page-fragment-select.md @@ -17,12 +17,13 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| -------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | ## 使用说明 diff --git a/docs/form-config/editor-fields/ui-select.md b/docs/form-config/editor-fields/ui-select.md index e0e5c3dc..e81ddfcd 100644 --- a/docs/form-config/editor-fields/ui-select.md +++ b/docs/form-config/editor-fields/ui-select.md @@ -17,12 +17,13 @@ ``` ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| -------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | ## 使用说明 diff --git a/docs/form-config/fields/date-picker.md b/docs/form-config/fields/date-picker.md index 7cc0be9e..999ad11c 100644 --- a/docs/form-config/fields/date-picker.md +++ b/docs/form-config/fields/date-picker.md @@ -9,11 +9,12 @@ name: 'date', text: '日期选择器' }]"> - + ## 禁用状态 @@ -24,11 +25,12 @@ text: '日期选择器', disabled: () => true }]"> - + ## 占位符 @@ -39,11 +41,12 @@ text: '日期选择器', placeholder: '请选择日期' }]"> - + ## 日期格式 @@ -56,23 +59,23 @@ 请注意大小写 ::: -| 格式 | 含义 | 备注 | 举例 | -|------|------|------|------| -| `YYYY` | 年 | | 2017 | -| `M` | 月 | 不补0 | 1 | -| `MM` | 月 | | 01 | -| `D` | 日 | 不补0 | 2 | -| `DD` | 日 | | 02 | -| `H` | 小时 | 24小时制；不补0 | 3 | -| `HH` | 小时 | 24小时制 | 03 | -| `h` | 小时 | 12小时制，须和 `A` 或 `a` 使用；不补0 | 3 | -| `hh` | 小时 | 12小时制，须和 `A` 或 `a` 使用 | 03 | -| `m` | 分钟 | 不补0 | 4 | -| `mm` | 分钟 | | 04 | -| `s` | 秒 | 不补0 | 5 | -| `ss` | 秒 | | 05 | -| `x` | JS时间戳 | 组件绑定值为`number`类型 | 1483326245000 | -| `[MM]` | 不需要格式化字符 | 使用方括号标识不需要格式化的字符 (如 [A] [MM]) | MM | +| 格式 | 含义 | 备注 | 举例 | +| ------ | ---------------- | ---------------------------------------------- | ------------- | +| `YYYY` | 年 | | 2017 | +| `M` | 月 | 不补0 | 1 | +| `MM` | 月 | | 01 | +| `D` | 日 | 不补0 | 2 | +| `DD` | 日 | | 02 | +| `H` | 小时 | 24小时制；不补0 | 3 | +| `HH` | 小时 | 24小时制 | 03 | +| `h` | 小时 | 12小时制，须和 `A` 或 `a` 使用；不补0 | 3 | +| `hh` | 小时 | 12小时制，须和 `A` 或 `a` 使用 | 03 | +| `m` | 分钟 | 不补0 | 4 | +| `mm` | 分钟 | | 04 | +| `s` | 秒 | 不补0 | 5 | +| `ss` | 秒 | | 05 | +| `x` | JS时间戳 | 组件绑定值为`number`类型 | 1483326245000 | +| `[MM]` | 不需要格式化字符 | 使用方括号标识不需要格式化的字符 (如 [A] [MM]) | MM | - + ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------------- |---------- |-------------------------------- |-------- | -| name | 绑定值的字段名 | string | — | — | -| text | 表单标签 | string | — | — | -| placeholder | 输入框占位文本 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| format | 显示在输入框中的格式 | string | 见[日期格式](#日期格式) | YYYY/MM/DD | -| valueFormat | 绑定值的格式。不指定则绑定值为 Date 对象 | string | 见[日期格式](#日期格式) | YYYY/MM/DD | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | — | +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ----------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------- | +| name | 绑定值的字段名 | string | — | — | +| text | 表单标签 | string | — | — | +| placeholder | 输入框占位文本 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| format | 显示在输入框中的格式 | string | 见[日期格式](#日期格式) | YYYY/MM/DD | +| valueFormat | 绑定值的格式。不指定则绑定值为 Date 对象 | string | 见[日期格式](#日期格式) | YYYY/MM/DD | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | — | ## TypeScript 定义 ```typescript interface DateConfig extends FormItem, Input { - type: 'date'; - format?: 'YYYY-MM-dd HH:mm:ss' | string; - valueFormat?: 'YYYY-MM-dd HH:mm:ss' | string; + type: "date"; + format?: "YYYY-MM-dd HH:mm:ss" | string; + valueFormat?: "YYYY-MM-dd HH:mm:ss" | string; } ``` - diff --git a/docs/form-config/fields/daterange-picker.md b/docs/form-config/fields/daterange-picker.md index 184ffefb..89e16cd8 100644 --- a/docs/form-config/fields/daterange-picker.md +++ b/docs/form-config/fields/daterange-picker.md @@ -9,11 +9,12 @@ name: 'daterange', text: '日期范围' }]"> - + ## 绑定多个字段 @@ -25,22 +26,24 @@ names: ['startTime', 'endTime'], text: '日期范围' }]"> - + ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------------- |---------- |-------------------------------- |-------- | -| name | 绑定值（数组形式） | string | — | — | -| names | 绑定值（拆分为两个字段） | string[] | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| dateFormat | 日期格式 | string | — | YYYY/MM/DD | -| timeFormat | 时间格式 | string | — | HH:mm:ss | -| valueFormat | 绑定值的格式 | string | — | YYYY/MM/DD HH:mm:ss | -| defaultTime | 默认时间 | Date[] | — | — | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ----------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------- | +| name | 绑定值（数组形式） | string | — | — | +| names | 绑定值（拆分为两个字段） | string[] | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| dateFormat | 日期格式 | string | — | YYYY/MM/DD | +| timeFormat | 时间格式 | string | — | HH:mm:ss | +| valueFormat | 绑定值的格式 | string | — | YYYY/MM/DD HH:mm:ss | +| defaultTime | 默认时间 | Date[] | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/fields/datetime-picker.md b/docs/form-config/fields/datetime-picker.md index 2e528290..cee7abb8 100644 --- a/docs/form-config/fields/datetime-picker.md +++ b/docs/form-config/fields/datetime-picker.md @@ -9,11 +9,12 @@ name: 'dateTime', text: '日期时间选择器' }]"> - + ## 带占位符 @@ -24,11 +25,12 @@ text: '日期时间选择器', placeholder: '请选择日期时间' }]"> - + ## 禁用状态 @@ -39,11 +41,12 @@ text: '日期时间选择器', disabled: () => true }]"> - + ## 日期格式 @@ -56,25 +59,25 @@ 请注意大小写 ::: -| 格式 | 含义 | 备注 | 举例 | -|------|------|------|------| -| `YYYY` | 年 | | 2017 | -| `M` | 月 | 不补0 | 1 | -| `MM` | 月 | | 01 | -| `D` | 日 | 不补0 | 2 | -| `DD` | 日 | | 02 | -| `H` | 小时 | 24小时制；不补0 | 3 | -| `HH` | 小时 | 24小时制 | 03 | -| `h` | 小时 | 12小时制，须和 `A` 或 `a` 使用；不补0 | 3 | -| `hh` | 小时 | 12小时制，须和 `A` 或 `a` 使用 | 03 | -| `m` | 分钟 | 不补0 | 4 | -| `mm` | 分钟 | | 04 | -| `s` | 秒 | 不补0 | 5 | -| `ss` | 秒 | | 05 | -| `A` | AM/PM | 仅 `format` 可用，大写 | AM | -| `a` | am/pm | 仅 `format` 可用，小写 | am | -| `x` | JS时间戳（毫秒） | 仅 `valueFormat` 可用 | 1483326245000 | -| `X` | Unix时间戳（秒） | 仅 `valueFormat` 可用 | 1483326245 | +| 格式 | 含义 | 备注 | 举例 | +| ------ | ---------------- | ------------------------------------- | ------------- | +| `YYYY` | 年 | | 2017 | +| `M` | 月 | 不补0 | 1 | +| `MM` | 月 | | 01 | +| `D` | 日 | 不补0 | 2 | +| `DD` | 日 | | 02 | +| `H` | 小时 | 24小时制；不补0 | 3 | +| `HH` | 小时 | 24小时制 | 03 | +| `h` | 小时 | 12小时制，须和 `A` 或 `a` 使用；不补0 | 3 | +| `hh` | 小时 | 12小时制，须和 `A` 或 `a` 使用 | 03 | +| `m` | 分钟 | 不补0 | 4 | +| `mm` | 分钟 | | 04 | +| `s` | 秒 | 不补0 | 5 | +| `ss` | 秒 | | 05 | +| `A` | AM/PM | 仅 `format` 可用，大写 | AM | +| `a` | am/pm | 仅 `format` 可用，小写 | am | +| `x` | JS时间戳（毫秒） | 仅 `valueFormat` 可用 | 1483326245000 | +| `X` | Unix时间戳（秒） | 仅 `valueFormat` 可用 | 1483326245 | - + ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------------- |---------- |-------------------------------- |-------- | -| name | 绑定值的字段名 | string | — | — | -| text | 表单标签 | string | — | — | -| placeholder | 输入框占位文本 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| format | 显示在输入框中的格式 | string | 见[日期格式](#日期格式) | YYYY/MM/DD HH:mm:ss | -| valueFormat | 绑定值的格式 | string | 见[日期格式](#日期格式) | YYYY/MM/DD HH:mm:ss | -| defaultTime | 选择日期后的默认时间值 | Date | — | — | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | — | +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ----------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------- | +| name | 绑定值的字段名 | string | — | — | +| text | 表单标签 | string | — | — | +| placeholder | 输入框占位文本 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| format | 显示在输入框中的格式 | string | 见[日期格式](#日期格式) | YYYY/MM/DD HH:mm:ss | +| valueFormat | 绑定值的格式 | string | 见[日期格式](#日期格式) | YYYY/MM/DD HH:mm:ss | +| defaultTime | 选择日期后的默认时间值 | Date | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | — | diff --git a/docs/form-config/fields/display.md b/docs/form-config/fields/display.md index cd7e2ee5..6edc41e6 100644 --- a/docs/form-config/fields/display.md +++ b/docs/form-config/fields/display.md @@ -1,4 +1,3 @@ - # Display 只读文本 用于显示，不可编辑 @@ -7,11 +6,11 @@ ```typescript interface Display extends FormItem { - type: 'display'; + type: "display"; } ``` -点击查看[FormItem](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts)的定义 +点击查看[FormItem](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L90)的定义 ## 基础用法 @@ -21,16 +20,16 @@ interface Display extends FormItem { text: '只读文本', defaultValue: 'display' }]"> - + - ## Input Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ---- | -------- | ------ | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | diff --git a/docs/form-config/fields/dynamic-field.md b/docs/form-config/fields/dynamic-field.md index d089b708..0c26c5e4 100644 --- a/docs/form-config/fields/dynamic-field.md +++ b/docs/form-config/fields/dynamic-field.md @@ -9,8 +9,8 @@ name: 'type', text: '类型', options: [ - { label: '类型A', value: 'a' }, - { label: '类型B', value: 'b' } + { text: '类型A', value: 'a' }, + { text: '类型B', value: 'b' } ] }, { type: 'dynamic-field', diff --git a/docs/form-config/fields/hidden.md b/docs/form-config/fields/hidden.md index e84dd6e1..7f83e0ce 100644 --- a/docs/form-config/fields/hidden.md +++ b/docs/form-config/fields/hidden.md @@ -6,11 +6,11 @@ ```typescript interface Hidden extends FormItem { - type: 'hidden'; + type: "hidden"; } ``` -点击查看[FormItem](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts)的定义 +点击查看[FormItem](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L90)的定义 ## 基础用法 @@ -18,15 +18,15 @@ interface Hidden extends FormItem { type: 'hidden', name: 'hidden' }]"> - + - ## Input Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ---- | ------ | ------ | ------ | ------ | +| name | 绑定值 | string | — | — | diff --git a/docs/form-config/fields/link.md b/docs/form-config/fields/link.md index 1c7a0a35..3b90964f 100644 --- a/docs/form-config/fields/link.md +++ b/docs/form-config/fields/link.md @@ -6,7 +6,7 @@ ```typescript interface Link extends FormItem { - type: 'link'; + type: "link"; href?: string | typeof LinkHrefFunction; css?: { [key: string]: string | number; @@ -18,10 +18,11 @@ interface Link extends FormItem { formWidth?: number | string; displayText?: string | typeof LinkDisplayTextFunction; form: FormConfig | typeof LinkFormFunction; + fullscreen?: boolean; } ``` -点击查看[FormItem](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts)的定义 +点击查看[FormItem](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L90)的定义 ## 基础用法 @@ -31,11 +32,11 @@ interface Link extends FormItem { text: '链接', href: 'https://tencent.github.io/tmagic-editor/playground/index.html#/' }]"> - + ## 打开表单 @@ -49,16 +50,16 @@ interface Link extends FormItem { text: 'input' }] }]"> - + - ## Input Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ---- | -------- | ------ | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | diff --git a/docs/form-config/fields/number-range.md b/docs/form-config/fields/number-range.md index 22a4e106..612254e1 100644 --- a/docs/form-config/fields/number-range.md +++ b/docs/form-config/fields/number-range.md @@ -9,18 +9,20 @@ name: 'numberRange', text: '数字范围' }]"> - + ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------------- |---------- |-------------------------------- |-------- | -| name | 绑定值（数组形式 [min, max]） | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| clearable | 是否可清空 | boolean | — | true | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| --------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值（数组形式 [min, max]） | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| clearable | 是否可清空 | boolean | — | true | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/fields/number.md b/docs/form-config/fields/number.md index 01e8d66b..2cff78f1 100644 --- a/docs/form-config/fields/number.md +++ b/docs/form-config/fields/number.md @@ -9,11 +9,12 @@ name: 'number', text: '计数器' }]"> - + ## 禁用状态 @@ -24,11 +25,12 @@ text: '计数器', disabled: () => true }]"> - + ## 步数 @@ -41,23 +43,24 @@ text: '计数器', step: 10 }]"> - + - ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|----------|-------------- |----------|-------------------------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| placeholder | 输入框占位文本 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| min | 设置计数器允许的最小值 | number | — | -Infinity | -| max | 设置计数器允许的最大值 | number | — | Infinity | -| step | 计数器步长 | number | — | 1 | -| tooltip | 输入框提示信息 | string | — | — | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ----------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------- | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| placeholder | 输入框占位文本 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| min | 设置计数器允许的最小值 | number | — | -Infinity | +| max | 设置计数器允许的最大值 | number | — | Infinity | +| step | 计数器步长 | number | — | 1 | +| tooltip | 输入框提示信息 | string | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/fields/radio.md b/docs/form-config/fields/radio.md index 6b730069..01a297ba 100644 --- a/docs/form-config/fields/radio.md +++ b/docs/form-config/fields/radio.md @@ -6,15 +6,18 @@ ```typescript interface RadioGroup extends FormItem { - type: 'radio-group'; + type: "radio-group"; + childType?: "default" | "button"; options: { value: any; - text: string; + text?: string; + icon?: any; + tooltip?: string; }[]; } ``` -点击查看[FormItem](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts)的定义 +点击查看[FormItem](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L90)的定义 ## 基础用法 @@ -29,11 +32,12 @@ interface RadioGroup extends FormItem { { text: '选项2', value: 2 } ] }]"> - + ## 禁用状态 @@ -50,18 +54,30 @@ interface RadioGroup extends FormItem { ], disabled: () => true }]"> - + ## RadioGroup Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| options | 选项 | Array | — | - | -| onChange | 值变化时触发的函数 | [OnChangeHandler ](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| --------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------- | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| childType | 子项展示形式 | string | default / button | default | +| options | 选项 | Array | — | - | +| onChange | 值变化时触发的函数 | [OnChangeHandler ](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | + +## options item + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ------- | ------------------------ | ------------------------- | ------ | ------ | +| value | 选项的值 | string / number / boolean | — | — | +| text | 选项的标签 | string | — | — | +| icon | 选项的图标组件 | any | — | — | +| tooltip | 鼠标悬停时显示的提示内容 | string | — | — | diff --git a/docs/form-config/fields/select.md b/docs/form-config/fields/select.md index fa15f6a5..6f98d6fa 100644 --- a/docs/form-config/fields/select.md +++ b/docs/form-config/fields/select.md @@ -16,11 +16,12 @@ { text: '选项2', value: 2 } ] }]"> - + ## 有禁用选项 @@ -35,11 +36,12 @@ { text: '选项2', value: 2, disabled: true } ] }]"> - + ## 禁用状态 @@ -57,11 +59,12 @@ { text: '选项2', value: 2 } ] }]"> - + ## 基础多选 @@ -110,11 +113,12 @@ } ] }]"> - + ## 创建条目 @@ -155,19 +159,21 @@ value: option => `${option.id}`, } }]"> - + 同时在 `src/main.ts` 中需要自定义实现请求 -```typescript + +```typescript app.use(MagicForm, { - request: async (options: any) => { - // 自定义请求实现 - }, + request: async (options: any) => { + // 自定义请求实现 + }, }); ``` @@ -176,34 +182,37 @@ app.use(MagicForm, { ::: ## Select Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------------- |---------- |-------------------------------- |-------- | -| name | 绑定值 | string | — | — | -| placeholder | 输入框占位文本 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| multiple | 是否多选 | boolean | — | false | -| valueKey | 作为 value 唯一标识的键名，绑定值为对象类型时必填 | string | — | value | -| allowCreate | 是否允许用户创建新条目 | boolean | — | false | -| remote | 是否为远程搜索 | boolean | — | false | -| group | 是否选择分组 | boolean | — | false | -| onChange | 值变化时触发的函数 | [OnChangeHandler ](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | -| options | 选项 | Array | — | - | -| option | 选项 | Object | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ----------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| placeholder | 输入框占位文本 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| multiple | 是否多选 | boolean | — | false | +| valueKey | 作为 value 唯一标识的键名，绑定值为对象类型时必填 | string | — | value | +| allowCreate | 是否允许用户创建新条目 | boolean | — | false | +| remote | 是否为远程搜索 | boolean | — | false | +| group | 是否选择分组 | boolean | — | false | +| onChange | 值变化时触发的函数 | [OnChangeHandler ](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L90) | — | - | +| options | 选项 | Array | — | - | +| option | 选项 | Object | — | - | ## options item -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------------- |---------- |-------------------------------- |-------- | -| text | | 选项的标签 | string/number/object | — | — | -| value | 选项的值 | string | — | — | -| disabled | 是否禁用 | boolean | — | false | -| label | string | — | — | — | -| options | Array | — | — | — | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| -------- | -------- | ---------- | -------------------- | ------ | --- | +| text | | 选项的标签 | string/number/object | — | — | +| value | 选项的值 | string | — | — | +| disabled | 是否禁用 | boolean | — | false | +| label | string | — | — | — | +| options | Array | — | — | — | ## option -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------------- |---------- |-------------------------------- |-------- | -| url | string | — | — | — | -| root | string | — | — | — | -| text | string / Function | — | — | — | -| value | string / Function | — | — | — | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ----- | ----------------- | ---- | ------ | ------ | +| url | string | — | — | — | +| root | string | — | — | — | +| text | string / Function | — | — | — | +| value | string / Function | — | — | — | diff --git a/docs/form-config/fields/switch.md b/docs/form-config/fields/switch.md index db715b15..ec9a9c29 100644 --- a/docs/form-config/fields/switch.md +++ b/docs/form-config/fields/switch.md @@ -19,11 +19,11 @@ activeValue: 'on', inactiveValue: 'off' }]"> - + ## 禁用状态 @@ -34,19 +34,18 @@ text: '开关', disabled: true }]"> - + - ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| disabled | 是否禁用 | boolean / [Function](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| active-value | switch 打开时的值 | boolean / string / number | — | true | -| inactive-value | switch 关闭时的值 | boolean / string / number | — | false | +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| -------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| disabled | 是否禁用 | boolean / [Function](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L90) | — | false | +| active-value | switch 打开时的值 | boolean / string / number | — | true | +| inactive-value | switch 关闭时的值 | boolean / string / number | — | false | diff --git a/docs/form-config/fields/text.md b/docs/form-config/fields/text.md index a7417a6f..15f68e82 100644 --- a/docs/form-config/fields/text.md +++ b/docs/form-config/fields/text.md @@ -8,13 +8,13 @@ name: 'text', text: '输入框' }]"> - - + + ## 禁用状态 @@ -23,11 +23,12 @@ text: '输入框', disabled: () => true }]"> - + ## 复合型输入框 @@ -39,11 +40,12 @@ text: '重量', append: '公斤' }]"> - + - + ## 过滤内容 @@ -71,11 +74,12 @@ text: '输入框', filter: 'number' }]"> - + ## 去掉首尾空格 @@ -85,11 +89,12 @@ text: '输入框', trim: true }]"> - + ## 显示详情 @@ -99,31 +104,34 @@ text: '输入框', tooltip: true }]"> - + ## Input Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| placeholder | 输入框占位文本 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| clearable | 是否可清空 | boolean | — | true | -| tooltip | 输入时显示内容 | string | — | — | -| trim | 是否去掉首尾空格 | boolean | — | false | -| filter | 过滤值 | string / Function | number | - | -| prepend | 前置内容 | string | — | - | -| append | 后置内容 | string / Object | — | - | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ----------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| placeholder | 输入框占位文本 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| clearable | 是否可清空 | boolean | — | true | +| tooltip | 输入时显示内容 | string / [ToolTipConfigType](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L90) | — | — | +| trim | 是否去掉首尾空格 | boolean | — | false | +| filter | 过滤值 | string / Function | number | - | +| prepend | 前置内容 | string | — | - | +| append | 后置内容 | string / Object | — | - | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | ## append Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| type | 内容类型 | string | button | — | -| text | 文本内容 | string | — | — | -| handler | 点击操作 | Function | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ------- | -------- | -------- | ------ | ------ | +| type | 内容类型 | string | button | — | +| text | 文本内容 | string | — | — | +| handler | 点击操作 | Function | — | - | diff --git a/docs/form-config/fields/textarea.md b/docs/form-config/fields/textarea.md index 44ad00f5..c2dc258c 100644 --- a/docs/form-config/fields/textarea.md +++ b/docs/form-config/fields/textarea.md @@ -7,11 +7,12 @@ name: 'textarea', text: '文本域' }]"> - + ## 禁用状态 @@ -22,21 +23,23 @@ text: '文本域', disabled: () => true }]"> - + ## Input Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | -| name | 绑定值 | string | — | — | -| placeholder | 输入框占位文本 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| placeholder | 输入框占位文本 | string | — | — | -| trim | 是否去掉首尾空格 | boolean | — | false | -| filter | 过滤值 | string / Function | number | - | -| onChange | 值变化时触发的函数 | [OnChangeHandler ](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ----------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| placeholder | 输入框占位文本 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| placeholder | 输入框占位文本 | string | — | — | +| trim | 是否去掉首尾空格 | boolean | — | false | +| filter | 过滤值 | string / Function | number | - | +| onChange | 值变化时触发的函数 | [OnChangeHandler ](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L90) | — | - | diff --git a/docs/form-config/fields/time-picker.md b/docs/form-config/fields/time-picker.md index 11f1124c..20d8ee2d 100644 --- a/docs/form-config/fields/time-picker.md +++ b/docs/form-config/fields/time-picker.md @@ -1,6 +1,6 @@ # TimePicker 时间选择器 - 用于选择或输入日期 +用于选择或输入日期 ## 基础用法 @@ -9,11 +9,11 @@ name: 'time', text: '时间选择器' }]"> - + ## 禁用状态 @@ -24,18 +24,18 @@ text: '时间选择器', disabled: () => true }]"> - + - ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------------- |---------- |-------------------------------- |-------- | -| name | 绑定值 | string | — | — | -| placeholder | 输入框占位文本 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [Function](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | +| name | 绑定值 | string | — | — | +| placeholder | 输入框占位文本 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [Function](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L90) | — | false | diff --git a/docs/form-config/fields/timerange-picker.md b/docs/form-config/fields/timerange-picker.md index 68c8ba59..b217ca47 100644 --- a/docs/form-config/fields/timerange-picker.md +++ b/docs/form-config/fields/timerange-picker.md @@ -9,11 +9,12 @@ name: 'timerange', text: '时间范围' }]"> - + ## 绑定多个字段 @@ -25,21 +26,23 @@ names: ['startTime', 'endTime'], text: '时间范围' }]"> - + ## Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------------- |---------- |-------------------------------- |-------- | -| name | 绑定值（数组形式） | string | — | — | -| names | 绑定值（拆分为两个字段） | string[] | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| format | 显示格式 | string | — | HH:mm:ss | -| valueFormat | 绑定值的格式 | string | — | HH:mm:ss | -| defaultTime | 默认时间 | Date[] | — | — | -| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +| ----------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | +| name | 绑定值（数组形式） | string | — | — | +| names | 绑定值（拆分为两个字段） | string[] | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L195) | — | false | +| format | 显示格式 | string | — | HH:mm:ss | +| valueFormat | 绑定值的格式 | string | — | HH:mm:ss | +| defaultTime | 默认时间 | Date[] | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/cce8b63fc3618b5b811aa33c703de21c22be8a6a/packages/form-schema/src/base.ts#L30) | — | - | diff --git a/docs/form-config/relate.md b/docs/form-config/relate.md index 141757fa..0d5f2c14 100644 --- a/docs/form-config/relate.md +++ b/docs/form-config/relate.md @@ -9,7 +9,7 @@ }, { name: 'text2', text: '配置2', - display: (state, { model }) => model.switch + display: (mForm, { model }) => model.switch }]"> ## 输入关联 @@ -17,14 +17,14 @@ ## 组件绑定 代码块的初衷是为了实现对组件逻辑的在线干预（代码执行的时机平台提供了组件created, mounted两个钩子），因此我们需要将创建的代码与组件进行关联。 组件绑定代码块 -选中组件之后，在组件配置-高级tab下需要支持下拉选择代码块，以及代码参数的输入。由于每一个组件绑定代码块的需求都是相同的，因此这一部分我们可以抽出为公共的表单配置，相关的逻辑处理在[prop文件](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/editor/src/utils/props.ts#L223)中，我们在高级tab下统一添加了名为created和mounted两个配置项，表单组件使用了自定义的'code-select'。前面已经提过，表单组件会按照type字段来进行渲染，即 :is="${type}"，[CodeSelect](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/editor/src/fields/CodeSelect.vue)组件是在editor中自定义的 +选中组件之后，在组件配置-高级tab下需要支持下拉选择代码块，以及代码参数的输入。由于每一个组件绑定代码块的需求都是相同的，因此这一部分我们可以抽出为公共的表单配置，相关的逻辑处理在[prop文件](https://github.com/Tencent/tmagic-editor/blob/master/packages/editor/src/utils/props.ts)中，我们在高级tab下统一添加了名为created和mounted两个配置项，表单组件使用了自定义的'code-select'。前面已经提过，表单组件会按照type字段来进行渲染，即 :is="${type}"，[CodeSelect](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/editor/src/fields/CodeSelect.vue)组件是在editor中自定义的 完成绑定的动作实质就是在组件配置中增加与代码块的映射关系 ```javascript @@ -70,9 +70,9 @@ ## 代码内容注入与执行 在实现代码块创建和绑定操作之后，DSL已经包含了代码块执行所需的所有信息，接下来我们在页面加载时对代码块进行解析，并在适当的时机运行。 -由于代码块的执行时机为组件created，mounted，因此触发执行的动作需要在runtime中完成，对于VUE3来说，我们在组件对应的生命周期去触发就可以了，react则需要在类似的时间点去触发，详细请参见[ui](https://github.com/Tencent/tmagic-editor/blob/master/packages/ui/src/useApp.ts#L29) +由于代码块的执行时机为组件created，mounted，因此触发执行的动作需要在runtime中完成，对于VUE3来说，我们在组件对应的生命周期去触发就可以了，react则需要在类似的时间点去触发，详细请参见 runtime 相关源码（参考 [runtime 目录](https://github.com/Tencent/tmagic-editor/tree/master/runtime)下的 `vue-runtime-help` 与 `react-runtime-help`） -接收事件的动作是在[Core](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/core/src/Node.ts)中完成的，请记得前面提到过Core主要负责对组件进行跨框架管理与一些通用复杂逻辑的实现，触发时机各个框架不同，但接收事件并执行代码块的逻辑与框架无关。[Core/Node](https://github.com/Tencent/tmagic-editor/blob/master/packages/core/src/Node.ts#L56)会对生命周期事件进行监听，并根据组件绑定的代码块ID拿到具体的代码内容，然后执行。在执行调用时我们以{ app, params }的形式传入了两个参数，其中app包含了全局的变量，params为组件绑定时针对代码块传入的参数。 +接收事件的动作是在[Core](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/core/src/Node.ts)中完成的，请记得前面提到过Core主要负责对组件进行跨框架管理与一些通用复杂逻辑的实现，触发时机各个框架不同，但接收事件并执行代码块的逻辑与框架无关。[Core/Node 中的 `listenLifeSafe`](https://github.com/Tencent/tmagic-editor/blob/c143a5f7670ae61d80c1a2cfcc780cfb5259849d/packages/core/src/Node.ts#L159)会对生命周期事件进行监听，并根据组件绑定的代码块ID拿到具体的代码内容，然后执行。在执行调用时我们以 `{ app, params }` 的形式传入了两个参数，其中 `app` 包含了全局的变量，`params` 为组件绑定时针对代码块传入的参数。 至此，我们就完成了代码块创建-绑定-注入-运行。与代码块功能相关的UI界面中我们也提供了丰富的插槽供开发者扩展，相关源码请见[sidebar/codeBlock](https://github.com/Tencent/tmagic-editor/tree/master/packages/editor/src/layouts/sidebar/code-block)。 diff --git a/docs/guide/advanced/coupling.md b/docs/guide/advanced/coupling.md index 460a2ea0..355d8d2f 100644 --- a/docs/guide/advanced/coupling.md +++ b/docs/guide/advanced/coupling.md @@ -25,7 +25,7 @@ tmagic-editor的联动，指这两种情况： }]`"> -在经过表单渲染器时，所有指出函数 API 都会传入当前渲染的**表单组件实例(vm)**，**当前项目(value)**，**当前表单model**，**表单值formValue**，model 即 vue 的[表单输入绑定](https://v3.cn.vuejs.org/guide/forms.html#%E5%9F%BA%E7%A1%80%E7%94%A8%E6%B3%95)，可以通过修改他来实现值联动。 +在经过表单渲染器时，所有注入的函数 API 都会传入当前渲染的**表单组件实例(vm)**，**当前项目(value)**，**当前表单model**，**表单值formValue**，model 即 vue 的[表单输入绑定](https://v3.cn.vuejs.org/guide/forms.html#%E5%9F%BA%E7%A1%80%E7%94%A8%E6%B3%95)，可以通过修改他来实现值联动。 当然我们也可以通过上述的参数传入，以及其他函数 API 实现更多灵活的表单联动，具体参考[表单 API](../../form-config/relate)。 @@ -95,28 +95,31 @@ const onClick = () => { }; // 此处实现事件动作 -const toast = () => { - toast('测试 vue3') +// 注意：示例中的 ElMessage 仅作演示，业务可替换为自己的弹窗工具 +import { ElMessage } from 'element-plus'; + +const showToast = () => { + ElMessage('测试 vue3'); }; -// 实际触发时是调用node上的方法，所以需要将改方法暴露到node上 +// 实际触发时是调用node上的方法，所以需要将该方法暴露到node上 registerNodeHooks(node, { - toast, + toast: showToast, }); defineExpose({ - toast, + toast: showToast, }); ``` #### react 版本实现 -在 react 的实现中，由于tmagic-editor提供的 @tmagic/ui-react 版本是用 hook 实现的。所以组件开发我们也相应的需要使用 hook 方式。 +在 react 的实现中，由于tmagic-editor提供的 @tmagic/react-runtime-help 版本是用 hook 实现的。所以组件开发我们也相应的需要使用 hook 方式。 ```jsx import React from 'react'; -import { useApp } from '@tmagic/ui-react'; +import { useApp } from '@tmagic/react-runtime-help'; function Test({ config }) { // react 和 vue 实现不同，我们通过 useApp 这个 hook 来提供 app 等核心内容 diff --git a/docs/guide/advanced/data-source.md b/docs/guide/advanced/data-source.md index dc268863..45e7a9e2 100644 --- a/docs/guide/advanced/data-source.md +++ b/docs/guide/advanced/data-source.md @@ -59,7 +59,7 @@ formConfig.js ```js [ { - type: 'data-source-filed-select' + type: 'data-source-field-select' } ] ``` diff --git a/docs/guide/advanced/tmagic-form.md b/docs/guide/advanced/tmagic-form.md index 9f7da6ec..3e5b31f7 100644 --- a/docs/guide/advanced/tmagic-form.md +++ b/docs/guide/advanced/tmagic-form.md @@ -21,7 +21,7 @@ $ npm install @tmagic/element-plus-adapter @tmagic/design element-plus -S ### 引入 @tmagic/form -MagicForm 使用了 element-ui 库 +MagicForm 使用了 element-plus 组件库 在 main.js 中写入以下内容： @@ -46,9 +46,9 @@ app.mount("#app"); ``` -以上代码便完成了 @tmagic/form 的引入。需要注意的是，ElementUI 的样式文件需要单独引入。 +以上代码便完成了 @tmagic/form 的引入。需要注意的是，Element Plus 的样式文件需要单独引入。 -在 App.Vue 中写入以下内容： +在 App.vue 中写入以下内容： ```html diff --git a/docs/guide/advanced/tmagic-ui.md b/docs/guide/advanced/tmagic-ui.md index 7c124abe..78e2d78d 100644 --- a/docs/guide/advanced/tmagic-ui.md +++ b/docs/guide/advanced/tmagic-ui.md @@ -3,15 +3,15 @@ tmagic-editor的设计是希望发布的页面支持多个前端框架，即各个业务方可以根据自己熟悉的语言来开发组件、发布页面。也可以通过 [实现一个 runtime](../runtime.html) 的方式，来实现一个自己的 @tmagic/ui。 -所以tmagic-editor的设计中，针对每个前端框架，都需要有一个对应的 @tmagic/ui 来承担渲染器职责。同时，也需要一个使用和 @tmagic/ui 相同前端框架的 runtime 来 @tmagic/ui 和业务组件的，具体 runtime 概念，可以参考[页面发布](../publish)。 +所以tmagic-editor的设计中，针对每个前端框架，都需要有一个对应的 @tmagic/ui 来承担渲染器职责。同时，也需要一个使用和 @tmagic/ui 相同前端框架的 runtime 用来加载 vue-components 和业务组件，具体 runtime 概念，可以参考[页面发布](../publish)。 -我们以项目代码中提供的 vue 版本的 [vue-components](https://tencent.github.io/tmagic-editor/vue-components) 作为示例介绍其中包含的内容。 +我们以项目代码中提供的 vue 版本的 vue-components 作为示例介绍其中包含的内容（参考 `vue-components/` 目录下的源码）。 ## 渲染器 -在 vue 中，实现渲染器的具体形式参考[页面渲染](../advanced/page)中描述的[容器渲染](../advanced/page.html#容器渲染)和[组件渲染](../advanced/page.html#容器渲染)。 +在 vue 中，实现渲染器的具体形式参考[页面渲染](../advanced/page)中描述的[容器渲染](../advanced/page.html#容器渲染)和[组件渲染](../advanced/page.html#组件渲染)。 ## 基础组件 -在 [vue-components](https://tencent.github.io/tmagic-editor/vue-components) 中，我们提供了几个基础组件，可以在项目源码中找到对应内容。 +在 vue-components 中，我们提供了几个基础组件，可以在项目源码中找到对应内容。 - page tmagic-editor的页面基础 - container tmagic-editor的容器渲染器 diff --git a/docs/guide/component.md b/docs/guide/component.md index e2112c95..5ac91ccd 100644 --- a/docs/guide/component.md +++ b/docs/guide/component.md @@ -152,7 +152,7 @@ react 版本组件代码示例 import React, { useContext } from 'react'; import Core from '@tmagic/core'; -import { AppContent } from '@tmagic/ui-react'; +import { AppContent } from '@tmagic/react-runtime-help'; function Test({ config }: { config: any }) { const app = useContext(AppContent); diff --git a/docs/guide/editor-expand.md b/docs/guide/editor-expand.md index 8ab5f644..3b4e7f0d 100644 --- a/docs/guide/editor-expand.md +++ b/docs/guide/editor-expand.md @@ -8,7 +8,7 @@ ### 一、顶部菜单栏定制 -通常使用 `m-editor` 组件的 [menu](/api/editor/props.html#menu) `prop` 来对齐进行设置； +通常使用 `m-editor` 组件的 [menu](/api/editor/props.html#menu) `prop` 来对其进行设置； 顶部菜单栏分为`左` `中` `右`三个部分组成，所以 [menu](/api/editor/props.html#menu) `prop`的数据格式如下： @@ -16,7 +16,7 @@ { left: [], center: [], right: [] } ``` -数组的内容可以有三种种形式：`内部定义好的字符串`、`其他字符串`、`MenuButton 或者 MenuComponent 对象` +数组的内容可以有三种形式：`内部定义好的字符串`、`其他字符串`、`MenuButton 或者 MenuComponent 对象` #### 1. 内部定义好的字符串: ```ts @@ -38,7 +38,7 @@ MenuButton 的[定义](https://github.com/Tencent/tmagic-editor/blob/239b5d3efea ```js { - type: 'buuton', + type: 'button', text: '返回', handler: () => window.history.back(), } @@ -122,7 +122,7 @@ editorService.on('select', (node) => { 默认的属性读取流程如下： -组件中定义`formConfig` -> 通过`tamgic-cli`构建成 `runtime` 中 `/config/index.umd.cjs` -> `m-editor`中加载然后配置到[propsConfig](/api/editor/props.html#propsconfigs) prop中 -> `m-editor`保存到`propsService`中 -> 选中组件时`editorService`会去`propsService`调用`getPropsConfig`中读取 +组件中定义`formConfig` -> 通过`tmagic-cli`构建成 `runtime` 中 `/config/index.umd.cjs` -> `m-editor`中加载然后配置到[propsConfig](/api/editor/props.html#propsconfigs) prop中 -> `m-editor`保存到`propsService`中 -> 选中组件时`editorService`会去`propsService`调用`getPropsConfig`中读取 `propsService.getPropsConfig`会调取`propsService.fillConfig`添加样式、事件、高级3个tab分页 diff --git a/docs/guide/index.md b/docs/guide/index.md index d317ae01..14e68682 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -13,7 +13,7 @@ $ pnpm create tmagic ``` ::: -按照提示操作可以创建`6`中项目： +按照提示操作可以创建`6`种项目： * runtime:运行时（DSL渲染） * admin-client:管理端（编辑器） @@ -75,7 +75,6 @@ const app = createApp(App); app.use(ElementPlus, { locale: zhCn, }); -app.use(router); app.use(editorPlugin, MagicElementPlusAdapter); app.mount('#app'); ``` @@ -166,7 +165,7 @@ app.mount('#app'); 关于 [@tmagic/editor](https://github.com/Tencent/tmagic-editor/tree/master/packages/editor) 组件，更多的属性配置详情请参考[编辑器 API](../api/editor/props.md)。 -其中，**有四个需要注意的属性配置项**：`runtimeUrl` `values` `configs` `componentGroupList`。这是能让我们的编辑器正常运行的关键。 +其中，**有四个需要注意的属性配置项**：`runtimeUrl` `propsValues` `propsConfigs` `componentGroupList`。这是能让我们的编辑器正常运行的关键。 :::tip 如果出现```Preprocessor dependency "sass" not found. Did you install it?```，那么需要install sass diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md index d2e967ca..b0a8b18c 100644 --- a/docs/guide/introduction.md +++ b/docs/guide/introduction.md @@ -22,7 +22,7 @@ tmagic-editor可视化开源项目是从魔方平台演化而来的开源项目 - **模拟器**，居中位置渲染了当前页面配置的组件内容，模拟真实页面的展示内容。 - **组件库**，左侧展示当前业务下的相关组件内容，包含tmagic-editor提供的基础组件和业务自定义组件。 - **组件树**，左侧展示当前页面添加的组件内容，以树状结构展示。 -- **[代码块](./advanced/code-block.md)**，左侧展示添加的函数，可供组件事件中联动所用，或者组件声明周期中调用。 +- **[代码块](./advanced/code-block.md)**，左侧展示添加的函数，可供组件事件中联动所用，或者组件生命周期中调用。 - **[数据源](./advanced/data-source.md)**，左侧展示添加的数据源，用于组件中的各项配置。 - **表单配置**，右侧表单项目，展示由组件内提供的配置描述，提供修改组件行为的配置项。 - **DSL 源码**，右上角的 📄 图标可以展示当前页面，各个组件配置，页面基础配置组合而成的配置源码。 diff --git a/docs/guide/migration.md b/docs/guide/migration.md index 30ed1e3a..f79514d2 100644 --- a/docs/guide/migration.md +++ b/docs/guide/migration.md @@ -9,7 +9,7 @@ ui中包含的组件被移除，这些组件由单独的npm包提供。1.5.0以 ```js { packages: [ - { button: '@tmagic/vue-button', + { button: '@tmagic/vue-button' }, { container: '@tmagic/vue-container' }, { img: '@tmagic/vue-img' }, { 'iterator-container': '@tmagic/vue-iterator-container' }, diff --git a/docs/guide/publish.md b/docs/guide/publish.md index e0cabee4..d823e2d4 100644 --- a/docs/guide/publish.md +++ b/docs/guide/publish.md @@ -65,7 +65,7 @@ import { defineConfig } from '@tmagic/cli'; export default defineConfig({ /** 组件目录或者npm包名 */ - packages: [path.join(__dirname, '../../packages/ui')], + packages: [path.join(__dirname, '../../vue-components')], /** 组件文件后缀名，例如vue文件为.vue，tsx文件为.tsx，普通js文件则为.js */ componentFileAffix: '.vue', /** npm 配置，用于当packages配置有npm包名时，可以自动安装npm包 */ @@ -113,7 +113,7 @@ tmagic-editor的页面发布，目前使用的是静态资源发布。而所有 Magic App - + @@ -139,7 +139,7 @@ tmagic-editor的页面发布，目前使用的是静态资源发布。而所有 Publish Page - + diff --git a/docs/guide/runtime.md b/docs/guide/runtime.md index 41a8a9e4..2ce9fc7c 100644 --- a/docs/guide/runtime.md +++ b/docs/guide/runtime.md @@ -25,5 +25,5 @@ page用于生产环境 playground用于编辑器中 :::tip -想要了解DSL的解析以及runtime与编辑器的通信，可以前往[教程](/guide/tutorial/index.md) +想要了解DSL的解析以及runtime与编辑器的通信，可以前往[教程](/guide/tutorial/) ::: diff --git a/docs/guide/tutorial/hello-world.md b/docs/guide/tutorial/hello-world.md index b6b2fa7c..3a3d165a 100644 --- a/docs/guide/tutorial/hello-world.md +++ b/docs/guide/tutorial/hello-world.md @@ -162,12 +162,14 @@ const value = ref({ 加上初始值后，点击新增页面就可以渲染出一个画布了，但是点击添加HelloWorld组件依然没有反应 -这是因为这时的编辑器并能理解HelloWorld是什么，需要在[render](../../api/editor/props.html#render)函数中处理 +这是因为这时的编辑器并不能理解HelloWorld是什么，需要在[render](../../api/editor/props.html#render)函数中处理 ## 渲染 api详情：[render](../../api/editor/props.md#render) +> 以下片段省略了 `page` 的获取与完整定义，仅展示渲染思路；完整示例见下文「最终完整的render函数实现」。 + ```ts const render = () => { const root = window.document.createElement('div'); @@ -279,10 +281,10 @@ const render = async ({ renderer }: StageCore) => { }; ``` -以上就是一个简单的搭建编辑器的示例，安装上面的步骤完成后会发现，可以添加组件，也可选中组件，但是无法拖动，配置属性中的样式也无法生效，这是因为上述的render函数并不完整，没有处理dsl中style，下一节将详细介绍runtime的搭建，将不再使用render函数的方式而是使用[runtimeUrl](../../api/editor/props.md#runtimeurl)。 +以上就是一个简单的搭建编辑器的示例，按照上面的步骤完成后会发现，可以添加组件，也可选中组件，但是无法拖动，配置属性中的样式也无法生效，这是因为上述的render函数并不完整，没有处理dsl中style，下一节将详细介绍runtime的搭建，将不再使用render函数的方式而是使用[runtimeUrl](../../api/editor/props.md#runtimeurl)。 ::: tip -并不是render函数不好，但是从设计上将，render函数还是让渲染逻辑落到了编辑器中，@tmagic/editor的设计是希望做到渲染跟编辑器解耦 +并不是render函数不好，但是从设计上讲，render函数还是让渲染逻辑落到了编辑器中，@tmagic/editor的设计是希望做到渲染跟编辑器解耦 ::: [源码](https://github.com/vft-magic/tmagic-tutorial) diff --git a/docs/guide/tutorial/render.md b/docs/guide/tutorial/render.md index ecdeb786..1d8c4fa0 100644 --- a/docs/guide/tutorial/render.md +++ b/docs/guide/tutorial/render.md @@ -1,6 +1,6 @@ # 3.[DSL](../conception.md#dsl) 解析渲染 -tmagic 提供了 vue/react 两个个版本的解析渲染组件，可以直接使用 +tmagic 提供了 vue/react 两个版本的解析渲染组件，可以直接使用 [@tmagic/ui](https://www.npmjs.com/package/@tmagic/ui) @@ -12,7 +12,7 @@ tmagic 提供了 vue/react 两个个版本的解析渲染组件，可以直接 ### 创建项目 -将[上一教程](./runtime.md)中的[editor-runtime](https://github.com/jia000/tmagic-tutorial/tree/master/course2/editor-runtime)和[hello-editor](https://github.com/jia000/tmagic-tutorial/tree/master/course2/hellow-editor)复制过来 +将[上一教程](./runtime.md)中的[editor-runtime](https://github.com/jia000/tmagic-tutorial/tree/master/course2/editor-runtime)和[hello-editor](https://github.com/jia000/tmagic-tutorial/tree/master/course2/hello-editor)复制过来 ## 基础概念 @@ -69,7 +69,7 @@ app.component('hello-world', HelloWorld); ```vue ``` -接下来就需要解析节点的样式，在tmagic/editor中默认会将样式配置保存到节点的style属性中，如果自行定义到了其他属性，则已实际为准 +接下来就需要解析节点的样式，在@tmagic/editor中默认会将样式配置保存到节点的style属性中，如果自行定义到了其他属性，则以实际为准 解析style需要注意几个地方 @@ -99,13 +99,13 @@ const id = computed(() => props.config.id); css中的数值有些是需要单位的，例如px，有些是不需要的，例如opacity -在tmagic/editor中，默认都是不带单位的，所以需要将需要单位的地方补齐单位 +在@tmagic/editor中，默认都是不带单位的，所以需要将需要单位的地方补齐单位 这里做补齐px处理，如果需要做屏幕大小适应， 可以使用rem或者vw，这个可以根据自身需求处理。 2. url -css中的[url](https://developer.mozilla.org/zh-CN/docs/Web/CSS/url)需要是用url()，所以当值为url时，需要转为url(xxx) +css中的[url](https://developer.mozilla.org/zh-CN/docs/Web/CSS/url)需要使用 url()，所以当值为url时，需要转为url(xxx) 3. transform diff --git a/docs/guide/tutorial/runtime.md b/docs/guide/tutorial/runtime.md index 02ea7c97..801fa7b6 100644 --- a/docs/guide/tutorial/runtime.md +++ b/docs/guide/tutorial/runtime.md @@ -178,6 +178,8 @@ declare global { } ``` +> 以下片段中 `page` 来自前文中 App.vue 内的 `const page = ref();`，此处省略其重复声明。 + ```ts import type { Id, MApp, MNode } from '@tmagic/core'; import type { RemoveData, UpdateData } from '@tmagic/stage'; @@ -228,7 +230,7 @@ watch(page, async () => { }); ``` -以上就是一个简单runtime实现，以及与编辑的交互，这是一个不完善的实现(会发现组件再画布中无法自由拖动，是因为没有完整的解析style)，但是其中已经几乎覆盖所有需要关心的内容 +以上就是一个简单runtime实现，以及与编辑的交互，这是一个不完善的实现(会发现组件在画布中无法自由拖动，是因为没有完整的解析style)，但是其中已经几乎覆盖所有需要关心的内容 当前教程中实现了一个简单的page，tmagic提供了一个比较完善的实现，将在下一节介绍 diff --git a/docs/runtime-api/core/app.md b/docs/runtime-api/core/app.md index 49cfe491..c8351ffc 100644 --- a/docs/runtime-api/core/app.md +++ b/docs/runtime-api/core/app.md @@ -36,15 +36,32 @@ new App(options: AppOptionsConfig) | 属性 | 类型 | 说明 | |------|------|------| | `env` | `Env` | 环境信息实例 | -| `dsl` | `MApp` | DSL 配置 | -| `codeDsl` | `CodeBlockDSL` | 代码块配置 | +| `dsl` | `MApp \| undefined` | DSL 配置 | +| `codeDsl` | `CodeBlockDSL \| undefined` | 代码块配置 | | `dataSourceManager` | `DataSourceManager \| undefined` | 数据源管理器 | | `page` | `Page \| undefined` | 当前页面 | | `pageFragments` | `Map` | 页面片段集合 | | `platform` | `string` | 平台类型 | | `jsEngine` | `JsEngine` | JS 引擎类型 | | `components` | `Map` | 已注册的组件 | -| `eventHelper` | `EventHelper` | 事件助手实例 | +| `eventHelper` | `EventHelper \| undefined` | 事件助手实例（仅当 `platform !== 'editor'` 时创建） | +| `useMock` | `boolean` | 是否使用 Mock 数据，默认 `false` | +| `request` | `RequestFunction \| undefined` | 请求函数 | +| `transformStyle` | `(style: Record) => Record` | 样式转换函数 | +| `pageFragmentContainerType` | `Set` | 页面片段容器类型集合，默认包含 `page-fragment-container` | +| `iteratorContainerType` | `Set` | 迭代器容器类型集合，默认包含 `iterator-container` | +| `errorHandler` | `ErrorHandler \| undefined` | 错误处理器 | +| `nodeStoreInitialData` | `(() => any) \| undefined` | 节点存储初始数据工厂函数 | + +## 静态属性 + +### nodeClassMap + +- **类型：** `Map` + +- **详情：** + + 自定义节点类型的映射表，由 `App.registerNode` 写入；`Page` 在初始化节点时会按 `config.type` 从此 Map 中查找对应的节点类，未命中则回退到默认 `Node`。 ## 静态方法 @@ -59,7 +76,7 @@ new App(options: AppOptionsConfig) - **详情：** - 注册自定义节点类型，用于扩展节点功能。 + 注册自定义节点类型，用于扩展节点功能。内部会将 `NodeClass` 写入 `App.nodeClassMap`。 - **示例：** @@ -78,22 +95,25 @@ App.registerNode('custom', CustomNode); ### setEnv - **参数：** - - `{string} ua` User Agent 字符串 + - `{string | Env} ua` User Agent 字符串或 `Env` 实例（可选） - **返回：** - `{void}` - **详情：** - 设置环境信息，会根据 UA 字符串更新 `env` 属性。 + 设置环境信息。当传入字符串（或不传）时，会基于 UA 创建一个新的 `Env` 实例并赋值给 `env` 属性；当传入 `Env` 实例时，直接将其设置为当前 `env`。 - **示例：** ```typescript -import App from '@tmagic/core'; +import App, { Env } from '@tmagic/core'; const app = new App({}); app.setEnv(navigator.userAgent); + +// 也可以直接传入已创建的 Env 实例 +app.setEnv(new Env(navigator.userAgent)); ``` ### setDesignWidth @@ -181,7 +201,7 @@ app.setPage('page_2'); - **详情：** - 获取指定 ID 的页面，不传 ID 则返回当前页面。 + 获取页面：不传 `id` 时返回当前 `this.page`；传入 `id` 时，仅当其与当前 `this.page.data.id` 一致时返回该页面，否则返回 `undefined`。该方法不会按 DSL 遍历所有页面查找。 - **示例：** @@ -260,6 +280,19 @@ app.registerComponent('my-button', MyButton); 解析组件，返回已注册的组件。 +### emit + +- **参数：** + - `{string | symbol} name` 事件名 + - `{...any[]} args` 事件参数；约定第一个参数为触发事件的 `Node` 实例 + +- **返回：** + - `{boolean}` + +- **详情：** + + 重写自 `EventEmitter.emit`。当第一个参数是 `Node` 实例，并且该节点的 `eventKeys` 中存在 `${name}_${node.data.id}` 时，会将事件经由 `EventHelper` 用对应的 `Symbol` 转发（即触发联动事件配置）；否则按 `EventEmitter` 默认逻辑触发。 + ### runCode - **参数：** @@ -270,16 +303,16 @@ app.registerComponent('my-button', MyButton); - `{Node} node` 节点（可选） - **返回：** - - `{any}` + - `{Promise}` 该方法不会显式返回代码块的返回值。如需获取代码块结果，需在代码块内自行通过 `params`/`flowState` 等回写。 - **详情：** - 执行代码块。 + 执行代码块。当 `codeId` 为空、`codeDsl` 为空，或代码块的 `content` 不是函数时直接返回；否则 `await` 执行代码块函数。如果执行过程中抛出异常，存在 `errorHandler` 时会交由其处理，否则继续抛出。 - **示例：** ```typescript -const result = await app.runCode('code_1', { key: 'value' }); +await app.runCode('code_1', { key: 'value' }); ``` ### runDataSourceMethod @@ -293,11 +326,11 @@ const result = await app.runCode('code_1', { key: 'value' }); - `{Node} node` 节点（可选） - **返回：** - - `{any}` + - `{Promise}` 取决于数据源方法的返回值。当 `dsId`、`methodName` 缺失，或数据源不存在、未匹配到方法时，返回 `undefined`。 - **详情：** - 执行数据源方法。 + 执行数据源方法。如果执行过程中抛出异常，存在 `errorHandler` 时会交由其处理，否则继续抛出。 - **示例：** @@ -319,3 +352,24 @@ const result = await app.runDataSourceMethod('ds_1', 'fetchData', { id: 123 }); ```typescript app.destroy(); ``` + +## 事件 + +`App` 继承自 `EventEmitter`，会通过 `super.emit` 触发以下事件： + +| 事件名 | 触发时机 | 回调参数 | +|--------|----------|----------| +| `dsl-change` | 调用 `setConfig` 时触发 | `({ dsl: MApp, curPage: Id })` | +| `page-change` | 调用 `setPage` 切换页面时触发；切换到不存在的页面时也会触发，此时回调无参数。**注意**：当 `pageConfig === this.page.data`（重复 setPage 到当前页）时会直接 `return`，**不**触发该事件 | `(page?: Page)` | + +### 监听示例 + +```typescript +app.on('dsl-change', ({ dsl, curPage }) => { + console.log('DSL 已更新', dsl, curPage); +}); + +app.on('page-change', (page) => { + console.log('当前页面切换为', page?.data?.id); +}); +``` diff --git a/docs/runtime-api/core/devtoolApi.md b/docs/runtime-api/core/devtoolApi.md index 4703908f..b0915bc4 100644 --- a/docs/runtime-api/core/devtoolApi.md +++ b/docs/runtime-api/core/devtoolApi.md @@ -58,17 +58,26 @@ devtoolApi.setDataSourceData('ds_1', { name: 'test' }); devtoolApi.setDataSourceData('ds_1', 'newValue', 'user.name'); ``` +### delDataSourceData + +- **返回：** + - `{void}` + +- **详情：** + + 当前为空实现（预留接口），由具体的开发工具/平台覆盖以实现"删除数据源数据"的能力。 + ### requestDataSource - **参数：** - `{Id} dsId` 数据源 ID - **返回：** - - `{Promise}` + - `{Promise | void}` - **详情：** - 触发 HTTP 数据源的请求。 + 触发 HTTP 数据源的请求。优先调用 `dataSource.refresh`，否则调用 `dataSource.request`，再否则将 `isInit` 置为 `false` 并通过 `dataSourceManager.init(ds)` 重新初始化。 - **示例：** @@ -80,59 +89,73 @@ await devtoolApi.requestDataSource('http_ds_1'); - **参数：** - `{Id} nodeId` 节点 ID - - `{CondItem} condItem` 条件项 + - `{DisplayCondItem} condItem` 单个条件项 - **返回：** - `{any}` - **详情：** - 获取显示条件的实际计算值。 + 获取显示条件的实际计算值。内部会以 `{ [NODE_CONDS_KEY]: [{ cond: [condItem] }] }` 的形式调用 `dataSourceManager.compliedConds`。 ### callHook - **参数：** - `{Id} nodeId` 节点 ID - `{string} hookName` 钩子名称 - - `{any} hookData` 钩子数据 - -- **返回：** - - `{Promise}` - -- **详情：** - - 调用节点的钩子函数。 - -- **示例：** - -```typescript -await devtoolApi.callHook('button_1', 'mounted', { data: 'test' }); -``` - -### trigger - -- **参数：** - - `{Id} nodeId` 节点 ID - - `{EventConfig[]} events` 事件配置数组 + - `{ { params: Record }[] } hookData` 钩子数据列表，依次传给 `node.runHookCode` - **返回：** - `{Promise}` - **详情：** - 触发节点的事件。 + 调用节点的钩子函数。会按 `hookData` 顺序执行，每项以 `item.params` 作为 `runHookCode` 的入参。 - **示例：** ```typescript -await devtoolApi.trigger('button_1', [ - { - name: 'click', - actions: [{ actionType: 'code', codeId: 'code_1' }] - } +await devtoolApi.callHook('button_1', 'mounted', [ + { params: { data: 'test' } }, ]); ``` +### trigger + +- **参数：** + - `{Id} nodeId` 节点 ID + - `{EventConfig} eventConfig` 事件配置（单个，非数组） + +- **返回：** + - `{void}` + +- **详情：** + + 按节点触发事件。内部通过 `app.emit(eventConfig.name, node)` 触发对应事件。 + +- **示例：** + +```typescript +devtoolApi.trigger('button_1', { + name: 'click', + actions: [{ actionType: 'code', codeId: 'code_1' }] +}); +``` + +### updateDsl + +- **参数：** + - `{Id} nodeId` 节点 ID + - `{any} data` 数据 + - `{string} path` 路径 + +- **返回：** + - `{void}` + +- **详情：** + + 当前为空实现（预留接口），由具体的开发工具/平台覆盖以实现"按节点更新 DSL"的能力。 + ### isValueIncludeDataSource - **参数：** @@ -175,14 +198,18 @@ const compiled = devtoolApi.compileDataSourceValue('用户名：${ds_1.user.name - **参数：** - `{Id} codeId` 代码块 ID - `{any} value` 新值 - - `{string} path` 路径（可选） + - `{string} path` 路径（必填） - **返回：** - `{void}` - **详情：** - 更新代码块的内容。 + 按 `path` 更新指定代码块的内容。当 `path === 'content'` 且 `value` 为字符串时，**当前实现**会通过 `eval` 拼接执行后将函数写回。 + + ::: warning 已知限制 + 当前 `eval` 模板存在多余的右括号（详见 `packages/core/src/DevtoolApi.ts` 中 `updateCode`），**对大部分常规函数字面量会因语法错误抛出**。直接传入纯函数体或可被裸赋值的合法表达式时也需自行验证；如需稳定使用建议在调用方先编译为函数再写回 `app.codeDsl[codeId].content`，或等待该实现修复。 + ::: - **示例：** diff --git a/docs/runtime-api/core/env.md b/docs/runtime-api/core/env.md index 3a4738a8..dc5657f2 100644 --- a/docs/runtime-api/core/env.md +++ b/docs/runtime-api/core/env.md @@ -5,18 +5,19 @@ ## 构造函数 ```typescript -new Env(ua?: string) +new Env(ua?: string, options?: Record) ``` ### 参数 | 参数 | 类型 | 说明 | |------|------|------| -| `ua` | `string` | User Agent 字符串（可选，默认使用 `navigator.userAgent`） | +| `ua` | `string` | User Agent 字符串（可选，默认使用 `globalThis.navigator?.userAgent`） | +| `options` | `Record` | 额外的环境字段（可选）。构造时会通过 `Object.entries` 写入到实例上，可用于扩展自定义环境标记。**注意**：构造函数在 `ua` 为空（包括 `''`、`undefined` 等 falsy 值）时会**提前返回**，此时 `options` 同样**不会**被应用 | ## 属性 -所有属性均为只读布尔值： +所有属性均为可赋值的公共字段（非只读），默认布尔值为 `false`： | 属性 | 类型 | 说明 | |------|------|------| @@ -32,6 +33,8 @@ new Env(ua?: string) | `isWeb` | `boolean` | 是否为 Web 环境 | | `isOpenHarmony` | `boolean` | 是否为鸿蒙系统 | +`Env` 上还允许通过索引签名 `[x: string]: any` 写入自定义字段。 + ## 使用示例 ```typescript @@ -51,6 +54,10 @@ if (env.isWechat) { // 使用自定义 UA const customEnv = new Env('Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)'); console.log(customEnv.isIphone); // true + +// 通过 options 注入自定义环境标记 +const customEnv2 = new Env(navigator.userAgent, { isMiniProgram: true }); +console.log(customEnv2.isMiniProgram); // true ``` ## 在 App 中使用 diff --git a/docs/runtime-api/core/eventHelper.md b/docs/runtime-api/core/eventHelper.md index c55cf2bb..c51cefba 100644 --- a/docs/runtime-api/core/eventHelper.md +++ b/docs/runtime-api/core/eventHelper.md @@ -13,12 +13,15 @@ new EventHelper(options: EventHelperOptions) | 参数 | 类型 | 说明 | |------|------|------| | `app` | `App` | 应用实例 | +| `beforeEventHandler` | `BeforeEventHandler` | 事件处理前钩子（可选），形如 `({ eventConfig, source, args }) => void` | +| `afterEventHandler` | `AfterEventHandler` | 事件处理后钩子（可选），形如 `({ eventConfig, source, args }) => void` | ## 属性 | 属性 | 类型 | 说明 | |------|------|------| | `app` | `App` | 应用实例 | +| `eventQueue` | `EventCache[]` | 暂存的待处理事件队列（参见 `getEventQueue`） | ## 实例方法 @@ -76,28 +79,28 @@ eventHelper.bindNodeEvents(node); ### removeDataSourceEvents - **参数：** - - `{DataSourceSchema[]} dataSourceList` 数据源列表（可选） + - `{DataSource[]} dataSourceList` 数据源实例列表（必填） - **返回：** - `{void}` - **详情：** - 移除数据源事件绑定。 + 移除给定数据源的事件绑定。内部根据已注册的事件名前缀，调用 `dataSource.offDataChange` 或 `dataSource.off` 注销监听，并清空 `dataSourceEventList`。 ### getEventQueue - **返回：** - - `{EventConfig[]}` + - `{EventCache[]}` 事件缓存项数组，每项形如 `{ toId: Id, method: string, fromCpt: any, args: any[], handled?: boolean }` - **详情：** - 获取当前事件队列。 + 获取当前事件队列。当目标节点尚未挂载时，联动事件会被缓存到此队列；目标节点 `mounted` 后，会消费匹配项并调用其 `instance` 上的对应方法。 ### addEventToQueue - **参数：** - - `{EventConfig} event` 事件配置 + - `{EventCache} event` 事件缓存项，形如 `{ toId: Id, method: string, fromCpt: any, args: any[] }` - **返回：** - `{void}` diff --git a/docs/runtime-api/core/iteratorContainer.md b/docs/runtime-api/core/iteratorContainer.md index 001a61e9..229dd482 100644 --- a/docs/runtime-api/core/iteratorContainer.md +++ b/docs/runtime-api/core/iteratorContainer.md @@ -60,16 +60,16 @@ iteratorContainer.setData({ - `{Map} map` 节点映射表 - **返回：** - - `{Node}` + - `{void}` - **详情：** - 在指定的节点映射表中初始化节点。 + 在指定的节点映射表中初始化节点。当节点类型属于 `app.iteratorContainerType` 时，会创建嵌套的 `IteratorContainer` 并直接返回（不再继续向下递归 `config.items`）；否则创建普通 `Node` 后会递归初始化 `config.items`。 ### setNodes - **参数：** - - `{Map} nodes` 节点映射表 + - `{MNode[]} nodes` 节点配置数组 - `{number} index` 迭代索引 - **返回：** @@ -77,26 +77,31 @@ iteratorContainer.setData({ - **详情：** - 设置指定索引的节点映射表。 + 按 `index` 在 `this.nodes[index]` 上构建/更新该迭代项对应的节点映射表，内部会对每个节点配置调用 `initNode`。 - **示例：** ```typescript -iteratorContainer.setNodes(nodesMap, 0); +iteratorContainer.setNodes( + [ + { id: 'text_1', type: 'text', text: 'hello' }, + ], + 0, +); ``` ### getNode - **参数：** - `{Id} id` 节点 ID - - `{number} index` 迭代索引（可选，默认为 0） + - `{number} index` 迭代索引 - **返回：** - `{Node | undefined}` - **详情：** - 获取指定迭代索引中的节点。 + 获取指定迭代索引中的节点。`index` 为必填参数。 - **示例：** diff --git a/docs/runtime-api/core/node.md b/docs/runtime-api/core/node.md index 5cfad3fc..3a4e003a 100644 --- a/docs/runtime-api/core/node.md +++ b/docs/runtime-api/core/node.md @@ -14,7 +14,7 @@ new Node(options: NodeOptions) |------|------|------| | `config` | `MNode` | 节点配置 | | `parent` | `Node` | 父节点（可选） | -| `page` | `Page` | 所属页面 | +| `page` | `Page` | 所属页面（可选） | | `app` | `App` | 应用实例 | ## 属性 @@ -25,7 +25,7 @@ new Node(options: NodeOptions) | `style` | `object` | 节点样式 | | `events` | `EventConfig[]` | 事件配置 | | `instance` | `any` | 组件实例 | -| `page` | `Page` | 所属页面 | +| `page` | `Page \| undefined` | 所属页面 | | `parent` | `Node \| undefined` | 父节点 | | `app` | `App` | 应用实例 | | `store` | `Store` | 节点存储 | @@ -59,14 +59,14 @@ node.setData({ ### addEventToQueue - **参数：** - - `{EventConfig} event` 事件配置 + - `{EventCache} event` 待处理事件项；类型为 `{ method: string, fromCpt: any, args: any[] }` - **返回：** - `{void}` - **详情：** - 将事件添加到事件队列，等待绑定到组件实例。 + 将事件添加到节点内部的事件队列，等待组件实例 `mounted` 后再依次调用对应的方法（`instance[event.method](event.fromCpt, ...event.args)`）。 ### setInstance @@ -87,18 +87,37 @@ node.setData({ node.setInstance(componentInstance); ``` -### runHookCode +### registerMethod + +::: warning @deprecated +该方法已废弃，请使用 `setInstance` 替代。 +::: - **参数：** - - `{'created' | 'mounted'} hook` 钩子名称 - - `{object} params` 参数 + - `{Methods} methods` 方法集合，形如 `{ [name: string]: (...args: any[]) => any }` - **返回：** - - `{Promise}` + - `{void}` - **详情：** - 执行节点的钩子代码。 + 将给定方法挂载到 `instance` 上。如果当前 `instance` 不存在，会先创建一个空对象再合并方法。 + +### runHookCode + +- **参数：** + - `{string} hook` 钩子名称（如 `'created'`、`'mounted'`、`'destroy'` 等，由节点 schema 决定） + - `{object} params` 参数（可选） + +- **返回：** + - `{Promise}` + +- **详情：** + + 执行节点的钩子代码。内部会根据节点 schema 中 `hook` 字段的实际形态进行处理： + + - 兼容旧格式：当 `data[hook]` 直接是函数时，作为函数调用； + - 新格式：当 `data[hook]` 是 `{ hookType, hookData[] }` 且 `hookType === HookType.CODE` 时，按顺序遍历 `hookData`，根据 `codeType` 调用 `app.runCode` 或 `app.runDataSourceMethod`。 - **示例：** diff --git a/docs/runtime-api/core/page.md b/docs/runtime-api/core/page.md index 74eec4af..97ab6de6 100644 --- a/docs/runtime-api/core/page.md +++ b/docs/runtime-api/core/page.md @@ -25,24 +25,31 @@ new Page(options: PageOptions) ### initNode - **参数：** - - `{MNode} config` 节点配置 - - `{Node} parent` 父节点（可选） + - `{MComponent | MContainer} config` 节点配置 + - `{Node} parent` 父节点 - **返回：** - - `{Node}` + - `{void}` - **详情：** - 初始化节点，根据配置创建节点实例并添加到页面。会递归初始化子节点。 + 初始化节点，根据配置创建节点实例并通过 `setNode` 添加到页面： + + - 当节点类型属于 `app.iteratorContainerType` 时，会创建 `IteratorContainer` 并直接返回，**不会**继续递归 `config.items`（迭代容器内的子节点由 `IteratorContainer` 自身在每次迭代时按需初始化）。 + - 当属于 `app.pageFragmentContainerType` 且配置了 `pageFragmentId` 时，会在 `app.pageFragments` 中创建对应的页面片段实例。 + - 其他类型会创建普通节点后递归初始化 `config.items` 子节点。 - **示例：** ```typescript -const node = page.initNode({ - id: 'button_1', - type: 'button', - style: { width: 100 } -}); +page.initNode( + { + id: 'button_1', + type: 'button', + style: { width: 100 } + }, + page, +); ``` ### getNode diff --git a/docs/runtime-api/core/utils.md b/docs/runtime-api/core/utils.md index a7a29b74..22b7c3aa 100644 --- a/docs/runtime-api/core/utils.md +++ b/docs/runtime-api/core/utils.md @@ -12,7 +12,7 @@ - **详情：** - 将 CSS 样式字符串转换为对象格式。 + 将 CSS 样式字符串转换为对象格式。若入参不是字符串，则原样返回。 - **示例：** @@ -47,20 +47,20 @@ console.log(bg); // 'url(https://example.com/image.png)' ## getTransform - **参数：** - - `{object} value` transform 配置 + - `{Record | string} value` transform 配置（对象或 CSS 字符串） - `{JsEngine} jsEngine` JS 引擎类型 - **返回：** - - `{string}` CSS transform 字符串 + - `{string | Record[]}` CSS transform 字符串；当 `jsEngine === 'hippy'` 时返回数组格式 - **详情：** - 根据配置生成 CSS transform 字符串，会根据 JS 引擎类型进行适配。 + 根据配置生成 CSS transform。当 `jsEngine === 'hippy'` 时，会将 `"rotate(90deg) scale(1.5)"` 这样的字符串解析成 `[{ rotate: '90deg' }, { scale: '1.5' }]` 形式以适配 Hippy；其它情况下返回标准 CSS transform 字符串。 ## transformStyle - **参数：** - - `{object} style` 样式对象 + - `{Record | string} style` 样式对象或 CSS 字符串 - `{JsEngine} jsEngine` JS 引擎类型 - **返回：** @@ -68,7 +68,7 @@ console.log(bg); // 'url(https://example.com/image.png)' - **详情：** - 转换样式对象，将数值转换为 rem 单位（移动端适配）。 + 转换样式对象，将数值转换为 rem 单位（移动端适配）。当 `style` 为字符串时，会先用 `style2Obj` 解析为对象再处理。 - **示例：** diff --git a/docs/runtime-api/data-source/dataSource.md b/docs/runtime-api/data-source/dataSource.md index d08d192c..d574d4b6 100644 --- a/docs/runtime-api/data-source/dataSource.md +++ b/docs/runtime-api/data-source/dataSource.md @@ -88,11 +88,35 @@ ds.setData('newValue', 'user.name'); ds.setValue('user.age', 25); ``` +### setFields + +- **参数：** + - `{DataSchema[]} fields` 字段配置 + +- **返回：** + - `{void}` + +- **详情：** + + 设置数据源的字段配置 `fields`。一般在初始化或 schema 更新后调用。 + +### setMethods + +- **参数：** + - `{CodeBlockContent[]} methods` 自定义方法配置 + +- **返回：** + - `{void}` + +- **详情：** + + 设置数据源的自定义方法配置 `methods`。 + ### onDataChange - **参数：** - `{string} path` 数据路径 - - `{Function} callback` 回调函数 + - `{(payload: any) => void} callback` 回调函数 - **返回：** - `{void}` @@ -101,11 +125,19 @@ ds.setValue('user.age', 25); 监听指定路径的数据变化。 + ::: warning callback 入参取决于 `ObservedData` 实现 + - `SimpleObservedData`（默认）：路径监听触发时，回调收到的是 `{ updateData, path }` 形式的 `ChangeEvent`，**不是**纯粹的 newVal。仅在 `options.immediate` 分支会以「当前路径值」回调一次。 + - `DeepObservedData`（基于 `deep-state-observer`）：回调入参贴近「值」的语义。 + + 如需统一拿到「最新值」，可在回调里用 `ds.getData(path)` 主动读取。 + ::: + - **示例：** ```typescript -ds.onDataChange('user.name', (newVal) => { - console.log('用户名变更:', newVal); +ds.onDataChange('user.name', (payload) => { + // SimpleObservedData 下 payload 形如 { updateData, path } + console.log('user.name 变更，最新值:', ds.getData('user.name')); }); ``` @@ -113,7 +145,7 @@ ds.onDataChange('user.name', (newVal) => { - **参数：** - `{string} path` 数据路径 - - `{Function} callback` 回调函数 + - `{(payload: any) => void} callback` 回调函数（与 `onDataChange` 相同的引用） - **返回：** - `{void}` @@ -153,15 +185,15 @@ ds.onDataChange('user.name', (newVal) => { DataSource 继承自 EventEmitter，支持以下事件： -| 事件名 | 说明 | -|--------|------| -| `change` | 数据变化时触发 | +| 事件名 | 说明 | 回调参数 | +|--------|------|----------| +| `change` | 数据变化时触发 | `(changeEvent: ChangeEvent)`，`ChangeEvent` 形如 `{ updateData, path? }` | ### 示例 ```typescript -ds.on('change', () => { - console.log('数据已变化', ds.data); +ds.on('change', (changeEvent) => { + console.log('数据已变化', changeEvent.updateData, changeEvent.path); }); ``` diff --git a/docs/runtime-api/data-source/dataSourceManager.md b/docs/runtime-api/data-source/dataSourceManager.md index fa80d98a..5a223fb8 100644 --- a/docs/runtime-api/data-source/dataSourceManager.md +++ b/docs/runtime-api/data-source/dataSourceManager.md @@ -91,30 +91,22 @@ DataSourceManager.register('custom', CustomDataSource); ### init - **参数：** - - `{DataSourceSchema[]} ds` 数据源配置数组 + - `{DataSource} ds` 单个数据源实例（必填） - **返回：** - `{Promise}` - **详情：** - 初始化数据源，会创建所有配置的数据源实例并初始化。 + 初始化单个数据源。会按 `methods` 中 `timing === 'beforeInit'` 的方法依次执行，再调用 `ds.init()`，最后执行 `timing === 'afterInit'` 的方法。当 `ds.isInit` 为 `true`，或当前 `app.jsEngine` 命中 `ds.schema.disabledInitInJsEngine` 时直接跳过。 - **示例：** ```typescript -await dataSourceManager.init([ - { - id: 'ds_1', - type: 'base', - fields: [{ name: 'count', defaultValue: 0 }] - }, - { - id: 'http_1', - type: 'http', - options: { url: '/api/data' } - } -]); +const ds = dataSourceManager.get('ds_1'); +if (ds) { + await dataSourceManager.init(ds); +} ``` ### get @@ -138,14 +130,14 @@ const ds = dataSourceManager.get('ds_1'); ### addDataSource - **参数：** - - `{DataSourceSchema} config` 数据源配置 + - `{DataSourceSchema} config` 数据源配置（可选） - **返回：** - - `{DataSource}` + - `{DataSource | undefined}` - **详情：** - 添加新的数据源。 + 添加新的数据源。当对应类型尚未注册（即 `dataSourceClassMap` 中无该类型）时，会将配置缓存到 `waitInitSchemaList`，并返回 `undefined`，待 `register` 时再补建实例。 - **示例：** @@ -172,15 +164,15 @@ const ds = dataSourceManager.addDataSource({ ### setData - **参数：** - - `{DataSourceSchema} ds` 数据源配置 - - `{ChangeEvent} changeEvent` 变化事件（可选） + - `{DataSource} ds` 数据源实例 + - `{ChangeEvent} changeEvent` 变化事件，形如 `{ updateData, path? }` - **返回：** - `{void}` - **详情：** - 设置数据源数据。 + 将 `ds.data` 同步到 `this.data[ds.id]`，并以 `(ds.id, changeEvent)` 触发 `change` 事件。 ### updateSchema @@ -188,11 +180,11 @@ const ds = dataSourceManager.addDataSource({ - `{DataSourceSchema[]} schemas` 数据源配置数组 - **返回：** - - `{Promise}` + - `{void}` - **详情：** - 更新数据源 DSL 配置，会自动处理新增、更新和删除。 + 同步更新数据源 DSL 配置：先按 `id` 移除已有数据源，再以 `cloneDeep` 重新 `addDataSource`，并对新建实例触发 `init`（异步执行，不会被该方法 `await`）。一般在编辑器中修改配置后调用。 ### compiledNode @@ -222,11 +214,11 @@ const compiledNode = dataSourceManager.compiledNode({ ### compliedConds - **参数：** - - `{MNode} node` 节点配置 - - `{object} data` 数据上下文（可选） + - `{ { [NODE_CONDS_KEY]?: DisplayCond[]; [NODE_CONDS_RESULT_KEY]?: boolean; [NODE_DISABLE_DATA_SOURCE_KEY]?: boolean } } node` 带条件字段的结构（不要求是完整的 MNode） + - `{DataSourceManagerData} data` 数据上下文（可选，默认使用 `this.data`） - **返回：** - - `{boolean}` + - `{boolean}` 节点是否应该显示 - **详情：** @@ -241,9 +233,9 @@ const shouldShow = dataSourceManager.compliedConds(node); ### compliedIteratorItemConds - **参数：** - - `{object} itemData` 迭代项数据 - - `{MNode} node` 节点配置 - - `{string} field` 条件字段名 + - `{any} itemData` 迭代项数据 + - `{ { [NODE_CONDS_KEY]?: DisplayCond[] } } node` 带条件字段的结构 + - `{string[]} dataSourceField` 迭代数据在数据源中的字段路径，格式如 `['dsId', 'key1', 'key2']`（可选，默认 `[]`） - **返回：** - `{boolean}` @@ -255,9 +247,9 @@ const shouldShow = dataSourceManager.compliedConds(node); ### compliedIteratorItems - **参数：** - - `{object} itemData` 迭代项数据 + - `{any} itemData` 迭代项数据 - `{MNode[]} nodes` 节点配置数组 - - `{string} field` 字段名 + - `{string[]} dataSourceField` 迭代数据在数据源中的字段路径（可选，默认 `[]`） - **返回：** - `{MNode[]}` @@ -266,19 +258,33 @@ const shouldShow = dataSourceManager.compliedConds(node); 编译迭代器项的节点配置。 +### isAllDataSourceRegistered + +- **返回：** + - `{boolean}` + +- **详情：** + + 判断 DSL 中声明的所有数据源是否都已注册并实例化（即 `dataSourceMap.size === dsl.dataSources.length`，或 DSL 未声明数据源）。 + + ::: tip `registered-all` 触发时机 + `registered-all` 事件**仅**在 `addDataSource` 末尾、`isAllDataSourceRegistered()` 为真时触发。当 `dsl.dataSources` 为空数组时，构造函数不会进入任何一次 `addDataSource` 调用，因此**不会**触发该事件，但仍可能执行 `callDsInit()`。 + ::: + ### onDataChange - **参数：** - `{string} id` 数据源 ID - `{string} path` 数据路径 - - `{Function} callback` 回调函数 + - `{(payload: any) => void} callback` 回调函数（具体入参取决于 `ObservedData` 实现，详见 [DataSource.onDataChange](./dataSource.md#ondatachange)） + - `{ { immediate?: boolean } } options` 选项（可选） - **返回：** - `{void}` - **详情：** - 监听数据源数据变化。 + 监听数据源数据变化。`options.immediate` 为 `true` 时，订阅后立即用当前值触发一次回调（具体语义取决于 `ObservedData` 的实现）。 - **示例：** @@ -293,7 +299,7 @@ dataSourceManager.onDataChange('ds_1', 'user.name', (newVal) => { - **参数：** - `{string} id` 数据源 ID - `{string} path` 数据路径 - - `{Function} callback` 回调函数 + - `{(newVal: any) => void} callback` 回调函数 - **返回：** - `{void}` @@ -317,19 +323,19 @@ DataSourceManager 继承自 EventEmitter，支持以下事件： | 事件名 | 说明 | 回调参数 | |--------|------|----------| -| `change` | 数据源数据变化 | `(dsId, path, newVal)` | -| `init` | 所有数据源初始化完成 | 无 | +| `change` | 单个数据源数据变化 | `(dsId: string, changeEvent: ChangeEvent)` | +| `init` | 所有数据源初始化完成；现代分支携带 `(data, errors)`，旧 Promise.all 分支为 `(this.data)` | `(data, errors?)` | | `registered-all` | 所有数据源注册完成 | 无 | -| `update-data` | 更新节点数据 | `(node, sourceId)` | +| `update-data` | 由 `createDataSourceManager` 在数据变化后发出，用于通知节点重新渲染 | `(newNodes: MNode[], sourceId: string, changeEvent: ChangeEvent, pageId: Id)` | ### 事件监听示例 ```typescript -dataSourceManager.on('change', (dsId, path, newVal) => { - console.log(`数据源 ${dsId} 的 ${path} 变更为:`, newVal); +dataSourceManager.on('change', (dsId, changeEvent) => { + console.log(`数据源 ${dsId} 变更:`, changeEvent); }); -dataSourceManager.on('init', () => { - console.log('所有数据源初始化完成'); +dataSourceManager.on('init', (data, errors) => { + console.log('所有数据源初始化完成', data, errors); }); ``` diff --git a/docs/runtime-api/data-source/httpDataSource.md b/docs/runtime-api/data-source/httpDataSource.md index e2a5e34f..7996399c 100644 --- a/docs/runtime-api/data-source/httpDataSource.md +++ b/docs/runtime-api/data-source/httpDataSource.md @@ -20,8 +20,8 @@ new HttpDataSource(options: DataSourceOptions) | `options` | `HttpOptionsSchema` | HTTP 请求配置 | | `responseOptions` | `{ dataPath?: string }` | 响应数据配置（可选） | | `autoFetch` | `boolean` | 是否自动请求（可选） | -| `beforeRequest` | `Function \| string` | 请求前钩子（可选） | -| `afterResponse` | `Function \| string` | 响应后钩子（可选） | +| `beforeRequest` | `string \| ((options: HttpOptions, content: { app, dataSource }) => HttpOptions)` | 请求前钩子。**运行时仅会调用函数形式**；字符串形式（代码块 ID）不会在 `HttpDataSource.request` 内被解析执行，需要由编辑器在导出 DSL 阶段或上层 `createDataSourceManager` 配置中将其转换为函数后挂到 schema 上 | +| `afterResponse` | `string \| ((response: any, content: { app, dataSource, options }) => any)` | 响应后钩子。**运行时仅会调用函数形式**；字符串形式（代码块 ID）的解析逻辑同上 | ### HttpOptionsSchema @@ -40,7 +40,7 @@ new HttpDataSource(options: DataSourceOptions) | 属性 | 类型 | 说明 | |------|------|------| | `isLoading` | `boolean` | 是否正在请求 | -| `error` | `{ msg?: string, code?: string }` | 错误信息 | +| `error` | `{ msg?: string, code?: string \| number }` | 错误信息 | | `httpOptions` | `HttpOptionsSchema` | 请求配置 | ## 实例方法 @@ -48,10 +48,10 @@ new HttpDataSource(options: DataSourceOptions) ### request - **参数：** - - `{HttpOptionsSchema} options` 请求选项（可选） + - `{Partial} options` 请求选项（可选，默认 `{}`） - **返回：** - - `{Promise}` 响应数据 + - `{Promise}` 该方法不会显式返回数据；请求结果会通过 `setData` 写入 `data`，失败时通过 `error` 暴露并触发 `error` 事件。 - **详情：** @@ -61,30 +61,33 @@ new HttpDataSource(options: DataSourceOptions) ```typescript // 使用默认配置请求 -const data = await httpDs.request(); +await httpDs.request(); // 覆盖部分配置 -const data = await httpDs.request({ +await httpDs.request({ params: { page: 1, size: 10 } }); + +// 通过 ds.data 读取结果 +console.log(httpDs.data); ``` ### get - **参数：** - - `{HttpOptionsSchema} options` 请求选项 + - `{Partial & { url: string }} options` 请求选项（必须包含 `url`） - **返回：** - - `{Promise}` 响应数据 + - `{Promise}` - **详情：** - 发起 GET 请求。 + 发起 GET 请求，等价于 `request({ ...options, method: 'GET' })`。 - **示例：** ```typescript -const data = await httpDs.get({ +await httpDs.get({ url: '/api/users', params: { id: 1 } }); @@ -93,24 +96,40 @@ const data = await httpDs.get({ ### post - **参数：** - - `{HttpOptionsSchema} options` 请求选项 + - `{Partial & { url: string }} options` 请求选项（必须包含 `url`） - **返回：** - - `{Promise}` 响应数据 + - `{Promise}` - **详情：** - 发起 POST 请求。 + 发起 POST 请求，等价于 `request({ ...options, method: 'POST' })`。 - **示例：** ```typescript -const data = await httpDs.post({ +await httpDs.post({ url: '/api/users', data: { name: 'test' } }); ``` +## 事件 + +继承自 [DataSource](./dataSource.md) 事件，额外包含： + +| 事件名 | 说明 | 回调参数 | +|--------|------|----------| +| `error` | 请求过程中捕获到异常时触发 | `(error: Error)` | + +### 示例 + +```typescript +httpDs.on('error', (error) => { + console.error('请求失败:', error); +}); +``` + ## 配置示例 ### 基础配置 diff --git a/docs/runtime-api/data-source/observedData.md b/docs/runtime-api/data-source/observedData.md index 52bd6aeb..eae4854c 100644 --- a/docs/runtime-api/data-source/observedData.md +++ b/docs/runtime-api/data-source/observedData.md @@ -11,8 +11,8 @@ | 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | `update` | `(data: any, path?: string)` | `void` | 更新数据 | -| `on` | `(path: string, callback: Function, options?: { immediate?: boolean })` | `void` | 监听数据变化 | -| `off` | `(path: string, callback: Function)` | `void` | 取消监听 | +| `on` | `(path: string, callback: (payload: any) => void, options?: { immediate?: boolean })` | `void` | 监听数据变化。`payload` 的形态取决于具体实现：`SimpleObservedData` 路径回调收到 `{ updateData, path }`（仅 `immediate` 分支为「当前值」），`DeepObservedData` 更接近「值」语义 | +| `off` | `(path: string, callback: (payload: any) => void)` | `void` | 取消监听 | | `getData` | `(path: string)` | `any` | 获取指定路径的数据 | | `destroy` | `()` | `void` | 销毁 | @@ -27,9 +27,9 @@ import { SimpleObservedData } from '@tmagic/data-source'; const observed = new SimpleObservedData({ name: 'test' }); -// 监听数据变化 -observed.on('name', (newVal) => { - console.log('name 变更为:', newVal); +// 监听数据变化（SimpleObservedData 路径监听收到的是 { updateData, path }） +observed.on('name', (payload) => { + console.log('name 变更，payload:', payload, '当前值:', observed.getData('name')); }); // 更新数据 @@ -119,28 +119,28 @@ import { ObservedData } from '@tmagic/data-source'; class CustomObservedData extends ObservedData { private data: any; - + constructor(data: any) { super(); this.data = data; } - + update(data: any, path?: string): void { // 自定义更新逻辑 } - - on(path: string, callback: Function, options?: { immediate?: boolean }): void { + + on(path: string, callback: (payload: any) => void, options?: { immediate?: boolean }): void { // 自定义监听逻辑 } - - off(path: string, callback: Function): void { + + off(path: string, callback: (payload: any) => void): void { // 自定义取消监听逻辑 } - + getData(path: string): any { // 自定义获取数据逻辑 } - + destroy(): void { // 自定义销毁逻辑 } diff --git a/docs/runtime-api/data-source/utils.md b/docs/runtime-api/data-source/utils.md index 455b36c3..e2445144 100644 --- a/docs/runtime-api/data-source/utils.md +++ b/docs/runtime-api/data-source/utils.md @@ -10,11 +10,11 @@ - `{DataSourceManagerData} initialData` 初始数据（可选） - **返回：** - - `{DataSourceManager}` 数据源管理器实例 + - `{DataSourceManager | undefined}` 数据源管理器实例；当 `app.dsl?.dataSources` 缺省时返回 `undefined` - **详情：** - 创建数据源管理器的工厂函数，会自动设置数据变化监听。 + 创建数据源管理器的工厂函数，会自动设置数据变化监听并在 `change` 事件中向 `update-data` 转发受影响的节点。 - **示例：** @@ -27,15 +27,15 @@ const dsManager = createDataSourceManager(app, false, initialData); ## compiledCondition - **参数：** - - `{CondItem} cond` 条件项 - - `{object} data` 数据上下文 + - `{DisplayCondItem[]} conds` 条件项数组（同一组条件 AND 关系） + - `{DataSourceManagerData} data` 数据上下文 - **返回：** - `{boolean}` 条件是否满足 - **详情：** - 编译单个显示条件。 + 编译一组显示条件，按 AND 语义返回是否全部满足。 - **示例：** @@ -43,8 +43,8 @@ const dsManager = createDataSourceManager(app, false, initialData); import { compiledCondition } from '@tmagic/data-source'; const result = compiledCondition( - { field: 'user.age', op: '>', value: 18 }, - { user: { age: 20 } } + [{ field: ['ds_1', 'user', 'age'], op: '>', value: 18 }], + { ds_1: { user: { age: 20 } } } ); console.log(result); // true ``` @@ -52,21 +52,21 @@ console.log(result); // true ## compliedConditions - **参数：** - - `{MNode} node` 节点配置 - - `{object} data` 数据上下文（可选） + - `{ { [NODE_CONDS_KEY]?: DisplayCond[] } } node` 带条件字段的结构 + - `{DataSourceManagerData} data` 数据上下文 - **返回：** - `{boolean}` 节点是否应该显示 - **详情：** - 编译条件组，支持 AND/OR 逻辑。 + 编译条件组（OR 语义：只要其中一组 `cond` 全部满足即返回 `true`）。 ## compiledNodeField - **参数：** - `{any} value` 字段值 - - `{object} data` 数据上下文 + - `{DataSourceManagerData} data` 数据上下文 - **返回：** - `{any}` 编译后的值 @@ -90,7 +90,7 @@ const compiled = compiledNodeField( - **参数：** - `{any} value` 字段值 - - `{object} data` 数据上下文 + - `{DataSourceManagerData} data` 数据上下文 - **返回：** - `{any}` 编译后的值 @@ -103,7 +103,7 @@ const compiled = compiledNodeField( - **参数：** - `{string} value` 模板字符串 - - `{object} data` 数据上下文 + - `{DataSourceManagerData} data` 数据上下文 - **返回：** - `{string}` 替换后的字符串 @@ -127,13 +127,13 @@ console.log(result); // '用户名：张三，年龄：20' ## createIteratorContentData - **参数：** - - `{object} itemData` 迭代项数据 + - `{any} itemData` 迭代项数据 - `{string} dsId` 数据源 ID - - `{DataSchema[]} fields` 字段配置 - - `{object} dsData` 数据源数据 + - `{string[]} fields` 字段路径，如 `['a', 'b', 'c']` + - `{DataSourceManagerData} dsData` 数据源数据（可选，默认 `{}`） - **返回：** - - `{object}` 迭代器数据上下文 + - `{DataSourceManagerData}` 迭代器数据上下文 - **详情：** @@ -179,21 +179,21 @@ const newDsl = updateNode( - **参数：** - `{MApp} dsl` DSL 配置 - - `{Record Promise>} modules` 数据源模块映射 + - `{Record Promise>} dataSourceModules` 数据源模块映射 - **返回：** - - `{Promise}` + - `{Promise>}` 按需加载到的数据源模块表（key 为数据源 `type`，value 为模块的 `default` 导出） - **详情：** - 按需加载数据源模块。根据 DSL 中使用的数据源类型动态加载对应模块。 + 按需加载数据源模块。根据 DSL 中实际依赖到的数据源类型动态加载对应模块，并以模块表形式返回。 - **示例：** ```typescript import { registerDataSourceOnDemand } from '@tmagic/data-source'; -await registerDataSourceOnDemand(dsl, { +const moduleMap = await registerDataSourceOnDemand(dsl, { custom: () => import('./CustomDataSource'), socket: () => import('./SocketDataSource') });