ZUI 3

English

开箱即用、可组合、可定制的 Web UI 组件库。

ZUI 3 不绑定特定的 JavaScript 框架，在原生 Web 项目以及各类前端框架中都可以使用。它同时提供 CSS 工具类、CSS 组件与 JavaScript 组件，并支持通过浏览器脚本、ES Module 或定制构建引入。

官网 · 开发文档 · GitHub · 更新日志

核心特性

• 框架无关：对外提供原生 DOM API，可以独立使用，也可以集成到现有应用中。
• 组件丰富：覆盖按钮、表单、导航、卡片、表格、下拉菜单、对话框、数据表格和文件上传等常见场景。
• 风格统一：使用 CSS 变量管理全局设计配置，支持主题定制与深色模式。
• 灵活引入：提供 UMD 和 ESM 产物，既可以直接通过 <script> 使用，也可以配合现代构建工具。
• 可组合构建：每个功能都是独立的 workspace 库，可以按项目需求生成定制组合版本。

Codex 插件

本仓库也是一个仅包含技能的 Codex 插件，提供两种互补工作流：

• $zui：识别现有项目的 ZUI 版本和接入方式，并安全地安装、集成、重构或排查 ZUI 3。
• $zui-build：从需求描述创建无需安装依赖或构建工具即可运行的独立 ZUI 3 页面或小型静态站点。

从 GitHub marketplace 安装

先添加本仓库提供的 marketplace，再安装 zui 插件：

codex plugin marketplace add easysoft/zui
codex plugin add zui@zui

安装后请重新启动 Codex，并新建一个会话，让新会话加载插件中的技能。

在已有应用中使用 ZUI 时，可以这样开始：

使用 $zui 检查当前项目，并按现有技术栈接入 ZUI 3。

需要从零创建独立页面时，使用：

使用 $zui-build 根据这份需求创建一个可直接运行的响应式页面：……

快速开始

通过 CDN 使用

将 ZUI 的 CSS 和 JavaScript 引入页面，即可使用组件样式与全局 zui 对象：

<!doctype html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>ZUI 3 Demo</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/zui/dist/zui.css">
</head>
<body>
    <button id="helloZui" type="button" class="btn primary">Hello ZUI</button>

    <script src="https://cdn.jsdelivr.net/npm/zui/dist/zui.js"></script>
    <script>
        document.querySelector('#helloZui').addEventListener('click', () => {
            zui.Messager.show('ZUI 3 已就绪！');
        });
    </script>
</body>
</html>

生产环境中建议在 CDN 地址中固定明确的 ZUI 版本。

通过包管理器使用

pnpm add zui

import 'zui/css';
import {Messager} from 'zui';

Messager.show('ZUI 3 已就绪！');

在 TypeScript 中使用

npm 包包含选项、事件、实例方法和 Web Components 的类型声明，无需配置 @zui/* 路径别名或安装 @types/zui。公开类型引用的第三方依赖会随包自动安装。

页面准备一个 <div id="productPicker"></div>，即可在客户端初始化组件：

import 'zui/css';
import {Picker, type PickerOptions} from 'zui';

const options: PickerOptions = {
    items: [{value: 'zui', text: 'ZUI'}],
    onChange(value, oldValue) {
        // value 和 oldValue 均推断为 string。
        console.log(value, oldValue);
    },
};

const picker = new Picker('#productPicker', options);
picker.render({disabled: true});
// 页面或宿主组件卸载时清理实例。
picker.destroy();

已使用 TypeScript 5.9 在 strict: true、skipLibCheck: false 下验收 Bundler、Node16 和 NodeNext 模块解析，包括 ESM、CommonJS 和 zui/css 入口。运行时仍需要浏览器 DOM，SSR 应用应在客户端加载并初始化组件。

同名类型可通过明确的名称导入：FileListFileInfo / FileSelectorFileInfo、DashboardBlockProps / DTableBlockProps。FileInfo、BlockProps 分别对应 FileList、Dashboard；通用 CustomRenderResult 系列来自 core，DTable 的版本使用 DTableCustomRenderResult、DTableCustomRenderResultGenerator 和 DTableCustomRenderResultList。

完整的引入方式、组件 API 与示例请查看 ZUI 文档。

源码开发

环境要求

• Node.js 22.13+
• pnpm 12.5.1

启动本地开发服务

git clone https://github.com/easysoft/zui.git
cd zui
pnpm install
pnpm dev

开发服务默认运行在 http://localhost:5173/。访问 http://localhost:5173/<lib-name>/ 可以直接打开指定库的调试页，例如 http://localhost:5173/button/。

常用命令

命令	说明
pnpm dev	启动内置库的开发服务
pnpm dev:exts	启动包含 exts/ 扩展库的开发服务
pnpm lint	运行 ESLint 检查
pnpm typecheck	检查源码、工具与测试的 TypeScript 类型
pnpm test	运行 Vitest 单元和 DOM 组件测试
pnpm test:coverage	运行单元和 DOM 测试并生成覆盖率报告
pnpm test:build	验证代表性分发产物，并在仓库外安装 npm 包验收运行时与严格 TypeScript 消费
pnpm test:e2e	使用 Chromium 运行 Playwright 浏览器测试
pnpm test:e2e:all	使用 Chromium、Firefox 和 WebKit 运行浏览器测试
pnpm check	运行 lint、typecheck、单元/DOM 测试和技能测试
pnpm build	构建完整的 ZUI 产物
pnpm build:npm	构建用于 npm 发布的 dist/zui 及 TypeScript 声明，不执行发布
pnpm pack:npm	独立构建并打包 npm 候选包，输出 .tgz 与摘要清单
pnpm publish:npm --tarball <file>	检查并验证指定包的私有快照，通过后发布同一文件
pnpm docs:dev	准备并启动 VitePress 文档服务
pnpm docs:build	构建文档站点

本项目以各库的 dev.ts 作为交互调试入口。修改 lib/<lib-name>/ 后，应在对应的单库页面验证功能与样式。

pack:npm 默认输出到 dist/npm/run-*，可通过 --out-dir <directory> 指定目录；版本读取根 package.json，发布模板保持只读，打包失败保留旧包。生成候选包或持有 artifact.json 摘要清单不代表通过发布检查。publish:npm 必须显式指定 .tgz，执行 check 和消费该文件的 test:build 后发布同字节快照，不重新构建或打包该候选包。CI 保存本次验证过的 npm 包与摘要，不自动发布。完整流程见打包与发布指南。

测试分层、浏览器安装和视觉基线更新方式请查看自动化测试指南。

定制构建

构建命令可以按需组合多个库：

pnpm build --lib button --lib dropdown --name zui-custom

产物将输出到 dist/zui-custom/。通过 --extensions 包含全部已注册扩展，或用可重复的 --extension <组名或目录> 指定扩展来源；--lib 选择其中的入口。构建不隐式执行类型检查，发布前使用 pnpm check 和 pnpm test:build 验证。更多选项和旧参数迁移表请查看 定制构建文档。

仓库结构

目录	职责
lib/	内置组件、辅助 API、样式、调试页与文档源文件
config/	共享的 Tailwind 主题配置
dev/	本地调试页的开发辅助工具
docs/	VitePress 文档站点与基础文档
scripts/	构建、文档同步和库元数据处理脚本
tests/	单元、DOM、构建消费和 Playwright 浏览器测试
exts/	通过 pnpm extend-lib <path> 接入的本地扩展库

技术栈

ZUI 3 使用 TypeScript、Preact、Cash、Tailwind CSS、Vite 和 VitePress 开发。

参与贡献

欢迎通过 Issue 报告问题或提交建议，也欢迎提交 Pull Request。提交代码前，请运行 pnpm check，并根据改动范围补充代表构建、浏览器测试和对应的单库调试页验证。

正在寻找 ZUI 1？请访问 ZUI 1 官网 或 zui1 分支。

开源许可

ZUI 3 基于 MIT License 开源。