@reglow/design

v0.5.1

Published

2 days ago

Reglow 后台管理基座库 — 组件 + 布局 + 通用页面 + 基础设施

0High
0Medium
0Low

xiangcaozhu

@reglow/design - 前端基座库

包名：@reglow/design | 版本：0.3.0

概述

@reglow/design 是基于 Vue 3 + TypeScript + Vite + Tailwind CSS v4 的后台管理基座库。它不是纯组件库，而是完整的后台基座——包含布局、通用页面、状态管理、API 层、路由工厂和应用工厂；UI 组件由企业组件库 @reglow/reui 提供。消费方只需编写业务页面即可启动完整后台。

架构分工

| 包 | 版本 | 定位 | 内容 | | ---------------- | ------ | -------------------------------------- | -------------------------------------------------------------------------------------------- | | @reglow/reui | ^0.3.0 | UI 组件库（基于 reka-ui 二次封装） | 企业级组件（PageTable / Drawer / Dialog / Select / Badge / useToast…）+ 基础组件 | | @reglow/design | 0.3.0 | 应用基座库 | 应用工厂、布局、通用页面、Store、API 层、路由工厂、主题引擎、基础 UI 组件（ui） |

组件统一从 @reglow/reui 导入；基座能力（布局 / Store / API / 类型 / 主题 / 工厂）从 @reglow/design 导入。

技术栈

| 类别 | 技术 | | ------ | ---------------------------------------- | | 框架 | Vue 3.5 + Composition API | | 构建 | Vite 8（双模式：SPA + Lib） | | 语言 | TypeScript 6 | | 样式 | Tailwind CSS v4 + tw-animate-css | | 组件 | reka-ui（底层）+ @reglow/reui（企业级） | | 基础UI | 自研 ui（16 个 shadcn-vue 基础组件包） | | 状态 | Pinia 3 | | 路由 | Vue Router 4 | | 请求 | Axios（Token 自动刷新） | | 表格 | TanStack Table | | 编辑器 | Tiptap 3（含协作 / Markdown / 表格扩展） | | 图标 | Lucide Vue Next |

目录结构

reglow-design/
├── src/
│   ├── components/
│   │   ├── ui/                # 16 个 shadcn-vue 基础组件包
│   │   ├── common/            # 7 个通用业务组件
│   │   ├── layout/            # 10 个布局组件
│   │   ├── ai/                # AI 面板组件（文生图 / 文生视频）
│   │   ├── setting/           # 设置类组件（邮件设置表单）
│   │   └── material/          # 素材分组筛选组件
│   ├── views/                 # 28 个通用页面
│   │   ├── login/             # 登录（4 套模板）
│   │   ├── register/          # 注册
│   │   ├── dashboard/         # 仪表盘
│   │   ├── profile/           # 个人中心
│   │   ├── system/            # 系统管理（主题/组织架构/部门/岗位/员工/用户/素材/协议/通知）
│   │   ├── operation/         # 运维管理（菜单/角色/字典/参数/设置/消息/日志）
│   │   ├── content/           # 内容管理（文章/照片/视频）
│   │   ├── customer-service/  # 智能客服
│   │   └── cs-*/              # 坐席工作台 / 坐席管理 / 对话记录
│   ├── layouts/               # DashboardLayout 主布局
│   ├── stores/                # useAuthStore + useAppStore
│   ├── api/                   # 全套 API（26 个模块）
│   ├── lib/                   # utils.ts + theme.ts 主题引擎
│   ├── router/                # createAdminRouter() 路由工厂
│   ├── i18n/                  # 国际化（zh-CN / en-US / zh-TW）
│   ├── types/                 # 全量 TypeScript 类型
│   ├── create-app.ts          # createAdminApp() 应用工厂
│   ├── index.ts               # 库统一导出入口
│   ├── App.vue                # 根组件
│   └── main.ts                # SPA 独立运行入口
├── vite.config.ts             # 双模式构建（SPA + Lib）
├── package.json               # @reglow/design
└── components.json            # shadcn-vue 配置

双模式构建

# SPA 模式 — 独立运行（开发调试）
npm run dev          # 开发服务器
npm run build        # 生产构建

# 库模式 — 打包为 npm 包
npm run build:lib    # 输出 dist/src/index.js + dist/src/reglow-design.css

消费方使用

安装

# 本地开发（npm link）
cd reglow-design && npm install && npm run build:lib && npm link

cd my-project && npm link @reglow/design

# 或发布后安装
npm install @reglow/design

启动应用

// main.ts — 3 行启动完整后台
import { createAdminApp } from "@reglow/design";
import "@reglow/design/style.css";
import businessRoutes from "./router";

createAdminApp({ extraRoutes: businessRoutes }).mount("#app");

样式接入

@reglow/design/style.css 已包含完整的 Tailwind 产物（主题变量、组件样式、工具类），消费方不跑 Tailwind 时 import 一次即可。

但消费方自身也用 Tailwind（有 src/assets/main.css 里的 @import "tailwindcss"）时，必须用 @source 把库产物纳入扫描：

/* src/assets/main.css */
@import "tailwindcss";
@import "tw-animate-css";
@import "@reglow/design/style.css";

/* 扫描库构建产物中的 class 名，生成对应的 Tailwind utility（放在 node_modules 下，需显式声明） */
@source "../../node_modules/@reglow/design/dist";
/* 业务页面若直接 `import ... from "@reglow/reui"`，再加这一条 */
@source "../../node_modules/@reglow/reui/dist";

原因：消费方自己的 utilities 层与库产物里的 utilities 层同层同优先级、后出现者生效。若不加 @source，消费方的 utilities 只含业务源码用到的类——例如它生成了无条件 .flex-col，却没有库组件用到的 sm:flex-row，于是无条件基础类会盖掉库的响应式变体（PageTable 的搜索栏 / 分页栏恒为 flex-direction: column，即「布局失效」）。加上 @source 后消费方的 utilities 是完备集合且内部顺序规范，两个层之间不再产生此类覆盖。

从库导入

// 组件（基础 + 企业级）→ 统一来自 @reglow/reui
import {
  PageTable,
  Drawer,
  Dialog,
  Button,
  Input,
  Select,
  useToast,
} from "@reglow/reui";

// 基座能力 → 来自 @reglow/design
import { cn, formatDate, exportToExcel } from "@reglow/design";

// Store
import { useAuthStore, useAppStore } from "@reglow/design";

// API
import { authApi, employeeApi, configApi, apiClient } from "@reglow/design";

// 类型
import type { ApiResponse, Employee, MenuItem } from "@reglow/design";

// 主题引擎
import { applyTheme, DEFAULT_THEME } from "@reglow/design";

// 路由工厂
import { createAdminRouter, routes } from "@reglow/design";

列表页排序（多列为后期业务预留）

内置列表页默认是单列服务端排序：点击表头 → 回到第 1 页 → 带 sort_by / sort_order 重新请求，排序跨页生效。

后期业务需要多列时，只需给该页的 PageTable 加一个 multi-sort，其余代码不用改（排序参数由 toSortParams() 自动拼接）：

<PageTable
  v-model:sorting="sorting"
  manual-sorting
  multi-sort
  :columns="columns"
  :data="list"
  :total="total"
  @sort-change="handleSortChange"
/>

交互：按住 Shift 点击表头累加列，普通点击仍只保留当前列；存在多列排序时表头显示优先级序号
请求：单列 ?sort_by=created_at&sort_order=desc；多列 ?sort_by=nickname:asc,created_at:desc（顺序即优先级）
上限：最多 3 列（组件与服务端一致），第 4 列起不再累加
校验：服务端逐列校验可排序白名单，非法/敏感列只跳过该列，全部非法则整体回落该接口默认排序（不报错）
要求：列的 accessorKey 必须与后端字段名（snake_case）一致，否则该列会被服务端忽略

内置通用页面（28 个）

| 分类 | 页面 | | ------ | ---------------------------------------------------------------------------------------------------- | | 认证 | login（4 套模板）、register | | 工作台 | dashboard、profile | | RBAC | organization、employee、user、dept、post、role、menu | | 运维 | dict、config、setting、login-logs、operation-logs、notice、message | | 内容 | articles、photos、videos | | 系统 | material、agreement、theme | | AI | customer-service（智能客服）、cs-agent（坐席工作台）、cs-agents（坐席管理）、cs-sessions（对话记录） |

主题引擎

支持 oklch 色彩空间，7 种基础色 + 18 种主色 + 9 种字体 + 亮/暗模式。

import { applyTheme, DEFAULT_THEME, type ThemeConfig } from "@reglow/design";

const config: ThemeConfig = {
  style: "vega",
  mode: "light",
  baseColor: "zinc",
  primaryColor: "blue",
  // ...
};
applyTheme(config);

发布

1. 前置准备

如果使用组织（@reglow），需先在 npm 创建组织：https://www.npmjs.com/org/create

# 注册 npm 账号：https://www.npmjs.com/signup
# 登录
npm login

# 验证登录
npm whoami

或使用 token 发布：需要创建一个粒度访问令牌（Granular Access Token），步骤如下：

打开 https://www.npmjs.com/settings/~/tokens
点击 "Generate New Token" -> "Granular Access Token"
配置：
- Token Name : reglow-design-publish
- Expiration : 自定义（如 30 天）
- Packages and Scopes : 选择 "Only select packages and scopes" -> 输入 @reglow
- Permissions : 勾选 "Read and write"
- 2FA 设置 : 务必勾选 "Bypass 2FA for publish" （关键！）

在项目根目录或用户目录的 .npmrc 中配置：

registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=npm_你的访问令牌

2. 更新版本号

# 方式一：npm version 命令（自动改 package.json + 创建 git tag）
npm version patch   # 0.2.1 -> 0.2.2
npm version minor   # 0.2.1 -> 0.3.0
npm version major   # 0.2.1 -> 1.0.0

# 方式二：手动改 package.json 中的 version 字段

3. 构建库

npm run build:lib

确认 dist/src/ 下生成了 index.js 和 reglow-design.css。

4. 发布

# 先检查将要发布的文件列表
npm pack --dry-run

# 发布（scoped 包默认私有，已在 package.json 中配置 publishConfig.access=public）
npm publish

# 如果是首次发布 scoped 包，可能需要显式指定
npm publish --access public

5. 验证

# 在新项目中安装
npm install @reglow/design

# 验证导入
node -e "import('@reglow/design').then(m => console.log(Object.keys(m).length, 'exports'))"

后续更新版本：npm version patch -> npm run build:lib -> npm publish

发布检查清单

| 检查项 | @reglow/design (npm) | | ------------------ | -------------------------------- | | 版本号已更新 | package.json | | 构建产物已清理重建 | npm run build:lib | | 已登录对应平台 | npm whoami | | 包名未被占用 | npmjs.com/package/@reglow/design | | 已删除旧 dist | 是 | | 发布后安装验证 | npm install @reglow/design |