jh-antdv-lib

jh-antdv-lib

基于 ant-design-vue 4 的 Vue3 + TypeScript 业务二次封装组件库。工程采用 Vite5 lib 模式构建，ant-design-vue 与 vue 作为 peerDependencies 不打包进产物。

特性

• 严格 TypeScript：组件 Props 继承 antdv 原生类型并扩展业务字段
• 属性透传：通过 v-bind="$attrs" 完整保留 antdv 原生能力
• 全量导入 + 子路径按需导入，ESM 输出天然支持 tree-shaking
• 内置 useProTable 业务 Hook，可脱离组件独立使用

组件

安装

# 组件库
pnpm add jh-antdv-lib

# peer 依赖（业务项目自行安装）
pnpm add vue ant-design-vue

样式（antdv4 采用 CSS-in-JS，仅需 reset）：

import "ant-design-vue/dist/reset.css";

引入

全量引入（全局注册）

app.use(JhAntdvLib) 会注册全部组件（jh-* 与 Pro 系列），之后可在模板中直接使用 <jh-button>、<jh-menu>、<ProTable> 等标签：

import { createApp } from "vue";
import Antd from "ant-design-vue";
import JhAntdvLib from "jh-antdv-lib";
import "ant-design-vue/dist/reset.css";
import App from "./App.vue";

const app = createApp(App);
app.use(Antd);
app.use(JhAntdvLib);
app.mount("#app");

按需引入（推荐）

// 命名导入（tree-shaking）
import { jhButton, jhMenu, jhMenuItem, jhSubMenu } from "jh-antdv-lib";
import { ProTable, ProSearchForm, ProModalForm } from "jh-antdv-lib";

// 子路径导入单个组件（均为命名导出，非默认导出）
import { ProTable } from "jh-antdv-lib/pro-table";
import { ProSearchForm } from "jh-antdv-lib/pro-search-form";
import { ProModalForm } from "jh-antdv-lib/pro-modal-form";

复用「属性调整」的主题

文档站左侧「设计规范 → 设计变量与全局令牌」用于统一维护变量池（可增删改查、支持变量指向变量）与 antd 全局令牌；每个组件页的「属性调整」维护该组件自己的组件令牌，值可以直接填，也可以引用变量池里的变量。

保存后整份主题文档写入：

• 本仓库内：packages/theme/tokens.json（playground 保存时实时写入）
• 发布包内：jh-antdv-lib/theme-tokens.json（发布时的快照）

主题文件结构（v2）：

{
  "version": 2,
  "variables": {
    "color-primary": { "type": "color", "value": "#1677ff", "label": "主色", "group": "颜色" },
    "radius-base": { "type": "number", "value": 6, "unit": "px", "label": "基础圆角" }
  },
  "token": { "colorPrimary": { "$var": "color-primary" }, "borderRadius": 8 },
  "components": { "Menu": { "colorItemBgSelected": { "$var": "color-primary" } } }
}

业务项目用 createJhTheme 把引用展开成最终值（antd 需要真实色值做派生色计算，不能直接传 CSS 变量）：

<script setup lang="ts">
import themeTokens from "jh-antdv-lib/theme-tokens.json";
import { createJhTheme, applyJhCssVars } from "jh-antdv-lib/theme";

const { theme, cssVars } = createJhTheme(themeTokens);
applyJhCssVars(cssVars); // 可选：设计变量会输出为 --jh-* CSS 变量，供自定义样式 var() 使用
</script>

<template>
  <jh-config-provider :theme="theme">
    <RouterView />
  </jh-config-provider>
</template>

createJhTheme(themeTokens) 返回：

• theme：{ token, components }，直接交给 ConfigProvider（jh-config-provider 会透传 theme）
• variables：变量解析后的键值（别名已展开）
• cssVars：--jh-<变量名>: 值，可用 applyJhCssVars 挂到 :root

本机开发想让业务项目实时跟随调整：在 playground/.env.local 里配置 JH_TOKENS_SYNC_TARGET=<业务项目主题文件绝对路径>，保存时会同时写入该文件，业务项目 dev 立即 HMR。

ProTable 快速示例

<script setup lang="ts">
import { ProTable, type ProTableColumn } from "jh-antdv-lib";

interface UserRow {
  id: number;
  name: string;
  status: "active" | "disabled";
  salary: number;
}

const columns: ProTableColumn<UserRow>[] = [
  { title: "ID", dataIndex: "id" },
  { title: "姓名", dataIndex: "name" },
  {
    title: "状态",
    dataIndex: "status",
    valueType: "tag",
    valueEnum: {
      active: { text: "启用", color: "success" },
      disabled: { text: "禁用", color: "default" },
    },
    search: {
      component: "select",
      options: [
        { label: "启用", value: "active" },
        { label: "禁用", value: "disabled" },
      ],
    },
  },
  {
    title: "薪资",
    dataIndex: "salary",
    valueType: "money",
    hideInSearch: true,
  },
];

const request = (params: { current: number; pageSize: number }) =>
  Promise.resolve({ data: [] as UserRow[], total: 0 });
</script>

<template>
  <ProTable :columns="columns" :request="request" row-key="id" />
</template>

目录结构

jh-antdv-lib/
├── packages/                  # 组件库源码
│   ├── components/            # 业务组件
│   │   ├── pro-table/
│   │   ├── pro-search-form/
│   │   └── pro-modal-form/
│   ├── hooks/                 # useProTable 等业务 Hook
│   ├── utils/                 # 通用工具
│   └── index.ts               # 总导出入口
├── playground/                # 本地调试 demo（pnpm dev 启动）
├── docs/                      # VitePress 文档
├── vite.config.ts             # lib 打包配置（external vue/antdv）
├── tsconfig.json
└── package.json

本地开发

# 1. 安装依赖
pnpm install

# 2. 打包组件库（生成 dist，含 JS + d.ts）
pnpm run build

# 3. 启动 playground 调试（源码直连，无需先 build）
pnpm dev

# 4. 启动文档站点
pnpm docs:dev

# 5. 类型检查
pnpm typecheck

开发规范（目录与命名、组件实现、playground 与文档约定、提交前自检）见 docs/guide/conventions.md。

发布前检查

• pnpm run build 产物 dist/ 内应包含 index.js、index.cjs、各子路径包与 types/ 类型声明
• package.json 已配置 peerDependencies、exports、types、files

License

MIT