@tmagic/form 1.8.0-manmanyu.9 → 1.8.0

package/src/containers/Tabs.vue

@@ -70,6 +70,7 @@
         "
         :size="size"
         :label-width="tab.labelWidth || labelWidth"
+        :label-position="tab.labelPosition || labelPosition"
         :expand-more="expandMore"
         @change="changeHandler"
         @addDiffCount="onAddDiffCount(Number(tabIndex))"
@@ -85,6 +86,7 @@ import { isEmpty } from 'lodash-es';
 import { getDesignConfig, TMagicBadge } from '@tmagic/design';
 
 import type { ContainerChangeEventData, FormState, TabConfig, TabPaneConfig } from '../schema';
+import { applyMountValueEffects } from '../utils/collectFields';
 import { display as displayFunc, filterFunction, initValue } from '../utils/form';
 
 import Container from './Container.vue';
@@ -106,6 +108,7 @@ const props = withDefaults(
     name: string;
     size?: string;
     labelWidth?: string;
+    labelPosition?: 'top' | 'left' | 'right';
     prop?: string;
     expandMore?: boolean;
     disabled?: boolean;
@@ -203,6 +206,13 @@ const onTabAdd = async () => {
       prop: props.prop,
       config: props.config,
     });
+    // 自定义回调可能直接 push 原始对象；对现有标签页再规整一遍（effect 必须幂等）
+    const tabsModel = props.model[props.name];
+    if (Array.isArray(tabsModel) && Array.isArray(props.config.items)) {
+      for (const tab of tabsModel) {
+        applyMountValueEffects(mForm, props.config.items, tab);
+      }
+    }
     emit('change', props.model[props.name]);
   } else {
     const newObj = await initValue(mForm, {
@@ -210,6 +220,9 @@ const onTabAdd = async () => {
       initValues: {},
     });
 
+    // 新增标签页的值在挂到表单上之前先规整一遍，与整表初始化走同一份登记表
+    applyMountValueEffects(mForm, props.config.items, newObj);
+
     newObj.title = `标签${tabs.value.length + 1}`;
 
     props.model[props.name].push(newObj);

package/src/containers/table/ActionsColumn.vue

@@ -43,7 +43,7 @@ import { cloneDeep } from 'lodash-es';
 
 import { TMagicButton, TMagicTooltip } from '@tmagic/design';
 
-import type { FormState, TableConfig } from '../../schema';
+import type { FormState, TableConfig } from '@form/schema';
 
 const emit = defineEmits(['change']);
 

package/src/containers/table/Table.vue

@@ -8,13 +8,14 @@
     >
       <div class="m-fields-table" :class="{ 'm-fields-table-item-extra': config.itemExtra }">
         <span v-if="config.extra" style="color: rgba(0, 0, 0, 0.45)" v-html="config.extra"></span>
+        <!-- v-if 必须挂在 Tooltip 上：表格未就绪时 ElOnlyChild 会报 no valid child node found -->
         <TMagicTooltip
+          v-if="model[modelName]"
           content="拖拽可排序"
           placement="left-start"
           :disabled="config.dropSort !== true || config.dropSortHandle"
         >
           <TMagicTable
-            v-if="model[modelName]"
             ref="tMagicTable"
             style="width: 100%"
             show-header
@@ -27,6 +28,7 @@
             :key="updateKey"
             @select="selectHandle"
             @sort-change="sortChangeHandler"
+            :empty-text="`暂无${config.titlePrefix || ''}数据`"
           ></TMagicTable>
         </TMagicTooltip>
 
@@ -91,8 +93,8 @@ import { FullScreen } from '@element-plus/icons-vue';
 
 import { TMagicButton, TMagicPagination, TMagicTable, TMagicTooltip, TMagicUpload } from '@tmagic/design';
 
-import type { SortProp } from '../../schema';
-import { sortChange } from '../../utils/form';
+import type { SortProp } from '@form/schema';
+import { sortChange } from '@form/utils/form';
 
 import type { TableProps } from './type';
 import { useFullscreen } from './useFullscreen';

package/src/containers/table/usePagination.ts

@@ -1,6 +1,6 @@
 import { computed, type Ref, ref } from 'vue';
 
-import { getDataByPage } from '../../utils/form';
+import { getDataByPage } from '@form/utils/form';
 
 import type { TableProps } from './type';
 

package/src/containers/table/useSortable.ts

@@ -4,7 +4,7 @@ import type { default as SortableType, SortableEvent } from 'sortablejs';
 import { type TMagicTable } from '@tmagic/design';
 import type { FormState } from '@tmagic/form-schema';
 
-import { sortArray } from '../../utils/form';
+import { sortArray } from '@form/utils/form';
 
 import type { TableProps } from './type';
 

package/src/containers/table/useTableColumns.ts

@@ -1,12 +1,14 @@
 import { computed, h, inject, type Ref } from 'vue';
 import { WarningFilled } from '@element-plus/icons-vue';
-import { cloneDeep } from 'lodash-es';
 
 import { type TableColumnOptions, TMagicIcon, TMagicTooltip } from '@tmagic/design';
-import type { FormItemConfig, FormState, TableColumnConfig } from '@tmagic/form-schema';
+import type { FormItemConfig, FormState } from '@tmagic/form-schema';
+
+import type { ContainerChangeEventData } from '@form/schema';
+import { isGlobalFlat } from '@form/utils/config';
+import { appendProp, display as displayFunc, getDataByPage, sortArray } from '@form/utils/form';
+import { isTableColumnRendered, makeTableColumnConfig } from '@form/utils/tableGroupList';
 
-import type { ContainerChangeEventData } from '../../schema';
-import { display as displayFunc, getDataByPage, sortArray } from '../../utils/form';
 import Container from '../Container.vue';
 
 import ActionsColumn from './ActionsColumn.vue';
@@ -64,18 +66,7 @@ export const useTableColumns = (
     return props.config.selection;
   });
 
-  const getProp = (index: number) => {
-    return `${props.prop}${props.prop ? '.' : ''}${index + 1 + currentPage.value * pageSize.value - 1}`;
-  };
-
-  const makeConfig = (config: TableColumnConfig, row: any): TableColumnConfig => {
-    const newConfig = cloneDeep(config);
-    if (typeof config.itemsFunction === 'function') {
-      newConfig.items = config.itemsFunction(row);
-    }
-    delete newConfig.display;
-    return newConfig;
-  };
+  const getProp = (index: number) => appendProp(props.prop, index + currentPage.value * pageSize.value);
 
   const changeHandler = (v: any, eventData: ContainerChangeEventData) => {
     emit('change', props.model, eventData);
@@ -111,24 +102,26 @@ export const useTableColumns = (
         },
       });
     }
-
-    let actionFixed: 'left' | 'right' | undefined = props.config.fixed === false ? undefined : 'left';
-
+    const defaultFixed: 'left' | 'right' = isGlobalFlat.value ? 'right' : 'left';
+    let actionFixed: 'left' | 'right' | undefined = props.config.fixed === false ? undefined : defaultFixed;
     if (typeof props.config.fixed === 'string' && ['left', 'right'].includes(props.config.fixed)) {
       actionFixed = props.config.fixed;
     }
 
+    const actionFlat = props.config.flat === undefined && isGlobalFlat.value ? true : props.config.flat;
+
     const actionColumn = {
       props: {
         label: '操作',
         fixed: actionFixed,
+
         width: props.config.operateColWidth ?? (props.config.dropSortHandle && props.config.dropSort ? 132 : 112),
         align: 'center',
       },
       cell: ({ row, $index }: any) =>
         h(ActionsColumn, {
           row,
-          flat: props.config.flat,
+          flat: actionFlat,
           index: $index,
           model: props.model,
           config: props.config,
@@ -182,7 +175,7 @@ export const useTableColumns = (
     }
 
     for (const column of props.config.items) {
-      if (column.type !== 'hidden' && display(column.display)) {
+      if (isTableColumnRendered(column, display)) {
         const titleTipValue = titleTip(column.titleTip);
 
         columns.push({
@@ -200,7 +193,7 @@ export const useTableColumns = (
               disabled: props.disabled,
               prop: getProp($index),
               rules: column.rules,
-              config: makeConfig(column, row) as FormItemConfig,
+              config: makeTableColumnConfig(column, row) as FormItemConfig,
               model: row,
               lastValues: lastData.value[$index],
               isCompare: props.isCompare,

package/src/containers/table-group-list/TableGroupList.vue

@@ -12,6 +12,7 @@
     :last-values="lastValues"
     :prop="prop"
     :label-width="labelWidth"
+    :label-position="labelPosition"
     :show-index="showIndex"
     :sort-key="sortKey"
     :sort="sort"
@@ -20,13 +21,8 @@
     @addDiffCount="onAddDiffCount"
     @add="onAdd"
   >
-    <template #toggle-button>
-      <TMagicButton
-        v-if="config.enableToggleMode || enableToggleMode"
-        :icon="Grid"
-        size="small"
-        @click="toggleDisplayMode"
-      >
+    <template #toggle-button v-if="config.enableToggleMode || enableToggleMode">
+      <TMagicButton :icon="Grid" size="small" @click="toggleDisplayMode">
         {{ displayMode === 'table' ? '展开配置' : '切换为表格' }}
       </TMagicButton>
     </template>
@@ -35,19 +31,23 @@
       <TMagicButton
         :class="displayMode === 'table' ? 'm-form-table-add-button' : ''"
         :size="addButtonSize"
-        :plain="displayMode === 'table'"
         :icon="Plus"
-        text
         :disabled="disabled"
-        v-bind="currentConfig.addButtonConfig?.props || { type: 'primary' }"
-        @click="newHandler"
+        v-bind="addButtonProps"
+        @click="handleAdd"
       >
         {{
           currentConfig.addButtonConfig?.text ||
-          (displayMode === 'table' ? '新增一行' : `新增${groupListConfig.titlePrefix || ''}`)
+          (displayMode === 'table'
+            ? `新增一行${groupListConfig.titlePrefix || ''}`
+            : `新增${groupListConfig.titlePrefix || ''}`)
         }}
       </TMagicButton>
     </template>
+
+    <template #title="slotProps" v-if="$slots.title">
+      <slot name="title" v-bind="slotProps"></slot>
+    </template>
   </component>
 </template>
 
@@ -58,11 +58,14 @@ import { Grid, Plus } from '@element-plus/icons-vue';
 import { TMagicButton } from '@tmagic/design';
 import type { GroupListConfig, TableConfig } from '@tmagic/form-schema';
 
-import type { ContainerChangeEventData } from '../../schema';
+import type { ContainerChangeEventData } from '@form/schema';
+import { isGroupListType, toGroupListConfig, toTableConfig } from '@form/utils/tableGroupList';
+
 import MFormGroupList from '../GroupList.vue';
 import MFormTable from '../table/Table.vue';
 
 import { useAdd } from './useAdd';
+import { useScrollLastItemIntoView } from './useScrollLastItemIntoView';
 
 defineOptions({
   name: 'MFormTableGroupList',
@@ -77,6 +80,7 @@ const props = defineProps<{
   name: string;
   prop?: string;
   labelWidth?: string;
+  labelPosition?: 'top' | 'left' | 'right';
   disabled?: boolean;
   size?: string;
   enableToggleMode?: true;
@@ -89,88 +93,58 @@ const emit = defineEmits(['change', 'select', 'addDiffCount']);
 
 const { addable, newHandler } = useAdd(props, emit);
 
-const isGroupListType = (type: string | undefined) => type === 'groupList' || type === 'group-list';
-
 const displayMode = ref<'table' | 'groupList'>(isGroupListType(props.config.type) ? 'groupList' : 'table');
 
-const calcLabelWidth = (label: string) => {
-  if (!label) return '0px';
-  const zhLength = label.match(/[^\x00-\xff]/g)?.length || 0;
-  const chLength = label.length - zhLength;
-  return `${Math.max(chLength * 8 + zhLength * 20, 80)}px`;
-};
-
 // 当原始 config 是 table 形态时，table 模式直接透传；
-// 若原始是 groupList，则基于它派生出 table 所需的 config
-const tableConfig = computed<TableConfig>(() => {
-  if (!isGroupListType(props.config.type)) {
-    return props.config as TableConfig;
-  }
-
-  const source = props.config as GroupListConfig;
-  return {
-    ...props.config,
-    type: 'table',
-    groupItems: source.items,
-    items:
-      source.tableItems ||
-      (source.items as any[]).map((item: any) => ({
-        ...item,
-        label: item.label || item.text,
-        text: null,
-      })),
-  } as any as TableConfig;
-});
-
-// 反向派生 groupList 所需的 config
-const groupListConfig = computed<GroupListConfig>(() => {
-  if (isGroupListType(props.config.type)) {
-    return props.config as GroupListConfig;
-  }
+// 若原始是 groupList，则基于它派生出 table 所需的 config（反之同理）
+const tableConfig = computed<TableConfig>(() => toTableConfig(props.config));
 
-  const source = props.config as TableConfig;
-  return {
-    ...props.config,
-    type: 'groupList',
-    tableItems: source.items,
-    items:
-      source.groupItems ||
-      (source.items as any[]).map((item: any) => {
-        const text = item.text || item.label;
-        return {
-          ...item,
-          text,
-          labelWidth: calcLabelWidth(text),
-          span: item.span || 12,
-        };
-      }),
-  } as any as GroupListConfig;
-});
+const groupListConfig = computed<GroupListConfig>(() => toGroupListConfig(props.config));
 
 // 运行时类型由 displayMode 决定，`<component :is>` 无法做联合类型收窄，统一转 any 交给子组件处理
 const currentConfig = computed<any>(() => (displayMode.value === 'table' ? tableConfig.value : groupListConfig.value));
 
 // 保持原 Table/GroupList 模式下新增按钮的不同尺寸策略
 const addButtonSize = computed(() => {
+  if (currentConfig.value.addButtonConfig?.sticky) return 'default';
   if (displayMode.value === 'table') return 'small';
   return props.config.enableToggleMode !== false ? 'small' : 'default';
 });
 
+const addButtonProps = computed(() => {
+  const custom = currentConfig.value.addButtonConfig?.props;
+  if (custom) return { type: 'primary', ...custom };
+  if (displayMode.value === 'table') return { type: 'primary', plain: true };
+  return { type: 'primary', text: true };
+});
+
 const toggleDisplayMode = () => {
   displayMode.value = displayMode.value === 'table' ? 'groupList' : 'table';
 };
 
+const tableGroupListRef = useTemplateRef<InstanceType<typeof MFormTable>>('tableGroupList');
+
+const { scrollLastItemIntoView } = useScrollLastItemIntoView(
+  tableGroupListRef,
+  () => Boolean(currentConfig.value.scrollLastItemIntoView) && displayMode.value === 'groupList',
+);
+
+const handleAdd = async () => {
+  const expectedCount = await newHandler();
+  if (expectedCount !== null) await scrollLastItemIntoView(expectedCount);
+};
+
 const onChange = (v: any, eventData?: ContainerChangeEventData) => emit('change', v, eventData);
 const onSelect = (...args: any[]) => emit('select', ...args);
 const onAddDiffCount = () => emit('addDiffCount');
-const onAdd = (rows: any[]) => {
-  rows.forEach((row: any) => {
-    newHandler(row);
-  });
+const onAdd = async (rows: any[]) => {
+  let expectedCount: number | null = null;
+  for (const row of rows) {
+    expectedCount = (await newHandler(row)) ?? expectedCount;
+  }
+  if (expectedCount !== null) await scrollLastItemIntoView(expectedCount);
 };
 
-const tableGroupListRef = useTemplateRef<InstanceType<typeof MFormTable>>('tableGroupList');
-
 defineExpose({
   toggleRowSelection: (row: any, selected: boolean) => tableGroupListRef.value?.toggleRowSelection?.(row, selected),
 });

package/src/containers/table-group-list/useAdd.ts

@@ -3,7 +3,9 @@ import { computed, inject } from 'vue';
 import { tMagicMessage } from '@tmagic/design';
 import type { FormConfig, FormState, TableConfig, TableGroupListCommonConfig } from '@tmagic/form-schema';
 
-import { initValue } from '../../utils/form';
+import { applyMountValueEffects } from '@form/utils/collectFields';
+import { initValue } from '@form/utils/form';
+
 import type { TableProps } from '../table/type';
 
 export const useAdd = (
@@ -22,54 +24,63 @@ export const useAdd = (
 
     if (!modelName) return false;
 
-    if (!props.model[modelName]?.length) {
-      return true;
+    if (typeof props.config.addable === 'function') {
+      return Boolean(
+        props.config.addable(mForm, {
+          model: props.model[modelName],
+          formValue: mForm?.values,
+          prop: props.prop,
+          config: props.config,
+        }),
+      );
     }
 
-    if (typeof props.config.addable === 'function') {
-      return props.config.addable(mForm, {
-        model: props.model[modelName],
-        formValue: mForm?.values,
-        prop: props.prop,
-        config: props.config,
-      });
+    if (!props.model[modelName]?.length) {
+      return true;
     }
 
-    return typeof props.config.addable === 'undefined' ? true : props.config.addable;
+    return typeof props.config.addable === 'undefined' ? true : Boolean(props.config.addable);
   });
 
-  const newHandler = async (row?: any) => {
-    const modelName = props.name || props.config.name || '';
-
-    if (props.config.max && props.model[modelName].length >= props.config.max) {
+  /**
+   * 新增一项，返回新增后列表应有的长度；没有新增（超上限 / 被 beforeAddRow 拦下 / enum 用尽）返回 null。
+   *
+   * 只抛 change，不直接改 `props.model`：写回由 `MForm` 按 changeRecords 的 propPath 完成。
+   * 返回长度是给调用方用的——新项要等写回后才出现在 DOM 里，靠它才能判断等到了没有。
+   */
+  const newHandler = async (row?: any): Promise<number | null> => {
+    const modelName = `${props.name || props.config.name || ''}`;
+    const list: any[] = Array.isArray(props.model[modelName]) ? props.model[modelName] : [];
+
+    if (props.config.max && list.length >= props.config.max) {
       tMagicMessage.error(`最多新增配置不能超过${props.config.max}条`);
-      return;
+      return null;
     }
 
     if (typeof props.config.beforeAddRow === 'function') {
       const beforeCheckRes = await props.config.beforeAddRow(mForm, {
-        model: props.model[modelName],
+        model: list,
         formValue: mForm?.values,
         prop: props.prop,
       });
-      if (!beforeCheckRes) return;
+      if (!beforeCheckRes) return null;
     }
 
     const columns = props.config.items;
     const enumValues = props.config.enum || [];
     let enumV = [];
-    const { length } = props.model[modelName];
+    const { length } = list;
     const key = props.config.key || 'id';
     let inputs: any = {};
 
     if (enumValues.length) {
       if (length >= enumValues.length) {
-        return;
+        return null;
       }
       enumV = enumValues.filter((item) => {
         let i = 0;
         for (; i < length; i++) {
-          if (item[key] === props.model[modelName][i][key]) {
+          if (item[key] === list[i][key]) {
             break;
           }
         }
@@ -87,7 +98,7 @@ export const useAdd = (
     } else {
       if (typeof props.config.defaultAdd === 'function') {
         inputs = await props.config.defaultAdd(mForm, {
-          model: props.model[modelName],
+          model: list,
           prop: props.prop,
           formValue: mForm?.values,
         });
@@ -101,18 +112,22 @@ export const useAdd = (
       });
     }
 
+    // enum / Excel 导入的数组行与默认新增共用同一份规整，字段组件不再在 setup 里改 model
+    applyMountValueEffects(mForm, columns as FormConfig, inputs);
+
     if (props.sortKey && length) {
-      inputs[props.sortKey] = props.model[modelName][length - 1][props.sortKey] - 1;
+      inputs[props.sortKey] = list[length - 1][props.sortKey] - 1;
     }
 
-    emit('change', [...props.model[modelName], inputs], {
+    emit('change', [...list, inputs], {
       changeRecords: [
         {
-          propPath: `${props.prop}.${props.model[modelName].length}`,
+          propPath: `${props.prop}.${length}`,
           value: inputs,
         },
       ],
     });
+    return length + 1;
   };
 
   return {

package/src/containers/table-group-list/useScrollLastItemIntoView.ts

@@ -0,0 +1,94 @@
+import { nextTick, type Ref } from 'vue';
+
+type ListRef = Ref<{ $el?: unknown } | HTMLElement | null | undefined>;
+
+interface ScrollTarget {
+  root: HTMLElement;
+  last: HTMLElement | null;
+  count: number;
+}
+
+const nextFrame = () => new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+
+/** 滚动要用的列表根与最后一项；组件已卸载（宿主重建了整棵表单）时返回 null */
+const resolveScrollTarget = (listRef: ListRef): ScrollTarget | null => {
+  const inst = listRef.value;
+  const root = inst instanceof HTMLElement ? inst : inst?.$el;
+  if (!(root instanceof HTMLElement)) return null;
+
+  const items = root.querySelectorAll(':scope > .m-fields-group-list-item');
+  const last = items[items.length - 1];
+  return { root, last: last instanceof HTMLElement ? last : null, count: items.length };
+};
+
+/** 吸顶标题自身的高度：滚动后新项的标题不能被上一层标题压住 */
+const getStickyHeaderOffset = (item: HTMLElement): number => {
+  const header = item.querySelector(':scope > .el-card__header, :scope > .t-card__header');
+  if (!(header instanceof HTMLElement)) return 0;
+  return Number.parseFloat(getComputedStyle(header).top) || 0;
+};
+
+/** 吸底「新增」按钮盖住的高度；嵌套列表的 footer 还用 bottom 给外层按钮留了位 */
+const getStickyFooterOffset = (root: HTMLElement): number => {
+  const footer = root.querySelector(':scope > .m-fields-group-list-footer.is-sticky-full');
+  if (!(footer instanceof HTMLElement)) return 0;
+  return footer.getBoundingClientRect().height + (Number.parseFloat(getComputedStyle(footer).bottom) || 0);
+};
+
+/**
+ * 等列表渲染出至少 `expectedCount` 项、且最后一项的 DOM 节点连续两帧不变再返回。
+ *
+ * 新增只抛 change，写回要经过宿主（如编辑器属性面板）的异步校验与表单值重建，
+ * 新项不一定当帧就出现；期间宿主还可能自己再追加项，末尾节点会换掉。
+ * 只判「节点不变」会滚到旧的最后一项上，所以先等够数量再等稳定。
+ */
+const waitForStableTarget = async (
+  listRef: ListRef,
+  expectedCount: number,
+  timeout = 600,
+): Promise<ScrollTarget | null> => {
+  const deadline = Date.now() + timeout;
+  let previous: HTMLElement | null = null;
+
+  while (Date.now() < deadline) {
+    const target = resolveScrollTarget(listRef);
+    if (!target) return null;
+    if (target.count >= expectedCount && target.last && target.last === previous) return target;
+    previous = target.last;
+    await nextFrame();
+  }
+
+  return resolveScrollTarget(listRef);
+};
+
+/**
+ * 新增后把最后一项滚进视口，避开吸顶标题与吸底按钮。
+ *
+ * `enabled` 为 false（未开配置、或不在 group-list 形态）时直接返回。
+ */
+export const useScrollLastItemIntoView = (listRef: ListRef, enabled: () => boolean) => {
+  const scrollLastItemIntoView = async (expectedCount: number) => {
+    if (!enabled()) return;
+
+    // 先让已经同步写回的那部分渲染出来，稳定判定的第一帧就能拿到新项，少等一帧
+    await nextTick();
+
+    const target = await waitForStableTarget(listRef, expectedCount);
+    if (!target?.last) return;
+
+    const { root, last } = target;
+
+    // 新项是追加在末尾的，下方往往没有多余内容可滚，用 `start` 会被浏览器夹住、
+    // 仍压在吸底按钮下面。`nearest` 只滚到刚好露出，配合两侧 scroll-margin 避开吸顶标题与吸底按钮。
+    const top = getStickyHeaderOffset(last);
+    const bottom = getStickyFooterOffset(root);
+    last.style.scrollMarginTop = top ? `${top}px` : '';
+    last.style.scrollMarginBottom = bottom ? `${bottom}px` : '';
+
+    // 用瞬时定位而不是 smooth：平滑滚动要持续几百毫秒，期间宿主的回写重绘会把滚动位置改掉，
+    // 动画继续奔向旧目标，看起来就是「先弹回顶部再滚下来」。瞬时定位没有这个窗口。
+    last.scrollIntoView({ behavior: 'auto', block: 'nearest' });
+  };
+
+  return { scrollLastItemIntoView };
+};

package/src/fields/{CheckboxGroup.vue → CheckboxGroup/Index.vue}

@@ -11,9 +11,9 @@ import { computed, inject } from 'vue';
 
 import { TMagicCheckbox, TMagicCheckboxGroup } from '@tmagic/design';
 
-import type { CheckboxGroupConfig, CheckboxGroupOption, FieldProps, FormState } from '../schema';
-import { filterFunction } from '../utils/form';
-import { useAddField } from '../utils/useAddField';
+import type { CheckboxGroupConfig, CheckboxGroupOption, FieldProps, FormState } from '@form/schema';
+import { filterFunction } from '@form/utils/form';
+import { useAddField } from '@form/utils/useAddField';
 
 defineOptions({
   name: 'MFormCheckGroup',
@@ -25,11 +25,6 @@ const emit = defineEmits(['change']);
 
 useAddField(props.prop);
 
-// 初始化选项
-if (props.model && !props.model[props.name]) {
-  props.model[props.name] = [];
-}
-
 const changeHandler = (v: Array<string | number | boolean>) => {
   emit('change', v);
 };

package/src/fields/CheckboxGroup/effect.ts

@@ -0,0 +1,27 @@
+/*
+ * Tencent is pleased to support the open source community by making TMagicEditor available.
+ *
+ * Copyright (C) 2025 Tencent.  All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { FieldMountValueEffect } from '@form/utils/fieldValueEffects';
+
+/** 空值初始化为空数组。 */
+export const effect: FieldMountValueEffect = ({ config, model }) => {
+  const { name } = config as any;
+  if (model && !model[name]) {
+    model[name] = [];
+  }
+};