@tmagic/form 1.8.0-beta.22 → 1.8.0-beta.24

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.0-beta.22",
+  "version": "1.8.0-beta.24",
   "name": "@tmagic/form",
   "type": "module",
   "sideEffects": [
@@ -40,21 +40,21 @@
   "dependencies": {
     "@element-plus/icons-vue": "^2.3.2",
     "@popperjs/core": "^2.11.8",
-    "dayjs": "^1.11.19",
-    "lodash-es": "^4.17.21",
-    "sortablejs": "^1.15.6"
+    "dayjs": "^1.11.21",
+    "lodash-es": "^4.18.1",
+    "sortablejs": "^1.15.7"
   },
   "devDependencies": {
-    "@types/lodash-es": "^4.17.4",
+    "@types/lodash-es": "^4.17.12",
     "@types/sortablejs": "^1.15.9",
-    "@vue/test-utils": "^2.4.6"
+    "@vue/test-utils": "^2.4.11"
   },
   "peerDependencies": {
-    "vue": "^3.5.40",
     "typescript": "^6.0.3",
-    "@tmagic/utils": "1.8.0-beta.22",
-    "@tmagic/design": "1.8.0-beta.22",
-    "@tmagic/form-schema": "1.8.0-beta.22"
+    "vue": "^3.5.41",
+    "@tmagic/design": "1.8.0-beta.24",
+    "@tmagic/utils": "1.8.0-beta.24",
+    "@tmagic/form-schema": "1.8.0-beta.24"
   },
   "peerDependenciesMeta": {
     "typescript": {

package/src/containers/Container.vue

@@ -27,7 +27,15 @@
     <template v-else-if="type && display && !showDiff">
       <TMagicFormItem v-bind="formItemProps" :class="{ 'tmagic-form-hidden': `${itemLabelWidth}` === '0' || !text }">
         <template #label>
-          <slot name="label" :config="config" :type="type" :text="text" :prop="itemProp" :disabled="disabled">
+          <slot
+            v-if="shouldRenderLeafField"
+            name="label"
+            :config="config"
+            :type="type"
+            :text="text"
+            :prop="itemProp"
+            :disabled="disabled"
+          >
             <FormLabel
               :tip="config.tip"
               :type="type"
@@ -41,8 +49,25 @@
           </slot>
         </template>
 
-        <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
+        <!-- 静默校验时只保留 FormItem：校验依赖其 prop / rules 与 model 值，与字段组件实例无关 -->
+        <template v-if="shouldRenderLeafField">
+          <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
+            <component
+              v-bind="fieldsProps"
+              :is="tagName"
+              :model="model"
+              :last-values="lastValues"
+              :is-compare="isCompare"
+              @change="onChangeHandler"
+              @addDiffCount="onAddDiffCount"
+            ></component>
+            <template #content>
+              <div v-html="tooltip.text"></div>
+            </template>
+          </TMagicTooltip>
+
           <component
+            v-else
             v-bind="fieldsProps"
             :is="tagName"
             :model="model"
@@ -51,24 +76,13 @@
             @change="onChangeHandler"
             @addDiffCount="onAddDiffCount"
           ></component>
-          <template #content>
-            <div v-html="tooltip.text"></div>
-          </template>
-        </TMagicTooltip>
-
-        <component
-          v-else
-          v-bind="fieldsProps"
-          :is="tagName"
-          :model="model"
-          :last-values="lastValues"
-          :is-compare="isCompare"
-          @change="onChangeHandler"
-          @addDiffCount="onAddDiffCount"
-        ></component>
+        </template>
       </TMagicFormItem>
 
-      <TMagicTooltip v-if="config.tip && type === 'checkbox' && !(config as CheckboxConfig).useLabel" placement="top">
+      <TMagicTooltip
+        v-if="shouldRenderLeafField && config.tip && type === 'checkbox' && !(config as CheckboxConfig).useLabel"
+        placement="top"
+      >
         <TMagicIcon style="line-height: 40px; margin-left: 5px"><warning-filled /></TMagicIcon>
         <template #content>
           <div v-html="config.tip"></div>
@@ -88,7 +102,15 @@
         }"
       >
         <template #label>
-          <slot name="label" :config="config" :type="type" :text="text" :prop="itemProp" :disabled="disabled">
+          <slot
+            v-if="shouldRenderLeafField"
+            name="label"
+            :config="config"
+            :type="type"
+            :text="text"
+            :prop="itemProp"
+            :disabled="disabled"
+          >
             <FormLabel
               :tip="config.tip"
               :type="type"
@@ -98,8 +120,23 @@
             ></FormLabel>
           </slot>
         </template>
-        <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
+        <template v-if="shouldRenderLeafField">
+          <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
+            <component
+              v-bind="fieldsProps"
+              :is="tagName"
+              :model="model"
+              :last-values="lastValues"
+              :is-compare="isCompare"
+              @change="onChangeHandler"
+            ></component>
+            <template #content>
+              <div v-html="tooltip.text"></div>
+            </template>
+          </TMagicTooltip>
+
           <component
+            v-else
             v-bind="fieldsProps"
             :is="tagName"
             :model="model"
@@ -107,20 +144,7 @@
             :is-compare="isCompare"
             @change="onChangeHandler"
           ></component>
-          <template #content>
-            <div v-html="tooltip.text"></div>
-          </template>
-        </TMagicTooltip>
-
-        <component
-          v-else
-          v-bind="fieldsProps"
-          :is="tagName"
-          :model="model"
-          :last-values="lastValues"
-          :is-compare="isCompare"
-          @change="onChangeHandler"
-        ></component>
+        </template>
       </TMagicFormItem>
 
       <!-- 普通字段：渲染前后两份独立的组件用于对比 -->
@@ -131,7 +155,15 @@
           :class="{ 'tmagic-form-hidden': `${itemLabelWidth}` === '0' || !text, 'show-before-diff': true }"
         >
           <template #label>
-            <slot name="label" :config="config" :type="type" :text="text" :prop="itemProp" :disabled="disabled">
+            <slot
+              v-if="shouldRenderLeafField"
+              name="label"
+              :config="config"
+              :type="type"
+              :text="text"
+              :prop="itemProp"
+              :disabled="disabled"
+            >
               <FormLabel
                 :tip="config.tip"
                 :type="type"
@@ -141,23 +173,28 @@
               ></FormLabel>
             </slot>
           </template>
-          <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
-            <component v-bind="fieldsProps" :is="tagName" :model="lastValues" @change="onChangeHandler"></component>
-            <template #content>
-              <div v-html="tooltip.text"></div>
-            </template>
-          </TMagicTooltip>
-
-          <component
-            v-else
-            v-bind="fieldsProps"
-            :is="tagName"
-            :model="lastValues"
-            @change="onChangeHandler"
-          ></component>
+          <template v-if="shouldRenderLeafField">
+            <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
+              <component v-bind="fieldsProps" :is="tagName" :model="lastValues" @change="onChangeHandler"></component>
+              <template #content>
+                <div v-html="tooltip.text"></div>
+              </template>
+            </TMagicTooltip>
+
+            <component
+              v-else
+              v-bind="fieldsProps"
+              :is="tagName"
+              :model="lastValues"
+              @change="onChangeHandler"
+            ></component>
+          </template>
         </TMagicFormItem>
 
-        <TMagicTooltip v-if="config.tip && type === 'checkbox' && !(config as CheckboxConfig).useLabel" placement="top">
+        <TMagicTooltip
+          v-if="shouldRenderLeafField && config.tip && type === 'checkbox' && !(config as CheckboxConfig).useLabel"
+          placement="top"
+        >
           <TMagicIcon style="line-height: 40px; margin-left: 5px"><warning-filled /></TMagicIcon>
           <template #content>
             <div v-html="config.tip"></div>
@@ -171,7 +208,15 @@
           :class="{ 'tmagic-form-hidden': `${itemLabelWidth}` === '0' || !text, 'show-after-diff': true }"
         >
           <template #label>
-            <slot name="label" :config="config" :type="type" :text="text" :prop="itemProp" :disabled="disabled">
+            <slot
+              v-if="shouldRenderLeafField"
+              name="label"
+              :config="config"
+              :type="type"
+              :text="text"
+              :prop="itemProp"
+              :disabled="disabled"
+            >
               <FormLabel
                 :tip="config.tip"
                 :type="type"
@@ -181,17 +226,22 @@
               ></FormLabel>
             </slot>
           </template>
-          <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
-            <component v-bind="fieldsProps" :is="tagName" :model="model" @change="onChangeHandler"></component>
-            <template #content>
-              <div v-html="tooltip.text"></div>
-            </template>
-          </TMagicTooltip>
-
-          <component v-else v-bind="fieldsProps" :is="tagName" :model="model" @change="onChangeHandler"></component>
+          <template v-if="shouldRenderLeafField">
+            <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
+              <component v-bind="fieldsProps" :is="tagName" :model="model" @change="onChangeHandler"></component>
+              <template #content>
+                <div v-html="tooltip.text"></div>
+              </template>
+            </TMagicTooltip>
+
+            <component v-else v-bind="fieldsProps" :is="tagName" :model="model" @change="onChangeHandler"></component>
+          </template>
         </TMagicFormItem>
 
-        <TMagicTooltip v-if="config.tip && type === 'checkbox' && !(config as CheckboxConfig).useLabel" placement="top">
+        <TMagicTooltip
+          v-if="shouldRenderLeafField && config.tip && type === 'checkbox' && !(config as CheckboxConfig).useLabel"
+          placement="top"
+        >
           <TMagicIcon style="line-height: 40px; margin-left: 5px"><warning-filled /></TMagicIcon>
           <template #content>
             <div v-html="config.tip"></div>
@@ -260,9 +310,10 @@ import type {
   FormValue,
   ToolTipConfigType,
 } from '../schema';
-import { FORM_DIFF_CONFIG_KEY, FORM_TYPE_MATCH_VALID_KEY } from '../schema';
+import { FORM_DIFF_CONFIG_KEY, FORM_SILENT_MODE_KEY, FORM_TYPE_MATCH_VALID_KEY } from '../schema';
 import { getField } from '../utils/config';
 import { createObjectProp, display as displayFunction, filterFunction, getRules } from '../utils/form';
+import { getSilentLeafFieldTypes } from '../utils/silentLeafFieldTypes';
 
 import FormLabel from './FormLabel.vue';
 
@@ -407,6 +458,11 @@ const effectiveSelfDiffFieldTypes = computed<Set<string>>(() => {
 
 const isSelfDiffField = computed(() => effectiveSelfDiffFieldTypes.value.has(type.value));
 
+// 静默模式下仅白名单叶子字段跳过渲染；扩展字段通过 registerSilentLeafFieldTypes 注册
+const silentMode = inject(FORM_SILENT_MODE_KEY, false);
+
+const shouldRenderLeafField = computed(() => !silentMode || !getSilentLeafFieldTypes().has(type.value));
+
 const disabled = computed(() => props.disabled || filterFunction(mForm, props.config.disabled, props));
 
 const text = computed(() => filterFunction(mForm, props.config.text, props));

package/src/index.ts

@@ -63,12 +63,21 @@ export {
   registerField as registerFormField,
 } from './utils/config';
 
+export {
+  clearSilentLeafFieldTypes,
+  getSilentLeafFieldTypes,
+  registerSilentLeafFieldTypes,
+} from './utils/silentLeafFieldTypes';
+
 export {
   clearTypeMatchRules,
   deleteTypeMatchRule,
   getTypeMatchRule,
+  MAX_SUGGESTION_OPTIONS,
+  optionSuggestion,
   registerTypeMatchRule,
   registerTypeMatchRules,
+  stringifyExampleValue,
   validateTypeMatch,
 } from './utils/typeMatch';
 

package/src/schema.ts

@@ -32,11 +32,12 @@ export const FORM_TYPE_MATCH_VALID_KEY: InjectionKey<ComputedRef<boolean>> = Sym
 /**
  * 静默模式标记，由 `submitForm` / `validateForm` 以隐藏方式挂载临时表单时 provide（debug 弹层模式不提供）。
  *
- * 重型字段组件（如 vs-code）可 inject 该标记并跳过自身渲染：字段校验由 FormItem 基于 model 值完成，
- * 与叶子 UI 组件实例无关，跳过可省去无谓的实例化开销（如 monaco worker / model 的创建）。
+ * Container 会基于该标记，并对照 `getSilentLeafFieldTypes()`（默认 `LEAF_FIELD_TYPES`）
+ * 跳过叶子字段的渲染，只保留 FormItem：字段校验由 FormItem 基于 model 值完成，与叶子 UI 组件实例无关。
+ * 重型字段组件（如 vs-code）也可 inject 该标记跳过自身渲染，省去无谓的实例化开销。
  *
  * 注意：仅「挂载无值副作用」（不在 onMounted/watch immediate 中 emit change、不依赖 DOM 计算值）的
- * 字段组件可以安全跳过，接入前需逐一审计。
+ * 字段组件可以安全跳过，接入前需逐一审计；业务扩展请使用 `registerSilentLeafFieldTypes`。
  */
 export const FORM_SILENT_MODE_KEY: InjectionKey<boolean> = Symbol('mFormSilentMode');
 

package/src/utils/silentLeafFieldTypes.ts

@@ -0,0 +1,71 @@
+/*
+ * 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 { toLine } from '@tmagic/utils';
+
+/**
+ * 可在静默校验模式下跳过渲染的内置叶子字段（默认集合）。
+ *
+ * 这些字段只渲染一个输入控件，内部没有嵌套 FormItem，且不会依赖组件挂载修改 model；
+ * 字段值由初始化逻辑处理（包括 defaultValue），因此跳过不影响校验结果。
+ *
+ * 业务侧可通过 `registerSilentLeafFieldTypes` 追加已审计的安全自定义字段。
+ */
+export const LEAF_FIELD_TYPES: ReadonlySet<string> = new Set([
+  'text',
+  'textarea',
+  'number',
+  'time',
+  'daterange',
+  'timerange',
+  'checkbox',
+  'radio-group',
+  'switch',
+  'select',
+  'cascader',
+  'color-picker',
+  'link',
+]);
+
+/** 业务侧追加的静默叶子字段（不含内置默认集合） */
+const extraSilentLeafFieldTypes = new Set<string>();
+
+/**
+ * 注册可在静默校验中跳过渲染的叶子字段 type（追加到默认 `LEAF_FIELD_TYPES` 之上）。
+ *
+ * 仅应纳入「无嵌套 FormItem、无挂载值副作用」的字段；复合 / 动态子表单不可加入。
+ */
+export const registerSilentLeafFieldTypes = (types: Iterable<string>): void => {
+  for (const type of types) {
+    if (typeof type !== 'string' || !type) continue;
+    extraSilentLeafFieldTypes.add(toLine(type));
+  }
+};
+
+/** 当前生效的静默叶子字段集合：内置默认 ∪ 已注册扩展 */
+export const getSilentLeafFieldTypes = (): ReadonlySet<string> => {
+  if (extraSilentLeafFieldTypes.size === 0) {
+    return LEAF_FIELD_TYPES;
+  }
+  return new Set([...LEAF_FIELD_TYPES, ...extraSilentLeafFieldTypes]);
+};
+
+/** 清空业务侧追加的静默叶子字段（不影响内置默认集合；主要用于单测） */
+export const clearSilentLeafFieldTypes = (): void => {
+  extraSilentLeafFieldTypes.clear();
+};

package/src/utils/typeMatch.ts

@@ -135,7 +135,7 @@ const TIMESTAMP_VALUE_FORMATS = new Set(['x', 'timestamp']);
 /**
  * 将值格式化为可读的参考示例字符串。
  */
-const stringifyExampleValue = (value: any): string => {
+export const stringifyExampleValue = (value: any): string => {
   if (typeof value === 'string') return `"${value}"`;
   if (value === null || value === undefined) return String(value);
   if (typeof value === 'object') {
@@ -148,19 +148,23 @@ const stringifyExampleValue = (value: any): string => {
   return String(value);
 };
 
-// 参考建议中最多展示的可选值个数，超出以「等」省略。
-const MAX_SUGGESTION_OPTIONS = 20;
+/** 参考建议中可选值全量展示上限；超出时仅举例 EXAMPLE_SUGGESTION_COUNT 个并标明总数。 */
+export const MAX_SUGGESTION_OPTIONS = 20;
+const EXAMPLE_SUGGESTION_COUNT = 5;
 
 /**
- * 生成「请使用以下某一个值：xxx；xxx」形式的参考建议；无可选值时返回空字符串（不追加建议）。
- * 可选值超过 MAX_SUGGESTION_OPTIONS 个时仅展示前若干个并以「等」省略。
+ * 生成可选项参考建议；无可选值时返回空字符串（不追加建议）。
+ * 未超过 MAX_SUGGESTION_OPTIONS 时全部列举；超过时仅举例前 EXAMPLE_SUGGESTION_COUNT 个并标明总数，避免 AI 误以为仅有举例值合法。
  */
-const optionSuggestion = (optionValues: any[]): string => {
+export const optionSuggestion = (optionValues: any[]): string => {
   const values = optionValues.filter((item) => typeof item !== 'undefined');
   if (!values.length) return '';
-  const shown = values.slice(0, MAX_SUGGESTION_OPTIONS).map(stringifyExampleValue);
-  const suffix = values.length > MAX_SUGGESTION_OPTIONS ? ' 等' : '';
-  return `请使用以下某一个值：${shown.join('；')}${suffix}`;
+  const truncated = values.length > MAX_SUGGESTION_OPTIONS;
+  const shown = values.slice(0, truncated ? EXAMPLE_SUGGESTION_COUNT : values.length).map(stringifyExampleValue);
+  if (truncated) {
+    return `请从可选项中选用合法值（共 ${values.length} 个，例如：${shown.join('；')}）`;
+  }
+  return `请使用以下某一个值：${shown.join('；')}`;
 };
 
 /**