diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index ee7cc62b..099b8dd1 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -48,14 +48,6 @@ export default defineConfig({ text: '快速开始', link: '/guide/' }, - { - text: '基础概念', - link: '/guide/conception.md', - }, - { - text: '页面发布', - link: '/guide/publish.md' - }, { text: 'RUNTIME', link: '/guide/runtime.md' @@ -64,6 +56,14 @@ export default defineConfig({ text: '组件开发', link: '/guide/component.md' }, + { + text: '基础概念', + link: '/guide/conception.md', + }, + { + text: '页面发布', + link: '/guide/publish.md' + }, { text: '编辑器扩展', link: '/guide/editor-expand.md' @@ -311,6 +311,10 @@ export default defineConfig({ text: 'InputNumber计数器', link: '/form-config/fields/number.md' }, + { + text: 'NumberRange数字范围', + link: '/form-config/fields/number-range.md' + }, { text: 'Display只读文本', link: '/form-config/fields/display.md' @@ -351,6 +355,10 @@ export default defineConfig({ text: 'DatePick日期选择器', link: '/form-config/fields/date-picker.md' }, + { + text: 'DateRangePick日期范围选择器', + link: '/form-config/fields/daterange-picker.md' + }, { text: 'DatetimePick日期时间选择器', link: '/form-config/fields/datetime-picker.md' @@ -358,9 +366,90 @@ export default defineConfig({ { text: 'TimePick时间选择器', link: '/form-config/fields/time-picker.md' + }, + { + text: 'TimeRangePick时间范围选择器', + link: '/form-config/fields/timerange-picker.md' + }, + { + text: 'DynamicField动态表单', + link: '/form-config/fields/dynamic-field.md' } ] }, + { + text: '编辑器中可用配置', + items: [ + { + text: 'Code代码编辑器', + link: '/form-config/editor-fields/code.md' + }, + { + text: 'CodeLink代码链接', + link: '/form-config/editor-fields/code-link.md' + }, + { + text: 'CodeSelect代码块选择器', + link: '/form-config/editor-fields/code-select.md' + }, + { + text: 'CodeSelectCol代码块选择列', + link: '/form-config/editor-fields/code-select-col.md' + }, + { + text: 'DataSourceSelect数据源选择器', + link: '/form-config/editor-fields/data-source-select.md' + }, + { + text: 'DataSourceFieldSelect数据源字段选择器', + link: '/form-config/editor-fields/data-source-field-select.md' + }, + { + text: 'DataSourceMethodSelect数据源方法选择器', + link: '/form-config/editor-fields/data-source-method-select.md' + }, + { + text: 'DataSourceFields数据源字段配置', + link: '/form-config/editor-fields/data-source-fields.md' + }, + { + text: 'DataSourceInput数据源输入框', + link: '/form-config/editor-fields/data-source-input.md' + }, + { + text: 'DataSourceMethods数据源方法配置', + link: '/form-config/editor-fields/data-source-methods.md' + }, + { + text: 'DataSourceMocks数据源Mock配置', + link: '/form-config/editor-fields/data-source-mocks.md' + }, + { + text: 'UISelect组件选择器', + link: '/form-config/editor-fields/ui-select.md' + }, + { + text: 'KeyValue键值对', + link: '/form-config/editor-fields/key-value.md' + }, + { + text: 'PageFragmentSelect页面片选择器', + link: '/form-config/editor-fields/page-fragment-select.md' + }, + { + text: 'EventSelect事件选择器', + link: '/form-config/editor-fields/event-select.md' + }, + { + text: 'DisplayConds显示条件配置', + link: '/form-config/editor-fields/display-conds.md' + }, + { + text: 'CondOpSelect条件操作选择器', + link: '/form-config/editor-fields/cond-op-select.md' + } + ], + }, { text: '布局配置', items: [ diff --git a/docs/form-config/editor-fields/code-link.md b/docs/form-config/editor-fields/code-link.md new file mode 100644 index 00000000..498fb15b --- /dev/null +++ b/docs/form-config/editor-fields/code-link.md @@ -0,0 +1,38 @@ +# CodeLink 代码链接 + +通过弹窗链接的方式编辑代码内容。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'code-link', + name: 'codeLink', + text: '代码配置' +} +``` + +## 自定义弹窗标题 + +```js +{ + type: 'code-link', + name: 'codeLink', + text: '代码配置', + formTitle: '编辑代码' +} +``` + +## 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) | — | - | diff --git a/docs/form-config/editor-fields/code-select-col.md b/docs/form-config/editor-fields/code-select-col.md new file mode 100644 index 00000000..c0650eab --- /dev/null +++ b/docs/form-config/editor-fields/code-select-col.md @@ -0,0 +1,37 @@ +# CodeSelectCol 代码块选择列 + +代码块选择器的列组件，支持选择代码块并配置参数。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'code-select-col', + name: 'codeId', + text: '代码块' +} +``` + +## 禁止编辑 + +```js +{ + type: 'code-select-col', + name: 'codeId', + text: '代码块', + notEditable: true +} +``` + +## 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) | — | - | diff --git a/docs/form-config/editor-fields/code-select.md b/docs/form-config/editor-fields/code-select.md new file mode 100644 index 00000000..f6ca8be0 --- /dev/null +++ b/docs/form-config/editor-fields/code-select.md @@ -0,0 +1,33 @@ +# CodeSelect 代码块选择器 + +用于选择代码块并配置参数的组件。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'code-select', + name: 'codeSelect', + text: '代码块' +} +``` + +## 功能说明 + +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) | — | - | diff --git a/docs/form-config/editor-fields/code.md b/docs/form-config/editor-fields/code.md new file mode 100644 index 00000000..53782884 --- /dev/null +++ b/docs/form-config/editor-fields/code.md @@ -0,0 +1,61 @@ +# Code 代码编辑器 + +代码编辑器字段，用于编辑代码内容。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'code', + name: 'code', + text: '代码' +} +``` + +## 指定语言 + +```js +{ + type: 'code', + name: 'code', + text: '代码', + language: 'javascript' +} +``` + +## 自动调整大小 + +```js +{ + type: 'code', + name: 'code', + text: '代码', + autosize: { + minRows: 3, + maxRows: 10 + } +} +``` + +## 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) | — | - | + +## autosize Attributes +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +|---------- |-------- |---------- |------------- |-------- | +| 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 new file mode 100644 index 00000000..8c87fb30 --- /dev/null +++ b/docs/form-config/editor-fields/cond-op-select.md @@ -0,0 +1,37 @@ +# CondOpSelect 条件操作选择器 + +用于选择条件操作符的选择器。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'cond-op', + name: 'op', + text: '操作符' +} +``` + +## 指定父级字段 + +```js +{ + type: 'cond-op', + name: 'op', + text: '操作符', + parentFields: ['field1', 'field2'] +} +``` + +## 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) | — | - | diff --git a/docs/form-config/editor-fields/data-source-field-select.md b/docs/form-config/editor-fields/data-source-field-select.md new file mode 100644 index 00000000..feee0ccb --- /dev/null +++ b/docs/form-config/editor-fields/data-source-field-select.md @@ -0,0 +1,67 @@ +# DataSourceFieldSelect 数据源字段选择器 + +用于选择数据源字段的级联选择器。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'data-source-field-select', + name: 'field', + text: '数据源字段' +} +``` + +## 返回字段key + +```js +{ + type: 'data-source-field-select', + name: 'field', + text: '数据源字段', + value: 'key' +} +``` + +## 限制字段类型 + +```js +{ + type: 'data-source-field-select', + name: 'field', + text: '数据源字段', + dataSourceFieldType: ['string', 'number'] +} +``` + +## 父子节点不关联 + +```js +{ + type: 'data-source-field-select', + name: 'field', + text: '数据源字段', + checkStrictly: true +} +``` + +## 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) | — | - | + +## 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 new file mode 100644 index 00000000..33a848da --- /dev/null +++ b/docs/form-config/editor-fields/data-source-fields.md @@ -0,0 +1,25 @@ +# DataSourceFields 数据源字段配置 + +用于配置数据源字段的表单组件。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'data-source-fields', + name: 'fields', + text: '字段配置' +} +``` + +## 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) | — | - | diff --git a/docs/form-config/editor-fields/data-source-input.md b/docs/form-config/editor-fields/data-source-input.md new file mode 100644 index 00000000..95434083 --- /dev/null +++ b/docs/form-config/editor-fields/data-source-input.md @@ -0,0 +1,25 @@ +# DataSourceInput 数据源输入框 + +支持绑定数据源的输入框组件。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'data-source-input', + name: 'input', + text: '输入框' +} +``` + +## 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) | — | - | diff --git a/docs/form-config/editor-fields/data-source-method-select.md b/docs/form-config/editor-fields/data-source-method-select.md new file mode 100644 index 00000000..d7fcba7a --- /dev/null +++ b/docs/form-config/editor-fields/data-source-method-select.md @@ -0,0 +1,37 @@ +# DataSourceMethodSelect 数据源方法选择器 + +用于选择数据源方法的选择器。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'data-source-method-select', + name: 'method', + text: '数据源方法' +} +``` + +## 禁止编辑 + +```js +{ + type: 'data-source-method-select', + name: 'method', + text: '数据源方法', + notEditable: true +} +``` + +## 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) | — | - | diff --git a/docs/form-config/editor-fields/data-source-methods.md b/docs/form-config/editor-fields/data-source-methods.md new file mode 100644 index 00000000..73a2d804 --- /dev/null +++ b/docs/form-config/editor-fields/data-source-methods.md @@ -0,0 +1,25 @@ +# DataSourceMethods 数据源方法配置 + +用于配置数据源方法的表单组件。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'data-source-methods', + name: 'methods', + text: '方法配置' +} +``` + +## 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) | — | - | diff --git a/docs/form-config/editor-fields/data-source-mocks.md b/docs/form-config/editor-fields/data-source-mocks.md new file mode 100644 index 00000000..fd095595 --- /dev/null +++ b/docs/form-config/editor-fields/data-source-mocks.md @@ -0,0 +1,25 @@ +# DataSourceMocks 数据源Mock配置 + +用于配置数据源Mock数据的表单组件。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'data-source-mocks', + name: 'mocks', + text: 'Mock配置' +} +``` + +## 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) | — | - | diff --git a/docs/form-config/editor-fields/data-source-select.md b/docs/form-config/editor-fields/data-source-select.md new file mode 100644 index 00000000..64c5bab7 --- /dev/null +++ b/docs/form-config/editor-fields/data-source-select.md @@ -0,0 +1,55 @@ +# DataSourceSelect 数据源选择器 + +用于选择数据源的下拉选择器。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'data-source-select', + name: 'dataSource', + text: '数据源' +} +``` + +## 过滤数据源类型 + +```js +{ + type: 'data-source-select', + name: 'dataSource', + text: '数据源', + dataSourceType: 'http' +} +``` + +## 返回数据源ID + +```js +{ + type: 'data-source-select', + name: 'dataSource', + text: '数据源', + value: 'id' +} +``` + +## 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) | — | - | + +## 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 new file mode 100644 index 00000000..620c8373 --- /dev/null +++ b/docs/form-config/editor-fields/display-conds.md @@ -0,0 +1,38 @@ +# DisplayConds 显示条件配置 + +用于配置组件显示条件的表单组件。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'display-conds', + name: 'displayConds', + text: '显示条件' +} +``` + +## 带标题前缀 + +```js +{ + type: 'display-conds', + name: 'displayConds', + text: '显示条件', + titlePrefix: '条件' +} +``` + +## 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) | — | - | diff --git a/docs/form-config/editor-fields/event-select.md b/docs/form-config/editor-fields/event-select.md new file mode 100644 index 00000000..77a86b28 --- /dev/null +++ b/docs/form-config/editor-fields/event-select.md @@ -0,0 +1,49 @@ +# EventSelect 事件选择器 + +用于配置组件或数据源事件的选择器。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'event-select', + name: 'events', + text: '事件配置', + src: 'component' +} +``` + +## 数据源事件 + +```js +{ + type: 'event-select', + name: 'events', + text: '事件配置', + src: 'datasource' +} +``` + +## 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) | — | - | + +## src说明 +- `component`: 组件事件 +- `datasource`: 数据源事件 diff --git a/docs/form-config/editor-fields/key-value.md b/docs/form-config/editor-fields/key-value.md new file mode 100644 index 00000000..54841fbc --- /dev/null +++ b/docs/form-config/editor-fields/key-value.md @@ -0,0 +1,39 @@ +# KeyValue 键值对 + +用于配置键值对数据的表单组件。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'key-value', + name: 'params', + text: '参数' +} +``` + +## 高级模式 + +设置 `advanced` 为 `true`，可切换到代码编辑模式。 + +```js +{ + type: 'key-value', + name: 'params', + text: '参数', + advanced: true +} +``` + +## 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) | — | - | diff --git a/docs/form-config/editor-fields/page-fragment-select.md b/docs/form-config/editor-fields/page-fragment-select.md new file mode 100644 index 00000000..3db1c170 --- /dev/null +++ b/docs/form-config/editor-fields/page-fragment-select.md @@ -0,0 +1,30 @@ +# PageFragmentSelect 页面片选择器 + +用于选择页面片的下拉选择器。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'page-fragment-select', + name: 'pageFragment', + text: '页面片' +} +``` + +## 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) | — | - | + +## 使用说明 + +1. 下拉框会自动列出当前项目中所有的页面片 +2. 选中页面片后，点击编辑图标可跳转到对应页面片进行编辑 diff --git a/docs/form-config/editor-fields/ui-select.md b/docs/form-config/editor-fields/ui-select.md new file mode 100644 index 00000000..e0e5c3dc --- /dev/null +++ b/docs/form-config/editor-fields/ui-select.md @@ -0,0 +1,33 @@ +# UISelect 组件选择器 + +用于在画布中选择组件的选择器。 + +::: warning 注意 +此组件仅在编辑器环境中可用，需要配合 `@tmagic/editor` 使用。 +::: + +## 基础用法 + +```js +{ + type: 'ui-select', + name: 'targetId', + text: '目标组件' +} +``` + +## 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) | — | - | + +## 使用说明 + +1. 点击"点击此处选择"按钮进入选择模式 +2. 在画布中点击目标组件完成选择 +3. 选择后会显示组件名称和ID +4. 可通过清除按钮清空选择 +5. 点击组件名称可跳转到对应组件 diff --git a/docs/form-config/fields/cascader.md b/docs/form-config/fields/cascader.md index d1da40b5..67949dbc 100644 --- a/docs/form-config/fields/cascader.md +++ b/docs/form-config/fields/cascader.md @@ -214,3 +214,241 @@

+ +## 任意一级可选 + +在单选模式下，你只能选择叶子节点；而在多选模式下，勾选父节点真正选中的都是叶子节点。启用该功能后，可让父子节点取消关联，选择任意一级选项。 + +可通过 `checkStrictly = true` 来设置父子节点取消选中关联，从而达到选择任意一级选项的目的。 + + + + + +## 仅返回选中节点的值 + +在选中节点改变时，默认返回由该节点所在的各级菜单的值所组成的数组。可通过 `emitPath = false` 设置仅返回该节点的值。 + + + + + +## 值分隔符 + +当需要将选中值以字符串形式存储时，可通过 `valueSeparator` 指定分隔符，组件会自动将数组转换为字符串存储，读取时也会自动还原。 + + + + + +## 远程选项 + +通过接口请求获取选项列表 + + + + + +同时在 `src/main.ts` 中需要自定义实现请求： + +```typescript +app.use(MagicForm, { + request: async (options: any) => { + // 自定义请求实现 + }, +}); +``` + +## 动态选项 + +options 支持传入函数，可根据表单其他字段动态生成选项列表 + +```typescript +{ + type: 'cascader', + name: 'cascader', + text: '选项', + options: (mForm, { model, formValue }) => { + // 根据表单值动态返回选项 + return [ + { value: 'a', label: '选项A', children: [] } + ]; + } +} +``` + +## Cascader Attributes + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +|------|------|------|--------|--------| +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| placeholder | 输入框占位文本 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | false | +| multiple | 是否多选 | boolean | — | false | +| emitPath | 在选中节点改变时，是否返回由该节点所在的各级菜单的值所组成的数组，若设置 false，则只返回该节点的值 | boolean | — | true | +| checkStrictly | 是否严格的遵守父子节点不互相关联 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | false | +| valueSeparator | 合并成字符串时的分隔符 | string / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | — | +| popperClass | 弹出内容的自定义类名 | string | — | — | +| remote | 是否为远程搜索 | boolean | — | false | +| options | 选项数据源 | Array / Function | — | — | +| option | 远程选项配置 | Object | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | — | + +## options item + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +|------|------|------|--------|--------| +| value | 选项的值 | any | — | — | +| label | 选项的标签 | string | — | — | +| children | 子选项 | Array | — | — | + +## option（远程配置） + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +|------|------|------|--------|--------| +| url | 请求地址 | string | — | — | +| root | 响应数据的根路径 | string | — | — | +| cache | 是否缓存请求结果 | boolean | — | false | +| timeout | 请求超时时间（毫秒） | number | — | — | +| body | 请求体 | Object / Function | — | — | +| item | 数据转换函数，将响应数据转换为选项格式 | Function | — | — | diff --git a/docs/form-config/fields/checkbox.md b/docs/form-config/fields/checkbox.md index f5e89766..ea6c8cc8 100644 --- a/docs/form-config/fields/checkbox.md +++ b/docs/form-config/fields/checkbox.md @@ -1,4 +1,5 @@ # Checkbox 多选框 + 一组备选项中进行多选 ## 基础用法 @@ -12,7 +13,7 @@ }]"> @@ -29,7 +30,59 @@ }]"> + + +## 自定义选中值 + +通过 `activeValue` 和 `inactiveValue` 自定义选中和未选中时的值。 + + + + + +## 数值类型 + +当需要绑定数值类型时，可以使用 `filter: 'number'` 配合默认的 activeValue/inactiveValue。 + + + + + +## 使用 Label 显示 + +通过 `useLabel` 属性控制是否使用 label 作为显示内容。 + + + @@ -44,32 +97,84 @@ text: '选项', options: [ { text: '选项1', value: 1 }, - { text: '选项2', value: 2 } + { text: '选项2', value: 2 }, + { text: '选项3', value: 3 } ] }]"> +## 多选框组禁用选项 + +在选项中设置 `disabled` 可禁用单个选项。 + + + + + +## 动态选项 + +options 支持函数形式，可根据表单状态动态生成选项。 + +```typescript +{ + type: 'checkbox-group', + name: 'checkbox', + text: '选项', + options: (mForm, { model, formValue }) => { + // 根据表单值动态返回选项 + return [ + { text: '选项A', value: 'a' }, + { text: '选项B', value: 'b' } + ]; + } +} +``` ## Checkbox Attributes -| 参数 | 说明 | 类型 | 可选值 | 默认值 | -|---------- |-------- |---------- |------------- |-------- | + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +|------|------|------|--------|--------| | name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| activeValue | 选中时的值 | string / number / Function | — | 1 | -| inactiveValue | 没有选中时的值 | string / number / Function | — | 0 | -| onChange | 值变化时触发的函数 | [OnChangeHandler ](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | false | +| activeValue | 选中时的值 | string / number | — | true（filter 为 'number' 时默认 1） | +| inactiveValue | 未选中时的值 | string / number | — | false（filter 为 'number' 时默认 0） | +| useLabel | 是否使用外部 label 显示 | boolean | — | false | +| filter | 值过滤器 | 'number' / Function | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | — | ## CheckboxGroup 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) | — | - | -| options | 选项 | Array | — | - | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | false | +| options | 选项列表 | Array / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | — | + +## options item + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +|------|------|------|--------|--------| +| value | 选项的值 | any | — | — | +| text | 选项的标签 | string | — | — | +| disabled | 是否禁用该选项 | boolean | — | false | diff --git a/docs/form-config/fields/color-picker.md b/docs/form-config/fields/color-picker.md index 10f3b7f0..f4743412 100644 --- a/docs/form-config/fields/color-picker.md +++ b/docs/form-config/fields/color-picker.md @@ -1,17 +1,86 @@ # ColorPicker 颜色选择器 -用于颜色选择，支持多种格式。 +用于颜色选择，支持多种颜色格式，包括透明度设置。 ## 基础用法 + +## 禁用状态 + + + + + +## 设置默认值 + + + + + +## 带透明度的颜色 + +颜色选择器默认开启透明度选择，返回值为 rgba 格式。 + + + + + +## ColorPicker Attributes + +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +|------|------|------|--------|--------| +| name | 绑定值 | string | — | — | +| text | 表单标签 | string | — | — | +| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | false | +| defaultValue | 默认颜色值 | string | — | — | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | — | + +## 颜色格式说明 + +支持以下颜色格式： + +| 格式 | 示例 | 说明 | +|------|------|------| +| HEX | #409EFF | 十六进制颜色值 | +| RGB | rgb(64, 158, 255) | RGB 颜色值 | +| RGBA | rgba(64, 158, 255, 0.5) | 带透明度的 RGBA 颜色值 | +| HSL | hsl(210, 100%, 63%) | HSL 颜色值 | +| HSLA | hsla(210, 100%, 63%, 0.5) | 带透明度的 HSLA 颜色值 | diff --git a/docs/form-config/fields/date-picker.md b/docs/form-config/fields/date-picker.md index 4c31f352..7cc0be9e 100644 --- a/docs/form-config/fields/date-picker.md +++ b/docs/form-config/fields/date-picker.md @@ -11,7 +11,7 @@ }]"> @@ -26,15 +26,31 @@ }]"> -## 日期格式 + +## 占位符 + + + + + +## 日期格式 使用`format`指定输入框的格式；使用`valueFormat`指定绑定值的格式。 -默认情况下，组件接受并返回`Date`对象。以下为可用的格式化字串，以 UTC 2017年1月2日 03:04:05 为例： +默认情况下，组件的 `format` 默认值为 `YYYY/MM/DD`，`valueFormat` 默认值为 `YYYY/MM/DD`。以下为可用的格式化字串，以 UTC 2017年1月2日 03:04:05 为例： :::warning 请注意大小写 @@ -42,13 +58,11 @@ | 格式 | 含义 | 备注 | 举例 | |------|------|------|------| -| `yyyy` | 年 | | 2017 | +| `YYYY` | 年 | | 2017 | | `M` | 月 | 不补0 | 1 | | `MM` | 月 | | 01 | -| `W` | 周 | 仅周选择器的 `format` 可用；不补0 | 1 | -| `WW` | 周 | 仅周选择器的 `format` 可用 | 01 | -| `d` | 日 | 不补0 | 2 | -| `dd` | 日 | | 02 | +| `D` | 日 | 不补0 | 2 | +| `DD` | 日 | | 02 | | `H` | 小时 | 24小时制；不补0 | 3 | | `HH` | 小时 | 24小时制 | 03 | | `h` | 小时 | 12小时制，须和 `A` 或 `a` 使用；不补0 | 3 | @@ -57,30 +71,42 @@ | `mm` | 分钟 | | 04 | | `s` | 秒 | 不补0 | 5 | | `ss` | 秒 | | 05 | -| `timestamp` | JS时间戳 | 组件绑定值为`number`类型 | 1483326245000 | +| `x` | JS时间戳 | 组件绑定值为`number`类型 | 1483326245000 | | `[MM]` | 不需要格式化字符 | 使用方括号标识不需要格式化的字符 (如 [A] [MM]) | MM | ## Attributes + | 参数 | 说明 | 类型 | 可选值 | 默认值 | |---------- |-------------- |---------- |-------------------------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| value-format | 可选，绑定值的格式。不指定则绑定值为 Date 对象 | string | 见[日期格式](#/zh-CN/component/date-picker#ri-qi-ge-shi) | — | -| 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/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) | — | — | +## 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; +} +``` diff --git a/docs/form-config/fields/daterange-picker.md b/docs/form-config/fields/daterange-picker.md new file mode 100644 index 00000000..184ffefb --- /dev/null +++ b/docs/form-config/fields/daterange-picker.md @@ -0,0 +1,46 @@ +# DateRangePicker 日期范围选择器 + +用于选择或输入日期范围 + +## 基础用法 + + + + + +## 绑定多个字段 + +可以通过配置 `names` 来将日期范围绑定到两个不同的字段上。 + + + + + +## 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) | — | - | diff --git a/docs/form-config/fields/datetime-picker.md b/docs/form-config/fields/datetime-picker.md index 3ed04722..2e528290 100644 --- a/docs/form-config/fields/datetime-picker.md +++ b/docs/form-config/fields/datetime-picker.md @@ -11,7 +11,22 @@ }]"> + + +## 带占位符 + + + @@ -26,16 +41,16 @@ }]"> -## 日期格式 +## 日期格式 -使用`format`指定输入框的格式；使用`valueFormat`指定绑定值的格式。 +使用 `format` 指定输入框的格式；使用 `valueFormat` 指定绑定值的格式。 -默认情况下，组件接受并返回`Date`对象。以下为可用的格式化字串，以 UTC 2017年1月2日 03:04:05 为例： +默认情况下，组件接受并返回格式化后的字符串。以下为可用的格式化字串，以 UTC 2017年1月2日 03:04:05 为例： :::warning 请注意大小写 @@ -43,13 +58,11 @@ | 格式 | 含义 | 备注 | 举例 | |------|------|------|------| -| `yyyy` | 年 | | 2017 | +| `YYYY` | 年 | | 2017 | | `M` | 月 | 不补0 | 1 | | `MM` | 月 | | 01 | -| `W` | 周 | 仅周选择器的 `format` 可用；不补0 | 1 | -| `WW` | 周 | 仅周选择器的 `format` 可用 | 01 | -| `d` | 日 | 不补0 | 2 | -| `dd` | 日 | | 02 | +| `D` | 日 | 不补0 | 2 | +| `DD` | 日 | | 02 | | `H` | 小时 | 24小时制；不补0 | 3 | | `HH` | 小时 | 24小时制 | 03 | | `h` | 小时 | 12小时制，须和 `A` 或 `a` 使用；不补0 | 3 | @@ -60,29 +73,32 @@ | `ss` | 秒 | | 05 | | `A` | AM/PM | 仅 `format` 可用，大写 | AM | | `a` | am/pm | 仅 `format` 可用，小写 | am | -| `timestamp` | JS时间戳 | 仅 `valueFormat` 可用；组件绑定值为`number`类型 | 1483326245000 | -| `[MM]` | 不需要格式化字符 | 使用方括号标识不需要格式化的字符 (如 [A] [MM]) | MM | +| `x` | JS时间戳（毫秒） | 仅 `valueFormat` 可用 | 1483326245000 | +| `X` | Unix时间戳（秒） | 仅 `valueFormat` 可用 | 1483326245 | ## Attributes + | 参数 | 说明 | 类型 | 可选值 | 默认值 | |---------- |-------------- |---------- |-------------------------------- |-------- | -| name | 绑定值 | string | — | — | -| text | 表单标签 | string | — | — | -| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| format | 显示在输入框中的格式 | string | 见[日期格式](#/zh-CN/component/date-picker#ri-qi-ge-shi) | yyyy-MM-dd HH:mm:ss | -| value-format | 可选，绑定值的格式。不指定则绑定值为 Date 对象 | string | 见[日期格式](#/zh-CN/component/date-picker#ri-qi-ge-shi) | — | -| 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/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) | — | — | diff --git a/docs/form-config/fields/dynamic-field.md b/docs/form-config/fields/dynamic-field.md new file mode 100644 index 00000000..d089b708 --- /dev/null +++ b/docs/form-config/fields/dynamic-field.md @@ -0,0 +1,52 @@ +# DynamicField 动态表单 + +根据模型中某个字段的值，动态生成一组表单字段。 + +## 基础用法 + + + + + +:::warning +特别注意：`dynamic-field` 的上一级配置必须设置 `extensible: true`，才能保存未在 schema 中声明的动态字段。 +::: + +## Attributes +| 参数 | 说明 | 类型 | 可选值 | 默认值 | +|---------- |-------------- |---------- |-------------------------------- |-------- | +| type | 组件类型 | string | dynamic-field | — | +| text | 表单标签 | string | — | — | +| dynamicKey | 监听的字段名。当该字段值变化时，触发 `returnFields` 重新计算 | string | — | — | +| returnFields | 返回字段列表的函数 | (config, model, request) => Promise | — | — | + +### Field 对象结构 +| 参数 | 说明 | 类型 | 默认值 | +|---------- |-------------- |---------- |-------- | +| name | 字段名 | string | — | +| label | 标签名 | string | — | +| defaultValue | 默认值 | any | — | diff --git a/docs/form-config/fields/number-range.md b/docs/form-config/fields/number-range.md new file mode 100644 index 00000000..22a4e106 --- /dev/null +++ b/docs/form-config/fields/number-range.md @@ -0,0 +1,26 @@ +# NumberRange 数字范围输入框 + +用于输入数字范围 + +## 基础用法 + + + + + +## 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) | — | - | diff --git a/docs/form-config/fields/number.md b/docs/form-config/fields/number.md index 204b403f..01e8d66b 100644 --- a/docs/form-config/fields/number.md +++ b/docs/form-config/fields/number.md @@ -53,10 +53,11 @@ | 参数 | 说明 | 类型 | 可选值 | 默认值 | |----------|-------------- |----------|-------------------------------- |-------- | | name | 绑定值 | string | — | — | -| placeholder | 输入框占位文本 | 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) | — | - | diff --git a/docs/form-config/fields/radio.md b/docs/form-config/fields/radio.md index 9425b47d..6b730069 100644 --- a/docs/form-config/fields/radio.md +++ b/docs/form-config/fields/radio.md @@ -5,8 +5,8 @@ ## TS 定义 ```typescript -interface RedioGroup extends FormItem { - type: 'redioGroup'; +interface RadioGroup extends FormItem { + type: 'radio-group'; options: { value: any; text: string; diff --git a/docs/form-config/fields/text.md b/docs/form-config/fields/text.md index 6fd0e90f..a7417a6f 100644 --- a/docs/form-config/fields/text.md +++ b/docs/form-config/fields/text.md @@ -110,15 +110,16 @@ | 参数 | 说明 | 类型 | 可选值 | 默认值 | |---------- |-------- |---------- |------------- |-------- | | name | 绑定值 | string | — | — | -| placeholder | 输入框占位文本 | string | — | — | | text | 表单标签 | string | — | — | +| placeholder | 输入框占位文本 | string | — | — | | disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | false | -| tooltip | 输入时显示内容 | boolean | — | false | -| placeholder | 输入框占位文本 | string | — | — | +| clearable | 是否可清空 | boolean | — | true | +| tooltip | 输入时显示内容 | string | — | — | | trim | 是否去掉首尾空格 | boolean | — | false | | filter | 过滤值 | string / Function | number | - | -| onChange | 值变化时触发的函数 | [OnChangeHandler ](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | +| prepend | 前置内容 | string | — | - | | append | 后置内容 | string / Object | — | - | +| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form/src/schema.ts) | — | - | ## append Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | diff --git a/docs/form-config/fields/timerange-picker.md b/docs/form-config/fields/timerange-picker.md new file mode 100644 index 00000000..68c8ba59 --- /dev/null +++ b/docs/form-config/fields/timerange-picker.md @@ -0,0 +1,45 @@ +# TimeRangePicker 时间范围选择器 + +用于选择或输入时间范围 + +## 基础用法 + + + + + +## 绑定多个字段 + +可以通过配置 `names` 来将时间范围绑定到两个不同的字段上。 + + + + + +## 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) | — | - | diff --git a/docs/form-config/layout.md b/docs/form-config/layout.md index e902728b..f081e93c 100644 --- a/docs/form-config/layout.md +++ b/docs/form-config/layout.md @@ -178,3 +178,38 @@ label: '配置1', }] }]"> + +### step + + + +### flex-layout + + diff --git a/docs/guide/advanced/coupling.md b/docs/guide/advanced/coupling.md index d6af837b..460a2ea0 100644 --- a/docs/guide/advanced/coupling.md +++ b/docs/guide/advanced/coupling.md @@ -83,30 +83,29 @@ export default { ``` @@ -151,10 +150,3 @@ function Test({ config }) { export default Test; ``` - -按照上述实现触发事件和事件动作，就可以完成组件的联动事件分发响应。 - -:::tip -组件事件的联动是借助了@tmagic/core，需要在组件实例化的时候将需要暴露的方法提供给@tmagic/core，在上述例子中useApp方法的调用就是完成这个操作，useApp返回的app对象就是@tmagic/core的实例。在vue的实现中useApp是将整个vue实例都提供给了app，所以需要defineExpose来定义vue instance上的方法，react则是将需要暴露的方法作为useApp的参数传入 -::: - diff --git a/docs/guide/component.md b/docs/guide/component.md index af80d0d1..452c6df6 100644 --- a/docs/guide/component.md +++ b/docs/guide/component.md @@ -1,28 +1,27 @@ # 如何开发一个组件 tmagic-editor支持业务方进行自定义组件开发。在tmagic-editor中，组件是以 npm 包形式存在的，组件和插件只要按照规范开发，就可以在tmagic-editor的 runtime 中被加入并正确渲染组件。 -## 组件开发 -以 vue 的组件开发为例。运行项目中的 playground 示例，会自动加载 vue 的 runtime。runtime会加载[@tmagic/ui](https://github.com/Tencent/tmagic-editor/tree/master/packages/ui) - -## 组件注册 -在 [playground](https://tencent.github.io/tmagic-editor/playground/index.html#/) 中，我们可以尝试点击添加一个组件，在模拟器区域里，就会出现这个组件。其中就涉及到组件注册。 - -这一步需要开发者基于tmagic-editor搭建了平台后，实现组件列表的注册、获取机制，tmagic-editor组件注册其实就是保存好组件 `type` 的映射关系。`type` 可以参考[组件介绍](../guide/conception.html#组件)。 - -可以参考 vue 版本的 @tmagic/ui 中，[组件渲染](../guide/advanced/page.html#组件渲染)逻辑里，type 会作为组件名进入渲染。所以在 vue 的组件开发中，我们也需要在为 vue 组件声明 name 字段时，和 type 值对应起来，才能正确渲染组件。 - ### 组件规范 组件的基础形式，需要有四个文件 - index 入口文件，引入下面几个文件 -- formConfig 表单配置描述 -- initValue 表单初始值 +- form-config 表单配置描述 +- init-value 表单初始值 - event 定义联动事件，具体可以参考[组件联动](../guide/advanced/coupling.html#组件联动) - component.{vue,jsx} 组件样式、逻辑代码 -@tmagic/ui 中的 button/text 就是基础的组件示例。我们要求声明 index 入口，因为我们希望在后续的配套打包工具实现上，可以有一个统一规范入口。 - ### 1. 创建组件 -在项目中，如 runtime 目录中，创建一个名为 test-component 的组件目录，其中包含上面四个规范文件。 + +可以使用`npm create tmagic` 选择 `components:组件库(组件/插件/数据源)` 来快速创建一个组件库。 + +然后继续使用`npm create tmagic` 选择 `component:组件` 来快速创建一个组件。 + +:::tip + +组件库并不是必须，组件如何管理可以根据具体情况来选择。直接放到 runtime 目录中也是一个不错的选择，如果选择放到runtime中可以在runtime中的package.json添加`"tmagicComponentsPath": "./components"` 来指定组件库的路径。这样在使用`npm create tmagic` 来创建组件时，会自动将组件添加到组件库中。 + +::: + +手动创建组件，可以在项目中，如 runtime 目录中，创建一个名为 test-component 的组件目录，其中包含上面四个规范文件。 ```javascript // index.js // vue @@ -30,14 +29,18 @@ import Test from './Test.vue'; // react import Test from './Test.tsx'; -export { default as config } from './formConfig'; -export { default as value } from './initValue'; +export { default as config } from './form-config'; +export { default as value } from './init-value'; export default Test; ``` +:::tip +如果在runtime中使用了@tmagic/cli，则必须保持此规范；不使用则可以自由书写。 +::: + ```javascript -// formConfig.js +// form-config.js export default [ { type: 'select', @@ -61,15 +64,40 @@ export default [ ]; ``` +:::tip +配置内容必须是一个数组，每个元素是一个对象，包含 type、text、name 等属性，每个对象代表一个表单项。 + +type 是表单项的类型 + +text 是表单项的文本 + +name 是表单项值的key。 + +上述实例对应生成的值为 +```json +{ + "color": "red", + "text": "一段文字", +} +``` + +type 在@tmagic/form 和 @tmagic/editor 中默认提供了种，@tmagic/form提供的可以前往[表单配置](/form-config/fields/text.html)查看。 +::: + + ```javascript -// initValue.js +// init-value.js export default { color: 'red', text: '一段文字', }; ``` - 版本的组件代码示例 +:::tip +在编辑器中添加组件时使用，作为初始值。 +::: + +Vue版本的组件代码示例 ```vue - ``` +:::tip +编辑器中配置的 config 对象，会作为 props 传入组件中。 +::: + react 版本组件代码示例 ```javascript // Test.tsx @@ -118,84 +148,52 @@ export default Test; ``` -### 2. 使用tmagic-cli -在 runtime vue 中，我们已经提供好一份示例。在 tmagic.config.ts 文件中。只需要在 packages 加入你创建的组件的路径（如果是个 npm 包，则将路径替换为包名即可），打包工具就会自动识别到你的组件。 +## 插件开发 +插件开发和组件开发形式类似，但是插件开发不需要有组件的规范。 + +我们只需要在插件中提供一个入口文件。插件需要提供一个 install 方法。 -### 3. 启动 playground -在上面的步骤完成后，在 playground/src/configs/componentGroupList 中。找到组件栏的基础组件列表，在其中加入你的开发组件 ```javascript -{ - title: '基础组件', - items: [ +// 在Vue的runtime中 +export default { + install(vueApp, { app: tmagicApp }) {} +} +``` + +```javascript +// 在React的runtime中 +export default { + install({ app: tmagicApp }) {} +} +``` + +在插件中开发者可以自由实现需要的业务逻辑。 + +## 集成到runtime中 + +### 使用@tmagic/cli + +在使用`npm create tmagic` 创建的runtime中，自动集成了@tmagic/cli，将组件集成到此runtime中只需要在`tmagic.config.ts`中的packages字段中添加 +```javascript +import { defineConfig } from '@tmagic/cli'; + +export default defineConfig({ + // other config + packages: [ { - text: '文本', - type: 'text', - }, - { - text: '按钮', - type: 'button', - }, - // 加入这个测试组件 - { - text: '测试', - type: 'test', + '组件type': '组件目录或者npm包名', }, ], -} -``` - -然后，在 magic 项目根目录中，运行 +}); -``` -npm run playground ``` -至此，我们打开 playground 后，就能添加开发的中的组件，并且得到这个开发中的组件**在编辑器中的表现**了。 +:::tip +组件type需要与[componentGroupList](../api/editor/props.html#componentgrouplist)中的type对应。 +::: - -### 4. 启动 runtime -在完成开发中组件在编辑器中的实现后，我们将编辑器中的 DSL 源码📄 打开，复制 DSL。并在 runtime/vue/src/page 下。创建一个 page-config.js 文件。将 DSL 作为配置导出。 +配置到packages字段中后，执行`npm run tmagic`来创建组件库的入口文件。 -```javascript -window.magicDSL = [ - // DSL -] -``` +然后使用`npm run build:libs`命令来构建用于编辑器中的组件配置、组件初始值、组件事件联动的资源文件。 -在 page/main.ts 中，将这份配置读入 -```javascript -import './page-config.js'; -``` - -然后执行在 runtime/ 目录下执行 -``` -npm run build:libs -npm run dev -``` - -至此，我们就可以得到这个开发中组件在编辑器中进行了配置并保存后，在真实页面中应该有的样子。 - - - -## 插件开发 -插件开发和组件开发形式类似，但是插件开发不需要有组件的规范。在以 vue 为基础的 ui 和 runtime 中，插件其实就是一个 vue 插件。 - -我们只需要在插件中提供一个入口文件，其中包含 vue 的 install 方法即可。 - -```javascript -export default { - install() {} -} -``` - -在插件中开发者可以自由实现需要的业务逻辑。插件和组件一样，只需要在 units.js 中，加入导出的 units 对象里即可。 - -## 业务定制 -上述的步骤，如 -1. 组件/插件初始化 -2. 编辑器中的组件调试 -3. 真实页面的组件调试 -4. 编辑器中的 DSL 同步至本地调试页面 - -等许多步骤，都可以交由业务方进行定制，开发业务自定义的脚手架工具，或者如示例中一样，使用打包脚本来处理。 \ No newline at end of file diff --git a/docs/guide/index.md b/docs/guide/index.md index 21521c3b..d317ae01 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -195,6 +195,9 @@ npm install sass -D ## runtimeUrl 该配置涉及到 [runtime 概念](runtime.md)，tmagic-editor编辑器中心的模拟器画布，是一个 iframe（这里的 `runtimeUrl` 配置的，就是你提供的 iframe 的 url），其中渲染了一个 runtime，用来响应编辑器中的组件增删改等操作。 +:::tip +可以使用`npm create tmagic` 来快速创建一个runtime项目。 +::: ## componentGroupList diff --git a/docs/guide/runtime.md b/docs/guide/runtime.md index e0194176..41a8a9e4 100644 --- a/docs/guide/runtime.md +++ b/docs/guide/runtime.md @@ -1,70 +1,29 @@ # RUNTIME 本章详细介绍如何深入理解tmagic-editor的打包，以及如何根据需求定制，修改tmagic-editor的页面打包发布方案。页面发布、打包相关的定制化开发，需要使用tmagic-editor的业务方，搭建好基于开源tmagic-editor的管理平台、存储服务等配套设施。 +## runtime 是什么 + +runtime是用来解析DSL的执行环境，用于渲染 DSL 呈现页面。 + +编辑器生成出来的DSL需要通过 runtime 来渲染。 + ## 实现一个 runtime -在 [@tmagic/ui](./advanced/tmagic-ui.html) 部分，我们已经说过，runtime 和 UI 是配套实现的。每个版本的 runtime 都需要一个对应的 UI 来作为渲染器，实现渲染 DSL 呈现页面的功能。 -### UI -一个 UI 应该至少包含一个渲染器，来实现[页面渲染](./advanced/page.html)。同时可以提供一些基础组件。具体实现可以参考[@tmagic/ui](./advanced/tmagic-ui.html)。 +:::tip +可以使用`npm create tmagic` 来快速创建一个runtime项目。 +::: -### page -runtime 的 `page` 部分，就是真实项目页面的渲染环境。发布出去的项目页都需要基于该部分来实现渲染功能。而 `page` 的主要逻辑，就是需要加载 UI，同时实现业务方需要的业务逻辑，比如： -- 提供页面需要的全局 api -- 业务需要的特殊实现逻辑 -- 加载第三方全局组件/插件等 - -具体的 page 实现示例，可以参考 -- [vue runtime](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue/page) -- [react runtime](https://github.com/Tencent/tmagic-editor/blob/master/runtime/react/page) - -### playground -runtime 的 `playground` 部分，和 `page` 做的事情几乎一致，业务方可以包含上述 `page` 所拥有的全部能力。但是，因为 playground 需要被编辑器加载，作为编辑器中页面模拟器的渲染容器，和编辑器通信，接受编辑器中组件的增删改查。所以，除了保持和 `page` 一样的渲染逻辑之外，`playground` 还要额外实现一套既定通信内容和 api，才能实现和编辑器的通信功能。 - -#### onRuntimeReady -**在 playground 页面渲染后**，需要调用接口通知编辑器完成加载。该调用需要传入一个参数 API，即挂载了增删改查功能的对象示例，提供给编辑器。 -```javascript -window.magic?.onRuntimeReady(API) +创建出来的项目会包含page、playground两个目录。 +```bash +. +├── page +├── playground ``` -#### onPageElUpdate -**playground 在每次更新了页面配置后**，调用一次 onPageElUpdate 并传入一个 DOM 节点，该方法作用是传入一个页面渲染组件的根节点，用来告知编辑器的模拟器遮罩如何作出反应。 -```javascript -window.magic.onPageElUpdate(document.querySelector('.magic-ui-page')); -``` +page用于生产环境 -#### 提供 API -| API | 说明 | 参数 | -|---------- |-------- |---------- | -|updateRootConfig| 根节点更新 | `root: MApp` | -|updatePageId| 更新当前页面 id | `id: string` | -|select| 选中组件 | `id: string`| -|add| 增加组件 | { `config` , `root` }: `UpdateData` | -|update| 更新组件 | { `config` , `root` }: `UpdateData` | -|remove| 删除组件 | { `config` , `root` }: `UpdateData` | -|sortNode| 组件在容器间排序 |{ `src` , `dist`, `root` }: `SortEventData` | +playground用于编辑器中 -runtime 的实现示例，可以参考tmagic-editor提供的： -- [vue runtime](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue) -- [react runtime](https://github.com/Tencent/tmagic-editor/blob/master/runtime/react) - -### 页面发布 -如介绍中提到的，tmagic-editor页面发布方案，是对构建产物 `page/index.html` 进行项目信息注入。项目信息就是搭建平台存储的页面配置。发布时，将注入项目信息的 `page/index.html` 发布出去即可。 - -## 版本管理 -基于上一步提到的打包原理，每次构建后，得到的产物都可以进行归档编号，存为版本。涉及到的组件改动和新增修改，体现在各个版本中。 - -版本选择 - -版本管理具体如何实现，这取决于使用tmagic-editor的业务方。版本管理具有如下优点： -1. 对于已经配置好发布的项目，使用固定版本，不会被新版本的特性影响，保证项目线上稳定运行 -2. 发布的新版本如果出现问题，可以及时回退选择使用旧版本 - -## 结合业务定制 -tmagic-editor的静态资源构建，项目配置保存，页面发布，在tmagic-editor的提供的示例方案中，流程是： -1. 触发构建，执行流水线，基于 runtime 执行 build -2. 将构建产物归档推送至 cdn，存为一个ui版本 -3. 项目配保存后，项目发布时，将项目配置发布至 CDN 存储为 DSL.js，同时根据当前项目使用的ui版本，获取到 page/index.html，将 DSL.js 引用方式以 script 标签形式写入。 -4. 将注入信息的 page/index.html 发布为项目静态资源 act.html -5. 线上可加载 act.html 访问项目 - -其中各个步骤的定制，可以交由业务方根据tmagic-editor提供的示例进行自定义修改。 \ No newline at end of file +:::tip +想要了解DSL的解析以及runtime与编辑器的通信，可以前往[教程](/guide/tutorial/index.md) +:::