自定义设置器与属性编辑器自定义 Setter 和属性编辑器构成了 VTJ 可扩展属性配置系统的基础使开发者能够为物料组件属性创建专门的输入控件。该系统提供了基于插件的架构与设计器环境无缝集成同时为属性编辑场景提供最大的灵活性。架构概览Setter 系统通过集中管理模式运行支持动态注册、基于类型的发现和组件生命周期管理。该架构由三个核心层组成Setter 管理层、Wrapper 集成层和组件渲染层。Setter 管理系统SetterManagerSetterManager作为所有属性编辑器的中央注册表管理 Setter 生命周期并提供注册接口。class SetterManager { private setters: Recordstring, Setter {}; public defaultSetter: Setter defaultSetter; // 核心方法 register(setter: Setter); get(name: string): Setter; set(name: string, setter: PartialSetter); getByType(type: BlockPropDataType): string[]; }主要职责注册通过register()方法添加自定义 setter检索使用get()方法按名称获取 setter修改使用set()方法更新现有 setter 配置类型发现使用getByType()查询与特定数据类型兼容的 setter 请始终在物料初始化之前注册自定义 setter以确保在组件渲染期间可用。当需要自定义而不完全替换时使用set()覆盖内置 setter 配置。Setter 接口Setter协议定义了所有属性编辑器的契约interface Setter { name: string; component: VueComponent; type: BlockPropDataType; props?: Recordstring, any; }属性nameSetter 的唯一标识符component实现编辑器 UI 的 Vue 组件typeSetter 处理的数据类型String, Boolean, Number, Object, Array, Functionprops传递给组件的默认配置内置 SettersVTJ 提供了一套全面的预配置 setter涵盖常见的属性编辑场景Setter 名称组件类型描述StringSetterElInputString标准文本输入字段BooleanSetter-Boolean布尔值的复选框/切换NumberSetterElInputNumberNumber带步控的数值输入ColorSetterElColorPickerString颜色选择器SelectSetterElSelectString选项下拉选择ExpressionSetter自定义输入Object带{{ }}语法的表达式编辑器JsonSetter自定义编辑器Object/Array用于复杂数据结构的 JSON 编辑器FunctionSetter自定义编辑器Function函数体编辑器IconSetter自定义选择器String图标选择界面ImageSetter自定义上传器String图片上传/选择FileSetter自定义上传器String文件上传控件SliderSetterElSliderNumber范围滑块输入RadioSetterElRadioString单选按钮组TagSetter自定义输入String标签管理界面SizeSetter自定义选择String尺寸预设选择器SectionSetter自定义 UIString可视化部分分隔符CssSetter自定义编辑器StringCSS 属性编辑器VanIconSetter自定义选择器StringVant 图标选择 内置 setter 默认使用 Element Plus 组件确保视觉一致性。利用props配置自定义行为而无需创建新的 setter 类型。创建自定义 Setters基本 Setter 实现通过实现一个 Vue 组件来创建自定义 setter该组件通过v-model或显式 props 接收值并通过事件发出更改。示例日期 Settertemplate ElDatePicker v-modellocalValue typedate formatYYYY-MM-DD value-formatYYYY-MM-DD changehandleChange / /template script langts setup import { ref, watch } from vue; import { ElDatePicker } from element-plus; import { isJSExpression } from vtj/renderer; export interface Props { modelValue?: string | any; placeholder?: string; disabled?: boolean; } const props withDefaults(definePropsProps(), { placeholder: Select date, disabled: false, }); const emit defineEmits{ change: [value: string]; }(); const localValue refstring | undefined( isJSExpression(props.modelValue) ? undefined : props.modelValue, ); watch( () props.modelValue, (v) { localValue.value isJSExpression(v) ? undefined : (v as string); }, ); const handleChange (value: string) { emit(change, value); }; defineOptions({ name: DateSetter, }); /script示例富文本 Settertemplate div classrich-text-setter ElButton v-if!isEditing clickstartEdit :disableddisabled Edit Content /ElButton div v-else classeditor-container textarea v-modeleditorValue :disableddisabled rows10 / div classactions ElButton clickcancelEditCancel/ElButton ElButton typeprimary clicksaveEditSave/ElButton /div /div /div /template script langts setup import { ref, computed } from vue; import { ElButton } from element-plus; import { isJSExpression } from vtj/renderer; export interface Props { modelValue?: string; disabled?: boolean; } const props withDefaults(definePropsProps(), { disabled: false, }); const emit defineEmits{ change: [value: string]; }(); const isEditing ref(false); const editorValue ref(); const startEdit () { const value props.modelValue; editorValue.value isJSExpression(value) ? : (value as string) || ; isEditing.value true; }; const saveEdit () { emit(change, editorValue.value); isEditing.value false; }; const cancelEdit () { isEditing.value false; }; defineOptions({ name: RichTextSetter, }); /script具有上下文访问的高级 Setter高级 setter 可以访问渲染上下文以提供变量绑定、表达式求值和项目元数据等功能。template div classadvanced-expression-setter ElInput v-modeltextValue changehandleChange :disableddisabled template #prefix{{ prefix }}/template template #suffix{{ suffix }}/template /ElInput ElButton v-ifcontext showBindButton clickshowVariablePicker sizesmall text Bind Variable /ElButton /div /template script langts setup import { ref, watch, computed } from vue; import { ElInput, ElButton } from element-plus; import { type JSExpression } from vtj/core; import { isJSExpression } from vtj/renderer; import { type Context } from vtj/renderer; import { expressionValidate } from ../../utils; export interface Props { modelValue?: JSExpression | string; context?: Context; disabled?: boolean; } const props withDefaults(definePropsProps(), { disabled: false, }); const emit defineEmits{ change: [value: JSExpression]; }(); const prefix {{; const suffix }}; const showBindButton computed(() { return isJSExpression(props.modelValue) || !props.modelValue; }); const createValue (value: JSExpression | string ) { return { type: JSExpression, value: isJSExpression(value) ? value.value : value, } as JSExpression; }; const textValue ref(createValue(props.modelValue).value); watch( () props.modelValue, (v) { textValue.value createValue(v).value; }, { immediate: true }, ); const validate (value: JSExpression) { return expressionValidate(value, props.context, true); }; const handleChange (value: string) { const expression: JSExpression { type: JSExpression, value, }; if (validate(expression)) { emit(change, expression); } }; const showVariablePicker () { // 实现变量选择器对话框 console.log(Show variable picker, props.context); }; defineOptions({ name: AdvancedExpressionSetter, }); /scriptSetter 注册注册方法方法 1通过 SetterManager 直接注册import { setterManager } from vtj/designer; import DateSetter from ./setters/DateSetter.vue; setterManager.register({ name: DateSetter, component: DateSetter, type: String, });方法 2基于插件的注册import type { Plugin } from vtj/designer; import { setterManager } from vtj/designer; import DateSetter from ./setters/DateSetter.vue; const customSettersPlugin: Plugin { name: CustomSettersPlugin, setup(ctx) { setterManager.register({ name: DateSetter, component: DateSetter, type: String, props: { format: YYYY-MM-DD, }, }); return { // 插件返回值 }; }, }; export default customSettersPlugin;动态 Setter 配置使用set()方法在运行时修改现有 setter 配置setterManager.set(DateSetter, { props: { format: DD/MM/YYYY, disabled: false, }, });物料 Schema 集成在物料 Schema 中配置 SettersSetter 在物料组件属性 schemas 中使用setter字段进行配置{ componentName: MyCustomComponent, props: [ { name: title, title: Title, type: String, defaultValue: Default Title, setter: { name: StringSetter, props: { maxlength: 50, showWordLimit: true } } }, { name: themeColor, title: Theme Color, type: String, setter: ColorSetter }, { name: publishDate, title: Publish Date, type: String, setter: { name: DateSetter, label: Select Date } }, { name: content, title: Content, type: Object, setter: [ StringSetter, { name: RichTextSetter, label: Rich Text }, ExpressionSetter ] } ] }多 Setter 支持属性可以支持多种 setter 类型允许用户在不同的编辑模式之间切换{ name: dataSource, title: Data Source, type: String, setter: [ SelectSetter, { name: JsonSetter, props: { type: Object } }, ExpressionSetter ], options: [static, api, local] }SetterWrapper 集成SetterWrapper组件连接物料 schemas 和 setter 实现提供自动类型检测、上下文注入和值规范化。组件属性属性类型默认值描述contextContextnull用于表达式求值的渲染上下文currentBlockModelnull当前正在编辑的组件namestring-属性名称labelstring-显示标签titlestring-工具提示/描述valueanyundefined当前属性值settersstring|MaterialSetter|Array必填Setter 配置optionsArray[]SelectSetter/RadioSetter 的选项variablebooleantrue启用表达式绑定removablebooleanfalse允许属性移除disabledbooleanfalse禁用编辑值流最佳实践性能优化script langts setup import { markRaw, defineComponent } from vue; // 使用 markRaw 防止不必要的响应式 const setterComponent markRaw(DateSetter); // 对于复杂组件避免深层响应式包装 const props defineProps{ modelValue: any; options?: Recordstring, any[]; }(); /script表达式处理始终检查JSExpression类型以防止当值包含绑定表达式时出现运行时错误import { isJSExpression } from vtj/renderer; const computedValue computed(() { if (isJSExpression(props.modelValue)) { return undefined; // 或显示表达式指示器 } return props.modelValue; });类型安全导出 setter props 的 TypeScript 接口以启用类型检查export interface DateSetterProps { modelValue?: string; placeholder?: string; format?: string; disabled?: boolean; minDate?: Date; maxDate?: Date; } const props withDefaults(definePropsDateSetterProps(), { placeholder: Select date, format: YYYY-MM-DD, });可访问性确保自定义 setter 遵循可访问性指南template label :forinputId classsetter-label {{ label }} input :idinputId v-modellocalValue :aria-labellabel :aria-invalidhasError changehandleChange / span v-iferrorMessage classerror-message rolealert {{ errorMessage }} /span /label /template高级场景条件 Setters实现根据上下文显示不同 setter 的逻辑template component :iscurrentSetter.component v-bindcurrentSetter.props :model-valuevalue changehandleChange / /template script langts setup import { computed } from vue; import { setterManager } from vtj/designer; const props defineProps{ value: any; context: any; }(); const currentSetter computed(() { if (props.context?.isComplex) { return setterManager.get(JsonSetter); } return setterManager.get(StringSetter); }); /script异步数据加载为 SelectSetter 动态加载选项template ElSelect v-modelselectedValue :loadingloading changehandleChange ElOption v-foritem in dynamicOptions :keyitem.value :labelitem.label :valueitem.value / /ElSelect /template script langts setup import { ref, onMounted } from vue; import { ElSelect, ElOption } from element-plus; const loading ref(false); const dynamicOptions refArray{ label: string; value: any }([]); const selectedValue ref(); const emit defineEmits{ change: [value: any]; }(); const loadOptions async () { loading.value true; try { const response await fetch(/api/options); dynamicOptions.value await response.json(); } finally { loading.value false; } }; onMounted(loadOptions); const handleChange (value: any) { emit(change, value); }; /script故障排除常见问题问题原因解决方案Setter 不显示注册时机在设计器初始化之前注册 setter值未更新缺少 emit确保change事件发出新值表达式错误未传递上下文通过 SetterWrapper 提供有效上下文类型不匹配类型声明不正确验证type是否与实际数据类型匹配Props 未传递组件名称不匹配确保 setter 名称与注册匹配调试模式为 setter 操作启用详细日志记录import { logger } from vtj/utils; // 记录 setter 注册 setterManager.register({ name: CustomSetter, component: CustomSetterComponent, type: String, }); logger.info(CustomSetter registered); // 记录 setter 检索 const setter setterManager.get(CustomSetter); logger.debug(Setter retrieved:, setter);后续步骤掌握自定义 setter 后探索以下相关主题物料 Schema 配置学习如何使用 setter 规范配置物料组件自定义小部件和设计器面板使用自定义面板和小部件扩展设计器 UI插件系统开发将自定义 setter 和扩展打包到插件中创建自定义物料组件开发具有属性编辑器的完整物料组件Provider API 参考了解用于上下文管理的 provider 系统参考资料官方文档https://vtj.pro/在线平台https://app.vtj.pro/开源仓库https://gitee.com/newgateway/vtj