@xmszm/core 0.0.1 → 0.0.3

package/types/index.d.ts

@@ -1,5 +1,30 @@
 import type { Component } from 'vue'
+import type {
+  CommonDialogOptions,
+  DialogAction,
+  DataFormProps,
+  DataFormExpose,
+  CommonQueryProps,
+  CommonQueryEmits,
+  DataTableProps,
+  DataTableExpose,
+  TableColumn,
+  DataTablePagination,
+  FormOption,
+  ActionOption,
+  OptionsProps,
+} from './components'
 
+/**
+ * commonDialogMethod 返回值
+ * 
+ * | 字段名 | 必填 | 类型 | 说明 |
+ * |--------|------|------|------|
+ * | cancel | 是 | () => void | 关闭弹窗方法 |
+ * | setValue | 是 | (v: any, key?: string) => void | 设置表单值方法 |
+ * | model | 是 | any | 表单数据对象（响应式） |
+ * | modeEnum | 是 | Record<string, { sub?: string; read?: boolean }> | 模式枚举对象 |
+ */
 export interface CommonDialogResult {
   cancel(): void
   setValue(v: any, key?: string): void
@@ -7,21 +32,130 @@ export interface CommonDialogResult {
   modeEnum: Record<string, { sub?: string; read?: boolean }>
 }
 
+/**
+ * 通用弹窗方法
+ * 
+ * @param options - 弹窗配置选项，详见 CommonDialogOptions
+ * @param dialogProps - 传递给 NDialog 的属性
+ * @returns CommonDialogResult 弹窗控制对象
+ * 
+ * @example
+ * ```typescript
+ * const { cancel, setValue, model } = commonDialogMethod({
+ *   title: '编辑',
+ *   mode: 'edit',
+ *   options: [
+ *     { key: 'name', label: '名称', way: 'input', required: true },
+ *     { key: 'type', label: '类型', way: 'select', options: [...] }
+ *   ],
+ *   valueData: { name: 'test', type: 'A' },
+ *   interfaceFn: async (data, { close }) => {
+ *     await saveData(data)
+ *     close()
+ *   }
+ * })
+ * ```
+ */
 export function commonDialogMethod(
-  options?: Record<string, any>,
+  options?: CommonDialogOptions,
   dialogProps?: Record<string, any>,
 ): CommonDialogResult
 
-export const DataForm: Component
-export const Options: Component
-export const CommonQuery: Component
-export const DataTable: Component
+// 导出类型定义
+export type {
+  CommonDialogOptions,
+  DialogAction,
+  FormOption,
+  DataFormProps,
+  DataFormExpose,
+  CommonQueryProps,
+  CommonQueryEmits,
+  DataTableProps,
+  DataTableExpose,
+  TableColumn,
+  DataTablePagination,
+  ActionOption,
+  OptionsProps,
+}
+
+/**
+ * DataForm 组件
+ * 
+ * Props 详见 DataFormProps
+ * Expose 详见 DataFormExpose
+ */
+export const DataForm: Component<DataFormProps>
+
+/**
+ * Options 组件（内部组件）
+ * 
+ * Props 详见 OptionsProps
+ */
+export const Options: Component<OptionsProps>
+
+/**
+ * CommonQuery 组件
+ * 
+ * Props 详见 CommonQueryProps
+ * Events 详见 CommonQueryEmits
+ */
+export const CommonQuery: Component<CommonQueryProps>
+
+/**
+ * DataTable 组件
+ * 
+ * Props 详见 DataTableProps
+ * Expose 详见 DataTableExpose
+ */
+export const DataTable: Component<DataTableProps>
+
 export const OprButton: Component
 export const Pop: Component
 
-export function createActionColumnJsx(...args: any[]): any
+/**
+ * 创建操作列
+ * 
+ * @param defaultOption - 操作按钮配置数组，详见 ActionOption
+ * @param oprParams - 操作列额外参数
+ * @param collectParams - 是否收集操作按钮（超过 max 个时收起）
+ * @returns TableColumn 表格列配置对象
+ * 
+ * @example
+ * ```typescript
+ * const opr = createActionColumnJsx([
+ *   {
+ *     label: '编辑',
+ *     type: 'primary',
+ *     onClick: (row) => onEdit(row)
+ *   },
+ *   {
+ *     label: '删除',
+ *     type: 'error',
+ *     mode: 'pop',
+ *     onClick: (row) => onDelete(row)
+ *   }
+ * ])
+ * ```
+ */
+export function createActionColumnJsx(
+  defaultOption: ActionOption[],
+  oprParams?: Record<string, any>,
+  collectParams?: boolean | { max: number; width: number }
+): TableColumn | undefined
+/**
+ * 初始化表单验证规则
+ * 
+ * | 参数名 | 必填 | 类型 | 说明 |
+ * |--------|------|------|------|
+ * | options | 否 | FormOption[] | 表单配置项数组 |
+ * | model | 否 | any | 表单数据对象 |
+ * | labelField | 否 | string | 标签字段名，默认 'label' |
+ * | formOpr | 否 | Record<string, any> | 表单操作对象 |
+ * 
+ * @returns ComputedRef<Record<string, any>> 验证规则对象
+ */
 export function initRules(args: {
-  options?: any[]
+  options?: FormOption[]
   model?: any
   labelField?: string
   formOpr?: Record<string, any>
@@ -65,3 +199,7 @@ declare module 'core/*' {
   export = mod
 }
 
+// 引用类型声明文件
+/// <reference path="./components.d.ts" />
+/// <reference path="./src.d.ts" />
+

package/types/plugin/vite/initRouteMeta.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 初始化路由元数据
+ * 
+ * @param routes - 路由配置数组
+ * @param str - 基础路径字符串，默认为空字符串
+ * @returns 处理后的路由配置数组
+ * 
+ * @example
+ * ```typescript
+ * const routes = [
+ *   {
+ *     path: '/user',
+ *     title: '用户管理',
+ *     children: [
+ *       { path: 'list', title: '用户列表' }
+ *     ]
+ *   }
+ * ]
+ * const processedRoutes = initRouteMeta(routes)
+ * ```
+ */
+export function initRouteMeta(routes: any[], str?: string): any[]
+

package/types/src.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @/ 路径别名类型声明
+ * 
+ * 此文件为 @xmszm/core 包中使用的 @/ 路径别名提供 TypeScript 类型支持
+ * 使用方项目需要提供对应的实现文件
+ * 
+ * @see LOCAL_DEPENDENCIES.md 了解详细的使用说明
+ */
+
+/**
+ * @/utils/permission 模块类型声明
+ * 
+ * 权限检查函数模块
+ * 使用方需要在项目的 src/utils/permission.js 或 src/utils/permission.ts 中实现
+ * 
+ * @example
+ * // src/utils/permission.ts
+ * export function hasPermission(permission: string): boolean {
+ *   const permissions = getPermissions() // 你的权限获取逻辑
+ *   return permissions.includes(permission)
+ * }
+ */
+declare module '@/utils/permission' {
+  /**
+   * 权限检查函数
+   * @param permission - 权限标识字符串
+   * @returns 是否拥有该权限
+   */
+  export function hasPermission(permission: string): boolean
+}
+
+/**
+ * @/utils/request 模块类型声明
+ * 
+ * 请求配置模块
+ * 使用方需要在项目的 src/utils/request.js 或 src/utils/request.ts 中实现
+ * 
+ * @example
+ * // src/utils/request.ts
+ * export const BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:3000'
+ */
+declare module '@/utils/request' {
+  /**
+   * API 基础地址
+   * 用于构建完整的请求 URL
+   */
+  export const BASE_URL: string
+}
+
+// 声明全局 $dialog（如果存在）
+// 外部可以通过 window.$dialog 或直接 $dialog 注入 dialog 实例
+declare global {
+  // eslint-disable-next-line no-var
+  var $dialog: import('naive-ui').DialogApi | undefined
+}

package/types/vue-shim.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Vue 组件类型声明
+ * 为 .vue 文件提供 TypeScript 支持
+ */
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<{}, {}, any>
+  export default component
+}

package/examples/demo.vue

@@ -1,224 +0,0 @@
-<script setup lang="jsx">
-import { computed, onMounted, reactive } from 'vue'
-import { NButton, NCard, NSpace } from 'naive-ui'
-import {
-  commonDialogMethod,
-  CommonQuery,
-  createActionColumnJsx,
-  DataTable,
-} from 'core'
-import 'core/dist/style.css'
-
-// 查询与分页状态（可替换为业务方的 useNaivePage）
-const listQuery = reactive({
-  page: 1,
-  pageSize: 10,
-  desc: true,
-  likeQuery: {
-    name1: '',
-    name2: '',
-    name3: '',
-  },
-})
-
-const pageState = reactive({
-  data: [],
-  itemCount: 0,
-  loading: false,
-  page: computed(() => listQuery.page),
-  pageSize: computed(() => listQuery.pageSize),
-  showSizePicker: true,
-  pageSizes: [10, 20, 50],
-  onUpdatePage: (p) => {
-    listQuery.page = p
-    pageState.fetchData()
-  },
-  onUpdatePageSize: (ps) => {
-    listQuery.pageSize = ps
-    listQuery.page = 1
-    pageState.fetchData()
-  },
-  fetchData: async () => {
-    pageState.loading = true
-    try {
-      // 模拟请求
-      const mock = Array.from({ length: 25 }).map((_, i) => ({
-        id: i + 1,
-        name: `名称-${i + 1}`,
-        type: i % 2 ? 'B' : 'A',
-      }))
-      pageState.itemCount = mock.length
-      const start = (listQuery.page - 1) * listQuery.pageSize
-      const end = start + listQuery.pageSize
-      pageState.data = mock.slice(start, end)
-    }
-    finally {
-      pageState.loading = false
-    }
-  },
-  search: () => {
-    listQuery.page = 1
-    pageState.fetchData()
-  },
-  reset: () => {
-    listQuery.likeQuery = { name1: '', name2: '', name3: '' }
-    listQuery.page = 1
-    pageState.fetchData()
-  },
-})
-
-// 查询项
-const keyQuery = [
-  { label: '名称1', key: 'name1', queryType: 'likeQuery' },
-  { label: '名称2', key: 'name2', queryType: 'likeQuery' },
-  { label: '名称3', key: 'name3', queryType: 'likeQuery' },
-]
-
-// 表格列与操作列
-const columns = [
-  { title: '名称', key: 'name', width: 160 },
-  { title: '类型', key: 'type', width: 120 },
-]
-const defaultColumns = []
-const selectColumns = { type: 'selection', width: '40px' }
-const opr = createActionColumnJsx([
-  {
-    label: '编辑',
-    type: 'primary',
-    onClick: row => onAdd(row, 'edit'),
-  },
-  {
-    label: '删除',
-    type: 'error',
-    mode: 'pop',
-    onClick: (row) => {
-      // del(row.id).then(() => pageState.fetchData())
-      console.log('删除', row)
-    },
-  },
-])
-
-// 弹窗新增/编辑
-function onAdd(row = null, mode = 'add') {
-  commonDialogMethod({
-    title: '示例弹窗',
-    mode,
-    options: [
-      { key: 'name', label: '名称', way: 'input', required: true },
-      {
-        key: 'type',
-        label: '类型',
-        way: 'select',
-        options: [
-          { label: '类型A', value: 'A' },
-          { label: '类型B', value: 'B' },
-        ],
-      },
-    ],
-    valueData: { ...row },
-    interfaceFn: async (data, { close }) => {
-      console.log('提交数据', data)
-      // await save(data)
-      pageState.fetchData()
-      close()
-    },
-  })
-}
-
-// 导出示例
-const exportLoading = reactive({ value: false })
-function onExport() {
-  exportLoading.value = true
-  // exportApi(listQuery).finally(() => (exportLoading.value = false))
-  setTimeout(() => (exportLoading.value = false), 800)
-}
-
-onMounted(() => pageState.fetchData())
-</script>
-
-<template>
-  <div class="page-box">
-    <!-- 头部筛选 -->
-    <NCard class="page-head">
-      <CommonQuery
-        :query="listQuery"
-        :options="keyQuery"
-        @submit="pageState.search()"
-        @reset="pageState.reset()"
-      />
-    </NCard>
-
-    <!-- 操作区 -->
-    <NSpace justify="space-between">
-      <NSpace>
-        <NButton type="primary" @click="onAdd()">新增</NButton>
-        <NButton type="primary" :loading="exportLoading.value" @click="onExport">
-          导出
-        </NButton>
-      </NSpace>
-    </NSpace>
-
-    <!-- 内容表格区 -->
-    <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>
-

package/src/dialog/commonDialog.jsx

@@ -1,230 +0,0 @@
-import { NButton, NSpace } from 'naive-ui'
-import { computed, reactive, ref, unref, watch } from 'vue'
-import DataForm from '../form/DataForm.vue'
-import { dialogDefaultOption } from './utils/dialog'
-import './style/commonDialog.less'
-
-/**
- *
- * @param {*} param
- * @param {object} dialogProps
- * @returns {object {cancel,model}}
- * 集成填写表单功能的弹窗
- */
-export function commonDialogMethod(
-  {
-    title = '',
-    noTitle = false,
-    titleFull = null,
-    options = [],
-    mode = 'add',
-    modeEnum = {},
-    labelField = 'label',
-    isNo = true,
-    formProps = {},
-    interfaceFn = null,
-    interfaceFnCancel = null,
-    valueData,
-    read,
-    isRead,
-    action = null,
-    contentStyle = {},
-    actionProps = {},
-  } = {
-    title: '自定义弹窗',
-    noTitle: false,
-    action: [],
-    options: [],
-    read: false,
-    isRead: false,
-    valueData: {},
-  },
-  dialogProps = null,
-) {
-  const defaultModeEnum = {
-    none: { sub: '', read: false },
-    create: { sub: '创建', read: false },
-    add: { sub: '添加', read: false },
-    edit: { sub: '编辑', read: false },
-    view: { sub: '查看', read: true },
-    export: { sub: '导出', read: false },
-    import: { sub: '导入', read: false },
-    delete: { sub: '删除', read: false },
-    copy: { sub: '复制', read: false },
-    ...modeEnum,
-  }
-  const formRef = ref()
-  const actionLoading = reactive([])
-  const model = ref({ ...valueData })
-  const defaultActionProps = {
-    justify: 'end',
-    wrapItem: false,
-    style: {
-      width: '100%',
-    },
-  }
-
-  const defaultButtonStyle = {
-    width: '120px',
-  }
-  const defaultAction = [
-    {
-      label: '取消',
-      props: {
-        type: 'primary',
-        ghost: true,
-      },
-      onClick: ({ cancel }) => {
-        if (interfaceFnCancel) {
-          interfaceFnCancel(unref(model), {
-            close: cancel,
-          })
-        }else {
-          cancel()
-        }
-      },
-    },
-    {
-      label: '确定',
-      valid: true,
-      onClick: async ({ cancel, hideLoading }) =>
-        interfaceFn
-          ? await interfaceFn(unref(model), {
-            close: cancel,
-            hideLoading,
-          })
-          : cancel(),
-    },
-  ]
-
-  action
-  || defaultAction.forEach((v, i) => {
-    actionLoading[i] = false
-  })
-  const titleRender
-    = typeof titleFull === 'function'
-      ? () => titleFull(defaultModeEnum[mode]?.sub)
-      : titleFull
-
-  const d = $dialog.create({
-    type: 'info',
-    ...dialogDefaultOption,
-    ...(!noTitle
-      ? { title: titleRender || (defaultModeEnum[mode]?.sub ?? '') + title }
-      : {}),
-    style: {
-      width: '500px',
-    },
-    content: () => (
-      <DataForm
-        ref={v => {
-          formRef.value = v
-        }}
-        options={options}
-        v-model:value={model.value}
-        isNo={isNo}
-        read={read ?? isRead}
-        labelField={labelField}
-        formProps={formProps}
-        contentStyle={contentStyle}
-        dialog
-      />
-    ),
-    action: !(read ?? isRead)
-      ? typeof action === 'function'
-        ? () => action({ formRef, data: unref(model), d, close: cancel })
-        : () => (
-            <NSpace
-              {...defaultActionProps}
-              {...actionProps}
-              style={{
-                ...defaultActionProps?.style,
-                ...(actionProps?.style || {}),
-              }}
-            >
-              {(action || defaultAction).map((v, i) =>
-                v?.render
-                  ? (
-                      v?.render?.()
-                    )
-                  : (
-                      <NButton
-                        type="primary" ghost={v.mode === 'cancel'} {...({ ...v?.props, ...actionProps?.buttonProps } || {})}
-                        style={{ ...defaultButtonStyle, ...(v?.style || {}) }}
-                        loading={actionLoading[i]}
-                        onClick={async () => {
-                          if (v.mode === 'cancel') {
-                            d.destroy()
-                          }
-                          else {
-                            const showLoading = () => (actionLoading[i] = true)
-                            const hideLoading = () => (actionLoading[i] = false)
-                            if (v?.loading)
-                              showLoading()
-                            try {
-                              console.log('model', unref(model));
-                              
-                              if (v?.valid)
-                                await validate()
-                              console.log(v?.valid)
-                              if (v?.valid || v?.loading)
-                                showLoading()
-                              await v?.onClick({
-                                model: unref(model),
-                                comfirm,
-                                cancel,
-                                validate,
-                                showLoading,
-                                hideLoading,
-                              })
-                            }
-                            catch (e) {
-                              console.log(e)
-                            }
-                            finally {
-                              if (v?.valid || v?.loading)
-                                hideLoading()
-                            }
-                          }
-                        }}
-                      >
-                        {v.label || ''}
-                      </NButton>
-                    ),
-              )}
-            </NSpace>
-          )
-      : null,
-    // ...readButton.value,
-    ...dialogProps,
-    class: `core-dialog ${ unref(read) ? 'core-dialog-read' : ''} ${dialogProps?.class || ''}`,
-  })
-
-  function cancel() {
-    console.log('取消', model.value)
-
-    d?.destroy()
-  }
-
- async function validate(arr = []) {
-    console.log('开启验证')
-     await formRef.value?.valid()
-  }
-
-  async function comfirm(fn) {
-    return fn && fn()
-  }
-
-  // onBeforeUnmount(() => {
-  //   console.log('commomDialog end')
-  //   cancel()
-  // })
-
-  return {
-    cancel,
-    setValue: (v, str) =>
-      str ? (model.value[str] = v) : (model.value = { ...model.value, ...v }),
-    model: unref(model),
-    modeEnum: defaultModeEnum,
-  }
-}