@xmszm/core 0.0.1

package/dist/style.css

@@ -0,0 +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-8fbdfcbb] .n-data-table-tr--summary{position:sticky;bottom:0;left:0;right:0;z-index:2}[data-v-8fbdfcbb] .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-a0acb8e2]{min-width:100px;max-width:240px;text-align:center}.select-line-text[data-v-a0acb8e2]{text-align:center;white-space:nowrap;display:inline}

package/docs/components/dataform.md

@@ -0,0 +1,61 @@
+---
+title: DataForm
+---
+
+配置式表单组件，依赖 `Options` 渲染字段，并自动生成校验规则。
+
+## 基础用法
+```vue
+<script setup>
+import { ref } from 'vue'
+import { DataForm } from 'core'
+
+const model = ref({})
+const options = [
+  { key: 'name', label: '名称', way: 'input', required: true },
+  {
+    key: 'type',
+    label: '类型',
+    way: 'select',
+    options: [{ label: 'A', value: 'a' }],
+    required: true,
+  },
+]
+</script>
+
+<template>
+  <DataForm v-model:value="model" :options="options" />
+</template>
+```
+
+## 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` 自定义渲染，优先级最高。
+
+## 方法（defineExpose）
+- `formRef` Naive UI `NForm` 实例引用。
+- `getRule()` 获取自动生成的 rules。
+- `valid(keyCode?: string[])` 返回 Promise，支持按键位校验。
+- `confirm(fn)` 触发校验后执行回调。
+
+## 场景提示
+- 自动校验逻辑由 `initRules` 提供，`required`/`rule`/`message` 会影响生成结果。
+- 若需要动态选项，可在 `options` 内传入函数或 `ref`，组件内部会自动解包。
+- 弹窗模式结合 `commonDialogMethod` 使用最少代码完成「表单 + 弹窗 + 校验 + 提交」。
+

package/docs/components/datatable.md

@@ -0,0 +1,77 @@
+---
+title: DataTable
+---
+
+基于 `naive-ui` `n-data-table` 的增强组件，提供列筛选、操作列、排序、虚拟滚动与省略。
+
+## 基础用法
+```vue
+<script setup>
+import { ref } from 'vue'
+import { DataTable } from 'core'
+
+const columns = [
+  { title: '名称', key: 'name', width: 160 },
+  { title: '类型', key: 'type', width: 120 },
+]
+const data = ref([
+  { name: '苹果', type: '水果' },
+  { name: '可乐', type: '饮品' },
+])
+</script>
+
+<template>
+  <DataTable :data="data" :columns="columns" />
+</template>
+```
+
+## Props（常用）
+- `data: Array` 数据源。
+- `columns: Array` 列定义，支持 `label`/`title`、`key`、`width`、`ellipsis`、`sorter` 等。
+- `pagination: Object | null` 透传 `n-data-table` 分页。
+- `oprColumns: Object | null` 右侧操作列配置。
+- `selectColumns: Object | null` 选择列。
+- `defaultColumns: Array` 默认可见列键。
+- `summaryColumns: Function` 汇总行。
+- `isFilter: boolean` 是否启用列筛选。
+- `isEllipsis: boolean` 默认开启省略，使用内置 `ellipsis` tooltip。
+- `virtual: boolean` 虚拟滚动，默认数据量大时自动开启。
+
+## 排序（orderEnum 内置工具）
+`orderEnum` 专为 `DataTable` 列排序提供，离开表格场景单独调用无意义。
+
+用法示例（结合后端查询参数与分页刷新）：
+```js
+import { orderEnum } from '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() // 重新拉取数据
+    },
+  },
+]
+```
+
+## 列筛选弹窗
+- 设定 `isFilter=true` 时，右上角会出现“筛选字段”按钮。
+- 弹窗使用 `FilterDialog` 组件记录用户选择，结果存储于 `localStorage`，Key 为 `filter_key + 路由全路径`。
+
+## 省略
+- 默认对列开启 `ellipsis`，使用 `core/table/utils/ellipsis` 配置 tooltip 样式。
+- 可通过列的 `ellipsisProp` 自定义。
+
+## 操作列
+- 可搭配 `createActionColumnJsx` 快速生成操作列，或直接传入 `oprColumns`。
+- `useDataColumnButton` / `useDataColumnPop` 组合了按钮与二次确认的通用场景。
+

package/docs/components/dialog.md

@@ -0,0 +1,78 @@
+---
+title: commonDialogMethod
+---
+
+将表单、弹窗与动作按钮整合的快捷方法，底层使用 `$dialog` 与 `DataForm`。
+
+## 基础用法（用函数包裹触发）
+`commonDialogMethod` 调用即会创建并打开弹窗，推荐用一个函数包裹，在需要时再触发：
+```js
+import { commonDialogMethod } from 'core'
+
+function openEditDialog(row) {
+  const { cancel, model } = commonDialogMethod(
+    {
+      title: '编辑',
+      options: [
+        { key: 'name', label: '名称', way: 'input', required: true },
+        { key: 'type', label: '类型', way: 'select', options: [{ label: 'A', value: 'a' }] },
+      ],
+      valueData: row,
+      interfaceFn: async (data, { close }) => {
+        await save(data)
+        close()
+      },
+    },
+    {
+      style: { width: '520px' },
+    },
+  )
+  return { cancel, model }
+}
+
+// 需要时再调用
+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`：只读模式。
+
+## 返回值
+- `cancel()` 关闭弹窗。
+- `setValue(v, key?)` 设置表单数据。
+- `model` 响应式数据快照。
+- `modeEnum` 默认模式枚举。
+
+## 自定义动作
+```js
+commonDialogMethod({
+  action: [
+    { label: '关闭', mode: 'cancel' },
+    {
+      label: '提交',
+      valid: true,   // 会执行 DataForm 校验
+      loading: true, // 自动切换 loading
+      async onClick({ model, cancel }) {
+        await save(model)
+        cancel()
+      },
+    },
+  ],
+})
+```
+
+## 小贴士
+- 表单校验委托给 `DataForm`，`valid: true` 时自动调用 `formRef.valid()`。
+- 只读场景可用 `mode: 'view'`，或直接传 `read: true`。
+- 若需要自定义 header，可传 `titleFull` 为渲染函数。
+

package/docs/components/options.md

@@ -0,0 +1,55 @@
+---
+title: Options（动态项渲染）
+---
+
+`Options` 负责根据配置渲染具体表单项，可单独使用，也被 `DataForm` 组合。
+
+## 基础用法
+```vue
+<script setup>
+import { ref } from 'vue'
+import { Options } from 'core'
+
+const model = ref({})
+const formRef = ref()
+const option = [
+  { key: 'name', label: '名称', way: 'input', required: true },
+  { key: 'age', label: '年龄', way: 'inputNumber', props: { min: 0 } },
+  {
+    key: 'tags',
+    label: '标签',
+    way: 'select',
+    props: { multiple: true },
+    options: [{ label: 'A', value: 'a' }],
+  },
+]
+</script>
+
+<template>
+  <Options v-model:value="model" :option="option" :form-ref="formRef" />
+</template>
+```
+
+## Props
+- `option: Array` 字段配置。
+- `value (v-model:value): Object` 数据对象。
+- `read: boolean` 只读模式。
+- `labelField` / `valueField`：默认取全局常量 `globalLabelField` / `globalValueField`。
+- `formRef`: 供内部校验、重置使用。
+- `formProps`: 透传给外层布局。
+- `style`: 根容器样式。
+
+## 配置字段说明
+- `way`: 控件类型（input/select/date/time/dateRange/radio/switch/uploadFile/image/dataTable/button 等）。
+- `default / prefix / suffix`: 支持函数或对象，组合渲染布局。
+- `props`: 透传控件的属性，支持函数，入参包含 `formRef`、`setValue`。
+- `formItemProps`: 透传 `NFormItem`，可控制 label/反馈/样式。
+- `render`: 完全自定义渲染。
+- `isRender`: 布尔或函数，控制是否渲染该项。
+- `enum`: 对象形式的枚举，将被转换为数组。
+
+## Tips
+- `options` 内的函数会收到当前表单值与 formRef，可做动态显隐、联动控制。
+- 只读模式会在大多数字段内回显文本，而不渲染输入控件。
+- `labelSuffix`/`labelSuffixProps` 支持传入图标（示例使用 `SvgIcon`）。
+

package/docs/components/query.md

@@ -0,0 +1,49 @@
+---
+title: CommonQuery
+---
+
+查询表单组件，基于 `DataForm` 封装，支持自动提交/重置按钮。
+
+## 基础用法
+```vue
+<script setup>
+import { ref } from 'vue'
+import { CommonQuery } from 'core'
+
+const query = ref({})
+const options = [
+  { key: 'keyword', label: '关键词', way: 'input' },
+  { key: 'type', label: '类型', way: 'select', options: [{ label: 'A', value: 'a' }] },
+]
+
+function onSubmit() {
+  // 根据 query.value 触发列表请求
+}
+</script>
+
+<template>
+  <CommonQuery v-model:query="query" :options="options" @submit="onSubmit" />
+</template>
+```
+
+## Props
+- `options: Array` 查询项配置，规则同 `Options`。
+- `query (v-model:query): Object` 查询对象。
+- `inlineText: boolean` 布局控制。
+- `selectCount: number` 默认 1。
+- `type: string` 按钮类型（传给 `NButton`）。
+- `noButton: boolean` 隐藏底部按钮区。
+- `btn: string[]` 默认 `['reset', 'search']`。
+- `size: string` 传入控件尺寸。
+- `isRead: boolean` 只读。
+
+## 事件
+- `update:query` 双向绑定。
+- `submit` 点击搜索或回车触发（内置 500ms 防抖）。
+- `reset` 重置查询模型。
+
+## 特性
+- 默认监听全局 Enter 键以触发搜索。
+- 为 `input`/`select` 自动绑定 `onUpdateValue`，输入即触发防抖搜索，可通过 `props.onUpdateValue` 自定义。
+- `formProps` 默认关闭校验反馈，适合轻量搜索区域。
+

package/docs/components/utils.md

@@ -0,0 +1,56 @@
+---
+title: 工具与常量
+---
+
+## 操作列 / 排序 / 省略
+
+### createActionColumnJsx
+快速生成表格操作列。
+
+```js
+import { createActionColumnJsx } from 'core'
+
+const oprColumn = createActionColumnJsx(
+  [
+    { label: '查看', onClick: (row) => view(row) },
+    { label: '删除', mode: 'pop', onClick: (row) => remove(row) },
+  ],
+  { fixed: 'right' },
+  { max: 3 }, // collectParams：超过数量折叠
+)
+```
+
+### orderEnum（表格内部用）
+- 来源：`src/enum/sort.jsx`，通过 `DataTable` 列的 `sorter` 使用。
+- 功能：提供升序/降序/默认三态的图标与处理函数，修改 `listQuery` 的排序字段并配合重新拉取数据。
+- 注意：离开 `DataTable` 排序场景单独调用无意义；详细示例见 `DataTable` 文档中的排序段落。
+
+### ellipsis
+表格省略 tooltip 配置：
+```js
+import { ellipsis } from 'core/table/utils/ellipsis'
+```
+
+## 上传工具
+```js
+import { registryUpload, customUpload, getFileUrl } from 'core'
+
+registryUpload((config) => axios.request(config)) // 注册实际上传实现
+await customUpload({ url: '/upload', data: file })
+const url = getFileUrl('/path/to/file', 200) // 拼接 OSS 样式
+```
+
+## 权限与路由
+- `useAuthPermission(...routeNames)` / `useApiConfig(...routeNames)`：读取路由 meta 中的 `auth` / `api`。
+- `cellectChildenPermission(route)`：合并子路由权限到父节点。
+- `initRouteMeta(routes, base?)`：补全 `meta.title`、`meta.permission`、`sourceFullPath` 等。
+- `handleParams(str, map)`：替换路径参数。
+
+## 数据工具
+- `toArray(value)`：非数组包装成数组。
+- `ArrayToObject(arr, { labelField, valueField })`：数组转对象映射。
+- `ObjectToArray(obj, { labelField, valueField })`：对象转数组。
+
+## 类型
+库内提供 `types/index.d.ts`，涵盖组件、方法与工具的基础类型，可在 TS 项目中直接获得提示。
+

package/docs/guide/demo.md

@@ -0,0 +1,213 @@
+---
+title: 示例 Demo 说明
+---
+
+## 本地预览 Demo
+
+项目内提供 `examples/demo.vue`，包含 `DataForm`、`DataTable`、`commonDialogMethod` 的最小示例。
+
+### 运行方式
+
+1) 确认已安装依赖：
+```bash
+npm install
+```
+
+2) 在你的宿主工程中引入该组件文件（或复制内容），确保存在以下 alias：
+```js
+// vite / webpack 示例
+resolve: {
+  alias: {
+    '@': path.resolve(__dirname, 'src'),
+    core: path.resolve(__dirname, 'src'),
+  },
+}
+```
+
+3) 在页面中引用 `examples/demo.vue`，即可直接运行。
+
+## 预览文档站点
+
+项目内已配置 VitePress：
+
+```bash
+npm run docs:dev     # 本地启动文档
+npm run docs:build   # 生成静态文档
+npm run docs:preview # 预览打包产物
+```
+
+生成的静态文件位于 `.vitepress/dist`，可部署到 GitHub Pages / 其他静态托管服务。
+
+## 小贴士
+- 需要更多自定义场景，可在 `examples/` 下新增页面，并在文档中添加入口链接。
+- 若使用 GitHub Actions 部署，可直接在构建步骤运行 `npm run docs:build` 后推送 `.vitepress/dist`。
+
+## 标准后台列表页示例
+典型布局：头部筛选区 + 操作区 + 内容表格区（含弹窗操作）。`DataTable` 本身是 flex 元素，会在容器内自适应填满。
+
+```vue
+<script setup lang="jsx">
+import AddButton from '@/components/button/AddButton.jsx'
+import { useNaivePage } from '@/use/useNaivePage'
+import { onMounted, ref } from 'vue'
+import {
+  commonDialogMethod,
+  CommonQuery,
+  createActionColumnJsx,
+  DataTable,
+} from 'core'
+
+// 列表数据与查询管理
+const { pageState, listQuery } = useNaivePage(() => {
+  listQuery.desc = true
+  // 示例：请求数据
+  // fetchList(listQuery)
+  //   .then(res => {
+  //     pageState.data = res.data.records
+  //     pageState.itemCount = res.data.total
+  //   })
+  //   .finally(pageState.hideLoading)
+})
+
+// 头部查询项
+const keyQuery = [
+  { label: '名称1', key: 'name1', queryType: 'likeQuery' },
+  { label: '名称2', key: 'name2', queryType: 'likeQuery' },
+  { label: '名称3', key: 'name3', queryType: 'likeQuery' },
+]
+
+// 表格列与操作列
+const columns = []
+const defaultColumns = []
+const selectColumns = { type: 'selection', width: '40px' }
+const opr = createActionColumnJsx([
+  {
+    label: '编辑',
+    type: 'primary',
+    onClick: row => onAdd(row),
+  },
+  {
+    label: '删除',
+    type: 'error',
+    mode: 'pop',
+    onClick: (row) => {
+      // del(row.id).then(() => pageState.fetchData())
+    },
+  },
+])
+
+// 弹窗新增/编辑
+function onAdd(row = null, mode = 'add') {
+  commonDialogMethod({
+    title: '示例弹窗',
+    mode,
+    options: [], // 这里填入 DataForm 配置
+    valueData: { ...row },
+    interfaceFn: (data, { close }) => {
+      // save(data).then(() => { pageState.fetchData(); close() })
+    },
+  })
+}
+
+// 导出示例
+const exportLoading = ref(false)
+function onExport() {
+  exportLoading.value = true
+  // exportApi(listQuery).finally(() => (exportLoading.value = false))
+}
+
+onMounted(() => pageState.fetchData())
+</script>
+
+<template>
+  <div class="page-box">
+    <!-- 头部筛选 -->
+    <n-card class="page-head">
+      <CommonQuery
+        :query="listQuery"
+        :options="keyQuery"
+        @submit="pageState.search()"
+        @reset="pageState.reset()"
+      />
+    </n-card>
+
+    <!-- 操作区 -->
+    <n-space justify="space-between">
+      <n-space>
+        <AddButton @click="onAdd()">新增</AddButton>
+        <n-button type="primary" :loading="exportLoading" @click="onExport">
+          导出
+        </n-button>
+      </n-space>
+    </n-space>
+
+    <!-- 内容表格区 -->
+    <div class="page-main">
+      <DataTable
+        :data="pageState.data"
+        :pagination="pageState"
+        :columns="columns"
+        :opr-columns="opr"
+        :default-columns="defaultColumns"
+        :row-key="row => row?.id"
+        :select-columns="selectColumns"
+        :loading="pageState.loading"
+      />
+    </div>
+  </div>
+</template>
+
+<style scoped lang="less">
+.page-head {
+  border-radius: 8px;
+  background-color: #fff;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  row-gap: 20px;
+}
+
+.page-main {
+  flex: 0 1 auto;
+  background-color: #fff;
+  border-radius: 8px;
+  padding: 20px;
+  box-sizing: border-box;
+  display: flex;
+  height: 100%;
+  flex-direction: column;
+  row-gap: 10px;
+
+  .n-data-table {
+    .n-data-table-th {
+      background-color: #f7f8fa;
+      border-right: 1px solid var(--n-merged-border-color);
+      white-space: break-spaces;
+    }
+    .n-data-table-th--last {
+      border-right: 1px solid transparent;
+    }
+    .n-data-table-td--last-row {
+      border-bottom: 1px solid var(--n-merged-border-color);
+    }
+  }
+}
+
+.page-box {
+  display: flex;
+  flex-direction: column;
+  height: calc(100vh - 120px); // 可按实际头/标签高度调整
+  margin: -16px;
+  padding: 24px;
+  box-sizing: border-box;
+  overflow: hidden;
+  row-gap: 20px;
+}
+</style>
+```
+
+> 说明：
+> - `.page-box / .page-head / .page-main` 可抽成全局布局样式复用。
+> - `DataTable` 是 flex 元素，会在容器内自适应填满；容器需设置高度或弹性布局。
+> - 示例中的接口调用、列配置、表单 options 需按业务填充。
+

package/docs/guide/quickstart.md

@@ -0,0 +1,77 @@
+---
+title: 快速开始
+---
+
+## 安装
+
+```bash
+npm install core
+```
+
+同时请在项目中安装（或确保已存在）以下 peer 依赖（版本可按你项目统一）：
+
+- vue 3.x
+- naive-ui
+- vue-router
+- dayjs
+- lodash-es
+- @vicons/ionicons5
+
+> 若项目使用 `@` 路径别名，请确认在构建/运行配置中存在相同的 alias。
+
+## 引入与基本使用
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { DataForm, DataTable, commonDialogMethod } from 'core'
+import 'core/dist/style.css' // 如需默认样式
+
+const formValue = ref({})
+const formOptions = [
+  { key: 'name', label: '名称', way: 'input', required: true },
+  { key: 'type', label: '类型', way: 'select', options: [{ label: 'A', value: 'a' }] },
+]
+
+const tableColumns = [
+  { title: '名称', key: 'name', width: 160 },
+  { title: '类型', key: 'type', width: 100 },
+]
+const tableData = ref([{ name: '示例', type: 'a' }])
+
+function openDialog() {
+  commonDialogMethod({
+    title: '示例弹窗',
+    options: formOptions,
+    valueData: { name: '张三' },
+    interfaceFn: async () => {
+      // 这里提交数据
+    },
+  })
+}
+</script>
+
+<template>
+  <div class="p-16">
+    <DataForm v-model:value="formValue" :options="formOptions" />
+    <DataTable :data="tableData" :columns="tableColumns" style="margin-top: 12px" />
+    <button @click="openDialog">打开弹窗</button>
+  </div>
+</template>
+```
+
+## 目录结构建议
+
+```
+docs/                # VitePress 文档
+examples/demo.vue    # 可运行的最小示例
+src/                 # 组件与工具源码
+types/               # 类型定义
+```
+
+## 常见问题
+
+- 找不到 `@/utils/...`：请在宿主项目配置 `@` 别名或提供对应实现。
+- 样式缺失：如需库内 less 默认样式，确保引入 `core/dist/style.css`。
+- TS 类型：库内已内置 `types/index.d.ts`，可直接获得基础提示。
+