@manohub/ui 0.7.0 → 0.8.0

package/dist/components/steps/index.d.ts

@@ -8,6 +8,12 @@ export interface StepsItem {
     icon?: IconName;
 }
 export type StepsVariant = 'node' | 'bar';
+/**
+ * 跳转验证：**能不能跳到第 `index` 步**（`current` 是当前步）。
+ *
+ * 不传即「全可跳」—— 件不猜业务规则，限制由调用方注入（如「只允许回退」= `i <= current`）。
+ */
+export type CanJump = (index: number, current: number) => boolean;
 /**
  * 步骤条（**自绘**；节点式 + 燕尾段式 + 进度条）。
  *
@@ -23,7 +29,28 @@ export type StepsVariant = 'node' | 'bar';
  * - `variant="node"`（缺省）：节点 + 同行标题 + 点线折角箭头，段长弹性 —— 步骤数少、要给每步留标题时用；
  * - `variant="bar"`：燕尾段条（定宽 140、相邻重叠 10），只有当前段是主色 —— 段数固定、像进度分段时用。
  *
- * 步骤条**不可点**（规范未演示跳步）：要跳转请在步骤旁自己放操作，或改用别的件。
+ * ## 可点档（`clickable`）
+ *
+ * 规范未演示跳步 ⇒ **缺省不可点**（连手型都不给；步的标签与类名也与老版本一致，只多一个
+ * `aria-current="step"` —— 那是当前步的语义标注，与可不可点无关）。要跳转就显式开
+ * `clickable`：步渲染成**原生 `<button>`**（键盘 / 焦点 / 禁用都交浏览器）。
+ *
+ * ### 「哪几步能跳」由调用方给（`canJump`）
+ *
+ * 本件**不猜业务规则**：`canJump` 缺省 `true`（每一步都可跳），要限制就注入一条判定：
+ *
+ * ```tsx
+ * <Steps clickable :can-jump="(index, current) => index <= current" … />
+ * ```
+ *
+ * 为什么不给内置的「前进最多一步 / 只允许后退」默认：向导的「往前走」几乎总带着前置校验
+ * （扫过了吗 / 风险确认了吗），而**步骤条上的点击不会跑那些校验** —— 件若自己放开一步，
+ * 就等于给了一条绕开门禁的旁路；可若定成「一律不许前进」，那又是替业务做了决定。
+ * 通用件该回答的是「能不能跳」，答案让调用方给。
+ *
+ * 本件**不给 `beforeChange` / `onBeforeChange` 一类的钩子**：它认 `current`（受控件），件本就不自己
+ * 换步，「跳转前验证」的落点是**渲染期的 `disabled`** —— 在事件里再判一次只会得到
+ * 「看着可点、点了没反应」这个更差的状态。
  *
  * 进度条（`Steps.Progress`）单列，用于"跑到百分之几"这类无步骤语义的场景。
  *
@@ -53,7 +80,43 @@ export declare const Steps: import("vue").DefineComponent<import("vue").ExtractP
         type: PropType<ControlSize>;
         default: string;
     };
-}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    /**
+     * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。
+     *
+     * 缺省 `false` —— 规范未演示跳步，件不凭空长交互。开了之后：
+     * - 步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环。
+     *   不要再靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持；
+     * - 「哪几步能跳」由 `canJump` 决定（缺省全可跳）；
+     * - 点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
+     *
+     * ⚠️ 「跳转前验证」写在**渲染期**（`disabled`），不要写成点击时的事件拦截 —— 见文件头。
+     */
+    clickable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步）。缺省全可跳。
+     *
+     * 返回 `false` 的步会被画成禁用态（置灰 + `not-allowed`）、拦掉点击、**也不进键盘序列** ——
+     * 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着可点、点了没反应」）。
+     * 需要异步验证才能决定能不能跳时，把结果先存进状态、再据此返回。
+     *
+     * ⚠️ 它只回答「能不能跳」。若某一步是「本身不可用」（不论从哪来），也用它统一表达 ——
+     * 本件不另设行级 `disabled`，免得同一条规则散在两处。
+     */
+    canJump: {
+        type: PropType<(index: number, current: number) => boolean>;
+        default: undefined;
+    };
+    /** 点击换步（`clickable` 档下生效）；`prevIndex` 为点击前的当前步 */
+    onChange: {
+        type: PropType<(index: number, prevIndex: number) => void>;
+        default: undefined;
+    };
+}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    'update:current': (index: number) => true;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
     /** 步骤表（标题 + 可选节点图标） */
     steps: {
         type: PropType<StepsItem[]>;
@@ -73,15 +136,55 @@ export declare const Steps: import("vue").DefineComponent<import("vue").ExtractP
         type: PropType<ControlSize>;
         default: string;
     };
-}>> & Readonly<{}>, {
+    /**
+     * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。
+     *
+     * 缺省 `false` —— 规范未演示跳步，件不凭空长交互。开了之后：
+     * - 步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环。
+     *   不要再靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持；
+     * - 「哪几步能跳」由 `canJump` 决定（缺省全可跳）；
+     * - 点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
+     *
+     * ⚠️ 「跳转前验证」写在**渲染期**（`disabled`），不要写成点击时的事件拦截 —— 见文件头。
+     */
+    clickable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步）。缺省全可跳。
+     *
+     * 返回 `false` 的步会被画成禁用态（置灰 + `not-allowed`）、拦掉点击、**也不进键盘序列** ——
+     * 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着可点、点了没反应」）。
+     * 需要异步验证才能决定能不能跳时，把结果先存进状态、再据此返回。
+     *
+     * ⚠️ 它只回答「能不能跳」。若某一步是「本身不可用」（不论从哪来），也用它统一表达 ——
+     * 本件不另设行级 `disabled`，免得同一条规则散在两处。
+     */
+    canJump: {
+        type: PropType<(index: number, current: number) => boolean>;
+        default: undefined;
+    };
+    /** 点击换步（`clickable` 档下生效）；`prevIndex` 为点击前的当前步 */
+    onChange: {
+        type: PropType<(index: number, prevIndex: number) => void>;
+        default: undefined;
+    };
+}>> & Readonly<{
+    "onUpdate:current"?: ((index: number) => any) | undefined;
+}>, {
     size: ControlSize;
+    onChange: (index: number, prevIndex: number) => void;
     variant: StepsVariant;
     current: number;
     steps: StepsItem[];
+    clickable: boolean;
+    canJump: (index: number, current: number) => boolean;
 }, SlotsType<{
     title?: (context: {
         item: StepsItem;
         index: number;
+        disabled: boolean;
     }) => VNodeChild;
 }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 export declare const StepsCompound: {
@@ -105,15 +208,57 @@ export declare const StepsCompound: {
             type: PropType<ControlSize>;
             default: string;
         };
-    }>> & Readonly<{}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, import("vue").PublicProps, {
+        /**
+         * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。
+         *
+         * 缺省 `false` —— 规范未演示跳步，件不凭空长交互。开了之后：
+         * - 步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环。
+         *   不要再靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持；
+         * - 「哪几步能跳」由 `canJump` 决定（缺省全可跳）；
+         * - 点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
+         *
+         * ⚠️ 「跳转前验证」写在**渲染期**（`disabled`），不要写成点击时的事件拦截 —— 见文件头。
+         */
+        clickable: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        /**
+         * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步）。缺省全可跳。
+         *
+         * 返回 `false` 的步会被画成禁用态（置灰 + `not-allowed`）、拦掉点击、**也不进键盘序列** ——
+         * 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着可点、点了没反应」）。
+         * 需要异步验证才能决定能不能跳时，把结果先存进状态、再据此返回。
+         *
+         * ⚠️ 它只回答「能不能跳」。若某一步是「本身不可用」（不论从哪来），也用它统一表达 ——
+         * 本件不另设行级 `disabled`，免得同一条规则散在两处。
+         */
+        canJump: {
+            type: PropType<(index: number, current: number) => boolean>;
+            default: undefined;
+        };
+        /** 点击换步（`clickable` 档下生效）；`prevIndex` 为点击前的当前步 */
+        onChange: {
+            type: PropType<(index: number, prevIndex: number) => void>;
+            default: undefined;
+        };
+    }>> & Readonly<{
+        "onUpdate:current"?: ((index: number) => any) | undefined;
+    }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+        'update:current': (index: number) => true;
+    }, import("vue").PublicProps, {
         size: ControlSize;
+        onChange: (index: number, prevIndex: number) => void;
         variant: StepsVariant;
         current: number;
         steps: StepsItem[];
+        clickable: boolean;
+        canJump: (index: number, current: number) => boolean;
     }, true, {}, SlotsType<{
         title?: (context: {
             item: StepsItem;
             index: number;
+            disabled: boolean;
         }) => VNodeChild;
     }>, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, {}, any, import("vue").ComponentProvideOptions, {
         P: {};
@@ -142,11 +287,50 @@ export declare const StepsCompound: {
             type: PropType<ControlSize>;
             default: string;
         };
-    }>> & Readonly<{}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, {
+        /**
+         * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。
+         *
+         * 缺省 `false` —— 规范未演示跳步，件不凭空长交互。开了之后：
+         * - 步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环。
+         *   不要再靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持；
+         * - 「哪几步能跳」由 `canJump` 决定（缺省全可跳）；
+         * - 点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
+         *
+         * ⚠️ 「跳转前验证」写在**渲染期**（`disabled`），不要写成点击时的事件拦截 —— 见文件头。
+         */
+        clickable: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        /**
+         * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步）。缺省全可跳。
+         *
+         * 返回 `false` 的步会被画成禁用态（置灰 + `not-allowed`）、拦掉点击、**也不进键盘序列** ——
+         * 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着可点、点了没反应」）。
+         * 需要异步验证才能决定能不能跳时，把结果先存进状态、再据此返回。
+         *
+         * ⚠️ 它只回答「能不能跳」。若某一步是「本身不可用」（不论从哪来），也用它统一表达 ——
+         * 本件不另设行级 `disabled`，免得同一条规则散在两处。
+         */
+        canJump: {
+            type: PropType<(index: number, current: number) => boolean>;
+            default: undefined;
+        };
+        /** 点击换步（`clickable` 档下生效）；`prevIndex` 为点击前的当前步 */
+        onChange: {
+            type: PropType<(index: number, prevIndex: number) => void>;
+            default: undefined;
+        };
+    }>> & Readonly<{
+        "onUpdate:current"?: ((index: number) => any) | undefined;
+    }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, {
         size: ControlSize;
+        onChange: (index: number, prevIndex: number) => void;
         variant: StepsVariant;
         current: number;
         steps: StepsItem[];
+        clickable: boolean;
+        canJump: (index: number, current: number) => boolean;
     }>;
     __isFragment?: never;
     __isTeleport?: never;
@@ -171,15 +355,57 @@ export declare const StepsCompound: {
         type: PropType<ControlSize>;
         default: string;
     };
-}>> & Readonly<{}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, {
+    /**
+     * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。
+     *
+     * 缺省 `false` —— 规范未演示跳步，件不凭空长交互。开了之后：
+     * - 步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环。
+     *   不要再靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持；
+     * - 「哪几步能跳」由 `canJump` 决定（缺省全可跳）；
+     * - 点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
+     *
+     * ⚠️ 「跳转前验证」写在**渲染期**（`disabled`），不要写成点击时的事件拦截 —— 见文件头。
+     */
+    clickable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步）。缺省全可跳。
+     *
+     * 返回 `false` 的步会被画成禁用态（置灰 + `not-allowed`）、拦掉点击、**也不进键盘序列** ——
+     * 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着可点、点了没反应」）。
+     * 需要异步验证才能决定能不能跳时，把结果先存进状态、再据此返回。
+     *
+     * ⚠️ 它只回答「能不能跳」。若某一步是「本身不可用」（不论从哪来），也用它统一表达 ——
+     * 本件不另设行级 `disabled`，免得同一条规则散在两处。
+     */
+    canJump: {
+        type: PropType<(index: number, current: number) => boolean>;
+        default: undefined;
+    };
+    /** 点击换步（`clickable` 档下生效）；`prevIndex` 为点击前的当前步 */
+    onChange: {
+        type: PropType<(index: number, prevIndex: number) => void>;
+        default: undefined;
+    };
+}>> & Readonly<{
+    "onUpdate:current"?: ((index: number) => any) | undefined;
+}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    'update:current': (index: number) => true;
+}, string, {
     size: ControlSize;
+    onChange: (index: number, prevIndex: number) => void;
     variant: StepsVariant;
     current: number;
     steps: StepsItem[];
+    clickable: boolean;
+    canJump: (index: number, current: number) => boolean;
 }, {}, string, SlotsType<{
     title?: (context: {
         item: StepsItem;
         index: number;
+        disabled: boolean;
     }) => VNodeChild;
 }>, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, import("vue").ComponentProvideOptions> & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps & {
     Progress: import("vue").DefineComponent<import("vue").ExtractPropTypes<{

package/dist/components/steps/index.js

@@ -1,4 +1,4 @@
-import { defineComponent, createVNode, Fragment } from "vue";
+import { defineComponent, computed, createVNode, mergeProps, Fragment } from "vue";
 import { Icon } from "@manohub/icon";
 const Steps = /* @__PURE__ */ defineComponent({
   name: "Steps",
@@ -22,27 +22,81 @@ const Steps = /* @__PURE__ */ defineComponent({
     size: {
       type: String,
       default: "md"
+    },
+    /**
+     * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。
+     *
+     * 缺省 `false` —— 规范未演示跳步，件不凭空长交互。开了之后：
+     * - 步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环。
+     *   不要再靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持；
+     * - 「哪几步能跳」由 `canJump` 决定（缺省全可跳）；
+     * - 点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
+     *
+     * ⚠️ 「跳转前验证」写在**渲染期**（`disabled`），不要写成点击时的事件拦截 —— 见文件头。
+     */
+    clickable: {
+      type: Boolean,
+      default: false
+    },
+    /**
+     * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步）。缺省全可跳。
+     *
+     * 返回 `false` 的步会被画成禁用态（置灰 + `not-allowed`）、拦掉点击、**也不进键盘序列** ——
+     * 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着可点、点了没反应」）。
+     * 需要异步验证才能决定能不能跳时，把结果先存进状态、再据此返回。
+     *
+     * ⚠️ 它只回答「能不能跳」。若某一步是「本身不可用」（不论从哪来），也用它统一表达 ——
+     * 本件不另设行级 `disabled`，免得同一条规则散在两处。
+     */
+    canJump: {
+      type: Function,
+      default: void 0
+    },
+    /** 点击换步（`clickable` 档下生效）；`prevIndex` 为点击前的当前步 */
+    onChange: {
+      type: Function,
+      default: void 0
     }
   },
+  emits: {
+    "update:current": (index) => true
+  },
   slots: Object,
   setup(props, {
     slots,
-    attrs
+    attrs,
+    emit
   }) {
+    const jumpable = computed(() => props.steps.map((_, index) => props.canJump?.(index, props.current) ?? true));
+    const selectStep = (index) => {
+      if (!jumpable.value[index]) return;
+      emit("update:current", index);
+      props.onChange?.(index, props.current);
+    };
+    const stepAction = (index) => props.clickable ? {
+      type: "button",
+      disabled: !jumpable.value[index],
+      onClick: () => selectStep(index)
+    } : {};
     return () => {
+      const PartTag = props.clickable ? "button" : props.variant === "bar" ? "span" : "div";
       const root = ["mh-steps", props.size === "md" ? "" : `mh-steps--${props.size}`, attrs.class].filter(Boolean).join(" ");
       const style = attrs.style;
       if (props.variant === "bar") {
         return createVNode("div", {
           "class": ["mh-steps__bar", attrs.class].filter(Boolean).join(" "),
           "style": style
-        }, [props.steps.map((step, index) => createVNode("span", {
+        }, [props.steps.map((step, index) => createVNode(PartTag, mergeProps({
           "key": `${step.title}-${index}`,
-          "class": ["mh-steps__seg", index === props.current ? "mh-steps__seg--active" : ""].filter(Boolean).join(" ")
-        }, [createVNode("span", null, [index + 1]), slots.title ? slots.title({
-          item: step,
-          index
-        }) : step.title]))]);
+          "class": ["mh-steps__seg", index === props.current ? "mh-steps__seg--active" : "", props.clickable ? "mh-steps__seg--clickable" : "", props.clickable && !jumpable.value[index] ? "mh-steps__seg--disabled" : ""].filter(Boolean).join(" "),
+          "aria-current": index === props.current ? "step" : void 0
+        }, stepAction(index)), {
+          default: () => [createVNode("span", null, [index + 1]), slots.title ? slots.title({
+            item: step,
+            index,
+            disabled: !jumpable.value[index]
+          }) : step.title]
+        }))]);
       }
       return createVNode("div", {
         "class": root,
@@ -57,24 +111,28 @@ const Steps = /* @__PURE__ */ defineComponent({
             // 连线在「步 index-1 之后」：当前步之后那一段才转蓝
             index - 1 === props.current ? "mh-steps__connector--active" : ""
           ].filter(Boolean).join(" ")
-        }, null) : null, createVNode("div", {
-          "class": ["mh-steps__step", state].filter(Boolean).join(" ")
-        }, [createVNode("span", {
-          "class": "mh-steps__node"
-        }, [index < props.current ? createVNode(Icon, {
-          "name": "check",
-          "class": "mh-steps__node-icon",
-          "size": 16
-        }, null) : step.icon ? createVNode(Icon, {
-          "name": step.icon,
-          "class": "mh-steps__node-icon",
-          "size": 16
-        }, null) : index + 1]), createVNode("span", {
-          "class": "mh-steps__title"
-        }, [slots.title ? slots.title({
-          item: step,
-          index
-        }) : step.title])])]);
+        }, null) : null, createVNode(PartTag, mergeProps({
+          "class": ["mh-steps__step", state, props.clickable ? "mh-steps__step--clickable" : "", props.clickable && !jumpable.value[index] ? "mh-steps__step--disabled" : ""].filter(Boolean).join(" "),
+          "aria-current": index === props.current ? "step" : void 0
+        }, stepAction(index)), {
+          default: () => [createVNode("span", {
+            "class": "mh-steps__node"
+          }, [index < props.current ? createVNode(Icon, {
+            "name": "check",
+            "class": "mh-steps__node-icon",
+            "size": 16
+          }, null) : step.icon ? createVNode(Icon, {
+            "name": step.icon,
+            "class": "mh-steps__node-icon",
+            "size": 16
+          }, null) : index + 1]), createVNode("span", {
+            "class": "mh-steps__title"
+          }, [slots.title ? slots.title({
+            item: step,
+            index,
+            disabled: !jumpable.value[index]
+          }) : step.title])]
+        })]);
       })]);
     };
   }

package/dist/components/switch/index.d.ts

@@ -13,8 +13,22 @@ import type { ControlSize } from '../control-size';
  * - 选中态三源等价：原生 `:checked` / 组件下发 `data-state` / 静态档 `.is-checked`；
  * - `labelPosition` 用 flex `order` 翻转，**不改 DOM 顺序** —— 否则那条 `~` 兄弟规则立刻失效。
  *
+ * ## 与 `Form.Item` 的关系（**同一个词别写两遍**）
+ *
+ * `label` 是**控件自己的文案** —— 它长在根 `<label>` 里，**点它也切换开关**；
+ * 而 `Form.Item` 的 `label` 是**字段名**（点它只是聚焦控件）。两者不是一回事。
+ *
+ * 所以放进表单行时**不要再传一次**：字段名归 `Form.Item`，开关只放控件本身。
+ *
+ * - 正确：`<Form.Item label="启用"><Switch v-model={on} /></Form.Item>`
+ * - 错误：`<Form.Item label="启用"><Switch v-model={on} label="启用" /></Form.Item>`
+ *   —— 同一行会显示成「启用 启用 （开关）」，同一个词出现两遍。
+ *
+ * 只有**没有表单行**的场合（表格行内 / 工具栏 / 设置面板）才需要 `label` 自己带文字；
+ * 那种场景若要把文字放到开关右侧，给 `labelPosition="right"`。
+ *
  * @example
- * <Switch modelValue={on} label="启用" onChange={(v) => (on = v)} />
+ * <Switch modelValue={on} onChange={(v) => (on = v)} />
  *
  * @example 轨道内文案 + 尺寸 + 加载
  * <Switch v-model={auto} checkedText="开" uncheckedText="关" size="lg" loading={saving} />
@@ -25,7 +39,12 @@ export declare const Switch: import("vue").DefineComponent<import("vue").Extract
         type: BooleanConstructor;
         default: boolean;
     };
-    /** 开关文字（复杂内容走默认插槽） */
+    /**
+     * 开关**自己的文案**（点它也切换；复杂内容走默认插槽）。
+     *
+     * ⚠️ 放进 `Form.Item` 时**不要传** —— 字段名由 `Form.Item` 的 `label` 给，
+     * 两处写同一个词会显示成「启用 启用 （开关）」。独立使用（表格行内 / 工具栏 / 设置面板）才用它。
+     */
     label: {
         type: StringConstructor;
         default: undefined;
@@ -44,7 +63,7 @@ export declare const Switch: import("vue").DefineComponent<import("vue").Extract
         type: BooleanConstructor;
         default: boolean;
     };
-    /** 文字相对开关的位置（缺省在左；表单里常放右） */
+    /** 文字相对开关的位置（缺省在左）—— 表单行内一般不传 `label`，这条主要服务独立使用的场景 */
     labelPosition: {
         type: PropType<"left" | "right">;
         default: string;
@@ -82,7 +101,12 @@ export declare const Switch: import("vue").DefineComponent<import("vue").Extract
         type: BooleanConstructor;
         default: boolean;
     };
-    /** 开关文字（复杂内容走默认插槽） */
+    /**
+     * 开关**自己的文案**（点它也切换；复杂内容走默认插槽）。
+     *
+     * ⚠️ 放进 `Form.Item` 时**不要传** —— 字段名由 `Form.Item` 的 `label` 给，
+     * 两处写同一个词会显示成「启用 启用 （开关）」。独立使用（表格行内 / 工具栏 / 设置面板）才用它。
+     */
     label: {
         type: StringConstructor;
         default: undefined;
@@ -101,7 +125,7 @@ export declare const Switch: import("vue").DefineComponent<import("vue").Extract
         type: BooleanConstructor;
         default: boolean;
     };
-    /** 文字相对开关的位置（缺省在左；表单里常放右） */
+    /** 文字相对开关的位置（缺省在左）—— 表单行内一般不传 `label`，这条主要服务独立使用的场景 */
     labelPosition: {
         type: PropType<"left" | "right">;
         default: string;

package/dist/components/switch/index.js

@@ -8,7 +8,12 @@ const Switch = /* @__PURE__ */ defineComponent({
       type: Boolean,
       default: false
     },
-    /** 开关文字（复杂内容走默认插槽） */
+    /**
+     * 开关**自己的文案**（点它也切换；复杂内容走默认插槽）。
+     *
+     * ⚠️ 放进 `Form.Item` 时**不要传** —— 字段名由 `Form.Item` 的 `label` 给，
+     * 两处写同一个词会显示成「启用 启用 （开关）」。独立使用（表格行内 / 工具栏 / 设置面板）才用它。
+     */
     label: {
       type: String,
       default: void 0
@@ -27,7 +32,7 @@ const Switch = /* @__PURE__ */ defineComponent({
       type: Boolean,
       default: false
     },
-    /** 文字相对开关的位置（缺省在左；表单里常放右） */
+    /** 文字相对开关的位置（缺省在左）—— 表单行内一般不传 `label`，这条主要服务独立使用的场景 */
     labelPosition: {
       type: String,
       default: "left"
@@ -76,6 +81,7 @@ const Switch = /* @__PURE__ */ defineComponent({
     };
     return () => createVNode("label", {
       "class": ["mh-switch", resolvedSize.value === "md" ? "" : `mh-switch--${resolvedSize.value}`, props.form ? "mh-switch--form" : "", hasTrackText.value ? "mh-switch--with-text" : "", props.labelPosition === "right" ? "mh-switch--label-right" : "", props.loading ? "is-loading" : "", props.disabled ? "is-disabled" : "", props.modelValue ? "is-checked" : "", attrs.class].filter(Boolean).join(" "),
+      "data-inline-control": "true",
       "style": attrs.style
     }, [createVNode("input", {
       "class": "mh-switch__input",