@cst-ui/nano-buttons 0.2.2 → 0.3.0

package/README.md

@@ -1,244 +1,292 @@
-# @cst-ui/nano-buttons
-
-Nano 项目主题按钮组件库，基于 Vue 3 和 Element Plus 封装。
-
-这个包用于统一提供 Nano 系列按钮组件，并通过子入口提供弹窗标签页化的公共能力。模板中统一使用横线法组件名，例如 `<nano-button>`，不再保留旧命名。
-
-## 入口说明
-
-包内能力按子入口拆分，按钮和弹窗标签页可以分开引入：
-
-```ts
-// 兼容旧按钮入口
-import NanoButtons from '@cst-ui/nano-buttons'
-
-// 明确的按钮入口
-import NanoButtons from '@cst-ui/nano-buttons/buttons'
-
+# @cst-ui/nano-buttons
+
+Nano 项目公共前端组件库，基于 Vue 3 和 Element Plus 封装。
+
+这个包用于统一提供 Nano 系列按钮、表格、分页组件，并通过子入口提供弹窗标签页化的公共能力。模板中统一使用横线法组件名，例如 `<nano-button>`，不再保留旧命名。
+
+## 入口说明
+
+包内能力按子入口拆分，按钮、表格和弹窗标签页可以分开引入：
+
+```ts
+// 兼容旧按钮入口
+import NanoButtons from '@cst-ui/nano-buttons'
+
+// 明确的按钮入口
+import NanoButtons from '@cst-ui/nano-buttons/buttons'
+
 // 弹窗标签页入口
 import { createNanoDialogTabs } from '@cst-ui/nano-buttons/dialog-tabs'
-```
-
-## 在线文档
-
-组件效果、安装方式、使用示例和 API 说明见在线文档：
-
-https://nano-buttons-docs.netlify.app/
-
-## 安装
-
-```bash
-pnpm add @cst-ui/nano-buttons
-```
-
-## 全局注册
-
-在应用入口文件中注册组件并引入样式：
-
-```ts
-import { createApp } from 'vue'
-import App from './App.vue'
-import NanoButtons from '@cst-ui/nano-buttons'
-import '@cst-ui/nano-buttons/style.css'
-
-const app = createApp(App)
-
-app.use(NanoButtons)
-app.mount('#app')
-```
 
+// 表格与分页入口
+import { CstTable, CstPagination } from '@cst-ui/nano-buttons/table'
+```
+
+## 在线文档
+
+组件效果、安装方式、使用示例和 API 说明见在线文档：
+
+https://nano-buttons-docs.netlify.app/
+
+## 安装
+
+```bash
+pnpm add @cst-ui/nano-buttons
+```
+
+## 全局注册
+
+在应用入口文件中注册组件并引入样式：
+
+```ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import NanoButtons from '@cst-ui/nano-buttons'
+import '@cst-ui/nano-buttons/style.css'
+
+const app = createApp(App)
+
+app.use(NanoButtons)
+app.mount('#app')
+```
+
 按钮插件也提供明确的平级子入口，旧入口继续兼容：
-
-```ts
+
+```ts
 import NanoButtons from '@cst-ui/nano-buttons/buttons'
 ```
 
-## 组件列表
+表格模块使用独立入口，可以按需引入组件或全局安装：
 
-模板中统一使用横线法：
+```ts
+import CstTableComponents from '@cst-ui/nano-buttons/table'
 
-```vue
-<nano-button />
-<nano-add-button />
-<nano-text-add-button />
-<nano-move-button />
-<nano-import-button />
-<nano-export-button />
-<nano-edit-button />
-<nano-manage-button />
-<nano-delete-button />
-<nano-submit-button />
-<nano-cancel-button />
+app.use(CstTableComponents)
+```
+
+## 组件列表
+
+模板中统一使用横线法：
+
+```vue
+<nano-button />
+<nano-add-button />
+<nano-text-add-button />
+<nano-move-button />
+<nano-import-button />
+<nano-export-button />
+<nano-edit-button />
+<nano-manage-button />
+<nano-delete-button />
+<nano-submit-button />
+<nano-cancel-button />
 <nano-back-top-button />
+<cst-table />
+<cst-pagination />
+```
+
+## 使用示例
+
+固定语义按钮直接使用对应组件：
+
+```vue
+<nano-add-button />
+<nano-import-button />
+<nano-export-button />
+<nano-delete-button />
+<nano-submit-button>保存</nano-submit-button>
+<nano-cancel-button>取消</nano-cancel-button>
+```
+
+不在固定语义里的普通按钮，统一使用 `<nano-button>`：
+
+```vue
+<nano-button icon="Refresh">刷新</nano-button>
+<nano-import-button>导入</nano-import-button>
+<nano-export-button :loading="exporting">导出</nano-export-button>
 ```
 
-## 使用示例
+## 表格与分页
 
-固定语义按钮直接使用对应组件：
+`CstPagination` 是独立分页组件，只负责展示分页状态和发送变更事件，不请求接口、不处理业务数据。服务端分页页面可以直接接入现有查询方法：
 
 ```vue
-<nano-add-button />
-<nano-import-button />
-<nano-export-button />
-<nano-delete-button />
-<nano-submit-button>保存</nano-submit-button>
-<nano-cancel-button>取消</nano-cancel-button>
+<CstPagination
+  :current-page="page.currentPage"
+  :page-size="page.pageSize"
+  :page-count="page.pageCount"
+  :page-sizes="page.pageSizes"
+  @update:current-page="onCurrentPageUpdate"
+  @update:page-size="onPageSizeUpdate"
+/>
 ```
 
-不在固定语义里的普通按钮，统一使用 `<nano-button>`：
+`CstTable` 组合了 Element Plus Table 和 `CstPagination`，默认对传入的完整数组做前端分页。列定义和其他表格属性继续按照 Element Plus Table 使用：
 
 ```vue
-<nano-button icon="Refresh">刷新</nano-button>
-<nano-import-button>导入</nano-import-button>
-<nano-export-button :loading="exporting">导出</nano-export-button>
+<CstTable
+  :data="rows"
+  :default-page-size="10"
+>
+  <el-table-column prop="name" label="名称" />
+  <el-table-column prop="status" label="状态" />
+</CstTable>
 ```
 
-## 依赖说明
-
-`vue`、`element-plus` 和 `vue-router` 是 peer dependencies，需要由使用方项目提供。
-
-## 弹窗标签页
-
-弹窗标签页能力用于把原本的弹窗按开关切换成系统 tab 页，同时保留原弹窗模式。公共包只负责打开模式、上下文缓存、保存结果通知、关闭回来源页和 `NanoDialogTabPage` 页面壳；业务项目负责注册页面、请求数据和保存业务。
-
-### 入口安装
-
-在应用入口安装插件：
-
-```ts
-import { createNanoDialogTabs } from '@cst-ui/nano-buttons/dialog-tabs'
-
-app.use(createNanoDialogTabs({
-  router,
-  parentRouteName: 'layout',
-  registry: dialogRegistry,
-  mode: () => DIALOG_OPEN_MODE,
-  translate: key => i18n.global.t(key),
-  tabAdapter: {
-    getTabs: () => tabStore.tabsOption,
-    getCurrentIndex: () => tabStore.currentIndex,
-    setCurrentIndex: index => tabStore.SET_TAB(index),
-    deleteTab: index => tabStore.DELETE_TAB(index),
-  },
-}))
-```
-
-### 注册页面
-
-在业务项目维护弹窗注册表：
-
-```ts
-export const dialogRegistry = {
-  userEdit: {
-    suffix: '/edit',
-    title: 'dialog.user.edit',
-    component: async () => await import('@/views/user/components/edit-page.vue'),
-    props: {
-      mode: 'edit',
-    },
-  },
-}
-```
-
-### 打开弹窗或 tab
-
-原页面统一使用 `openDialog`。开关为 `dialog` 时走 `openModal`，开关为 `tab` 时打开注册页面：
-
-```ts
-import { useDialogOpen } from '@cst-ui/nano-buttons/dialog-tabs'
-
-const { openDialog } = useDialogOpen()
-
-openDialog({
-  key: 'userEdit',
-  routeSuffix: `/edit/${row.id}`,
-  routePatternSuffix: '/edit/:id',
-  context: {
-    id: row.id,
-  },
-  openModal: () => {
-    data.showEdit = true
-  },
-})
-```
-
-### tab 页面
-
-tab 页面用 `NanoDialogTabPage` 统一标题、内容滚动、底部操作区和上下文失效兜底：
+只需要表格、不需要分页时关闭分页：
 
 ```vue
-<template>
-  <NanoDialogTabPage
-    :title-key="pageTitleKey"
-    :loading="loading"
-    :expired="expired"
-    @close="closeCurrentDialogTab"
-  >
-    <UserEditForm
-      :item="item"
-      variant="page"
-      @cancel="closeCurrentDialogTab"
-      @save-ok="onSaveOk"
-    />
-  </NanoDialogTabPage>
-</template>
-
-<script setup lang="ts">
-import { NanoDialogTabPage, useDialogPage } from '@cst-ui/nano-buttons/dialog-tabs'
-
-const {
-  route,
-  dialogContext,
-  closeCurrentDialogTab,
-  emitSavedAndClose,
-} = useDialogPage<{ id?: string }>('dialog.user.edit')
-
-const id = computed(() => dialogContext.value?.id ?? route.params.id)
-
-const onSaveOk = () => {
-  emitSavedAndClose('userEdit', { id: id.value })
-}
-</script>
-```
-
-### 保存后刷新来源页
-
-来源页可以监听保存结果并刷新列表：
-
-```ts
-import { onDialogResult } from '@cst-ui/nano-buttons/dialog-tabs'
-
-onMounted(() => {
-  const remove = onDialogResult((result) => {
-    if (result.key === 'userEdit' && result.type === 'saved')
-      loadList()
-  })
-
-  onUnmounted(remove)
-})
+<CstTable :data="rows" :pagination="false">
+  <el-table-column prop="name" label="名称" />
+</CstTable>
 ```
 
-### 使用建议
-
-1. 路由上的业务主键只放可被正常访问的 ID，不放敏感数据。
-2. `context` 只作为临时上下文，页面刷新后可能失效，页面应提供兜底提示或根据路由主键重新查数据。
-3. 标题传多语言 key，不在公共模块里写死业务文案。
-4. 保存成功统一用 `emitSavedAndClose` 通知来源页刷新。
-
-## 维护与发布
-
-包维护、版本发布和权限交接说明见 [MAINTAINING.md](./MAINTAINING.md)。
-
-文档站本地开发：
-
-```bash
-pnpm docs:dev
-```
-
-文档站构建：
-
-```bash
-pnpm docs:build
-```
-
-更新线上文档时，重新构建后将 `docs-dist/` 上传到 Netlify。若 Netlify 站点或域名发生变化，请同步修改本文档中的在线文档链接。
+## 依赖说明
+
+`vue`、`element-plus` 和 `vue-router` 是 peer dependencies，需要由使用方项目提供。
+
+## 弹窗标签页
+
+弹窗标签页能力用于把原本的弹窗按开关切换成系统 tab 页，同时保留原弹窗模式。公共包只负责打开模式、上下文缓存、保存结果通知、关闭回来源页和 `NanoDialogTabPage` 页面壳；业务项目负责注册页面、请求数据和保存业务。
+
+### 入口安装
+
+在应用入口安装插件：
+
+```ts
+import { createNanoDialogTabs } from '@cst-ui/nano-buttons/dialog-tabs'
+
+app.use(createNanoDialogTabs({
+  router,
+  parentRouteName: 'layout',
+  registry: dialogRegistry,
+  mode: () => DIALOG_OPEN_MODE,
+  translate: key => i18n.global.t(key),
+  tabAdapter: {
+    getTabs: () => tabStore.tabsOption,
+    getCurrentIndex: () => tabStore.currentIndex,
+    setCurrentIndex: index => tabStore.SET_TAB(index),
+    deleteTab: index => tabStore.DELETE_TAB(index),
+  },
+}))
+```
+
+### 注册页面
+
+在业务项目维护弹窗注册表：
+
+```ts
+export const dialogRegistry = {
+  userEdit: {
+    suffix: '/edit',
+    title: 'dialog.user.edit',
+    component: async () => await import('@/views/user/components/edit-page.vue'),
+    props: {
+      mode: 'edit',
+    },
+  },
+}
+```
+
+### 打开弹窗或 tab
+
+原页面统一使用 `openDialog`。开关为 `dialog` 时走 `openModal`，开关为 `tab` 时打开注册页面：
+
+```ts
+import { useDialogOpen } from '@cst-ui/nano-buttons/dialog-tabs'
+
+const { openDialog } = useDialogOpen()
+
+openDialog({
+  key: 'userEdit',
+  routeSuffix: `/edit/${row.id}`,
+  routePatternSuffix: '/edit/:id',
+  context: {
+    id: row.id,
+  },
+  openModal: () => {
+    data.showEdit = true
+  },
+})
+```
+
+### tab 页面
+
+tab 页面用 `NanoDialogTabPage` 统一标题、内容滚动、底部操作区和上下文失效兜底：
+
+```vue
+<template>
+  <NanoDialogTabPage
+    :title-key="pageTitleKey"
+    :loading="loading"
+    :expired="expired"
+    @close="closeCurrentDialogTab"
+  >
+    <UserEditForm
+      :item="item"
+      variant="page"
+      @cancel="closeCurrentDialogTab"
+      @save-ok="onSaveOk"
+    />
+  </NanoDialogTabPage>
+</template>
+
+<script setup lang="ts">
+import { NanoDialogTabPage, useDialogPage } from '@cst-ui/nano-buttons/dialog-tabs'
+
+const {
+  route,
+  dialogContext,
+  closeCurrentDialogTab,
+  emitSavedAndClose,
+} = useDialogPage<{ id?: string }>('dialog.user.edit')
+
+const id = computed(() => dialogContext.value?.id ?? route.params.id)
+
+const onSaveOk = () => {
+  emitSavedAndClose('userEdit', { id: id.value })
+}
+</script>
+```
+
+### 保存后刷新来源页
+
+来源页可以监听保存结果并刷新列表：
+
+```ts
+import { onDialogResult } from '@cst-ui/nano-buttons/dialog-tabs'
+
+onMounted(() => {
+  const remove = onDialogResult((result) => {
+    if (result.key === 'userEdit' && result.type === 'saved')
+      loadList()
+  })
+
+  onUnmounted(remove)
+})
+```
+
+### 使用建议
+
+1. 路由上的业务主键只放可被正常访问的 ID，不放敏感数据。
+2. `context` 只作为临时上下文，页面刷新后可能失效，页面应提供兜底提示或根据路由主键重新查数据。
+3. 标题传多语言 key，不在公共模块里写死业务文案。
+4. 保存成功统一用 `emitSavedAndClose` 通知来源页刷新。
+
+## 维护与发布
+
+包维护、版本发布和权限交接说明见 [MAINTAINING.md](./MAINTAINING.md)。
+
+文档站本地开发：
+
+```bash
+pnpm docs:dev
+```
+
+文档站构建：
+
+```bash
+pnpm docs:build
+```
+
+更新线上文档时，重新构建后将 `docs-dist/` 上传到 Netlify。若 Netlify 站点或域名发生变化，请同步修改本文档中的在线文档链接。