接入业务物料与属性配置

完整活动页在文本物料之外增加公告、资源选择器和页面设置。选中公告后，右栏可以修改文案、色调和精选状态；打开“使用背景图”后才显示资源字段。这个联动由 ifShow 控制，关闭开关只移除字段，不会自动清空已经保存的图片值。

定义带表单的业务物料

公告的 Vue 组件和编辑协议位于同一个模块：

import { computed, defineComponent, h } from 'vue'

export const NoticeWidget = defineComponent({
  name: 'GuideNoticeWidget',
  props: {
    text: { type: String, default: '活动公告' },
    tone: { type: String, default: 'warm' },
    image: { type: String, default: '' },
    featured: { type: Boolean, default: false },
  },
  setup(props) {
    const backgroundImage = computed(() => props.image
      ? { backgroundImage: `url(${props.image})` }
      : undefined)

    return () => h('section', {
      class: {
        'guide-notice': true,
        [`guide-notice--${props.tone}`]: true,
        'guide-notice--featured': props.featured,
      },
      style: backgroundImage.value,
    }, [
      h('strong', props.featured ? '精选活动' : '活动提示'),
      h('p', props.text),
    ])
  },
})

这个定义展示了四条常用规则：

material 只影响物料栏的标题、描述、标签和搜索，不进入页面 Schema。
defaultProps 决定新节点的初始数据，不会覆盖导入 Schema 中已有的 props。
ifShow 根据当前表单值显示背景图字段。
rules 在字段变化时验证输入；服务端仍必须重新验证保存和发布数据。

字段未声明 bindTo 时，Designer 默认把值写到 props.{key}。因此 text、tone 和 image 不需要重复声明路径；hasImage 只控制表单显示，不会改变 image 的保存位置。

注册业务字段

Asset 不是内置字段键。示例将业务按钮包装为字段 adapter，再与 Ant Design Vue 字段合并：

import type { FieldComponentMap } from '@dragcraft/designer'
import { createAntDesignVueFields } from '@dragcraft/fields-ant-design-vue'
import { defineComponent, h } from 'vue'

export const AssetField = defineComponent({
  name: 'GuideAssetField',
  props: {
    modelValue: { type: String, default: '' },
  },
  emits: ['update:modelValue'],
  setup(props, { emit }) {
    return () => h('button', {
      type: 'button',
      class: 'guide-asset-field',
      onClick: () => emit('update:modelValue', props.modelValue
        ? ''
        : 'https://images.unsplash.com/photo-1492684223066-81342ee5ff30?auto=format&fit=crop&w=1200&q=80'),
    }, props.modelValue ? '移除背景图' : '选择示例背景图')
  },
})

export function createGuideFieldComponentMap(): FieldComponentMap {
  return {
    ...createAntDesignVueFields(),
    Asset: {
      component: AssetField,
      modelPropName: 'modelValue',
      updateEventName: 'onUpdate:modelValue',
    },
  }
}

adapter 明确组件从哪个 prop 读取值，以及通过哪个事件提交新值。资源权限、上传、远程搜索和错误提示仍由字段组件与宿主服务负责。

收集物料定义

贯穿项目从同一组 MaterialDefinition 生成 Designer 的全部物料能力：

export { ColumnContainerWidget } from './container'
export { FloatingActionWidget } from './floating-action'
export { NoticeWidget } from './notice'
export { GuidePageHeaderWidget } from './page-header'
export { GuideTextWidget } from './text'

这种组织避免分别维护注册表后发生 type 漂移。Schema 托管页头也在 materials 中，但不会出现在标准物料面板；它由初始 Schema 或导入数据提供。

绑定页面级配置

全局配置表单默认写入 globalConfig。页面背景属于页面 surface，因此使用显式 Schema 绑定：

import type { FormSchema } from '@dragcraft/designer'

export const guideGlobalConfigSchema: FormSchema = {
  sections: [{
    title: '页面设置',
    fields: [
      {
        key: 'title',
        label: '页面标题',
        component: 'Input',
        rules: [{ required: true, message: '页面标题不能为空' }],
      },
      {
        key: 'backgroundColor',
        label: '背景颜色',
        component: 'Input',
        bindTo: { scope: 'schema', path: 'root.style.surface.backgroundColor' },
      },
    ],
  }],
}

title 写入 globalConfig.title，backgroundColor 写入 root.style.surface.backgroundColor。不要为了从全局页签编辑背景色，就把页面视觉数据改存到 globalConfig。

字段提交后的路径是：

text

字段组件发出 adapter update event
  -> FormGenerator 更新和验证字段值
  -> Designer 解析默认绑定或 bindTo
  -> designer.execute(update-node | update-page | update-global-config)
  -> Authoring engine 提交 DocumentSchema 和 history
  -> Designer Presentation 读取新文档

验证结果

打开完整示例并执行以下操作：

拖入公告并修改文案。
打开“使用背景图”，确认资源字段出现。
选择示例背景图，再关闭开关；字段隐藏但原值仍保存在 Schema 中。
在全局配置中修改页面标题和背景色。
撤销背景色修改，确认页面 surface 恢复。

字段绑定、转换和验证的完整选择标准见表单与字段。

接入业务物料与属性配置 ​

定义带表单的业务物料 ​

注册业务字段 ​

收集物料定义 ​

绑定页面级配置 ​