From 285434ef3effd94c51d3ed10198842f6e689046a Mon Sep 17 00:00:00 2001
From: roymondchen <roymondchen@tencent.com>
Date: Thu, 28 May 2026 16:45:11 +0800
Subject: [PATCH] =?UTF-8?q?feat(form):=20=E6=94=AF=E6=8C=81=E8=87=AA?=
 =?UTF-8?q?=E5=AE=9A=E4=B9=89=20label=20slot?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

在 MForm / Container 上新增具名作用域插槽 label，允许使用方自定义表单项标题渲染。
Slot 作用域参数：config、type、text、prop、disabled。
类型 FormLabelSlotProps / FormSlots 提取到 schema.ts 复用。
---
 packages/form/src/Form.vue                 | 18 ++++++-
 packages/form/src/containers/Container.vue | 57 +++++++++++++---------
 packages/form/src/schema.ts                | 21 ++++++++
 3 files changed, 72 insertions(+), 24 deletions(-)

diff --git a/packages/form/src/Form.vue b/packages/form/src/Form.vue
index a750a753..d3a73b04 100644
--- a/packages/form/src/Form.vue
+++ b/packages/form/src/Form.vue
@@ -22,7 +22,11 @@
         :step-active="stepActive"
         :size="size"
         @change="changeHandler"
-      ></Container>
+      >
+        <template v-if="$slots.label" #label="labelProps">
+          <slot name="label" v-bind="labelProps"></slot>
+        </template>
+      </Container>
     </template>
   </TMagicForm>
 </template>
@@ -37,12 +41,22 @@ import { setValueByKeyPath } from '@tmagic/utils';
 import Container from './containers/Container.vue';
 import { getConfig } from './utils/config';
 import { initValue } from './utils/form';
-import type { ChangeRecord, ContainerChangeEventData, FormConfig, FormState, FormValue, ValidateError } from './schema';
+import type {
+  ChangeRecord,
+  ContainerChangeEventData,
+  FormConfig,
+  FormSlots,
+  FormState,
+  FormValue,
+  ValidateError,
+} from './schema';
 
 defineOptions({
   name: 'MForm',
 });
 
+defineSlots<FormSlots>();
+
 const props = withDefaults(
   defineProps<{
     /** 表单配置 */
diff --git a/packages/form/src/containers/Container.vue b/packages/form/src/containers/Container.vue
index 7b2db891..9f0ac056 100644
--- a/packages/form/src/containers/Container.vue
+++ b/packages/form/src/containers/Container.vue
@@ -25,13 +25,15 @@
     <template v-else-if="type && display && !showDiff">
       <TMagicFormItem v-bind="formItemProps" :class="{ 'tmagic-form-hidden': `${itemLabelWidth}` === '0' || !text }">
         <template #label>
-          <FormLabel
-            :tip="config.tip"
-            :type="type"
-            :use-label="(config as CheckboxConfig).useLabel"
-            :label-title="config.labelTitle"
-            :text="text"
-          ></FormLabel>
+          <slot name="label" :config="config" :type="type" :text="text" :prop="itemProp" :disabled="disabled">
+            <FormLabel
+              :tip="config.tip"
+              :type="type"
+              :use-label="(config as CheckboxConfig).useLabel"
+              :label-title="config.labelTitle"
+              :text="text"
+            ></FormLabel>
+          </slot>
         </template>
 
         <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
@@ -77,13 +79,15 @@
         :class="{ 'tmagic-form-hidden': `${itemLabelWidth}` === '0' || !text, 'show-diff': true }"
       >
         <template #label>
-          <FormLabel
-            :tip="config.tip"
-            :type="type"
-            :use-label="(config as CheckboxConfig).useLabel"
-            :label-title="config.labelTitle"
-            :text="text"
-          ></FormLabel>
+          <slot name="label" :config="config" :type="type" :text="text" :prop="itemProp" :disabled="disabled">
+            <FormLabel
+              :tip="config.tip"
+              :type="type"
+              :use-label="(config as CheckboxConfig).useLabel"
+              :label-title="config.labelTitle"
+              :text="text"
+            ></FormLabel>
+          </slot>
         </template>
         <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
           <component v-bind="fieldsProps" :is="tagName" :model="lastValues" @change="onChangeHandler"></component>
@@ -109,13 +113,15 @@
         :class="{ 'tmagic-form-hidden': `${itemLabelWidth}` === '0' || !text, 'show-diff': true }"
       >
         <template #label>
-          <FormLabel
-            :tip="config.tip"
-            :type="type"
-            :use-label="(config as CheckboxConfig).useLabel"
-            :label-title="config.labelTitle"
-            :text="text"
-          ></FormLabel>
+          <slot name="label" :config="config" :type="type" :text="text" :prop="itemProp" :disabled="disabled">
+            <FormLabel
+              :tip="config.tip"
+              :type="type"
+              :use-label="(config as CheckboxConfig).useLabel"
+              :label-title="config.labelTitle"
+              :text="text"
+            ></FormLabel>
+          </slot>
         </template>
         <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
           <component v-bind="fieldsProps" :is="tagName" :model="model" @change="onChangeHandler"></component>
@@ -152,7 +158,11 @@
           :prop="itemProp"
           @change="onChangeHandler"
           @addDiffCount="onAddDiffCount"
-        ></Container>
+        >
+          <template v-if="$slots.label" #label="labelProps">
+            <slot name="label" v-bind="labelProps"></slot>
+          </template>
+        </Container>
       </template>
     </template>
 
@@ -179,6 +189,7 @@ import type {
   ContainerChangeEventData,
   ContainerCommonConfig,
   FormItemConfig,
+  FormSlots,
   FormState,
   FormValue,
   ToolTipConfigType,
@@ -192,6 +203,8 @@ defineOptions({
   name: 'MFormContainer',
 });
 
+defineSlots<FormSlots>();
+
 const props = withDefaults(
   defineProps<{
     /** 表单值 */
diff --git a/packages/form/src/schema.ts b/packages/form/src/schema.ts
index 60f3f942..c771644d 100644
--- a/packages/form/src/schema.ts
+++ b/packages/form/src/schema.ts
@@ -1,3 +1,5 @@
+import type { FormItemConfig } from '@tmagic/form-schema';
+
 export * from '@tmagic/form-schema';
 
 export interface ValidateError {
@@ -14,3 +16,22 @@ export interface ContainerChangeEventData {
   modifyKey?: string;
   changeRecords?: ChangeRecord[];
 }
+
+/** 自定义 label slot 的作用域参数 */
+export interface FormLabelSlotProps {
+  /** 当前表单项配置 */
+  config: FormItemConfig;
+  /** 经处理后的类型 */
+  type: string;
+  /** 经 filterFunction 处理后的 label 文案 */
+  text?: string;
+  /** 完整字段路径（包含父级前缀） */
+  prop: string;
+  /** 经 filterFunction 处理后的最终禁用状态 */
+  disabled?: boolean;
+}
+
+/** Form / Container 暴露的具名 slot 定义 */
+export interface FormSlots {
+  label(_props: FormLabelSlotProps): any;
+}