@cst-ui/nano-buttons 0.2.1 → 0.2.2

package/README.md

@@ -4,6 +4,21 @@ 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 说明见在线文档：
@@ -84,13 +99,131 @@ import NanoButtons from '@cst-ui/nano-buttons/buttons'
 
 ## 弹窗标签页
 
-弹窗标签页能力从子入口导入：
+弹窗标签页能力用于把原本的弹窗按开关切换成系统 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 { createNanoDialogTabs, useDialogOpen } from '@cst-ui/nano-buttons/dialog-tabs'
+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>
 ```
 
-公共包只负责打开模式、上下文缓存、保存结果通知、关闭回来源页和 `NanoDialogTabPage` 页面壳。业务项目需要传入 `router`、`registry`、`tabAdapter` 和打开模式。
+### 保存后刷新来源页
+
+来源页可以监听保存结果并刷新列表：
+
+```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` 通知来源页刷新。
 
 ## 维护与发布
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cst-ui/nano-buttons",
-    "version": "0.2.1",
+    "version": "0.2.2",
     "description": "Nano themed Vue 3 button components and dialog tab helpers based on Element Plus.",
     "license": "UNLICENSED",
     "type": "module",