@xmszm/core 0.0.1 → 0.0.3

package/docs/components/dialog.md

@@ -6,8 +6,8 @@ title: commonDialogMethod
 
 ## 基础用法（用函数包裹触发）
 `commonDialogMethod` 调用即会创建并打开弹窗，推荐用一个函数包裹，在需要时再触发：
-```js
-import { commonDialogMethod } from 'core'
+```javascript
+import { commonDialogMethod } from '@xmszm/core'
 
 function openEditDialog(row) {
   const { cancel, model } = commonDialogMethod(
@@ -34,27 +34,43 @@ 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` | 默认模式枚举对象 |
 
 ## 自定义动作
-```js
+
+`action` 参数支持数组或函数，数组项配置详见 [commonDialogMethod Action 配置](/components/config-options#commondialogmethod-action-配置)。
+
+```javascript
 commonDialogMethod({
   action: [
     { label: '关闭', mode: 'cancel' },
@@ -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` 适用于需要更细粒度控制的场景。
 

package/docs/components/options.md

@@ -8,7 +8,7 @@ title: Options（动态项渲染）
 ```vue
 <script setup>
 import { ref } from 'vue'
-import { Options } from 'core'
+import { Options } from '@xmszm/core'
 
 const model = ref({})
 const formRef = ref()
@@ -31,25 +31,54 @@ const option = [
 ```
 
 ## Props
-- `option: Array` 字段配置。
-- `value (v-model:value): Object` 数据对象。
-- `read: boolean` 只读模式。
-- `labelField` / `valueField`：默认取全局常量 `globalLabelField` / `globalValueField`。
-- `formRef`: 供内部校验、重置使用。
-- `formProps`: 透传给外层布局。
-- `style`: 根容器样式。
+
+| 字段名 | 必填 | 类型 | 说明 |
+|--------|------|------|------|
+| `option` | 否 | `Array` | 字段配置数组，默认 `[]` |
+| `value` / `v-model:value` | 否 | `Object` | 数据对象，支持 v-model 双向绑定，默认 `{}` |
+| `read` | 否 | `boolean` | 只读模式，默认 `false` |
+| `labelField` | 否 | `string` | label 字段名，默认取全局常量 `globalLabelField`（`'name'`） |
+| `valueField` | 否 | `string` | value 字段名，默认取全局常量 `globalValueField`（`'id'`） |
+
+::: tip 全局字段常量
+- `globalLabelField`：默认值为 `'name'`，用于指定选项数组中 label 字段名
+- `globalValueField`：默认值为 `'id'`，用于指定选项数组中 value 字段名
+
+这些常量可以在组件级别通过 `labelField` 和 `valueField` props 覆盖。
+:::
+| `formRef` | 否 | `Object` | 表单引用，供内部校验、重置使用，默认 `{}` |
+| `formProps` | 否 | `Object` | 透传给外层布局的属性，默认 `{}` |
+| `style` | 否 | `Object` | 根容器样式，默认 `{}` |
 
 ## 配置字段说明
-- `way`: 控件类型（input/select/date/time/dateRange/radio/switch/uploadFile/image/dataTable/button 等）。
-- `default / prefix / suffix`: 支持函数或对象，组合渲染布局。
-- `props`: 透传控件的属性，支持函数，入参包含 `formRef`、`setValue`。
-- `formItemProps`: 透传 `NFormItem`，可控制 label/反馈/样式。
-- `render`: 完全自定义渲染。
-- `isRender`: 布尔或函数，控制是否渲染该项。
-- `enum`: 对象形式的枚举，将被转换为数组。
+
+`option` 配置项使用 [Options 配置字段](/components/config-options#options-配置字段)，详见配置项说明文档。
+
+## 自定义控件类型
+
+`Options` 支持通过 `setupOptions` 注册自定义控件类型，详见 [初始化配置 - Options 注册](/guide/config#options-注册)。
+
+### 示例
+
+```javascript
+// main.js
+import { setupOptions } from '@xmszm/core'
+import { NCascader } from 'naive-ui'
+
+// 注册自定义控件
+setupOptions('cascader', (item, { _value, _isRead }) => {
+  return <NCascader v-model:value={_value[item.key]} options={item.options} />
+})
+
+// 使用
+const options = [
+  { key: 'region', label: '地区', way: 'cascader', options: regionData }
+]
+```
 
 ## Tips
 - `options` 内的函数会收到当前表单值与 formRef，可做动态显隐、联动控制。
 - 只读模式会在大多数字段内回显文本，而不渲染输入控件。
 - `labelSuffix`/`labelSuffixProps` 支持传入图标（示例使用 `SvgIcon`）。
+- 可以通过 `setupOptions` 扩展自定义控件类型，详见 [初始化配置](/guide/config)。
 

package/docs/components/query.md

@@ -8,7 +8,7 @@ title: CommonQuery
 ```vue
 <script setup>
 import { ref } from 'vue'
-import { CommonQuery } from 'core'
+import { CommonQuery } from '@xmszm/core'
 
 const query = ref({})
 const options = [
@@ -22,28 +22,82 @@ function onSubmit() {
 </script>
 
 <template>
-  <CommonQuery v-model:query="query" :options="options" @submit="onSubmit" />
+  <CommonQuery v-model:query="query" :options="options" @submit="onSubmit" @reset="onReset" />
+</template>
+```
+
+### 完整示例（结合分页）
+
+```vue
+<script setup>
+import { reactive } from 'vue'
+import { CommonQuery } from '@xmszm/core'
+
+const listQuery = reactive({
+  page: 1,
+  pageSize: 10,
+  likeQuery: {
+    keyword: '',
+    type: '',
+  },
+})
+
+const queryOptions = [
+  { label: '关键词', key: 'keyword', queryType: 'likeQuery', way: 'input' },
+  { label: '类型', key: 'type', queryType: 'likeQuery', way: 'select', options: [
+    { label: '类型A', value: 'A' },
+    { label: '类型B', value: 'B' }
+  ]},
+]
+
+function handleSearch() {
+  listQuery.page = 1
+  fetchData()
+}
+
+function handleReset() {
+  listQuery.likeQuery = { keyword: '', type: '' }
+  listQuery.page = 1
+  fetchData()
+}
+</script>
+
+<template>
+  <CommonQuery
+    :query="listQuery"
+    :options="queryOptions"
+    @submit="handleSearch"
+    @reset="handleReset"
+  />
 </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` 只读。
+
+| 字段名 | 必填 | 类型 | 说明 |
+|--------|------|------|------|
+| `options` | 否 | `Array` | 查询项配置，规则同 `Options`，默认 `[]` |
+| `query` / `v-model:query` | 否 | `Object` | 查询对象，支持 v-model 双向绑定，默认 `{}` |
+| `inlineText` | 否 | `boolean` | 布局控制，默认 `true` |
+| `selectCount` | 否 | `number` | 每行显示的查询项数量，默认 `1` |
+| `type` | 否 | `string` | 按钮类型（传给 `NButton`），默认 `'primary'` |
+| `noButton` | 否 | `boolean` | 是否隐藏底部按钮区，默认 `false` |
+| `btn` | 否 | `string[]` | 按钮配置数组，默认 `['reset', 'search']` |
+| `size` | 否 | `string` | 传入控件尺寸，默认 `'medium'` |
+| `isRead` | 否 | `boolean` | 只读模式，默认 `false` |
 
 ## 事件
-- `update:query` 双向绑定。
-- `submit` 点击搜索或回车触发（内置 500ms 防抖）。
-- `reset` 重置查询模型。
+
+| 事件名 | 类型 | 说明 |
+|--------|------|------|
+| `update:query` | `(query: Object) => void` | 查询对象变化时触发，用于 v-model 双向绑定 |
+| `submit` | `() => void` | 点击搜索或回车触发（内置 500ms 防抖） |
+| `reset` | `() => void` | 重置查询模型时触发 |
 
 ## 特性
 - 默认监听全局 Enter 键以触发搜索。
 - 为 `input`/`select` 自动绑定 `onUpdateValue`，输入即触发防抖搜索，可通过 `props.onUpdateValue` 自定义。
 - `formProps` 默认关闭校验反馈，适合轻量搜索区域。
+- `options` 配置项支持 `queryType` 字段，用于指定查询参数类型，详见 [CommonQuery queryType 说明](/components/config-options#commonquery-querytype-说明)。
+- `options` 中的 `way` 字段支持自定义控件类型，可通过 `setupOptions` 注册，详见 [初始化配置 - Options 注册](/guide/config#options-注册)。
 

package/docs/components/utils.md

@@ -2,13 +2,15 @@
 title: 工具与常量
 ---
 
-## 操作列 / 排序 / 省略
+## 操作列 / 省略
 
 ### createActionColumnJsx
 快速生成表格操作列。
 
-```js
-import { createActionColumnJsx } from 'core'
+配置项说明详见 [createActionColumnJsx 配置](/components/config-options#createactioncolumnjsx-配置)。
+
+```javascript
+import { createActionColumnJsx } from '@xmszm/core'
 
 const oprColumn = createActionColumnJsx(
   [
@@ -20,31 +22,137 @@ const oprColumn = createActionColumnJsx(
 )
 ```
 
-### orderEnum（表格内部用）
-- 来源：`src/enum/sort.jsx`，通过 `DataTable` 列的 `sorter` 使用。
-- 功能：提供升序/降序/默认三态的图标与处理函数，修改 `listQuery` 的排序字段并配合重新拉取数据。
-- 注意：离开 `DataTable` 排序场景单独调用无意义；详细示例见 `DataTable` 文档中的排序段落。
-
 ### ellipsis
 表格省略 tooltip 配置：
-```js
-import { ellipsis } from 'core/table/utils/ellipsis'
+```javascript
+import { ellipsis } from '@xmszm/core/table/utils/ellipsis'
 ```
 
 ## 上传工具
-```js
-import { registryUpload, customUpload, getFileUrl } from 'core'
+```javascript
+import { registryUpload, customUpload, getFileUrl } from '@xmszm/core'
 
 registryUpload((config) => axios.request(config)) // 注册实际上传实现
 await customUpload({ url: '/upload', data: file })
 const url = getFileUrl('/path/to/file', 200) // 拼接 OSS 样式
 ```
 
+## 二维码工具
+
+### useQRCode
+
+在组件中使用二维码弹窗的便捷 Hook。
+
+```javascript
+import { useQRCode } from '@xmszm/core'
+
+const showQRCode = useQRCode()
+
+function handleShowQR(row) {
+  showQRCode(row, async () => {
+    // 返回二维码图片 URL
+    return await getQRCodeImage(row.id)
+  })
+}
+```
+
+### createQRCode
+
+创建二维码弹窗的函数，需要手动传入 Dialog 实例。
+
+```javascript
+import { useDialog } from 'naive-ui'
+import { createQRCode, registerDialogInstance } from '@xmszm/core'
+
+const dialog = useDialog()
+registerDialogInstance(dialog)
+
+// 显示二维码
+await createQRCode(row, async () => {
+  return await getQRCodeImage(row.id)
+})
+```
+
 ## 权限与路由
-- `useAuthPermission(...routeNames)` / `useApiConfig(...routeNames)`：读取路由 meta 中的 `auth` / `api`。
-- `cellectChildenPermission(route)`：合并子路由权限到父节点。
-- `initRouteMeta(routes, base?)`：补全 `meta.title`、`meta.permission`、`sourceFullPath` 等。
-- `handleParams(str, map)`：替换路径参数。
+
+### useAuthPermission / useApiConfig
+
+读取路由 meta 中的 `auth` / `api` 配置。
+
+```javascript
+import { useAuthPermission, useApiConfig } from '@xmszm/core'
+
+// 读取当前路由的 auth 配置
+const auth = useAuthPermission()
+
+// 读取指定路由的 auth 配置
+const auth = useAuthPermission('userList', 'userDetail')
+
+// 读取当前路由的 api 配置
+const api = useApiConfig()
+```
+
+### cellectChildenPermission
+
+合并子路由权限到父节点。
+
+```javascript
+import { cellectChildenPermission } from '@xmszm/core'
+
+const route = cellectChildenPermission(routeConfig)
+```
+
+### initRouteMeta
+
+补全路由 `meta.title`、`meta.permission`、`sourceFullPath` 等。
+
+```javascript
+import { initRouteMeta } from '@xmszm/core'
+
+const routes = initRouteMeta(routes, '/base')
+```
+
+### handleParams
+
+替换路径参数。
+
+```javascript
+import { handleParams } from '@xmszm/core'
+
+const url = handleParams('/api/user/{id}', {
+  '{id}': userId,
+})
+// => '/api/user/123'
+```
+
+## 权限指令
+
+### permissionDirective (v-corePermission)
+
+权限指令，根据权限标识控制元素的显示/隐藏。
+
+```javascript
+import { permissionDirective } from '@xmszm/core'
+
+// 在 main.js 中注册
+app.directive('corePermission', permissionDirective)
+```
+
+### 使用示例
+
+```vue
+<template>
+  <!-- 单个权限 -->
+  <div v-corePermission="'user:edit'">编辑按钮</div>
+  
+  <!-- 多个权限（任一满足即可） -->
+  <div v-corePermission="['user:edit', 'user:view']">需要编辑或查看权限</div>
+</template>
+```
+
+::: tip
+指令会自动调用 `setupConfig` 中配置的 `hasPermission` 函数进行权限检查。如果未配置，默认返回 `true`（会显示警告）。
+:::
 
 ## 数据工具
 - `toArray(value)`：非数组包装成数组。

package/docs/guide/changelog.md

@@ -0,0 +1,81 @@
+---
+title: 版本历史
+---
+
+# 版本历史
+
+本文档记录了 `@xmszm/core` 的所有发布版本及其更新内容。
+
+## 0.0.2
+
+**发布日期**: 2025-12-12
+
+### 新增
+- 完善文档系统，使用 VitePress 构建
+- 添加初始化配置文档，支持 `setupConfig` 和 `setupOptions`
+- 统一配置项说明文档
+
+### 改进
+- 优化文档结构，统一使用表格展示组件 API
+- 提取公共配置项到独立文档
+- 改进代码示例和说明
+
+### 修复
+- 修复文档中的代码高亮问题
+- 修复 GitHub Pages 部署路径问题
+
+---
+
+## 0.0.1
+
+**发布日期**: 2025-12-11
+
+### 新增
+- 初始版本发布
+- 核心组件：`DataForm`、`DataTable`、`CommonQuery`、`Options`
+- 弹窗方法：`commonDialogMethod`
+- 工具函数：上传、权限、路由等
+- 基础样式和类型定义
+
+---
+
+## 如何查看最新版本
+
+你可以通过以下方式查看最新的发布版本：
+
+### npm
+
+```bash
+npm view @xmszm/core version
+```
+
+### 查看所有版本
+
+```bash
+npm view @xmszm/core versions
+```
+
+### 在 package.json 中查看
+
+```json
+{
+  "dependencies": {
+    "@xmszm/core": "^0.0.2"
+  }
+}
+```
+
+---
+
+## 版本说明
+
+- **主版本号**：不兼容的 API 修改
+- **次版本号**：向下兼容的功能性新增
+- **修订版本号**：向下兼容的问题修正
+
+建议使用 `^` 前缀来安装，以自动获取兼容的更新：
+
+```bash
+npm install @xmszm/core@^0.0.2
+```
+