@xmszm/core 0.0.2 → 0.0.4

package/dist/plugin/vite/initRouteMeta.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function h(a,s=""){return a.length?(a.forEach(e=>{var m;e.children&&h(e.children,e==null?void 0:e.path),e.path&&(e.sourceFullPath=`${s?`${s}/`.replace(/^\/\//,"/"):""}${e.path}`),e.meta||(e.meta={});const n=(e==null?void 0:e.title)??((m=e==null?void 0:e.meta)==null?void 0:m.title)??"未命名页面";e!=null&&e.api&&(e.meta.api=e.api),n&&(e.meta.title=n,e.title=n),e!=null&&e.hidden&&(e.meta.hidden=e.hidden);let t=[];e!=null&&e.auth&&(e.meta.auth=e.auth,t=Object.keys(e.auth).reduce((r,i)=>(typeof e.auth[i]=="string"?r.push(e.auth[i]):typeof e.auth[i]=="boolean"&&r.push(i),r),[])),e!=null&&e.permission&&(e.meta.permission=e.permission),e.meta.permission&&Array.isArray(e.meta.permission)?e.meta.permission=e.meta.permission.concat(t):t.length&&(e.meta.permission=t)}),a):[]}exports.initRouteMeta=h;

package/dist/plugin/vite/initRouteMeta.mjs

@@ -0,0 +1,13 @@
+function m(a, r = "") {
+  return a.length ? (a.forEach((e) => {
+    var h;
+    e.children && m(e.children, e == null ? void 0 : e.path), e.path && (e.sourceFullPath = `${r ? `${r}/`.replace(/^\/\//, "/") : ""}${e.path}`), e.meta || (e.meta = {});
+    const n = (e == null ? void 0 : e.title) ?? ((h = e == null ? void 0 : e.meta) == null ? void 0 : h.title) ?? "未命名页面";
+    e != null && e.api && (e.meta.api = e.api), n && (e.meta.title = n, e.title = n), e != null && e.hidden && (e.meta.hidden = e.hidden);
+    let i = [];
+    e != null && e.auth && (e.meta.auth = e.auth, i = Object.keys(e.auth).reduce((s, t) => (typeof e.auth[t] == "string" ? s.push(e.auth[t]) : typeof e.auth[t] == "boolean" && s.push(t), s), [])), e != null && e.permission && (e.meta.permission = e.permission), e.meta.permission && Array.isArray(e.meta.permission) ? e.meta.permission = e.meta.permission.concat(i) : i.length && (e.meta.permission = i);
+  }), a) : [];
+}
+export {
+  m as initRouteMeta
+};

package/dist/style.css

@@ -1 +1 @@
-.filter-box[data-v-2aba8b9e]{padding:20px;margin:-16px -28px -20px;box-sizing:border-box}.filter-main[data-v-2aba8b9e]{display:flex;align-content:flex-start;flex-wrap:wrap;min-height:500px;max-height:700px;overflow-y:auto;row-gap:20px;padding:0 0 15px;box-sizing:border-box}.filter-main .filter-item[data-v-2aba8b9e]{--info-color: var(--e0ecc754);--n-border-checked: 1px solid var(--info-color) !important;--n-border-focus: 1px solid var(--info-color) !important;--n-color-checked: var(--info-color) !important;--n-box-shadow-focus: 0 0 0 2px #6a1f7403 !important;width:calc(100% / 3)}.filter-footer[data-v-2aba8b9e]{display:flex;justify-content:space-between;align-items:center}.filter-footer .submit-btn[data-v-2aba8b9e]{width:80px}[data-v-d6710561] .n-data-table-tr--summary{position:sticky;bottom:0;left:0;right:0;z-index:2}[data-v-d6710561] .n-data-table-tr--summary .n-data-table-td--summary{border-top:1px solid var(--n-merged-border-color)}.upload-box[data-v-54e2cc87]{width:auto}.upload-box[data-v-54e2cc87] .n-upload-file-list.n-upload-file-list--grid{display:flex;flex-wrap:wrap}.upload-box[data-v-54e2cc87] .n-upload-file.n-upload-file--image-card-type{width:var(--image-w);height:var(--image-h)}.upload-box[data-v-54e2cc87] .n-upload-file.n-upload-file--image-card-type .n-image img{object-fit:var(--image-mode)!important}.upload-box[data-v-54e2cc87] .n-upload-trigger--image-card{width:var(--image-w);height:var(--image-h)}.upload-box[data-v-54e2cc87] .n-upload-file--error-status:not(:hover) .n-upload-file-info,.upload-box[data-v-54e2cc87] .n-upload-file--info-status:not(:hover) .n-upload-file-info{position:relative}.upload-box[data-v-54e2cc87] .n-upload-file--error-status:not(:hover) .n-upload-file-info:after,.upload-box[data-v-54e2cc87] .n-upload-file--info-status:not(:hover) .n-upload-file-info:after{content:"";position:absolute;top:0;left:0;right:0;bottom:0;z-index:5;display:block;background-color:#0006}.upload-box[data-v-54e2cc87] .n-upload-file--error-status:not(:hover):after{font-size:12px;white-space:nowrap;content:"上传失败~";position:absolute;color:#ffffffbf;top:50%;left:50%;transform:translate(-50%,-50%);z-index:5;display:block}.upload-box[data-v-54e2cc87] .n-upload-file--info-status:not(:hover):after{font-size:12px;white-space:nowrap;content:"加载中~";position:absolute;color:#ffffffbf;top:50%;left:50%;transform:translate(-50%,-50%);z-index:5;display:block}.svg-icon[data-v-9dbe5f10]{width:inherit;height:inherit;fill:currentColor;vertical-align:middle}.core-dialog-main,.core-dialog-content{box-sizing:border-box;display:flex;align-items:flex-start}.core-dialog-main{min-height:300px}.core-dialog .n-dialog__content{overflow-y:auto;margin:10px -28px 0;box-sizing:border-box;flex:1;border-top:1px solid #91919147;border-bottom:1px solid #91919147;padding:28px}.core-dialog .n-dialog__action{padding:20px 0 0;box-sizing:border-box}.core-dialog-read .n-dialog__content{border-bottom:unset}.select-text[data-v-6ef17b7a]{min-width:100px;max-width:240px;text-align:center}.select-line-text[data-v-6ef17b7a]{text-align:center;white-space:nowrap;display:inline}
+.filter-box[data-v-2aba8b9e]{padding:20px;margin:-16px -28px -20px;box-sizing:border-box}.filter-main[data-v-2aba8b9e]{display:flex;align-content:flex-start;flex-wrap:wrap;min-height:500px;max-height:700px;overflow-y:auto;row-gap:20px;padding:0 0 15px;box-sizing:border-box}.filter-main .filter-item[data-v-2aba8b9e]{--info-color: var(--e0ecc754);--n-border-checked: 1px solid var(--info-color) !important;--n-border-focus: 1px solid var(--info-color) !important;--n-color-checked: var(--info-color) !important;--n-box-shadow-focus: 0 0 0 2px #6a1f7403 !important;width:calc(100% / 3)}.filter-footer[data-v-2aba8b9e]{display:flex;justify-content:space-between;align-items:center}.filter-footer .submit-btn[data-v-2aba8b9e]{width:80px}[data-v-9de17e68] .n-data-table-tr--summary{position:sticky;bottom:0;left:0;right:0;z-index:2}[data-v-9de17e68] .n-data-table-tr--summary .n-data-table-td--summary{border-top:1px solid var(--n-merged-border-color)}.upload-box[data-v-54e2cc87]{width:auto}.upload-box[data-v-54e2cc87] .n-upload-file-list.n-upload-file-list--grid{display:flex;flex-wrap:wrap}.upload-box[data-v-54e2cc87] .n-upload-file.n-upload-file--image-card-type{width:var(--image-w);height:var(--image-h)}.upload-box[data-v-54e2cc87] .n-upload-file.n-upload-file--image-card-type .n-image img{object-fit:var(--image-mode)!important}.upload-box[data-v-54e2cc87] .n-upload-trigger--image-card{width:var(--image-w);height:var(--image-h)}.upload-box[data-v-54e2cc87] .n-upload-file--error-status:not(:hover) .n-upload-file-info,.upload-box[data-v-54e2cc87] .n-upload-file--info-status:not(:hover) .n-upload-file-info{position:relative}.upload-box[data-v-54e2cc87] .n-upload-file--error-status:not(:hover) .n-upload-file-info:after,.upload-box[data-v-54e2cc87] .n-upload-file--info-status:not(:hover) .n-upload-file-info:after{content:"";position:absolute;top:0;left:0;right:0;bottom:0;z-index:5;display:block;background-color:#0006}.upload-box[data-v-54e2cc87] .n-upload-file--error-status:not(:hover):after{font-size:12px;white-space:nowrap;content:"上传失败~";position:absolute;color:#ffffffbf;top:50%;left:50%;transform:translate(-50%,-50%);z-index:5;display:block}.upload-box[data-v-54e2cc87] .n-upload-file--info-status:not(:hover):after{font-size:12px;white-space:nowrap;content:"加载中~";position:absolute;color:#ffffffbf;top:50%;left:50%;transform:translate(-50%,-50%);z-index:5;display:block}.svg-icon[data-v-9dbe5f10]{width:inherit;height:inherit;fill:currentColor;vertical-align:middle}.core-dialog-main,.core-dialog-content{box-sizing:border-box;display:flex;align-items:flex-start}.core-dialog-main{min-height:300px}.core-dialog .n-dialog__content{overflow-y:auto;margin:10px -28px 0;box-sizing:border-box;flex:1;border-top:1px solid #91919147;border-bottom:1px solid #91919147;padding:28px}.core-dialog .n-dialog__action{padding:20px 0 0;box-sizing:border-box}.core-dialog-read .n-dialog__content{border-bottom:unset}.select-text[data-v-643f6214]{min-width:100px;max-width:240px;text-align:center}.select-line-text[data-v-643f6214]{text-align:center;white-space:nowrap;display:inline}

package/docs/.vitepress/config.mjs

@@ -16,7 +16,9 @@ export default defineConfig({
       { text: '指南', link: '/guide/quickstart' },
       { text: '组件', link: '/components/dataform' },
       { text: '工具', link: '/components/utils' },
+      { text: '版本历史', link: '/guide/changelog' },
       { text: '示例 Demo', link: '/guide/demo' },
+      { text: '在线示例', link: '/examples/', target: '_self' },
     ],
     sidebar: {
       '/guide/': [
@@ -24,8 +26,9 @@ export default defineConfig({
           text: '指南',
           items: [
             { text: '快速开始', link: '/guide/quickstart' },
-            { text: '配置指南', link: '/guide/config' },
+            { text: '初始化配置', link: '/guide/config' },
             { text: '本地开发', link: '/guide/local-development' },
+            { text: '版本历史', link: '/guide/changelog' },
             { text: '示例 Demo 说明', link: '/guide/demo' },
           ],
         },
@@ -55,6 +58,12 @@ export default defineConfig({
             { text: '权限与路由', link: '/components/utils#权限与路由' },
           ],
         },
+        {
+          text: '配置项',
+          items: [
+            { text: '配置项说明', link: '/components/config-options' },
+          ],
+        },
       ],
     },
     socialLinks: [

package/docs/components/config-options.md

@@ -0,0 +1,125 @@
+---
+title: 配置项说明
+---
+
+本文档包含所有组件中使用的通用配置项说明。
+
+## Options 配置字段
+
+`Options` 配置字段用于 `DataForm`、`CommonQuery`、`Options` 等组件的表单项配置。
+
+| 字段名 | 必填 | 类型 | 说明 |
+|--------|------|------|------|
+| `key` | 是 | `string \| string[]` | 字段键名，支持数组键用于区间 |
+| `label` | 否 | `string` | 显示文本 |
+| `way` | 否 | `string` | 控件类型，默认 `'input'`。支持的枚举值见下方 [way 字段类型说明](#way-字段类型说明) |
+| `options` | 否 | `Array` | 选择类数据，数组项默认使用 `name` 和 `id` 字段（可通过 `labelField`、`valueField` 配置） |
+| `enum` | 否 | `Object` | 对象形式的枚举，会通过 `ObjectToArray` 转数组 |
+| `props` | 否 | `Object \| Function` | 透传到具体控件（如 `NInput`、`NSelect`），支持函数，入参包含 `formRef`、`setValue` |
+| `formItemProps` | 否 | `Object` | 透传到 `NFormItem`，可控制 label、样式、校验反馈等 |
+| `required` | 否 | `boolean` | 是否必填，影响自动校验 |
+| `rule` | 否 | `Function \| Array` | 自定义校验规则 |
+| `message` | 否 | `string` | 校验失败时的提示信息 |
+| `render` | 否 | `Function` | 完全自定义渲染，优先级最高 |
+| `isRender` | 否 | `boolean \| Function` | 控制是否渲染该项 |
+| `default` | 否 | `any \| Function` | 默认值，支持函数 |
+| `prefix` | 否 | `Function \| Object` | 前缀内容，支持函数或对象 |
+| `suffix` | 否 | `Function \| Object` | 后缀内容，支持函数或对象 |
+| `labelSuffix` | 否 | `string \| Function` | label 后缀，支持图标或函数 |
+| `labelSuffixProps` | 否 | `Object` | label 后缀的属性配置 |
+| `noLabel` | 否 | `boolean` | 是否隐藏 label |
+| `labelClass` | 否 | `string` | label 的 class |
+| `permission` | 否 | `string` | 权限标识，用于权限指令控制显示 |
+
+### way 字段类型说明
+
+| 类型值 | 说明 | 对应组件 |
+|--------|------|----------|
+| `input` | 文本输入框 | `NInput` |
+| `select` | 选择器 | `NSelect` |
+| `date` | 日期选择器 | `NDatePicker` |
+| `dateRange` | 日期范围选择器 | `NDatePicker` |
+| `time` | 时间选择器 | `NTimePicker` |
+| `radio` | 单选框 | `NRadioGroup` |
+| `switch` | 开关 | `NSwitch` |
+| `uploadFile` | 文件上传 | 自定义上传组件 |
+| `image` | 图片上传 | 自定义图片组件 |
+| `dataTable` | 表格选择 | `DataTable` |
+| `button` | 按钮 | `NButton` |
+
+## commonDialogMethod Mode 枚举
+
+`commonDialogMethod` 的 `mode` 参数用于指定弹窗模式。
+
+| 枚举值 | 说明 | 是否只读 |
+|--------|------|----------|
+| `none` | 无模式，不显示模式前缀 | 否 |
+| `create` | 创建模式，标题前缀为"创建" | 否 |
+| `add` | 添加模式，标题前缀为"添加"，默认值 | 否 |
+| `edit` | 编辑模式，标题前缀为"编辑" | 否 |
+| `view` | 查看模式，标题前缀为"查看"，自动设置为只读 | 是 |
+| `export` | 导出模式，标题前缀为"导出" | 否 |
+| `import` | 导入模式，标题前缀为"导入" | 否 |
+| `delete` | 删除模式，标题前缀为"删除" | 否 |
+| `copy` | 复制模式，标题前缀为"复制" | 否 |
+
+> 注意：`view` 模式会自动设置 `read: true`，使表单变为只读状态。
+
+## commonDialogMethod Action 配置
+
+`commonDialogMethod` 的 `action` 参数用于自定义弹窗底部按钮。
+
+| 字段名 | 必填 | 类型 | 说明 |
+|--------|------|------|------|
+| `label` | 否 | `string` | 按钮文本 |
+| `mode` | 否 | `string` | 按钮模式，`'cancel'` 表示取消按钮 |
+| `valid` | 否 | `boolean` | 是否执行 DataForm 校验，默认 `false` |
+| `loading` | 否 | `boolean` | 是否自动切换 loading 状态，默认 `false` |
+| `onClick` | 否 | `Function` | 点击事件，入参 `{ model, cancel, validate, showLoading, hideLoading }` |
+| `render` | 否 | `Function` | 自定义渲染函数，优先级高于 `label` |
+| `props` | 否 | `Object` | 透传给 `NButton` 的属性 |
+| `style` | 否 | `Object` | 按钮样式 |
+
+## createActionColumnJsx 配置
+
+`createActionColumnJsx` 用于生成表格操作列配置。
+
+| 字段名 | 必填 | 类型 | 说明 |
+|--------|------|------|------|
+| `label` | 否 | `string` | 按钮文本 |
+| `type` | 否 | `string` | 按钮类型，默认 `'primary'`。支持的枚举值见下方 [按钮类型枚举](#按钮类型枚举) |
+| `mode` | 否 | `string` | 操作模式，`'pop'` 表示需要二次确认，其他值或不设置则直接执行 |
+| `onClick` | 否 | `Function` | 点击事件，入参为当前行数据 `row` |
+| `permission` | 否 | `string` | 权限标识，用于权限控制 |
+| `render` | 否 | `Function` | 自定义渲染函数 |
+| `props` | 否 | `Object` | 透传给按钮的属性 |
+
+### 按钮类型枚举
+
+| 类型值 | 说明 |
+|--------|------|
+| `default` | 默认按钮 |
+| `primary` | 主要按钮（默认值） |
+| `success` | 成功按钮 |
+| `info` | 信息按钮 |
+| `warning` | 警告按钮 |
+| `error` | 错误按钮 |
+| `tertiary` | 第三级按钮 |
+| `quaternary` | 第四级按钮 |
+
+## CommonQuery queryType 说明
+
+`CommonQuery` 组件中，`options` 配置项的 `queryType` 字段用于指定查询参数的类型。
+
+| queryType 值 | 说明 | 示例 |
+|--------------|------|------|
+| `likeQuery` | 模糊查询，值会放入 `query.likeQuery[key]` | `{ key: 'name', queryType: 'likeQuery' }` |
+| 不设置或空字符串 | 直接放入 `query[key]` | `{ key: 'status' }` |
+
+## 相关链接
+
+- [DataForm 组件](/components/dataform)
+- [Options 组件](/components/options)
+- [CommonQuery 组件](/components/query)
+- [commonDialogMethod](/components/dialog)
+

package/docs/components/dataform.md

@@ -29,33 +29,186 @@ const options = [
 ```
 
 ## Props
-- `options: Array` 表单项配置，透传给 `Options`。
-- `value (v-model:value): Object` 表单数据。
-- `read: boolean` 只读模式。
-- `labelField: string` 默认 `label`，决定 label 字段名。
-- `formProps: Object` 透传给 `naive-ui` `NForm`。
-- `formItemProps: Object` 透传给每个 `NFormItem`。
-- `dialog: boolean` 在弹窗场景下使用时自动附加样式。
-- `rules: Object` 自定义校验规则；不传则根据 `options` 自动生成。
-
-## Options 关键字段
-- `key` 必填，字段键名。支持数组键用于区间。
-- `label` 显示文本。
-- `way` 字段类型，默认 `input`。常用：`select`、`date`、`dateRange`、`time`、`radio`、`switch`、`uploadFile`、`image`、`dataTable` 等。
-- `options / enum` 选择类数据。`enum` 会通过 `ObjectToArray` 转数组。
-- `props` 透传到具体控件（如 `NInput`、`NSelect`）。
-- `formItemProps` 透传到 `NFormItem`，可控制 label、样式、校验反馈等。
-- `required / rule / message` 影响自动校验。
-- `render` 自定义渲染，优先级最高。
+
+| 字段名 | 必填 | 类型 | 说明 |
+|--------|------|------|------|
+| `options` | 否 | `Array` | 表单项配置，透传给 `Options` |
+| `value` / `v-model:value` | 否 | `Object` | 表单数据，支持 v-model 双向绑定 |
+| `read` | 否 | `boolean` | 只读模式，默认 `false` |
+| `labelField` | 否 | `string` | 决定 label 字段名，默认 `'label'` |
+| `formProps` | 否 | `Object` | 透传给 `naive-ui` `NForm` 的属性 |
+| `formItemProps` | 否 | `Object` | 透传给每个 `NFormItem` 的属性 |
+| `dialog` | 否 | `boolean` | 在弹窗场景下使用时自动附加样式，默认 `false` |
+| `rules` | 否 | `Object` | 自定义校验规则；不传则根据 `options` 自动生成 |
+| `isNo` | 否 | `boolean` | 内容最小高度控制，默认 `true` |
+| `contentStyle` | 否 | `Object` | 内容区域样式，默认 `{}` |
+
+## Options 配置字段
+
+`options` 配置项使用 [Options 配置字段](/components/config-options#options-配置字段)，详见配置项说明文档。
 
 ## 方法（defineExpose）
-- `formRef` Naive UI `NForm` 实例引用。
-- `getRule()` 获取自动生成的 rules。
-- `valid(keyCode?: string[])` 返回 Promise，支持按键位校验。
-- `confirm(fn)` 触发校验后执行回调。
+
+| 方法名 | 类型 | 说明 |
+|--------|------|------|
+| `formRef` | `Ref<FormInstance>` | Naive UI `NForm` 实例引用 |
+| `getRule()` | `() => Object` | 获取自动生成的 rules |
+| `valid(keyCode?)` | `(keyCode?: string[]) => Promise<void>` | 表单校验，返回 Promise，支持按键位校验 |
+| `confirm(fn)` | `(fn?: Function) => Promise<Object>` | 触发校验后执行回调，返回 Promise |
+
+## initRules
+
+`initRules` 用于根据 `options` 配置自动生成表单校验规则。规则处理基于 [async-validator](https://github.com/yiminghe/async-validator) 库。
+
+```javascript
+import { initRules } from '@xmszm/core'
+
+const options = [
+  { key: 'name', label: '名称', way: 'input', required: true },
+  { key: 'email', label: '邮箱', way: 'input', rule: /^[\w-]+(\.[\w-]+)*@[\w-]+(\.[\w-]+)+$/ },
+]
+
+const rules = initRules(options)
+// => {
+//   name: [{ required: true, message: '请输入名称', trigger: 'blur' }],
+//   email: [{ pattern: /^[\w-]+(\.[\w-]+)*@[\w-]+(\.[\w-]+)+$/, message: '请输入正确的邮箱', trigger: 'blur' }]
+// }
+```
+
+### 规则生成逻辑
+
+#### required
+
+- `required: true`：自动生成必填校验
+- 默认情况下，只需要 `required: true` 即可满足大部分校验需求
+
+```javascript
+const options = [
+  { key: 'name', label: '名称', way: 'input', required: true },
+  // 自动生成：{ required: true, message: '请输入名称', trigger: 'blur' }
+]
+```
+
+#### rule（自定义校验规则）
+
+`rule` 支持以下形式：
+
+1. **对象形式**：直接传入校验规则对象
+
+```javascript
+const options = [
+  {
+    key: 'age',
+    label: '年龄',
+    way: 'input',
+    rule: {
+      type: 'number',
+      min: 18,
+      max: 100,
+      message: '年龄必须在 18-100 之间',
+    },
+  },
+]
+```
+
+2. **函数形式**：函数返回校验规则对象，可以根据当前值和表单数据动态生成规则
+
+```javascript
+const options = [
+  {
+    key: 'password',
+    label: '密码',
+    way: 'input',
+    rule: (value, formData) => {
+      // 函数返回的是规则配置对象，可以根据 value 和 formData 动态生成规则
+      if (value && value.length < 8) {
+        return {
+          required: true,
+          message: '密码长度不能少于 8 位',
+        }
+      }
+      // 返回规则对象，用于动态校验
+      return {
+        required: true,
+        min: 8,
+        message: '密码长度不能少于 8 位',
+      }
+    },
+  },
+  {
+    key: 'confirmPassword',
+    label: '确认密码',
+    way: 'input',
+    rule: (value, formData) => {
+      // 可以根据其他字段的值动态生成规则
+      return {
+        required: true,
+        validator: (rule, val) => {
+          if (val !== formData.password) {
+            return Promise.reject('两次输入的密码不一致')
+          }
+          return Promise.resolve()
+        },
+      }
+    },
+  },
+]
+```
+
+::: tip 函数形式的优势
+函数形式的 `rule` 可以根据当前字段的值（`value`）和整个表单数据（`formData`）动态生成校验规则，从而实现：
+- 动态必填校验（根据其他字段的值决定是否必填）
+- 联动校验（如确认密码需要与密码一致）
+- 条件校验（根据表单状态动态调整校验规则）
+:::
+
+::: warning 重要提示
+当使用 `rule` 自定义校验规则时，**外部的 `required` 配置将无效**。如果需要在自定义规则中包含必填校验，请在 `rule` 对象中显式设置 `required: true`。
+
+```javascript
+// ❌ 错误：rule 存在时，外部的 required 无效
+{
+  key: 'name',
+  required: true,
+  rule: { type: 'string', min: 2 },
+}
+
+// ✅ 正确：在 rule 中包含 required
+{
+  key: 'name',
+  rule: {
+    type: 'string',
+    required: true,
+    min: 2,
+    message: '名称至少需要 2 个字符',
+  },
+}
+```
+:::
+
+#### message
+
+自定义错误提示信息。
+
+```javascript
+const options = [
+  {
+    key: 'name',
+    label: '名称',
+    way: 'input',
+    required: true,
+    message: '请输入您的姓名', // 自定义错误提示
+  },
+]
+```
+
+### 参考文档
+
+更多关于校验规则的详细说明，请参考 [async-validator](https://github.com/yiminghe/async-validator) 官方文档。
 
 ## 场景提示
 - 自动校验逻辑由 `initRules` 提供，`required`/`rule`/`message` 会影响生成结果。
 - 若需要动态选项，可在 `options` 内传入函数或 `ref`，组件内部会自动解包。
 - 弹窗模式结合 `commonDialogMethod` 使用最少代码完成「表单 + 弹窗 + 校验 + 提交」。
+- `options` 中的 `way` 字段支持自定义控件类型，可通过 `setupOptions` 注册，详见 [初始化配置 - Options 注册](/guide/config#options-注册)。
 

package/docs/components/datatable.md

@@ -2,7 +2,7 @@
 title: DataTable
 ---
 
-基于 `naive-ui` `n-data-table` 的增强组件，提供列筛选、操作列、排序、虚拟滚动与省略。
+基于 `naive-ui` `n-data-table` 的增强组件，提供列筛选、操作列、虚拟滚动与省略。
 
 ## 基础用法
 ```vue
@@ -25,44 +25,26 @@ const data = ref([
 </template>
 ```
 
-## Props（常用）
-- `data: Array` 数据源。
-- `columns: Array` 列定义，支持 `label`/`title`、`key`、`width`、`ellipsis`、`sorter` 等。
-- `pagination: Object | null` 透传 `n-data-table` 分页。
-- `oprColumns: Object | null` 右侧操作列配置（模板中使用 `opr-columns`）。
-- `selectColumns: Object | null` 选择列（模板中使用 `select-columns`）。
-- `defaultColumns: Array` 默认可见列键（模板中使用 `default-columns`）。
-- `summaryColumns: Function` 汇总行（模板中使用 `summary-columns`）。
-- `isFilter: boolean` 是否启用列筛选。
-- `isEllipsis: boolean` 默认开启省略，使用内置 `ellipsis` tooltip。
-- `virtual: boolean` 虚拟滚动，默认数据量大时自动开启。
-- `rowKey: Function | String` 行键，用于标识每一行数据。
-
-## 排序（orderEnum 内置工具）
-`orderEnum` 专为 `DataTable` 列排序提供，离开表格场景单独调用无意义。
-
-用法示例（结合后端查询参数与分页刷新）：
-```javascript
-import { orderEnum } from '@xmszm/core'
-
-const listQuery = reactive({ sortFieldName: '', desc: false })
-const pageState = {
-  fetchData: () => loadTableData(listQuery),
-}
-
-const columns = [
-  {
-    title: '创建时间',
-    key: 'createdAt',
-    width: 180,
-    sorter: (listQueryParam, pageStateParam, key) => {
-      // 选择升序/降序/默认时会进入这里
-      orderEnum.ascend.fn(listQueryParam, key) // 设置排序字段与方向
-      pageStateParam.fetchData() // 重新拉取数据
-    },
-  },
-]
-```
+## Props
+
+| 字段名 | 必填 | 类型 | 说明 |
+|--------|------|------|------|
+| `data` | 否 | `Array` | 数据源，默认 `[]` |
+| `columns` | 否 | `Array` | 列定义，支持 `label`/`title`、`key`、`width`、`ellipsis` 等 |
+| `pagination` | 否 | `Object \| null` | 透传 `n-data-table` 分页配置 |
+| `oprColumns` | 否 | `Object \| null` | 右侧操作列配置（模板中使用 `opr-columns`） |
+| `selectColumns` | 否 | `Object \| null` | 选择列配置（模板中使用 `select-columns`） |
+| `defaultColumns` | 否 | `Array` | 默认可见列键（模板中使用 `default-columns`），默认 `[]` |
+| `summaryColumns` | 否 | `Function \| null` | 汇总行函数（模板中使用 `summary-columns`） |
+| `isFilter` | 否 | `boolean` | 是否启用列筛选，默认 `false` |
+| `isEllipsis` | 否 | `boolean` | 是否开启省略，使用内置 `ellipsis` tooltip，默认 `true` |
+| `virtual` | 否 | `boolean \| Object` | 虚拟滚动配置，默认数据量大时自动开启 |
+| `rowKey` | 否 | `Function \| String` | 行键，用于标识每一行数据 |
+| `emptyText` | 否 | `string` | 空数据提示文本，默认 `'没有数据'` |
+| `emptyIcon` | 否 | `string` | 空数据图标，默认 `''` |
+| `singleColumn` | 否 | `boolean` | 单列模式，默认 `false` |
+
+## 事件
 
 ## 列筛选弹窗
 - 设定 `isFilter=true` 时，右上角会出现“筛选字段”按钮。

package/docs/components/dialog.md

@@ -34,26 +34,42 @@ function openEditDialog(row) {
 openEditDialog(currentRow)
 ```
 
-## 参数（主要）
-- `title / noTitle / titleFull`：标题配置。
-- `options: Array` 表单项，直接传给 `DataForm`。
-- `mode` 与 `modeEnum`：内置 `create/add/edit/view/import/export/delete/copy/none`，`view` 会自动只读。
-- `labelField`：默认 `label`。
-- `isNo`：内容最小高度控制。
-- `formProps`、`contentStyle`：透传 `DataForm`。
-- `action`：自定义底部按钮数组或函数；不传则使用默认“取消 / 确定”。
-- `actionProps`：NSpace/按钮样式补充。
-- `interfaceFn`：点击默认“确定”时执行，入参 `(model, { close, hideLoading })`。
-- `interfaceFnCancel`：点击默认“取消”时执行。
-- `read / isRead`：只读模式。
+## 参数
+
+| 字段名 | 必填 | 类型 | 说明 |
+|--------|------|------|------|
+| `title` | 否 | `string` | 弹窗标题，默认 `''` |
+| `noTitle` | 否 | `boolean` | 是否隐藏标题，默认 `false` |
+| `titleFull` | 否 | `Function \| string` | 自定义标题渲染函数或完整标题 |
+| `options` | 否 | `Array` | 表单项配置，直接传给 `DataForm`，默认 `[]` |
+| `mode` | 否 | `string` | 模式，默认 `'add'`。支持的枚举值见 [commonDialogMethod Mode 枚举](/components/config-options#commondialogmethod-mode-枚举) |
+| `modeEnum` | 否 | `Object` | 自定义模式枚举，会与默认模式合并 |
+| `labelField` | 否 | `string` | label 字段名，默认 `'label'` |
+| `isNo` | 否 | `boolean` | 内容最小高度控制，默认 `true` |
+| `formProps` | 否 | `Object` | 透传给 `DataForm` 的 `formProps`，默认 `{}` |
+| `contentStyle` | 否 | `Object` | 透传给 `DataForm` 的 `contentStyle`，默认 `{}` |
+| `action` | 否 | `Array \| Function` | 自定义底部按钮数组或函数；不传则使用默认“取消 / 确定” |
+| `actionProps` | 否 | `Object` | NSpace/按钮样式补充，默认 `{}` |
+| `interfaceFn` | 否 | `Function` | 点击默认“确定”时执行，入参 `(model, { close, hideLoading })` |
+| `interfaceFnCancel` | 否 | `Function` | 点击默认“取消”时执行，入参 `(model, { close })` |
+| `read` | 否 | `boolean` | 只读模式，默认 `false` |
+| `isRead` | 否 | `boolean` | 只读模式（与 `read` 同义），默认 `false` |
+| `valueData` | 否 | `Object` | 表单初始数据，默认 `{}` |
+| `dialogProps` | 否 | `Object` | 透传给 `n-dialog` 的属性（第二个参数） |
 
 ## 返回值
-- `cancel()` 关闭弹窗。
-- `setValue(v, key?)` 设置表单数据。
-- `model` 响应式数据快照。
-- `modeEnum` 默认模式枚举。
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| `cancel` | `() => void` | 关闭弹窗的方法 |
+| `setValue` | `(v: any, key?: string) => void` | 设置表单数据，`key` 为空时更新整个表单对象 |
+| `model` | `Ref<Object>` | 响应式表单数据快照 |
+| `modeEnum` | `Object` | 默认模式枚举对象 |
 
 ## 自定义动作
+
+`action` 参数支持数组或函数，数组项配置详见 [commonDialogMethod Action 配置](/components/config-options#commondialogmethod-action-配置)。
+
 ```javascript
 commonDialogMethod({
   action: [
@@ -71,8 +87,131 @@ commonDialogMethod({
 })
 ```
 
+## useCommonDialog Hook
+
+在组件中使用 `commonDialogMethod` 的便捷方式，自动注册 Dialog 实例。
+
+### 基础用法
+
+```javascript
+import { useCommonDialog } from '@xmszm/core'
+
+export default {
+  setup() {
+    const openDialog = useCommonDialog()
+    
+    const handleEdit = (row) => {
+      openDialog({
+        title: '编辑',
+        options: [
+          { key: 'name', label: '名称', way: 'input', required: true },
+        ],
+        valueData: row,
+        interfaceFn: async (data, { close }) => {
+          await save(data)
+          close()
+        },
+      })
+    }
+    
+    return { handleEdit }
+  },
+}
+```
+
+### 在 Composition API 中使用
+
+```javascript
+import { useCommonDialog } from '@xmszm/core'
+
+const openDialog = useCommonDialog()
+
+function handleAdd() {
+  openDialog({
+    title: '新增',
+    options: formOptions,
+    interfaceFn: async (data, { close }) => {
+      await create(data)
+      close()
+    },
+  })
+}
+```
+
+## Dialog 工具函数
+
+### createDialog
+
+使用 dialog 的工具函数，需要手动传入 dialog 实例。
+
+```javascript
+import { useDialog } from 'naive-ui'
+import { createDialog } from '@xmszm/core'
+
+const dialog = useDialog()
+
+// 创建自定义弹窗
+const { destroy } = createDialog(dialog, {
+  title: '提示',
+  content: '这是一个自定义弹窗',
+})
+```
+
+### createDialogMethods
+
+创建 Dialog 快捷方法（info、success、warning、error、create）。
+
+```javascript
+import { useDialog } from 'naive-ui'
+import { createDialogMethods } from '@xmszm/core'
+
+const dialog = useDialog()
+const dialogMethods = createDialogMethods(dialog)
+
+// 使用快捷方法
+dialogMethods.info({
+  title: '信息',
+  content: '这是一条信息',
+})
+
+dialogMethods.success({
+  title: '成功',
+  content: '操作成功',
+})
+
+dialogMethods.warning({
+  title: '警告',
+  content: '请注意',
+})
+
+dialogMethods.error({
+  title: '错误',
+  content: '操作失败',
+})
+```
+
+### createDialogOptions
+
+创建 dialog 配置，应用主题色继承设置。通常用于自定义 Dialog 主题。
+
+```javascript
+import { useDialog } from 'naive-ui'
+import { createDialogOptions } from '@xmszm/core'
+
+const dialog = useDialog()
+
+const options = createDialogOptions({
+  title: '自定义主题',
+  content: '内容',
+})
+
+dialog.create(options)
+```
+
 ## 小贴士
 - 表单校验委托给 `DataForm`，`valid: true` 时自动调用 `formRef.valid()`。
 - 只读场景可用 `mode: 'view'`，或直接传 `read: true`。
 - 若需要自定义 header，可传 `titleFull` 为渲染函数。
+- 在组件中推荐使用 `useCommonDialog` Hook，它会自动处理 Dialog 实例注册。
+- `createDialog`、`createDialogMethods`、`createDialogOptions` 适用于需要更细粒度控制的场景。