@xmszm/core 0.0.2 → 0.0.3

package/docs/components/options.md

@@ -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

@@ -73,23 +73,31 @@ function handleReset() {
 ```
 
 ## 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,11 +2,13 @@
 title: 工具与常量
 ---
 
-## 操作列 / 排序 / 省略
+## 操作列 / 省略
 
 ### createActionColumnJsx
 快速生成表格操作列。
 
+配置项说明详见 [createActionColumnJsx 配置](/components/config-options#createactioncolumnjsx-配置)。
+
 ```javascript
 import { createActionColumnJsx } from '@xmszm/core'
 
@@ -20,11 +22,6 @@ const oprColumn = createActionColumnJsx(
 )
 ```
 
-### orderEnum（表格内部用）
-- 来源：`src/enum/sort.jsx`，通过 `DataTable` 列的 `sorter` 使用。
-- 功能：提供升序/降序/默认三态的图标与处理函数，修改 `listQuery` 的排序字段并配合重新拉取数据。
-- 注意：离开 `DataTable` 排序场景单独调用无意义；详细示例见 `DataTable` 文档中的排序段落。
-
 ### ellipsis
 表格省略 tooltip 配置：
 ```javascript
@@ -40,11 +37,122 @@ 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
+```
+

package/docs/guide/config.md

@@ -1,10 +1,22 @@
-# 配置指南
+---
+title: 初始化配置
+---
 
-## 统一配置系统
+# 初始化配置
 
-`@xmszm/core` 提供了统一的配置系统，用于管理外部依赖和业务配置。
+`@xmszm/core` 提供了统一的初始化配置系统，用于管理外部依赖、业务配置和自定义选项注册。
 
-## 初始化配置
+## 配置概览
+
+| 配置项 | 说明 | 相关文档 |
+|--------|------|----------|
+| `setupConfig` | 全局配置（baseURL、权限、上传等） | 见下方说明 |
+| `setupOptions` | 注册自定义 Options 控件类型 | 见 [Options 注册](#options-注册) |
+| `registerDialogInstance` | 注册 Dialog 实例（可选） | 见 [Dialog 配置](#dialog-配置) |
+
+## setupConfig - 全局配置
+
+`setupConfig` 用于配置全局设置，包括 API 地址、权限检查、上传方法等。
 
 在应用启动时，使用 `setupConfig` 进行统一配置：
 
@@ -169,10 +181,235 @@ setupConfig({
 app.mount('#app')
 ```
 
+## Options 注册（setupOptions） {#options-注册}
+
+`setupOptions` 允许你注册自定义的控件类型，扩展 `Options` 组件的功能。
+
+### 基础用法
+
+```javascript
+import { setupOptions } from '@xmszm/core'
+import { NCascader } from 'naive-ui'
+
+// 注册一个级联选择器控件
+setupOptions('cascader', (item, { _value, _isRead, labelField, valueField }) => {
+  const { key, label, props, options = [] } = item
+  
+  return _isRead ? (
+    <div>{_value[key]}</div>
+  ) : (
+    <NCascader
+      v-model:value={_value[key]}
+      options={options}
+      placeholder={`请选择${label}`}
+      {...props}
+    />
+  )
+})
+```
+
+### 注册参数说明
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `key` | `string` | 控件类型标识，如 `'cascader'`、`'customInput'` 等。注意：不能与内置类型重复（如 `input`、`select` 等） |
+| `fn` | `Function` | 渲染函数，接收两个参数：<br/>1. `item`: 配置项对象（包含 `key`、`label`、`props`、`options` 等）<br/>2. `context`: 上下文对象 `{ _value, _isRead, labelField, valueField, _formRef }`<br/><br/>函数应返回一个 VNode 或 JSX 元素 |
+
+### 使用自定义控件
+
+注册后，在 `options` 配置中使用 `way` 字段指定你注册的类型：
+
+```javascript
+const options = [
+  { key: 'region', label: '地区', way: 'cascader', options: regionOptions },
+  { key: 'custom', label: '自定义', way: 'customInput' },
+]
+```
+
+### 完整示例
+
+```javascript
+// main.js
+import { createApp } from 'vue'
+import { setupOptions, setupConfig } from '@xmszm/core'
+import { NCascader, NColorPicker } from 'naive-ui'
+import App from './App.vue'
+
+// 注册级联选择器控件
+setupOptions('cascader', (item, { _value, _isRead }) => {
+  const { key, label, props, options = [] } = item
+  return _isRead ? (
+    <div>{_value[key]}</div>
+  ) : (
+    <NCascader
+      v-model:value={_value[key]}
+      options={options}
+      placeholder={`请选择${label}`}
+      {...props}
+    />
+  )
+})
+
+// 注册颜色选择器控件
+setupOptions('colorPicker', (item, { _value, _isRead }) => {
+  const { key, props } = item
+  return _isRead ? (
+    <div style={{ 
+      width: '20px', 
+      height: '20px', 
+      backgroundColor: _value[key],
+      border: '1px solid #ccc'
+    }} />
+  ) : (
+    <NColorPicker
+      v-model:value={_value[key]}
+      {...props}
+    />
+  )
+})
+
+// 其他全局配置
+setupConfig({
+  baseURL: 'https://api.example.com',
+  // ... 其他配置
+})
+
+const app = createApp(App)
+app.mount('#app')
+```
+
+### 使用自定义控件
+
+注册后，在 `DataForm`、`CommonQuery`、`Options` 等组件的 `options` 配置中使用：
+
+```javascript
+const formOptions = [
+  { key: 'region', label: '地区', way: 'cascader', options: regionData },
+  { key: 'theme', label: '主题色', way: 'colorPicker' },
+]
+```
+
+### getAllOptions / getOptions
+
+获取已注册的 Options 控件。
+
+```javascript
+import { getAllOptions, getOptions } from '@xmszm/core'
+
+// 获取所有已注册的 Options
+const allOptions = getAllOptions()
+// => { input: fn, select: fn, cascader: fn, ... }
+
+// 获取指定的 Options
+const specificOptions = getOptions(['input', 'select'])
+// => { input: fn, select: fn }
+```
+
+::: tip
+这些方法主要用于调试或高级用法，一般不需要直接调用。
+:::
+
+## Dialog 配置 {#dialog-配置}
+
+### registerDialogInstance
+
+可选配置，用于注册外部 Dialog 实例。如果不注册，库会自动尝试获取。
+
+```javascript
+import { registerDialogInstance, useDialog } from '@xmszm/core'
+import { useDialog as useNaiveDialog } from 'naive-ui'
+
+// 在组件中注册
+const dialog = useNaiveDialog()
+registerDialogInstance(dialog)
+```
+
+### Dialog 主题配置
+
+```javascript
+import { setupConfig } from '@xmszm/core'
+
+setupConfig({
+  dialog: {
+    // 是否继承外部定义的主题色（默认 true）
+    inheritTheme: true,
+    // 主题色覆盖（当 inheritTheme 为 false 时使用）
+    themeOverrides: {
+      // 自定义主题色配置
+    }
+  }
+})
+```
+
+## 插件和指令
+
+### CorePlugin / install
+
+库插件，用于注册指令等全局功能。
+
+```javascript
+import { createApp } from 'vue'
+import { CorePlugin } from '@xmszm/core'
+import App from './App.vue'
+
+const app = createApp(App)
+
+// 使用插件（会自动注册所有指令）
+app.use(CorePlugin)
+
+app.mount('#app')
+```
+
+或者使用 `install` 函数：
+
+```javascript
+import { install } from '@xmszm/core'
+
+app.use({ install })
+```
+
+### registerDirectives
+
+手动注册所有指令到应用实例。
+
+```javascript
+import { registerDirectives } from '@xmszm/core'
+
+registerDirectives(app)
+```
+
+### autoRegisterDirectives
+
+尝试自动注册指令（通过 `getCurrentInstance` 获取应用实例）。
+
+```javascript
+import { autoRegisterDirectives } from '@xmszm/core'
+
+// 在组件中调用
+autoRegisterDirectives()
+```
+
+### getGlobalApp
+
+获取全局应用实例（如果已通过 `registerDirectives` 注册）。
+
+```javascript
+import { getGlobalApp } from '@xmszm/core'
+
+const app = getGlobalApp()
+```
+
+::: tip
+通常不需要手动调用这些函数，使用 `CorePlugin` 或 `install` 即可自动注册所有指令。
+:::
+
 ## 注意事项
 
 1. **配置时机**：建议在应用启动时（如 `main.js`）进行配置
 2. **权限检查**：如果未配置 `hasPermission`，默认返回 `true`（会显示警告）
 3. **BASE_URL**：如果未配置 `baseURL`，`getFileUrl` 会返回原始 URL（会显示警告）
 4. **上传方法**：如果未配置 `uploadMethod`，调用 `customUpload` 会抛出错误
+5. **Options 注册**：`setupOptions` 应在使用相关组件之前注册，建议在 `main.js` 中统一注册
+6. **Dialog 实例**：`registerDialogInstance` 是可选的，库会自动尝试获取，仅在特殊场景下需要手动注册
+7. **插件使用**：推荐使用 `CorePlugin` 或 `install` 自动注册指令，无需手动调用 `registerDirectives`
 

package/docs/guide/quickstart.md

@@ -25,11 +25,27 @@ yarn add @xmszm/core
 
 ## 引入与基本使用
 
+### 全局引入样式（推荐）
+
+在项目的入口文件（如 `main.js` 或 `main.ts`）中全局引入样式：
+
+```javascript
+// main.js 或 main.ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import '@xmszm/core/dist/style.css' // 全局引入样式
+
+const app = createApp(App)
+app.mount('#app')
+```
+
+### 组件中使用
+
 ```vue
 <script setup>
 import { ref } from 'vue'
 import { DataForm, DataTable, commonDialogMethod } from '@xmszm/core'
-import '@xmszm/core/dist/style.css' // 如需默认样式
+// 如果已在全局引入样式，这里无需重复引入
 
 const formValue = ref({})
 const formOptions = [
@@ -73,9 +89,18 @@ src/                 # 组件与工具源码
 types/               # 类型定义
 ```
 
+## 初始化配置（可选）
+
+如果需要配置全局设置或注册自定义控件类型，详见 [初始化配置](/guide/config)：
+
+- **全局配置**：使用 `setupConfig` 配置 API 地址、权限检查、上传方法等
+- **自定义控件**：使用 `setupOptions` 注册自定义 `Options` 控件类型
+- **Dialog 配置**：使用 `registerDialogInstance` 注册 Dialog 实例（可选）
+
 ## 常见问题
 
 - 找不到 `@/utils/...`：请在宿主项目配置 `@` 别名或提供对应实现。
-- 样式缺失：如需库内 less 默认样式，确保引入 `@xmszm/core/dist/style.css`。
+- 样式缺失：如需库内 less 默认样式，确保引入 `@xmszm/core/dist/style.css`。**推荐在全局入口文件（如 `main.js`）中引入，这样整个项目都可以使用默认样式，无需在每个组件中重复引入。**
 - TS 类型：库内已内置 `types/index.d.ts`，可直接获得基础提示。
+- 自定义控件：可以通过 `setupOptions` 注册自定义控件类型，详见 [初始化配置](/guide/config)。
 

package/docs/index.md

@@ -16,7 +16,7 @@ features:
   - title: 配置化表单
     details: 通过 Options 定义字段，自动生成 rules，轻松构建复杂表单。
   - title: 表格增强
-    details: 内置操作列创建器、排序、筛选、虚拟滚动与省略 tooltip。
+    details: 内置操作列创建器、筛选、虚拟滚动与省略 tooltip。
   - title: 弹窗集成
     details: commonDialogMethod 将表单与弹窗能力合并，减少样板代码。
   - title: 实用工具