@xmszm/core 0.0.1 → 0.0.3

package/docs/guide/config.md

@@ -0,0 +1,415 @@
+---
+title: 初始化配置
+---
+
+# 初始化配置
+
+`@xmszm/core` 提供了统一的初始化配置系统，用于管理外部依赖、业务配置和自定义选项注册。
+
+## 配置概览
+
+| 配置项 | 说明 | 相关文档 |
+|--------|------|----------|
+| `setupConfig` | 全局配置（baseURL、权限、上传等） | 见下方说明 |
+| `setupOptions` | 注册自定义 Options 控件类型 | 见 [Options 注册](#options-注册) |
+| `registerDialogInstance` | 注册 Dialog 实例（可选） | 见 [Dialog 配置](#dialog-配置) |
+
+## setupConfig - 全局配置
+
+`setupConfig` 用于配置全局设置，包括 API 地址、权限检查、上传方法等。
+
+在应用启动时，使用 `setupConfig` 进行统一配置：
+
+```javascript
+import { setupConfig } from '@xmszm/core'
+import axios from 'axios'
+
+// 初始化配置
+setupConfig({
+  // API 基础地址（用于文件 URL 拼接）
+  baseURL: 'https://api.example.com',
+  
+  // 权限检查函数
+  hasPermission: (permission) => {
+    // 你的权限检查逻辑
+    const permissions = getPermissions() // 从 store、context 等获取权限列表
+    return permissions.includes(permission)
+  },
+  
+  // 上传方法
+  uploadMethod: (config) => {
+    // 你的上传实现
+    return axios.request(config)
+  }
+})
+```
+
+## 配置项说明
+
+### baseURL
+
+API 基础地址，用于 `getFileUrl` 函数拼接文件 URL。
+
+```javascript
+import { setupConfig, getFileUrl } from '@xmszm/core'
+
+setupConfig({
+  baseURL: 'https://api.example.com'
+})
+
+// 使用
+const url = getFileUrl('/images/avatar.jpg')
+// => 'https://api.example.com/images/avatar.jpg'
+```
+
+### hasPermission
+
+权限检查函数，用于表格操作列的权限过滤。
+
+```javascript
+import { setupConfig } from '@xmszm/core'
+
+setupConfig({
+  hasPermission: (permission) => {
+    // 从 Vuex/Pinia store 获取权限
+    const store = useStore()
+    return store.state.permissions.includes(permission)
+    
+    // 或从 localStorage 获取
+    // const permissions = JSON.parse(localStorage.getItem('permissions') || '[]')
+    // return permissions.includes(permission)
+  }
+})
+
+// 在 createActionColumnJsx 中使用
+const opr = createActionColumnJsx([
+  {
+    label: '编辑',
+    permission: 'user:edit', // 会调用 hasPermission('user:edit')
+    onClick: (row) => edit(row)
+  }
+])
+```
+
+### uploadMethod
+
+上传方法实现，用于 `customUpload` 函数。
+
+```javascript
+import { setupConfig, customUpload } from '@xmszm/core'
+import axios from 'axios'
+
+setupConfig({
+  uploadMethod: (config) => {
+    return axios.request({
+      ...config,
+      headers: {
+        'Authorization': `Bearer ${getToken()}`,
+        ...config.headers
+      }
+    })
+  }
+})
+
+// 使用
+await customUpload({
+  url: '/upload',
+  method: 'POST',
+  data: formData
+})
+```
+
+## 兼容旧版 API
+
+为了向后兼容，仍然支持旧的 API：
+
+```javascript
+import { registryUpload } from '@xmszm/core'
+
+// 旧版方式（仍然可用，但不推荐）
+registryUpload((config) => axios.request(config))
+```
+
+## 获取配置
+
+如果需要获取当前配置：
+
+```javascript
+import { getConfig, getBaseURL, getHasPermission, getUploadMethod } from '@xmszm/core'
+
+// 获取所有配置
+const config = getConfig()
+
+// 获取单个配置
+const baseURL = getBaseURL()
+const hasPermission = getHasPermission()
+const uploadMethod = getUploadMethod()
+```
+
+## 完整示例
+
+```javascript
+// main.js
+import { createApp } from 'vue'
+import { setupConfig } from '@xmszm/core'
+import App from './App.vue'
+import axios from 'axios'
+import { useStore } from './store'
+
+const app = createApp(App)
+
+// 配置库
+setupConfig({
+  baseURL: import.meta.env.VITE_API_BASE_URL || 'http://localhost:3000',
+  
+  hasPermission: (permission) => {
+    const store = useStore()
+    return store.state.user.permissions?.includes(permission) ?? false
+  },
+  
+  uploadMethod: (config) => {
+    return axios.request({
+      ...config,
+      headers: {
+        'Authorization': `Bearer ${localStorage.getItem('token')}`,
+        ...config.headers
+      }
+    })
+  }
+})
+
+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/demo.md

@@ -14,7 +14,7 @@ npm install
 ```
 
 2) 在你的宿主工程中引入该组件文件（或复制内容），确保存在以下 alias：
-```js
+```javascript
 // vite / webpack 示例
 resolve: {
   alias: {
@@ -55,7 +55,7 @@ import {
   CommonQuery,
   createActionColumnJsx,
   DataTable,
-} from 'core'
+} from '@xmszm/core'
 
 // 列表数据与查询管理
 const { pageState, listQuery } = useNaivePage(() => {

package/docs/guide/local-development.md

@@ -0,0 +1,109 @@
+# 本地开发配置
+
+## npm/pnpm link 时的路径解析问题
+
+当使用 `npm link` 或 `pnpm link` 进行本地开发时，Vite 可能无法正确解析链接包的路径。这是因为：
+
+1. **符号链接解析问题**：npm/pnpm link 创建的是符号链接，Vite 的模块解析在处理符号链接时可能失败
+2. **package.json exports**：链接包的 `exports` 字段路径解析可能不生效
+3. **CSS 文件路径**：样式文件的路径解析尤其容易出问题
+
+## 最小化配置方案
+
+在测试项目的 `vite.config.js` 中添加以下配置即可：
+
+```javascript
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import vueJsx from '@vitejs/plugin-vue-jsx'
+import path from 'path'
+
+export default defineConfig({
+  plugins: [vue(), vueJsx()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, 'src'),
+      // 解决 npm/pnpm link 时的路径解析问题
+      '@xmszm/core': path.resolve(__dirname, '..'), // 指向库项目根目录
+      '@xmszm/core/dist/style.css': path.resolve(__dirname, '../dist/style.css'),
+    },
+  },
+  server: {
+    port: 3000,
+    open: true
+  }
+})
+```
+
+## 为什么需要这个配置？
+
+### 问题 1: 模块无法解析
+
+**错误信息**：
+```
+Failed to resolve import "@xmszm/core" from "src/App.vue"
+```
+
+**原因**：
+- npm/pnpm link 创建的符号链接路径可能无法被 Vite 正确识别
+- 链接路径如 `link:C:/Users/admin/AppData/Local/pnpm/global/5/node_modules/@xmszm/core` 可能解析失败
+
+**解决方案**：
+```javascript
+'@xmszm/core': path.resolve(__dirname, '..')
+```
+直接指向源项目根目录，绕过符号链接解析问题。
+
+### 问题 2: 样式文件无法解析
+
+**错误信息**：
+```
+Failed to resolve import "@xmszm/core/dist/style.css"
+```
+
+**原因**：
+- CSS 文件的路径解析在链接包中更容易失败
+- `exports` 字段对 CSS 文件的处理可能不一致
+
+**解决方案**：
+```javascript
+'@xmszm/core/dist/style.css': path.resolve(__dirname, '../dist/style.css')
+```
+直接指向源项目的样式文件。
+
+## 生产环境使用
+
+在生产环境中（通过 npm 安装），**不需要**这些配置，因为：
+
+1. 正常安装的包路径解析没有问题
+2. `package.json` 的 `exports` 字段会正确工作
+3. Vite 可以正确解析 `node_modules` 中的包
+
+## 完整示例
+
+```javascript
+// vite.config.js
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import vueJsx from '@vitejs/plugin-vue-jsx'
+import path from 'path'
+
+export default defineConfig({
+  plugins: [vue(), vueJsx()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, 'src'),
+      // 仅在使用 npm/pnpm link 时需要
+      '@xmszm/core': path.resolve(__dirname, '..'),
+      '@xmszm/core/dist/style.css': path.resolve(__dirname, '../dist/style.css'),
+    },
+  },
+})
+```
+
+## 注意事项
+
+1. **仅本地开发需要**：这个配置只在本地开发（使用 link）时需要
+2. **相对路径**：`path.resolve(__dirname, '..')` 假设测试项目在库项目的 `test-app` 目录下
+3. **路径调整**：如果目录结构不同，需要相应调整路径
+

package/docs/guide/quickstart.md

@@ -5,27 +5,47 @@ title: 快速开始
 ## 安装
 
 ```bash
-npm install core
+npm install @xmszm/core
+# 或
+pnpm add @xmszm/core
+# 或
+yarn add @xmszm/core
 ```
 
 同时请在项目中安装（或确保已存在）以下 peer 依赖（版本可按你项目统一）：
 
-- vue 3.x
-- naive-ui
-- vue-router
-- dayjs
-- lodash-es
-- @vicons/ionicons5
+- `vue` >= 3.3.0
+- `naive-ui` >= 2.38.0
+- `vue-router` >= 4.2.0
+- `dayjs` >= 1.11.0
+- `lodash-es` >= 4.17.21
+- `@vicons/ionicons5` >= 0.13.0
 
 > 若项目使用 `@` 路径别名，请确认在构建/运行配置中存在相同的 alias。
 
 ## 引入与基本使用
 
+### 全局引入样式（推荐）
+
+在项目的入口文件（如 `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 'core'
-import 'core/dist/style.css' // 如需默认样式
+import { DataForm, DataTable, commonDialogMethod } from '@xmszm/core'
+// 如果已在全局引入样式，这里无需重复引入
 
 const formValue = ref({})
 const formOptions = [
@@ -62,16 +82,25 @@ function openDialog() {
 
 ## 目录结构建议
 
-```
+```text
 docs/                # VitePress 文档
 examples/demo.vue    # 可运行的最小示例
 src/                 # 组件与工具源码
 types/               # 类型定义
 ```
 
+## 初始化配置（可选）
+
+如果需要配置全局设置或注册自定义控件类型，详见 [初始化配置](/guide/config)：
+
+- **全局配置**：使用 `setupConfig` 配置 API 地址、权限检查、上传方法等
+- **自定义控件**：使用 `setupOptions` 注册自定义 `Options` 控件类型
+- **Dialog 配置**：使用 `registerDialogInstance` 注册 Dialog 实例（可选）
+
 ## 常见问题
 
 - 找不到 `@/utils/...`：请在宿主项目配置 `@` 别名或提供对应实现。
-- 样式缺失：如需库内 less 默认样式，确保引入 `core/dist/style.css`。
+- 样式缺失：如需库内 less 默认样式，确保引入 `@xmszm/core/dist/style.css`。**推荐在全局入口文件（如 `main.js`）中引入，这样整个项目都可以使用默认样式，无需在每个组件中重复引入。**
 - TS 类型：库内已内置 `types/index.d.ts`，可直接获得基础提示。
+- 自定义控件：可以通过 `setupOptions` 注册自定义控件类型，详见 [初始化配置](/guide/config)。
 

package/docs/index.md

@@ -1,8 +1,8 @@
 ---
 layout: home
-title: Nex Core
+title: '@xmszm/core'
 hero:
-  name: Nex Core
+  name: '@xmszm/core'
   text: Vue 3 + Naive UI 的表单、表格、弹窗与工具集合
   tagline: 开箱即用的配置式表单与表格方案，内置弹窗、上传、权限、路由工具。
   actions:
@@ -16,7 +16,7 @@ features:
   - title: 配置化表单
     details: 通过 Options 定义字段，自动生成 rules，轻松构建复杂表单。
   - title: 表格增强
-    details: 内置操作列创建器、排序、筛选、虚拟滚动与省略 tooltip。
+    details: 内置操作列创建器、筛选、虚拟滚动与省略 tooltip。
   - title: 弹窗集成
     details: commonDialogMethod 将表单与弹窗能力合并，减少样板代码。
   - title: 实用工具

package/docs/usage.md

@@ -2,18 +2,41 @@
 
 ## 安装
 ```bash
-npm install core
+npm install @xmszm/core
+# 或
+pnpm add @xmszm/core
+# 或
+yarn add @xmszm/core
 ```
 
-需要同时安装的 peer 依赖（版本可按项目统一）：`vue`、`naive-ui`、`vue-router`、`dayjs`、`lodash-es`、`@vicons/ionicons5`。  
+需要同时安装的 peer 依赖（版本可按项目统一）：
+- `vue` >= 3.3.0
+- `naive-ui` >= 2.38.0
+- `vue-router` >= 4.2.0
+- `dayjs` >= 1.11.0
+- `lodash-es` >= 4.17.21
+- `@vicons/ionicons5` >= 0.13.0
+
 如项目使用 `@` 别名，请确保存在对应的打包/运行时配置。
 
 ## 快速开始
+
+### 全局引入样式（推荐）
+
+在项目的入口文件中全局引入样式：
+
+```javascript
+// main.js 或 main.ts
+import '@xmszm/core/dist/style.css'
+```
+
+### 组件中使用
+
 ```vue
 <script setup>
 import { ref } from 'vue'
-import { DataForm, DataTable, commonDialogMethod } from 'core'
-import 'core/dist/style.css' // 如需默认样式
+import { DataForm, DataTable, commonDialogMethod } from '@xmszm/core'
+// 如果已在全局引入样式，这里无需重复引入
 
 const formValue = ref({})
 const formOptions = [
@@ -50,12 +73,13 @@ function openDialog() {
 
 ## 主要导出清单
 - 组件：`DataForm`、`Options`、`CommonQuery`、`DataTable`、`OprButton`、`Pop`
-- 方法：`commonDialogMethod`、`createActionColumnJsx`、`initRules`
+- 方法：`commonDialogMethod`、`createActionColumnJsx`、`initRules`（用于自动生成表单校验规则）
 - 工具：`toArray`、`ArrayToObject`、`ObjectToArray`、`customUpload`、`registryUpload`、`getFileUrl`
-- 常量：`orderEnum`、`globalLabelField`、`globalValueField`
+- 常量：`globalLabelField`（默认 `'name'`）、`globalValueField`（默认 `'id'`）
 - 路由辅助：`initRouteMeta`、`useApiConfig`、`useAuthPermission`、`cellectChildenPermission`
 
 ## 常见提示
 - 若打包时报 `@/utils/...` 未找到，请在宿主项目配置 `@` 路径或提供对应实现。
+- **样式引入**：推荐在全局入口文件（`main.js` 或 `main.ts`）中引入 `@xmszm/core/dist/style.css`，这样整个项目都可以使用默认样式，无需在每个组件中重复引入。
 - Vue TS 项目可直接使用内置 `types/index.d.ts` 获取基础类型提示。