@cst-ui/nano-buttons

Nano 项目主题按钮组件库，基于 Vue 3 和 Element Plus 封装。

这个包用于统一提供 Nano 系列按钮组件，并通过子入口提供弹窗标签页化的公共能力。模板中统一使用横线法组件名，例如 <nano-button>，不再保留旧命名。

入口说明

包内能力按子入口拆分，按钮和弹窗标签页可以分开引入：

// 兼容旧按钮入口
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/

安装

pnpm add @cst-ui/nano-buttons

全局注册

在应用入口文件中注册组件并引入样式：

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 NanoButtons from '@cst-ui/nano-buttons/buttons'

组件列表

模板中统一使用横线法：

<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 />

使用示例

固定语义按钮直接使用对应组件：

<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>：

<nano-button icon="Refresh">刷新</nano-button>
<nano-import-button>导入</nano-import-button>
<nano-export-button :loading="exporting">导出</nano-export-button>

依赖说明

vue、element-plus 和 vue-router 是 peer dependencies，需要由使用方项目提供。

弹窗标签页

弹窗标签页能力用于把原本的弹窗按开关切换成系统 tab 页，同时保留原弹窗模式。公共包只负责打开模式、上下文缓存、保存结果通知、关闭回来源页和 NanoDialogTabPage 页面壳；业务项目负责注册页面、请求数据和保存业务。

入口安装

在应用入口安装插件：

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),
  },
}))

注册页面

在业务项目维护弹窗注册表：

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 时打开注册页面：

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 统一标题、内容滚动、底部操作区和上下文失效兜底：

<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>

保存后刷新来源页

来源页可以监听保存结果并刷新列表：

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。

文档站本地开发：

pnpm docs:dev

文档站构建：

pnpm docs:build

更新线上文档时，重新构建后将 docs-dist/ 上传到 Netlify。若 Netlify 站点或域名发生变化，请同步修改本文档中的在线文档链接。