GZ UI Web 组件库

安装

要求项目使用 React ^19.2.5、ReactDOM ^19.2.5 和 Ant Design ^6.5.1。

普通组件项目安装主包：

npm install gz-ui-web

项目使用 Table 或 gz-ui-web/gz-table 时，还要安装表格相关的 peer dependencies：

npm install [email protected] [email protected] [email protected]

使用

1. 根组件包裹（main.tsx）

import 'gz-ui-web/gz-ui-web.css';
import { createRoot } from 'react-dom/client';
import { RouterProvider } from 'react-router-dom';
import { ConfigProvider, type GZThemeMode } from 'gz-ui-web';
import { router } from '@/router';

const themeMode: GZThemeMode = 'gold-dark';

createRoot(document.getElementById('root')!).render(
  <ConfigProvider themeMode={themeMode}>
    <RouterProvider router={router} />
  </ConfigProvider>,
);

2. 组件使用

• 以 Button 组件为例

import { Button } from 'gz-ui-web';

const App = () => {
  return (
    <div>
      <Button>默认按钮</Button>
    </div>
  );
};

3. Table 和 AG Grid API

Table 从主包导入；AG Grid 类型、底层 API 和 gz-ui-web 生成的 Grid Token 从 gz-table 子入口导入：

import { Table } from 'gz-ui-web';
import {
  goldDarkAgGridTokens,
  type ColDef,
} from 'gz-ui-web/gz-table';

Table 在 Gold 主题下会自动使用对应的 AG Grid Token。详见 Table 文档 和 AG Grid Token 文档。

项目图表技术栈统一使用 ECharts，不单独维护图表 Token。图表颜色、文字和背景直接通过 getDesignTokens({ themeMode }).globalToken 获取，完整示例见 全局 Tokens。

导入 UI Design Tokens

在仓库根目录执行，一次完成 UI 交付包导入与 Token、文档生成：

npm run tokens:import -- "/path/to/UI 交付包目录"

这是日常导入的唯一入口，已包含 Token 转换和文档生成，无需再执行其他生成命令。

自动导入交付目录中 gold-theme/、blue-theme/ 下的所有主题及明暗模式，统一生成一次；追加 --dry-run 可只预览。没有主题标识的单主题旧包需用 --theme gold 或 --theme blue 指明归属。交付包结构、失败恢复及验证说明见 Design Tokens 源文件维护指南。