@wg-song/bare 0.1.0 → 0.1.1

package/AGENTS.md

@@ -13,12 +13,23 @@
 接入项目的 `main.ts` 通常已包含：
 
 ```ts
+import { createApp } from 'vue'
+import VXETable from 'vxe-table'
+import VXEPcUI from 'vxe-pc-ui'
 import BareComponents from '@wg-song/bare'
+import 'vxe-table/lib/style.css'
+import 'vxe-pc-ui/lib/style.css'
 import '@wg-song/bare/index.css'
 
+const app = createApp(App)
+app.use(VXEPcUI)
+app.use(VXETable)
 app.use(BareComponents)
+app.mount('#app')
 ```
 
+**顺序要求**：必须先 `app.use(VXETable)` / `app.use(VXEPcUI)`，再 `app.use(BareComponents)`。若未注册 `vxe-table`，表格组件会报 `Failed to resolve component: vxe-grid`。
+
 因此业务页面中直接使用组件即可，无需再次安装或注册。
 
 ## 3. 组件选择速查表
@@ -165,7 +176,16 @@ function handleDetail(row: any) {
 }
 ```
 
-## 5. 类型导入清单
+## 5. 首次接入检查清单
+
+在业务页面引用组件前，请确认：
+
+1. `main.ts` 已 `app.use(VXETable)` 并引入 `vxe-table/lib/style.css`。
+2. 若使用 vxe-table 高级 UI 能力（tooltip、loading、筛选面板），已 `app.use(VXEPcUI)` 并引入 `vxe-pc-ui/lib/style.css`。
+3. 已 `import '@wg-song/bare/index.css'`。
+4. `package.json` 中 `@wg-song/bare` 的 peer dependencies 已满足（vue、ant-design-vue、vxe-table、@ant-design/icons-vue、vue-router）。
+
+## 6. 类型导入清单
 
 ```ts
 import type {

package/README.md

@@ -8,95 +8,103 @@
 pnpm add @wg-song/bare
 ```
 
-Peer dependencies（需由接入应用提供）：
+Peer dependencies（必需，由接入应用提供）：
 
 ```json
 {
   "vue": "^3.0.0",
   "ant-design-vue": "^4.0.0",
   "vxe-table": "^4.0.0",
-  "vxe-pc-ui": "^4.0.0",
   "@ant-design/icons-vue": "^7.0.0",
-  "vue-router": "^4.0.0"
+  "vue-router": "^4.0.0 || ^5.0.0"
 }
 ```
 
+推荐一并安装（以获得完整 vxe-table 体验）：
+
+```bash
+pnpm add vxe-pc-ui
+```
+
+> `vxe-pc-ui` 是 `vxe-table` 的配套 UI 包，提供 tooltip、loading、筛选面板等能力。本库表格组件默认使用 `showOverflow: 'title'` 避免强依赖，不强制要求 `vxe-pc-ui`；但建议接入方一并安装并注册，否则部分 vxe-table 高级交互可能表现不一致。
+
 ## 快速开始
 
-在 `main.ts` 中安装：
+在 `main.ts` 中**先注册 vxe-table / vxe-pc-ui**，再安装本库：
 
 ```ts
 import { createApp } from 'vue'
+import VXETable from 'vxe-table'
+import VXEPcUI from 'vxe-pc-ui'
 import BareComponents from '@wg-song/bare'
+import 'vxe-table/lib/style.css'
+import 'vxe-pc-ui/lib/style.css'
 import '@wg-song/bare/index.css'
 
 const app = createApp(App)
+app.use(VXEPcUI)
+app.use(VXETable)
 app.use(BareComponents)
 app.mount('#app')
 ```
 
-> 注意：若使用本库内置的 Vite 应用演示工程，安装时已自动调用 `setupModal(app._context)`，接入方无需手动处理命令式弹窗上下文。
+> 若未注册 `vxe-table`，表格组件会报 `[Vue warn]: Failed to resolve component: vxe-grid`。开发环境下本库 `install` 阶段会在控制台给出明确提示。
 
-## 组件总览
+## 组件能力矩阵
 
-### 表单 Form
+### 场景组件
 
 | 组件 / API | 说明 |
 |---|---|
-| `Form` | Schema 驱动表单 |
-| `SearchForm` | 搜索表单（含高级搜索、FilterBar） |
-| `SearchFormSimple` | 简易单行搜索 |
-| `DialogForm` | 弹窗表单场景 |
-| `useForm` | 表单核心 hook |
-| `useSearchForm` | 搜索表单 hook |
-
-### 表格 Table
-
-| 组件 / API | 说明 |
-|---|---|
-| `Table` | 基础 vxe-table 封装 |
+| `PageList` | 完整列表页（搜索 + 工具栏 + 表格 + 分页 + 详情弹窗） |
+| `PageShell` | 列表页外壳（搜索 + 工具栏 + 表格插槽 + 分页） |
+| `PageEditList` | 可编辑列表页 |
+| `PageChildList` | 子列表页 |
 | `TableRead` | 只读表格（固定操作列等） |
 | `TableEdit` | 行内编辑表格 |
 | `TableChild` | 父子表格 |
 | `TableGroup` / `TableGroupPage` | 分组表格 |
-| `Pagination` | 分页 |
-
-### 列表页 PageList
-
-| 组件 / API | 说明 |
-|---|---|
-| `PageList` | 完整列表页 |
-| `PageShell` | 列表页外壳（搜索 + 工具栏 + 表格插槽 + 分页） |
-| `PageEditList` | 可编辑列表页 |
-| `PageChildList` | 子列表页 |
-| `usePageList` | 列表页逻辑 hook |
-| `definePageList` / `defineLoader` | 列表页配置定义 |
+| `DialogForm` | 弹窗表单场景 |
+| `PageModals` / `PageModalSlot` | 页面级弹窗管理器 |
+| `PageListTabs` | 标签页 + 列表组合 |
 
-### 弹窗 Modal
+### 基础组件
 
 | 组件 / API | 说明 |
 |---|---|
+| `Form` | Schema 驱动表单 |
+| `SearchForm` | 搜索表单（含高级搜索、FilterBar） |
+| `SearchFormSimple` | 简易单行搜索 |
+| `Table` | 基础 vxe-table 封装 |
+| `Pagination` | 分页 |
 | `Modal` / `Drawer` | 声明式弹窗/抽屉 |
-| `openModal` / `openDrawer` | 命令式打开弹窗/抽屉 |
-| `confirm` / `alert` | 命令式确认/提示 |
-| `PageModals` | 页面级弹窗管理器 |
+| `Button` | 按钮 |
+| `Switch` | 开关 |
+| `Tag` | 标签 |
+| `Link` | 链接 |
+| `Icon` | 图标 |
+| `Col` | 布局列 |
+| `Dropdown` / `DropdownMenuItem` / `DropdownSplitButton` | 下拉菜单 |
+| `Dialog` | 对话框 |
+| `Popover` / `Tooltip` / `Popconfirm` | 反馈类浮层 |
+| `Tabs` / `TabsView` / `PageTabs` | 标签页 |
+| `SplitPane` / `SplitPaneLayout` | 分割面板 |
+| `ToolbarActionBar` / `ToolbarActionButtonMenu` | 表格工具栏操作 |
 
-### 标签页 Tabs
+### Hooks / 工具函数
 
-| 组件 / API | 说明 |
+| API | 说明 |
 |---|---|
-| `Tabs` | 基础标签页 |
-| `TabsView` / `PageTabs` | 页签视图 |
-| `PageListTabs` | 标签页 + 列表组合 |
+| `useForm` / `useSearchForm` | 表单核心 hook |
+| `usePageList` | 列表页逻辑 hook |
+| `definePageList` / `defineLoader` | 列表页配置定义 |
+| `usePageModals` / `usePageModalContext` / `definePageModals` | 页面弹窗管理 |
 | `useTabState` / `useTabbedList` | 标签页状态 hook |
+| `openModal` / `openDrawer` / `confirm` / `alert` / `setupModal` / `useModalContext` | 命令式弹窗/反馈 |
+| `localColDriver` / `remoteColDriver` / `storeColDriver` / `setupColPref` | 列偏好存储 |
+| `mapToOptions` / `formatDictLabel` / `formatAmountValue` / `formatDateValue` / `formatCellDisplay` | 表格格式化工具 |
 
-### 布局与原子组件
-
-| 组件 / API | 说明 |
-|---|---|
-| `SplitPane` / `SplitPaneLayout` | 分割面板 |
-| `ToolbarActionBar` / `ToolbarActionButtonMenu` | 表格工具栏操作 |
-| `Button`、`Input`、`Select`、`Tag`、`Link` 等 | 字段级原子组件（同样从 `@wg-song/bare` 导入） |
+> 当前版本**未提供**独立的 `Input`、`Select`、`Card` 组件；表单输入请使用 `Form` / `SearchForm` 的 `FormField` 配置，或继续使用 Ant Design Vue 原生组件。
 
 ## 核心使用模式
 
@@ -160,26 +168,30 @@ const data = [
 ```vue
 <script setup lang="ts">
 import { PageShell } from '@wg-song/bare'
-import type { FormField, PageShellProps } from '@wg-song/bare'
+import type { FormField, PageShellProps, ActionItem } from '@wg-song/bare'
 
 const searchSchemas: FormField[] = [
   { field: 'keyword', label: '关键词', component: 'input' },
 ]
 
-const loader: PageShellProps['loader'] = async ({ query, currentPage, pageSize }) => {
-  // 调用接口
-  return { list: [], total: 0 }
-}
-
-const toolbarActions = [
+const toolbarActions: ActionItem[] = [
   { label: '新增', onClick: () => {} },
 ]
+
+const loader: PageShellProps['loader'] = async ({ params, page, pageSize }) => {
+  // 调用业务 API，params 为搜索表单值
+  return { list: [], total: 0 }
+}
 </script>
 
 <template>
-  <PageShell :search-schemas="searchSchemas" :loader="loader" :toolbar-actions="toolbarActions">
+  <PageShell
+    :search-schemas="searchSchemas"
+    :loader="loader"
+    :toolbar-actions="toolbarActions"
+  >
     <template #default="{ tableData, loading }">
-      <!-- 渲染具体表格场景 -->
+      <!-- 渲染表格或其他内容 -->
     </template>
   </PageShell>
 </template>
@@ -202,6 +214,173 @@ function onOpen() {
 }
 ```
 
+## 完整 CRUD 示例：角色管理
+
+```vue
+<!-- views/role/index.vue -->
+<script setup lang="ts">
+import { ref } from 'vue'
+import { ref } from 'vue'
+import { PageList, confirm } from '@wg-song/bare'
+import type {
+  FormField,
+  TableColumn,
+  ActionItem,
+  PageListProps,
+  PageListToolbarContext,
+} from '@wg-song/bare'
+import RoleDetail from './RoleDetail.vue'
+
+const pageListRef = ref<InstanceType<typeof PageList> | null>(null)
+
+const searchSchemas: FormField[] = [
+  { field: 'roleName', label: '角色名称', component: 'input' },
+  { field: 'status', label: '状态', component: 'select', options: [
+    { label: '启用', value: 1 },
+    { label: '禁用', value: 0 },
+  ]},
+]
+
+const columns: TableColumn[] = [
+  { field: 'roleName', title: '角色名称', component: 'link' },
+  { field: 'roleCode', title: '角色编码' },
+  { field: 'status', title: '状态', component: 'tag', tagColor: ({ value }) => value === 1 ? 'success' : 'default' },
+  { field: 'updateTime', title: '更新时间' },
+]
+
+function toolbarActions(ctx: PageListToolbarContext): ActionItem[] {
+  return [
+    { label: '新增', type: 'primary', onClick: () => pageListRef.value?.openDetail(null) },
+    {
+      label: '批量删除',
+      danger: true,
+      disabled: ctx.selectedCount === 0,
+      onClick: async () => {
+        const rows = ctx.getSelectedRows()
+        const ok = await confirm(`确认删除选中的 ${rows.length} 项？`)
+        if (!ok) return
+        // 业务侧调用删除 API，例如 await deleteRole(rows.map((r) => r.id))
+        pageListRef.value?.reload()
+      },
+    },
+  ]
+}
+
+function rowActions(row: any): ActionItem[] {
+  return [
+    { label: '编辑', onClick: () => pageListRef.value?.openDetail(row) },
+    { label: '删除', danger: true, onClick: async () => {
+      const ok = await confirm('确认删除该角色？')
+      if (!ok) return
+      // 业务侧调用删除 API，例如 await deleteRole([row.id])
+      pageListRef.value?.reload()
+    }},
+  ]
+}
+
+const page: PageListProps['page'] = {
+  tableId: 'role-management',
+  search: searchSchemas,
+  columns,
+  loader: async ({ params, page, pageSize }) => {
+    // 业务侧调用分页 API，例如 const res = await getRolePage({ ...params, currentPage: page, pageSize })
+    return { list: [], total: 0 }
+  },
+  toolbarActions,
+  rowActions,
+  detailComponent: RoleDetail,
+  detailTitle: '角色详情',
+  detailWidth: 600,
+}
+</script>
+
+<template>
+  <PageList ref="pageListRef" :page="page" />
+</template>
+```
+
+```vue
+<!-- views/role/RoleDetail.vue -->
+<script setup lang="ts">
+import { computed } from 'vue'
+import { Form, usePageModalContext } from '@wg-song/bare'
+import type { FormField } from '@wg-song/bare'
+const { row, close, confirmLoading } = usePageModalContext<any>()
+
+/** row 存在表示编辑，不存在表示新增 */
+const isEdit = computed(() => !!row.value)
+
+const schemas: FormField[] = [
+  { field: 'roleName', label: '角色名称', component: 'input', required: true },
+  { field: 'roleCode', label: '角色编码', component: 'input', required: true },
+  { field: 'status', label: '状态', component: 'select', options: [
+    { label: '启用', value: 1 },
+    { label: '禁用', value: 0 },
+  ]},
+  { field: 'remark', label: '备注', component: 'textarea' },
+]
+
+async function submit() {
+  confirmLoading.value = true
+  try {
+    // 业务侧调用保存 API，例如 await saveRole(row.value)
+    close({ success: true })
+  } finally {
+    confirmLoading.value = false
+  }
+}
+
+defineExpose({ submit })
+</script>
+
+<template>
+  <Form
+    :model="row"
+    :schemas="schemas"
+    :disabled="!isEdit && false"
+  />
+</template>
+```
+
+> 关键约定：
+> - `detailComponent` 通过 `usePageModalContext()` 获取 `row`；`row` 为 `null/undefined` 表示新增，否则为编辑。
+> - 详情组件必须 `defineExpose({ submit })`，PageList 在点击「确定」时调用该方法。
+> - `submit` 中通过 `confirmLoading.value = true/false` 控制确认按钮加载态；调用 `close(result)` 关闭弹窗。
+
+## 核心 API 速查
+
+### `PageList` 实例方法（通过 `ref` 获取）
+
+| 方法 | 说明 |
+|---|---|
+| `openDetail(row?)` | 打开详情弹窗；`row` 为空表示新增 |
+| `reload()` | 重新加载当前页数据 |
+| `load()` | 同 `reload` |
+| `reset()` | 重置搜索条件 |
+| `gotoPage(page)` | 跳转到指定页 |
+| `getSelectedRows()` | 获取当前已选行 |
+| `setFieldsValue(values)` | 设置搜索表单字段值 |
+| `clearCheckboxSelection()` | 清空复选框选择 |
+
+### `usePageModalContext()`
+
+| 属性 / 方法 | 类型 | 说明 |
+|---|---|---|
+| `row` | `Ref<D \| undefined>` | 当前行数据；为空表示新增 |
+| `close` | `(result?: any) => void` | 关闭并触发 ok |
+| `cancel` | `() => void` | 关闭并触发 cancel |
+| `confirmLoading` | `Ref<boolean>` | 确认按钮加载状态 |
+
+### `ActionItem` 常用字段
+
+| 字段 | 说明 |
+|---|---|
+| `label` | 按钮文字 |
+| `type` | Ant Design Vue Button `type`：`primary` / `default` / `dashed` / `link` / `text` |
+| `danger` | 是否危险样式 |
+| `disabled` | 是否禁用 |
+| `onClick` | 点击回调 |
+
 ## 全局配置
 
 通过 `app.use(BareComponents, { globalConfig })` 传入：
@@ -220,15 +399,50 @@ app.use(BareComponents, {
 
 ```ts
 import type {
+  // 表单
   FormField,
   FormProps,
+  SearchFormProps,
+  DialogFormProps,
+
+  // 表格
   TableColumn,
   TableProps,
+  TableReadProps,
+  TableEditColumn,
+  TableChildProps,
+  TableGroupProps,
+
+  // 列表页
   PageShellProps,
+  PageListProps,
+  PageListConfig,
+  PageListRowActions,
+  PageListToolbarContext,
   ActionItem,
+
+  // 弹窗
+  ModalContext,
+  ModalProps,
+  DrawerProps,
+  PageModalContext,
+  PageModalConfig,
+
+  // 工具
+  OptionItem,
+  ColProps,
 } from '@wg-song/bare'
 ```
 
+## 包内示例
+
+本包附带可直接运行的业务场景示例，统一使用 `from '@wg-song/bare'` 导入：
+
+- `examples/role-management/` — 角色管理完整 CRUD
+- `examples/user-management/` — 用户管理 PageShell + TableRead
+
+复制到业务项目的 `views/` 目录即可参考使用。
+
 ## 构建产物
 
 `pnpm build:bare` 输出到 `dist/packages/`：
@@ -239,6 +453,7 @@ import type {
 - `index.css` — 样式
 - `types.d.ts` — TypeScript 类型声明
 - `README.md` / `AGENTS.md` — 使用文档与 AI 指南
+- `examples/` — 业务场景示例
 - `package.json`
 
 本地联调可在其他项目中：

package/examples/role-management/RoleDetail.vue

@@ -0,0 +1,41 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { Form, usePageModalContext } from '@wg-song/bare'
+import type { FormField } from '@wg-song/bare'
+
+const { row, close, confirmLoading } = usePageModalContext<any>()
+
+const isEdit = computed(() => !!row.value)
+
+const schemas: FormField[] = [
+  { field: 'roleName', label: '角色名称', component: 'input', required: true },
+  { field: 'roleCode', label: '角色编码', component: 'input', required: true },
+  {
+    field: 'status',
+    label: '状态',
+    component: 'select',
+    options: [
+      { label: '启用', value: 1 },
+      { label: '禁用', value: 0 },
+    ],
+  },
+  { field: 'remark', label: '备注', component: 'textarea' },
+]
+
+async function submit() {
+  confirmLoading.value = true
+  try {
+    // 业务侧调用保存 API，例如 await saveRole(row.value)
+    await new Promise((resolve) => setTimeout(resolve, 500))
+    close({ success: true })
+  } finally {
+    confirmLoading.value = false
+  }
+}
+
+defineExpose({ submit })
+</script>
+
+<template>
+  <Form :model="row" :schemas="schemas" />
+</template>

package/examples/role-management/index.vue

@@ -0,0 +1,115 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { PageList, confirm } from '@wg-song/bare'
+import type {
+  FormField,
+  TableColumn,
+  ActionItem,
+  PageListProps,
+  PageListToolbarContext,
+} from '@wg-song/bare'
+import RoleDetail from './RoleDetail.vue'
+
+const pageListRef = ref<InstanceType<typeof PageList> | null>(null)
+
+const searchSchemas: FormField[] = [
+  { field: 'roleName', label: '角色名称', component: 'input' },
+  {
+    field: 'status',
+    label: '状态',
+    component: 'select',
+    options: [
+      { label: '启用', value: 1 },
+      { label: '禁用', value: 0 },
+    ],
+  },
+]
+
+const columns: TableColumn[] = [
+  { field: 'roleName', title: '角色名称', component: 'link' },
+  { field: 'roleCode', title: '角色编码' },
+  {
+    field: 'status',
+    title: '状态',
+    component: 'tag',
+    tagColor: ({ value }) => (value === 1 ? 'success' : 'default'),
+  },
+  { field: 'updateTime', title: '更新时间' },
+]
+
+// 模拟后端分页数据
+const allRows = Array.from({ length: 35 }).map((_, i) => ({
+  id: i + 1,
+  roleName: `角色 ${i + 1}`,
+  roleCode: `ROLE_${String(i + 1).padStart(3, '0')}`,
+  status: i % 3 === 0 ? 0 : 1,
+  updateTime: '2024-01-01 12:00:00',
+}))
+
+function toolbarActions(ctx: PageListToolbarContext): ActionItem[] {
+  return [
+    {
+      label: '新增',
+      type: 'primary',
+      onClick: () => pageListRef.value?.openDetail(null),
+    },
+    {
+      label: '批量删除',
+      danger: true,
+      disabled: ctx.selectedCount === 0,
+      onClick: async () => {
+        const rows = ctx.getSelectedRows()
+        const ok = await confirm(`确认删除选中的 ${rows.length} 项？`)
+        if (!ok) return
+        // 业务侧调用删除 API 后刷新
+        pageListRef.value?.reload()
+      },
+    },
+  ]
+}
+
+function rowActions(row: any): ActionItem[] {
+  return [
+    { label: '编辑', onClick: () => pageListRef.value?.openDetail(row) },
+    {
+      label: '删除',
+      danger: true,
+      onClick: async () => {
+        const ok = await confirm('确认删除该角色？')
+        if (!ok) return
+        // 业务侧调用删除 API 后刷新
+        pageListRef.value?.reload()
+      },
+    },
+  ]
+}
+
+const page: PageListProps['page'] = {
+  tableId: 'role-management',
+  search: searchSchemas,
+  columns,
+  loader: async ({ params, page, pageSize }) => {
+    // 模拟 API 延迟
+    await new Promise((resolve) => setTimeout(resolve, 300))
+    const filtered = allRows.filter((r) => {
+      if (params.roleName && !r.roleName.includes(String(params.roleName))) return false
+      if (params.status != null && r.status !== Number(params.status)) return false
+      return true
+    })
+    const start = (page - 1) * pageSize
+    return {
+      list: filtered.slice(start, start + pageSize),
+      total: filtered.length,
+    }
+  },
+  toolbarActions,
+  rowActions,
+  detailComponent: RoleDetail,
+  detailTitle: '角色详情',
+  detailWidth: 600,
+}
+</script>
+
+<template>
+  <PageList ref="pageListRef" :page="page" />
+</template>