n-design-readonly-plugin 1.0.0

package/.gitignore

@@ -0,0 +1,31 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+.DS_Store
+dist
+dist-ssr
+coverage
+*.local
+package-lock.json
+report.html
+
+/cypress/videos/
+/cypress/screenshots/
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
+.idea
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/README.md

@@ -0,0 +1,89 @@
+# n-design-readonly-plugin
+
+[![npm version](https://img.shields.io/npm/v/n-design-readonly-plugin?color=blue)](https://www.npmjs.com/package/n-design-readonly-plugin)
+[![npm downloads](https://img.shields.io/npm/dm/n-design-readonly-plugin)](https://www.npmjs.com/package/n-design-readonly-plugin)
+[![License](https://img.shields.io/npm/l/n-design-readonly-plugin)](LICENSE)
+
+> 一个 Vue 3 高阶组件（HOC），用于将 `n-designv3` 表单组件一键切换为只读模式。
+
+在业务系统中，经常需要在「编辑态」和「详情态」之间切换。本插件通过 `:readonly="true"` 全局控制或组件级控制，自动将 `<NkInput>`、`<NkSelect>` 等组件渲染为不可编辑的静态文本，无需重复编写展示逻辑。
+
+## ✨ 特性
+
+- ✅ 支持 `n-designv3` 所有表单组件（`Input`, `Select`, `DatePicker` 等）
+- ✅ 全局控制：通过 `<NkForm :readonly="true">` 一键禁用整个表单
+- ✅ 组件级控制：单个组件设置 `:readonly="true"`
+- ✅ 自动提取显示文本（支持 `label` / `value` 映射）
+- ✅ 完整 TypeScript 类型支持
+- ✅ 零运行时依赖（仅依赖 `vue` 和 `n-designv3`）
+
+## 📦 安装
+
+```bash
+npm install n-design-readonly-plugin
+```
+
+## 1.全局注册插件
+```ts
+// main.ts
+import { createApp } from 'vue';
+import App from './App.vue';
+
+// 引入 n-designv3（必须）
+import NDesignV3 from 'n-designv3';
+import 'n-designv3/dist/style.css';
+
+// 引入本插件
+import { NkReadonlyPlugin } from 'nk-readonly-hoc';
+
+const app = createApp(App);
+app.use(NDesignV3);
+app.use(NkReadonlyPlugin); // 注册后自动提供 NkInput, NkSelect 等组件
+app.mount('#app');
+
+```
+
+## 2.在模板中使用
+### 全局只读（推荐）
+```vue
+<template>
+  <nk-form :readonly="isReadonly" :model="form">
+    <nk-form-item label="用户名">
+      <nk-input v-model:value="form.name" />
+    </nk-form-item>
+    <nk-form-item label="城市">
+      <nk-select
+        v-model:value="form.city"
+        :options="cityOptions"
+      />
+    </nk-form-item>
+  </nk-form>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+
+const isReadonly = ref(true);
+const form = reactive({ name: '张三', city: 'bj' });
+const cityOptions = [
+  { label: '北京', value: 'bj' },
+  { label: '上海', value: 'sh' }
+];
+</script>
+```
+
+## 3.组件映射
+| 原始组件 (`n-designv3`) | 只读包装组件 |
+|------------------------|-------------|
+| `<n-input>`            | `<nk-input>` |
+| `<n-select>`           | `<nk-select>` |
+| `<n-date-picker>`      | `<nk-date-picker>` |
+| ...                    | ... |
+
+所有 n-* 表单组件均自动映射为 nk-*，命名规则一致。
+
+## 4.工作原理
+插件内部使用 provide/inject 传递 readonly 上下文
+每个 nk-* 组件是 withReadonly(WrappedComponent) 的高阶封装
+当 readonly === true 时，不再渲染原始组件，而是渲染一个带样式的 <span> 显示文本
+文本内容通过智能解析 value + options 自动获取（如 Select 的 label）

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { Plugin } from 'vue';
+import { withReadonly } from './withReadonly';
+export declare const NkReadonlyPlugin: Plugin;
+export { withReadonly };

package/dist/index.mjs

@@ -0,0 +1,243 @@
+import { defineComponent as E, inject as B, ref as T, computed as w, provide as U, useAttrs as z, h as j } from "vue";
+import { Form as K, Checkbox as O, Radio as N, Select as M, Switch as q, TimePicker as J, DatePicker as Q, Cascader as W, TreeSelect as X, Textarea as Y, InputNumber as Z, Input as _ } from "n-designv3";
+function A(e) {
+  if (e == null) return "";
+  if (typeof e == "string") return e;
+  if (Array.isArray(e)) return e.map(A).join("");
+  if (typeof e == "object") {
+    if (typeof e.children == "string")
+      return e.children;
+    if (e?.default && typeof e.default == "function") {
+      const n = e.default();
+      if (Array.isArray(n))
+        return A(n);
+    }
+    e.children && A(e.children);
+  }
+  return "";
+}
+function P(e, n = {}) {
+  const t = /* @__PURE__ */ new Map(), { value: l = "value", label: c = "label" } = n;
+  if (!e) return t;
+  const s = Array.isArray(e) ? e : [e];
+  for (const r of s)
+    if (!(!r || typeof r != "object")) {
+      if (r.type && (typeof r.type == "object" || typeof r.type == "function")) {
+        let u = r.type.name?.toLowerCase() || "";
+        if (typeof r.type == "function" ? u = r.type.displayName?.toLowerCase() || "" : typeof r.type == "string" && (u = r.type?.toLowerCase() || ""), /option|radio|checkbox/i.test(u)) {
+          const o = r.props || {}, a = o[l] ?? o.value, f = o[c] ?? o.label;
+          if (a != null) {
+            const x = A(r.children) || f || String(a);
+            t.set(a, x);
+          }
+        }
+      }
+      r.children && P(r.children, n).forEach((o, a) => {
+        t.has(a) || t.set(a, o);
+      });
+    }
+  return t;
+}
+function V(e, n, t) {
+  const { value: l = "value", label: c = "label", children: s = "children" } = t, r = [];
+  let u = e;
+  for (const o of n) {
+    const a = u.find((f) => f[l] === o);
+    if (a)
+      r.push(a[c] || a[l] || String(o)), u = a[s] || [];
+    else {
+      r.push(String(o));
+      break;
+    }
+  }
+  return r;
+}
+function ee(e, n, t) {
+  const { value: l = "value", label: c = "title", children: s = "children" } = t, r = [], u = new Set(Array.isArray(n) ? n : [n]);
+  function o(a) {
+    for (const f of a)
+      u.has(f[l]) && r.push(f[c] || f[l]), f[s] && o(f[s]);
+  }
+  return o(e), r;
+}
+function te({
+  modelValue: e,
+  options: n,
+  treeData: t,
+  valueToLabel: l,
+  fieldNames: c,
+  slots: s,
+  isSelect: r,
+  isRadioGroup: u,
+  isCheckboxGroup: o,
+  isCheckbox: a,
+  isRadio: f,
+  isCascader: x,
+  isTreeSelect: m,
+  isSwitch: R,
+  attrs: d,
+  emptyText: b
+}) {
+  if (l)
+    try {
+      return l(e) || b;
+    } catch (i) {
+      console.warn("[ReadonlyHOC] valueToLabel error", i);
+    }
+  if (R) {
+    const i = d.checkedValue ?? d["checked-value"] ?? !0, y = d.uncheckedValue ?? d["un-checked-value"] ?? !1;
+    return e === i ? d.checkedChildren ?? d["checked-children"] ?? "开启" : e === y ? d.uncheckedChildren ?? d["un-checked-children"] ?? "关闭" : String(e || b);
+  }
+  if (x && Array.isArray(e) && n?.length)
+    return V(n, e, c).join(" / ") || b;
+  if (m && t?.length)
+    return ee(t, e, c).join(", ") || b;
+  if (n?.length) {
+    const i = c.value || "value", y = c.label || "label", g = (v) => {
+      const C = n.find((k) => k[i] === v);
+      return C ? C[y] || C[i] : v == null ? "" : String(v);
+    };
+    return Array.isArray(e) ? e.map(g).join(", ") || b : g(e) || b;
+  } else if ((r || u || o) && s?.default)
+    try {
+      const i = s.default(), y = P(i, c);
+      if (y.size > 0) {
+        const g = (v) => v == null ? "" : y.get(v) || String(v);
+        return Array.isArray(e) ? e.map(g).join(", ") || b : g(e) || b;
+      }
+    } catch (i) {
+      console.warn("[ReadonlyHOC] Failed to parse slot options", i);
+    }
+  else if (s?.default && (a || f) && typeof e == "boolean")
+    try {
+      const i = s.default(), y = A(i);
+      if (y) return y;
+    } catch {
+    }
+  return e == null || e === "" ? b : Array.isArray(e) ? e.join(", ") : String(e);
+}
+function re(e) {
+  const n = e.name || "", t = n.toLowerCase(), l = /select/i.test(t) && !/tree|cascader/i.test(t), c = /radio/i.test(t) && !/group/i.test(t), s = /radio.*group/i.test(t), r = /checkbox/i.test(t) && !/group/i.test(t), u = /checkbox.*group/i.test(t), o = /switch/i.test(t), a = /cascader/i.test(t), f = /tree.*select/i.test(t), m = r || o || c ? "checked" : "value", R = `update:${m}`, d = /form$/i.test(t), b = /form.*item/i.test(t);
+  return E({
+    name: n,
+    inheritAttrs: !1,
+    props: {
+      modelValue: { type: [String, Number, Boolean, Array, Object], default: void 0 },
+      [m]: { type: [String, Number, Boolean, Array, Object], default: void 0 },
+      readonly: { type: Boolean, default: void 0 },
+      emptyText: { type: String, default: "--" },
+      valueToLabel: { type: Function, default: null }
+    },
+    emits: ["update:modelValue", R],
+    setup(i, { emit: y, slots: g, expose: v }) {
+      const C = B("nkReadonly", T(!1)), k = w(() => i.readonly ?? C.value), F = w(() => i.readonly ?? C.value);
+      d && U("nkReadonly", F);
+      const L = w(() => i[m] !== void 0 ? i[m] : i.modelValue), G = (h) => {
+        y("update:modelValue", h), y(R, h);
+      }, p = z(), I = w(() => {
+        if (!k.value) return "";
+        const h = p.fieldNames ?? p["field-names"] ?? {}, $ = p.options, D = p.treeData ?? p["tree-data"];
+        return te({
+          modelValue: L.value,
+          options: $,
+          treeData: D,
+          valueToLabel: i.valueToLabel,
+          fieldNames: h,
+          slots: g,
+          isSelect: l,
+          isRadioGroup: s,
+          isCheckboxGroup: u,
+          isCheckbox: r,
+          isRadio: c,
+          isCascader: a,
+          isTreeSelect: f,
+          isSwitch: o,
+          attrs: p,
+          emptyText: i.emptyText
+        });
+      }), H = {
+        lineHeight: "32px",
+        padding: "0 6px",
+        display: "inline-block",
+        minHeight: "32px",
+        border: "none",
+        backgroundColor: "none",
+        cursor: "default",
+        wordBreak: "break-all",
+        color: "rgba(0, 0, 0, 0.65)"
+      }, S = T();
+      return d && v({
+        validate: () => k.value ? Promise.resolve({}) : S.value?.validate?.(),
+        validateFields: (h) => k.value ? Promise.resolve({}) : S.value?.validateFields?.(h),
+        resetFields: (h) => !k.value && S.value?.resetFields?.(h),
+        clearValidate: (h) => !k.value && S.value?.clearValidate?.(h),
+        scrollToField: (h) => !k.value && S.value?.scrollToField?.(h)
+      }), () => b ? j(
+        e,
+        {
+          ...p,
+          style: { ...p.style || {}, marginBottom: k.value ? "10px" : void 0 }
+        },
+        g
+      ) : d ? j(
+        e,
+        {
+          ...p,
+          rules: F.value ? null : p.rules,
+          disabled: F.value ? !0 : p.disabled,
+          ref: S
+        },
+        g
+      ) : k.value ? j(
+        "span",
+        {
+          class: "nk-readonly-wrapper",
+          style: H,
+          role: "text",
+          tabindex: 0,
+          "aria-readonly": "true"
+        },
+        I.value
+      ) : j(
+        e,
+        {
+          ...p,
+          [m]: L.value,
+          [`onUpdate:${m}`]: G,
+          ref: d ? S : void 0
+        },
+        g
+      );
+    }
+  });
+}
+const ne = {
+  Input: _,
+  InputNumber: Z,
+  Textarea: Y,
+  Select: M,
+  SelectOption: M.Option,
+  TreeSelect: X,
+  Cascader: W,
+  DatePicker: Q,
+  TimePicker: J,
+  Radio: N,
+  Checkbox: O,
+  RadioGroup: N.Group,
+  CheckboxGroup: O.Group,
+  Switch: q,
+  Form: K,
+  FormItem: K.Item
+}, ae = {
+  install(e) {
+    for (const [n, t] of Object.entries(ne))
+      if (t) {
+        const l = re(t);
+        e.component(`Nk${n}`, l);
+      }
+  }
+};
+export {
+  ae as NkReadonlyPlugin,
+  re as withReadonly
+};

package/dist/index.umd.js

@@ -0,0 +1 @@
+(function(A,o){typeof exports=="object"&&typeof module<"u"?o(exports,require("vue"),require("n-designv3")):typeof define=="function"&&define.amd?define(["exports","vue","n-designv3"],o):(A=typeof globalThis<"u"?globalThis:A||self,o(A.NDesignReadolyPlugin={},A.Vue,A.nDesignv3))})(this,(function(A,o,c){"use strict";function w(e){if(e==null)return"";if(typeof e=="string")return e;if(Array.isArray(e))return e.map(w).join("");if(typeof e=="object"){if(typeof e.children=="string")return e.children;if(e?.default&&typeof e.default=="function"){const n=e.default();if(Array.isArray(n))return w(n)}e.children&&w(e.children)}return""}function L(e,n={}){const t=new Map,{value:s="value",label:u="label"}=n;if(!e)return t;const d=Array.isArray(e)?e:[e];for(const r of d)if(!(!r||typeof r!="object")){if(r.type&&(typeof r.type=="object"||typeof r.type=="function")){let f=r.type.name?.toLowerCase()||"";if(typeof r.type=="function"?f=r.type.displayName?.toLowerCase()||"":typeof r.type=="string"&&(f=r.type?.toLowerCase()||""),/option|radio|checkbox/i.test(f)){const a=r.props||{},l=a[s]??a.value,y=a[u]??a.label;if(l!=null){const j=w(r.children)||y||String(l);t.set(l,j)}}}r.children&&L(r.children,n).forEach((a,l)=>{t.has(l)||t.set(l,a)})}return t}function O(e,n,t){const{value:s="value",label:u="label",children:d="children"}=t,r=[];let f=e;for(const a of n){const l=f.find(y=>y[s]===a);if(l)r.push(l[u]||l[s]||String(a)),f=l[d]||[];else{r.push(String(a));break}}return r}function K(e,n,t){const{value:s="value",label:u="title",children:d="children"}=t,r=[],f=new Set(Array.isArray(n)?n:[n]);function a(l){for(const y of l)f.has(y[s])&&r.push(y[u]||y[s]),y[d]&&a(y[d])}return a(e),r}function M({modelValue:e,options:n,treeData:t,valueToLabel:s,fieldNames:u,slots:d,isSelect:r,isRadioGroup:f,isCheckboxGroup:a,isCheckbox:l,isRadio:y,isCascader:j,isTreeSelect:R,isSwitch:F,attrs:p,emptyText:m}){if(s)try{return s(e)||m}catch(i){console.warn("[ReadonlyHOC] valueToLabel error",i)}if(F){const i=p.checkedValue??p["checked-value"]??!0,h=p.uncheckedValue??p["un-checked-value"]??!1;return e===i?p.checkedChildren??p["checked-children"]??"开启":e===h?p.uncheckedChildren??p["un-checked-children"]??"关闭":String(e||m)}if(j&&Array.isArray(e)&&n?.length)return O(n,e,u).join(" / ")||m;if(R&&t?.length)return K(t,e,u).join(", ")||m;if(n?.length){const i=u.value||"value",h=u.label||"label",g=S=>{const T=n.find(C=>C[i]===S);return T?T[h]||T[i]:S==null?"":String(S)};return Array.isArray(e)?e.map(g).join(", ")||m:g(e)||m}else if((r||f||a)&&d?.default)try{const i=d.default(),h=L(i,u);if(h.size>0){const g=S=>S==null?"":h.get(S)||String(S);return Array.isArray(e)?e.map(g).join(", ")||m:g(e)||m}}catch(i){console.warn("[ReadonlyHOC] Failed to parse slot options",i)}else if(d?.default&&(l||y)&&typeof e=="boolean")try{const i=d.default(),h=w(i);if(h)return h}catch{}return e==null||e===""?m:Array.isArray(e)?e.join(", "):String(e)}function P(e){const n=e.name||"",t=n.toLowerCase(),s=/select/i.test(t)&&!/tree|cascader/i.test(t),u=/radio/i.test(t)&&!/group/i.test(t),d=/radio.*group/i.test(t),r=/checkbox/i.test(t)&&!/group/i.test(t),f=/checkbox.*group/i.test(t),a=/switch/i.test(t),l=/cascader/i.test(t),y=/tree.*select/i.test(t),R=r||a||u?"checked":"value",F=`update:${R}`,p=/form$/i.test(t),m=/form.*item/i.test(t);return o.defineComponent({name:n,inheritAttrs:!1,props:{modelValue:{type:[String,Number,Boolean,Array,Object],default:void 0},[R]:{type:[String,Number,Boolean,Array,Object],default:void 0},readonly:{type:Boolean,default:void 0},emptyText:{type:String,default:"--"},valueToLabel:{type:Function,default:null}},emits:["update:modelValue",F],setup(i,{emit:h,slots:g,expose:S}){const T=o.inject("nkReadonly",o.ref(!1)),C=o.computed(()=>i.readonly??T.value),v=o.computed(()=>i.readonly??T.value);p&&o.provide("nkReadonly",v);const N=o.computed(()=>i[R]!==void 0?i[R]:i.modelValue),H=k=>{h("update:modelValue",k),h(F,k)},b=o.useAttrs(),$=o.computed(()=>{if(!C.value)return"";const k=b.fieldNames??b["field-names"]??{},q=b.options,B=b.treeData??b["tree-data"];return M({modelValue:N.value,options:q,treeData:B,valueToLabel:i.valueToLabel,fieldNames:k,slots:g,isSelect:s,isRadioGroup:d,isCheckboxGroup:f,isCheckbox:r,isRadio:u,isCascader:l,isTreeSelect:y,isSwitch:a,attrs:b,emptyText:i.emptyText})}),E={lineHeight:"32px",padding:"0 6px",display:"inline-block",minHeight:"32px",border:"none",backgroundColor:"none",cursor:"default",wordBreak:"break-all",color:"rgba(0, 0, 0, 0.65)"},x=o.ref();return p&&S({validate:()=>C.value?Promise.resolve({}):x.value?.validate?.(),validateFields:k=>C.value?Promise.resolve({}):x.value?.validateFields?.(k),resetFields:k=>!C.value&&x.value?.resetFields?.(k),clearValidate:k=>!C.value&&x.value?.clearValidate?.(k),scrollToField:k=>!C.value&&x.value?.scrollToField?.(k)}),()=>m?o.h(e,{...b,style:{...b.style||{},marginBottom:C.value?"10px":void 0}},g):p?o.h(e,{...b,rules:v.value?null:b.rules,disabled:v.value?!0:b.disabled,ref:x},g):C.value?o.h("span",{class:"nk-readonly-wrapper",style:E,role:"text",tabindex:0,"aria-readonly":"true"},$.value):o.h(e,{...b,[R]:N.value,[`onUpdate:${R}`]:H,ref:p?x:void 0},g)}})}const I={Input:c.Input,InputNumber:c.InputNumber,Textarea:c.Textarea,Select:c.Select,SelectOption:c.Select.Option,TreeSelect:c.TreeSelect,Cascader:c.Cascader,DatePicker:c.DatePicker,TimePicker:c.TimePicker,Radio:c.Radio,Checkbox:c.Checkbox,RadioGroup:c.Radio.Group,CheckboxGroup:c.Checkbox.Group,Switch:c.Switch,Form:c.Form,FormItem:c.Form.Item},G={install(e){for(const[n,t]of Object.entries(I))if(t){const s=P(t);e.component(`Nk${n}`,s)}}};A.NkReadonlyPlugin=G,A.withReadonly=P,Object.defineProperty(A,Symbol.toStringTag,{value:"Module"})}));

package/dist/withReadonly.d.ts

@@ -0,0 +1,71 @@
+import { PropType, Component, VNode } from 'vue';
+type FormModelValue = string | number | boolean | any[] | null | undefined;
+type ValueToLabelFn = (value: FormModelValue) => string;
+export declare function withReadonly(BaseComponent: Component): import('vue').DefineComponent<{
+    [x: string]: {
+        type: PropType<FormModelValue>;
+        default: undefined;
+    } | {
+        type: BooleanConstructor;
+        default: undefined;
+    } | {
+        type: StringConstructor;
+        default: string;
+    } | {
+        type: PropType<ValueToLabelFn>;
+        default: null;
+    };
+    modelValue: {
+        type: PropType<FormModelValue>;
+        default: undefined;
+    };
+    readonly: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    emptyText: {
+        type: StringConstructor;
+        default: string;
+    };
+    valueToLabel: {
+        type: PropType<ValueToLabelFn>;
+        default: null;
+    };
+}, () => VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>, unknown, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, string[], string, import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, Readonly<import('vue').ExtractPropTypes<{
+    [x: string]: {
+        type: PropType<FormModelValue>;
+        default: undefined;
+    } | {
+        type: BooleanConstructor;
+        default: undefined;
+    } | {
+        type: StringConstructor;
+        default: string;
+    } | {
+        type: PropType<ValueToLabelFn>;
+        default: null;
+    };
+    modelValue: {
+        type: PropType<FormModelValue>;
+        default: undefined;
+    };
+    readonly: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    emptyText: {
+        type: StringConstructor;
+        default: string;
+    };
+    valueToLabel: {
+        type: PropType<ValueToLabelFn>;
+        default: null;
+    };
+}>> & {
+    [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
+}, {
+    [x: string]: FormModelValue | ValueToLabelFn;
+}, {}>;
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "n-design-readonly-plugin",
+  "version": "1.0.0",
+  "description": "只读模式插件 for n-designv3",
+  "main": "./dist/index.cjs.js",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.cjs.js"
+    }
+  },
+  "files": [
+    "dist",
+    ""
+  ],
+  "scripts": {
+    "dev": "vite --config vite.config.playground.ts",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "keywords": [
+    "vue",
+    "n-design-readonly-plugin",
+    "vue",
+    "readonly",
+    "n-designv3",
+    "form",
+    "hoc"
+  ],
+  "author": "pangsh<psh2416623245@163.com>",
+  "license": "ISC",
+  "packageManager": "pnpm@10.21.0",
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "@vitejs/plugin-vue": "^6.0.3",
+    "n-designv3": "1.1.42",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vue": "3.3.4"
+  }
+}

package/playground/App.vue

@@ -0,0 +1,77 @@
+<template>
+  <div class="form-wrapper">
+    <nk-form :readonly="false" :model="form" :rules="rules">
+      <nk-form-item label="用户名" name="name">
+        <nk-input placeholder="用户名" v-model:value="form.name"></nk-input>
+      </nk-form-item>
+      <n-row>
+        <n-col :span="24">
+        <nk-form-item label="下拉options" name="ep6ClusterObjId">
+          <nk-select
+            allowClear
+            placeholder="请选择"
+            :options="options"
+            :showSearch="false"
+            v-model:value="form.ep6ClusterObjId"
+          >
+          </nk-select>
+        </nk-form-item>
+        </n-col>
+      </n-row>
+      <n-row>
+        <n-col :span="24">
+        <nk-form-item label="下拉options" name="ep6ClusterObjId">
+          <n-select
+            allowClear
+            placeholder="请选择"
+            :options="options"
+            :showSearch="false"
+            v-model:value="form.ep6ClusterObjId"
+          >
+          </n-select>
+        </nk-form-item>
+        </n-col>
+      </n-row>
+    </nk-form>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { reactive } from "vue";
+
+const form = reactive({
+  name: "张三",
+  ep6ClusterObjId: "1",
+});
+const options = [
+  {
+    label: "选项1",
+    value: "1",
+    externalValue: "externalValue1",
+  },
+  {
+    label: "选项2",
+    value: "2",
+    externalValue: "externalValue2",
+  },
+  {
+    label: "选项3",
+    value: "3",
+    externalValue: "externalValue3",
+  },
+];
+const rules = {
+  name: [{ required: true, message: "请输入用户名" }],
+  ep6ClusterObjId: [{ required: true, message: "请选择" }],
+};
+</script>
+<style>
+.form-wrapper {
+  width: 100%;
+  height: 100vh;
+  padding: 20px;
+  box-sizing: border-box;
+  position: relative;
+  background-color: bisque;
+}
+</style>

package/playground/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <link rel="icon" href="/favicon.ico" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>NkReadonlyHOC Playground</title>
+</head>
+
+<body>
+  <div id="app"></div>
+  <script type="module" src="./main.ts"></script>
+</body>
+
+</html>

package/playground/main.ts

@@ -0,0 +1,12 @@
+// main.ts
+import { createApp } from 'vue';
+import App from './App.vue';
+import { NkReadonlyPlugin } from '../src/index';
+import NDesign from 'n-designv3';
+import 'n-designv3/dist/nancal.variable.min.css';
+import './reset.css'
+
+const app = createApp(App);
+app.use(NDesign);
+app.use(NkReadonlyPlugin); // ← 一行注册！
+app.mount('#app');

package/playground/reset.css

@@ -0,0 +1,126 @@
+html,
+body,
+div,
+span,
+applet,
+object,
+iframe,
+p,
+blockquote,
+pre,
+a,
+abbr,
+acronym,
+address,
+big,
+cite,
+code,
+del,
+dfn,
+em,
+img,
+ins,
+kbd,
+q,
+s,
+samp,
+small,
+strike,
+strong,
+sub,
+sup,
+tt,
+var,
+b,
+u,
+i,
+center,
+dl,
+dt,
+dd,
+ol,
+ul,
+li,
+fieldset,
+form,
+label,
+legend,
+table,
+caption,
+tbody,
+tfoot,
+thead,
+tr,
+th,
+td,
+article,
+aside,
+canvas,
+details,
+embed,
+figure,
+figcaption,
+footer,
+header,
+hgroup,
+menu,
+nav,
+output,
+ruby,
+section,
+summary,
+time,
+mark,
+audio,
+video {
+  margin: 0;
+  padding: 0;
+  border: 0;
+  font-size: 100%;
+  font: inherit;
+  // vertical-align: baseline;
+}
+/* HTML5 display-role reset for older browsers */
+article,
+aside,
+details,
+figcaption,
+figure,
+footer,
+header,
+hgroup,
+menu,
+nav,
+section {
+  display: block;
+}
+body {
+  line-height: 1;
+}
+ol,
+ul {
+  list-style: none;
+}
+blockquote,
+q {
+  quotes: none;
+}
+blockquote:before,
+blockquote:after,
+q:before,
+q:after {
+  content: '';
+  content: none;
+}
+table {
+  border-collapse: collapse;
+  border-spacing: 0;
+}
+html,
+body {
+  width: 100%;
+  height: 100%;
+  padding: 0;
+  margin: 0;
+  font-family: 'PingFang SC-Medium', 'PingFang SC-Regular', 'PingFang SC', 'STHeitiSC-Light', 'Helvetica-Light', 'Arial', 'sans-serif';
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+// src/index.ts
+import type { App, Plugin } from 'vue';
+import { withReadonly } from './withReadonly';
+
+// 👇 直接从 n-designv3 导入组件（构建时 external，不打包）
+import {
+  Input,
+  InputNumber,
+  Textarea,
+  Select,
+  TreeSelect,
+  Cascader,
+  DatePicker,
+  TimePicker,
+  Radio,
+  Checkbox,
+  Switch,
+  Form,
+} from 'n-designv3';
+
+const COMPONENTS = {
+  Input,
+  InputNumber,
+  Textarea,
+  Select,
+  SelectOption: Select.Option,
+  TreeSelect,
+  Cascader,
+  DatePicker,
+  TimePicker,
+  Radio,
+  Checkbox,
+  RadioGroup: Radio.Group,
+  CheckboxGroup: Checkbox.Group,
+  Switch,
+  Form,
+  FormItem: Form.Item,
+};
+
+export const NkReadonlyPlugin: Plugin = {
+  install(app: App) {
+    for (const [name, Comp] of Object.entries(COMPONENTS)) {
+      if (Comp) {
+        const ReadonlyComp = withReadonly(Comp);
+        app.component(`Nk${name}`, ReadonlyComp);
+      }
+    }
+  },
+};
+
+// 可选：导出 HOC 供用户按需使用
+export { withReadonly };

package/src/types/env.d.ts

@@ -0,0 +1,11 @@
+// src/types/env.d.ts
+interface ImportMetaEnv {
+  readonly DEV: boolean;
+  readonly PROD: boolean;
+  readonly SSR: boolean;
+  // 可以根据实际需要添加其他环境变量
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/src/withReadonly.tsx

@@ -0,0 +1,414 @@
+// composables/withReadonly.ts
+import { defineComponent, h, computed, inject, provide, ref, watch, useAttrs, type PropType, type Component, type VNode, Ref } from 'vue';
+
+type FormModelValue = string | number | boolean | any[] | null | undefined;
+type ValueToLabelFn = (value: FormModelValue) => string;
+
+// ========================
+// 工具函数：提取静态文本（用于单个 checkbox/radio/select ）
+// ========================
+function extractStaticText(vnode: any): string {
+  if (vnode == null) return '';
+  if (typeof vnode === 'string') return vnode;
+  if (Array.isArray(vnode)) return vnode.map(extractStaticText).join('');
+  if (typeof vnode === 'object') {
+    if (typeof vnode.children === 'string') {
+      return vnode.children;
+    }
+    // 处理动态插槽内容
+    if (vnode?.default && typeof vnode.default === 'function') {
+      const dynamicContent = vnode.default();
+      if (Array.isArray(dynamicContent)) {
+        return extractStaticText(dynamicContent);
+      }
+    }
+    if (vnode.children) {
+      extractStaticText(vnode.children);
+    }
+  }
+  return '';
+}
+
+// ========================
+// 从插槽中提取 value → label 映射（支持 n-option / n-radio / n-checkbox / n-select）
+// ========================
+function collectOptionLabelMapFromSlots(vnodes: VNode | VNode[] | undefined, fieldNames: Record<string, string> = {}): Map<any, string> {
+  const labelMap = new Map<any, string>();
+  const { value: valKey = 'value', label: labelKey = 'label' } = fieldNames;
+
+  if (!vnodes) return labelMap;
+
+  const nodes = Array.isArray(vnodes) ? vnodes : [vnodes];
+
+  for (const vnode of nodes) {
+    if (!vnode || typeof vnode !== 'object') continue;
+
+    // 处理组件节点
+    if (vnode.type && (typeof vnode.type === 'object' || typeof vnode.type === 'function')) {
+      let compName = (vnode.type as any).name?.toLowerCase() || '';
+      if (typeof vnode.type === 'function') {
+        compName = (vnode.type as any).displayName?.toLowerCase() || '';
+      } else if (typeof vnode.type === 'string') {
+        compName = (vnode.type as any)?.toLowerCase() || '';
+      }
+      if (/option|radio|checkbox/i.test(compName)) {
+        const props = vnode.props || {};
+        const value = props[valKey] ?? props.value;
+        const labelText = props[labelKey] ?? props.label;
+        if (value != null) {
+          const label = extractStaticText(vnode.children) || labelText || String(value);
+          labelMap.set(value, label);
+        }
+      }
+    }
+
+    // 递归子节点
+    if (vnode.children) {
+      const childMap = collectOptionLabelMapFromSlots(vnode.children as any, fieldNames);
+      childMap.forEach((label, val) => {
+        if (!labelMap.has(val)) labelMap.set(val, label);
+      });
+    }
+  }
+
+  return labelMap;
+}
+
+// ========================
+// Cascader: 递归查找 label 路径
+// ========================
+function findCascaderLabels(options: any[], value: any[], fieldNames: Record<string, string>): string[] {
+  const { value: valKey = 'value', label: labelKey = 'label', children: childrenKey = 'children' } = fieldNames;
+  const labels: string[] = [];
+  let current = options;
+
+  for (const v of value) {
+    const node = current.find((item: any) => item[valKey] === v);
+    if (node) {
+      labels.push(node[labelKey] || node[valKey] || String(v));
+      current = node[childrenKey] || [];
+    } else {
+      labels.push(String(v));
+      break;
+    }
+  }
+  return labels;
+}
+
+// ========================
+// TreeSelect: 从 treeData 递归查找 label
+// ========================
+function findTreeSelectLabels(treeData: any[], value: any, fieldNames: Record<string, string>): string[] {
+  const { value: valKey = 'value', label: labelKey = 'title', children: childrenKey = 'children' } = fieldNames;
+  const labels: string[] = [];
+  const targetValues = new Set(Array.isArray(value) ? value : [value]);
+
+  function dfs(nodes: any[]) {
+    for (const node of nodes) {
+      if (targetValues.has(node[valKey])) {
+        labels.push(node[labelKey] || node[valKey]);
+      }
+      if (node[childrenKey]) {
+        dfs(node[childrenKey]);
+      }
+    }
+  }
+
+  dfs(treeData);
+  return labels;
+}
+
+// ========================
+// 获取只读显示文本
+// ========================
+function getDisplayText({
+  modelValue,
+  options,
+  treeData,
+  valueToLabel,
+  fieldNames,
+  slots,
+  isSelect,
+  isRadioGroup,
+  isCheckboxGroup,
+  isCheckbox,
+  isRadio,
+  isCascader,
+  isTreeSelect,
+  isSwitch,
+  attrs,
+  emptyText,
+}: {
+  modelValue: FormModelValue;
+  options?: any[];
+  treeData?: any[];
+  valueToLabel?: ValueToLabelFn;
+  fieldNames: Record<string, string>;
+  slots?: any;
+  isSelect: boolean;
+  isRadioGroup: boolean;
+  isCheckboxGroup: boolean;
+  isCheckbox: boolean;
+  isRadio: boolean;
+  isCascader: boolean;
+  isTreeSelect: boolean;
+  isSwitch: boolean;
+  attrs: Record<string, any>;
+  emptyText: string;
+}): string {
+  // 1. 自定义映射
+  if (valueToLabel) {
+    try {
+      return valueToLabel(modelValue) || emptyText;
+    } catch (e) {
+      console.warn('[ReadonlyHOC] valueToLabel error', e);
+    }
+  }
+
+  // 2. Switch 特殊处理
+  if (isSwitch) {
+    const checkedVal = attrs.checkedValue ?? attrs['checked-value'] ?? true;
+    const uncheckedVal = attrs.uncheckedValue ?? attrs['un-checked-value'] ?? false;
+    if (modelValue === checkedVal) return attrs.checkedChildren ?? attrs['checked-children'] ?? '开启';
+    if (modelValue === uncheckedVal) return attrs.uncheckedChildren ?? attrs['un-checked-children'] ?? '关闭';
+    return String(modelValue || emptyText);
+  }
+
+  // 3. Cascader
+  if (isCascader && Array.isArray(modelValue) && options?.length) {
+    return findCascaderLabels(options, modelValue, fieldNames).join(' / ') || emptyText;
+  }
+
+  // 4. TreeSelect
+  if (isTreeSelect && treeData?.length) {
+    return findTreeSelectLabels(treeData, modelValue, fieldNames).join(', ') || emptyText;
+  }
+
+  // 5. 动态 options（Select / RadioGroup / CheckboxGroup）
+  if (options?.length) {
+    const valKey = fieldNames.value || 'value';
+    const labelKey = fieldNames.label || 'label';
+    const getLabel = (val: any) => {
+      const opt = options.find(item => item[valKey] === val);
+      return opt ? opt[labelKey] || opt[valKey] : val === undefined || val === null ? '' : String(val);
+    };
+    if (Array.isArray(modelValue)) {
+      return modelValue.map(getLabel).join(', ') || emptyText;
+    } else {
+      return getLabel(modelValue) || emptyText;
+    }
+  }
+
+  // 6. 静态插槽 fallback（Select / RadioGroup / CheckboxGroup）
+  else if ((isSelect || isRadioGroup || isCheckboxGroup) && slots?.default) {
+    try {
+      const slotContent = slots.default();
+
+      const labelMap = collectOptionLabelMapFromSlots(slotContent, fieldNames);
+      if (labelMap.size > 0) {
+        const getLabel = (val: any) => (val === undefined || val === null ? '' : labelMap.get(val) || String(val));
+        if (Array.isArray(modelValue)) {
+          return modelValue.map(getLabel).join(', ') || emptyText;
+        } else {
+          return getLabel(modelValue) || emptyText;
+        }
+      }
+    } catch (e) {
+      console.warn('[ReadonlyHOC] Failed to parse slot options', e);
+    }
+  }
+
+  // 7. 单个 Checkbox / Radio 静态文本兜底
+  else if (slots?.default && (isCheckbox || isRadio) && typeof modelValue === 'boolean') {
+    try {
+      const content = slots.default();
+      const text = extractStaticText(content);
+      if (text) return text;
+    } catch (e) {
+      /* ignore */
+    }
+  }
+
+  // 8. 最终兜底
+  if (modelValue == null || modelValue === '') return emptyText;
+  return Array.isArray(modelValue) ? modelValue.join(', ') : String(modelValue);
+}
+
+// ========================
+// 高阶组件
+// ========================
+export function withReadonly(BaseComponent: Component) {
+  const baseName = BaseComponent.name || '';
+  const componentName = baseName.toLowerCase();
+
+  const isSelect = /select/i.test(componentName) && !/tree|cascader/i.test(componentName);
+  const isRadio = /radio/i.test(componentName) && !/group/i.test(componentName);
+  const isRadioGroup = /radio.*group/i.test(componentName);
+  const isCheckbox = /checkbox/i.test(componentName) && !/group/i.test(componentName);
+  const isCheckboxGroup = /checkbox.*group/i.test(componentName);
+  const isSwitch = /switch/i.test(componentName);
+  const isCascader = /cascader/i.test(componentName);
+  const isTreeSelect = /tree.*select/i.test(componentName);
+
+  const isCheckType = isCheckbox || isSwitch || isRadio;
+  const nativeProp = isCheckType ? 'checked' : 'value';
+  const updateEvent = `update:${nativeProp}`;
+
+  const isForm = /form$/i.test(componentName);
+  const isFormItem = /form.*item/i.test(componentName);
+
+  return defineComponent({
+    name: baseName,
+    inheritAttrs: false,
+    props: {
+      modelValue: { type: [String, Number, Boolean, Array, Object] as PropType<FormModelValue>, default: undefined },
+      [nativeProp]: { type: [String, Number, Boolean, Array, Object] as PropType<FormModelValue>, default: undefined },
+      readonly: { type: Boolean, default: undefined },
+      emptyText: { type: String, default: '--' },
+      valueToLabel: { type: Function as PropType<ValueToLabelFn>, default: null },
+    },
+    emits: ['update:modelValue', updateEvent],
+    setup(props, { emit, slots, expose }) {
+      const globalReadonly = inject<Ref<boolean>>('nkReadonly', ref(false));
+      const isReadonly = computed(() => props.readonly ?? globalReadonly.value);
+      const formReadonly = computed(() => props.readonly ?? globalReadonly.value);
+
+      if (isForm) provide('nkReadonly', formReadonly);
+
+      const finalValue = computed(() => (props[nativeProp] !== undefined ? props[nativeProp] : props.modelValue));
+
+      const emitUpdate = (val: FormModelValue) => {
+        emit('update:modelValue', val);
+        emit(updateEvent, val);
+      };
+
+      // ✅ 使用 useAttrs() 保证响应式
+      const attrs = useAttrs();
+
+      const displayText = computed(() => {
+        if (!isReadonly.value) return '';
+
+        const fieldNames = attrs.fieldNames ?? attrs['field-names'] ?? {};
+        const options = attrs.options as any[] | undefined;
+        const treeData = (attrs.treeData ?? attrs['tree-data']) as any[] | undefined;
+
+        return getDisplayText({
+          modelValue: finalValue.value as FormModelValue,
+          options,
+          treeData,
+          valueToLabel: props.valueToLabel as ValueToLabelFn,
+          fieldNames: fieldNames as Record<string, string>,
+          slots,
+          isSelect,
+          isRadioGroup,
+          isCheckboxGroup,
+          isCheckbox,
+          isRadio,
+          isCascader,
+          isTreeSelect,
+          isSwitch,
+          attrs,
+          emptyText: props.emptyText as string,
+        });
+      });
+
+      // ⚠️ 开发警告
+      if (import.meta?.env?.DEV) {
+        watch(
+          () => isReadonly.value,
+          readonly => {
+            if (
+              readonly &&
+              !attrs.options &&
+              !attrs.treeData &&
+              !props.valueToLabel &&
+              slots?.default &&
+              (isSelect || isRadioGroup || isCheckboxGroup || isCascader || isTreeSelect)
+            ) {
+              console.warn(
+                `[ReadonlyHOC] Detected slot-only usage for  ${baseName} in readonly mode. ` +
+                  `This works for static content, but will fail for async/dynamic data. ` +
+                  `✅ Recommended: Use \`options\` or \`treeData\` prop instead.`
+              );
+            }
+          },
+          { immediate: true }
+        );
+      }
+
+      const readonlyStyle = {
+        lineHeight: '32px',
+        padding: '0 6px',
+        display: 'inline-block',
+        minHeight: '32px',
+        border: 'none',
+        backgroundColor: 'none',
+        cursor: 'default',
+        wordBreak: 'break-all',
+        color: 'rgba(0, 0, 0, 0.65)',
+      };
+
+      const formRef = ref<any>();
+      if (isForm) {
+        expose({
+          validate: () => (isReadonly.value ? Promise.resolve({}) : formRef.value?.validate?.()),
+          validateFields: (names?: string[]) => (isReadonly.value ? Promise.resolve({}) : formRef.value?.validateFields?.(names)),
+          resetFields: (names?: string[]) => !isReadonly.value && formRef.value?.resetFields?.(names),
+          clearValidate: (names?: string[]) => !isReadonly.value && formRef.value?.clearValidate?.(names),
+          scrollToField: (name: string) => !isReadonly.value && formRef.value?.scrollToField?.(name),
+        });
+      }
+
+      return () => {
+        if (isFormItem) {
+          return h(
+            BaseComponent,
+            {
+              ...attrs,
+              style: { ...(attrs.style || {}), marginBottom: isReadonly.value ? '10px' : undefined },
+            },
+            slots
+          );
+        }
+
+        if (isForm) {
+          return h(
+            BaseComponent,
+            {
+              ...attrs,
+              rules: formReadonly.value ? null : attrs.rules,
+              disabled: formReadonly.value ? true : attrs.disabled,
+              ref: formRef,
+            },
+            slots
+          );
+        }
+
+        if (isReadonly.value) {
+          return h(
+            'span',
+            {
+              class: 'nk-readonly-wrapper',
+              style: readonlyStyle,
+              role: 'text',
+              tabindex: 0,
+              'aria-readonly': 'true',
+            },
+            displayText.value
+          );
+        }
+
+        return h(
+          BaseComponent,
+          {
+            ...attrs,
+            [nativeProp]: finalValue.value,
+            [`onUpdate:${nativeProp}`]: emitUpdate,
+            ref: isForm ? formRef : undefined,
+          },
+          slots
+        );
+      };
+    },
+  });
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM"],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "preserve",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationDir": "./dist",
+    "outDir": "./dist",
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"]
+}

package/vite.config.playground.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { resolve } from 'path'
+
+export default defineConfig({
+  root: 'playground',
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+    },
+  },
+  server: {
+    host: '0.0.0.0',
+    port: 5200,
+  },
+})

package/vite.config.ts

@@ -0,0 +1,19 @@
+import { resolve } from 'path';
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'src/index.ts'),
+      name: 'NDesignReadolyPlugin',
+      fileName: 'index',
+    },
+    rollupOptions: {
+      // external 排除 vue 和 n-designv3
+      external: ['vue','n-designv3'],
+      output: { globals: { vue: 'Vue' } }
+    }
+  },
+  plugins: [dts({ insertTypesEntry: true })]
+});