# @caspeco/casper-ui-library 中文文档

规范地址：https://npmcn.com/package/%40caspeco/casper-ui-library/

版本：12\.2\.0
npm 元数据更新时间：2026-11-06T15:42:43.493Z
中文译文更新时间：2026-11-09T05:27:50.343Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40caspeco/casper-ui-library
原文对照：https://npmcn.com/package/%40caspeco/casper-ui-library/?lang=original
项目主页：https://caspeco.github.io/casper-ui-library/
源码仓库：https://github.com/Caspeco/casper-ui-library

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.9 MB，2258 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：17 个
- peer 依赖：react ^19\.2\.7，react-dom ^19\.2\.7，@emotion/cache ^11\.14\.0，@emotion/react ^11\.14\.0，@chakra-ui/react ^3\.32\.0
- 首次发布：2025-08-05T08:41:19.544Z
- 最新版本发布：2026-11-06T15:42:43.253Z
- 近 30 天下载量：7149（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：118（近 12 个月 86 个）

## 中文简介

[![NPM Version](https://img.shields.io/npm/v/%40caspeco%2Fcasper-ui-library)](https://www.npmjs.com/package/@caspeco/casper-ui-library)

## 安装

```sh
npm install @caspeco/casper-ui-library
```

也可以使用：`pnpm add @caspeco/casper-ui-library`、`yarn add @caspeco/casper-ui-library`、`bun add @caspeco/casper-ui-library`

## README

# @caspeo/casper-ui-图书馆

[![NPM Version](https://img.shields.io/npm/v/%40caspeco%2Fcasper-ui-library)](https://www.npmjs.com/package/@caspeco/casper-ui-library)

卡斯克的UI组件库,建于顶部 [查克拉乌伊](https://chakra-ui.com/)。 。 。 .

👉 **使用量文档可见于 [https://caspeco.github.io/casper-ui-library \* 互联网档案馆的存檔,存档日期2013-12-22](https://caspeco.github.io/casper-ui-library*)\* 联合国**

## 地方发展

为了建造这个项目,你需要 [节点.js](https://nodejs.org/en) 已安装.

### 图标

所有命令都从工程的根部,从终端运行.

| 命令 | 说明 |
| --- | --- |
| `npm install` | 安装依赖关系 . |
| `npm run dev` | 构建整个库的本地开发版本,编译为单一的.js文件来改进HMR. 当文件内容发生变化时自动重建. |
| `npm run build` | 在 npm 上运出时构建库 。 在文件更改时不自动重建, 但是您仍然可以使用此构建输出来验证您在文档网站或其他工程中的更改 . |
| `cd ../docs && npm run dev` | 启动文档网站。 通常您想要在 Dev 模式下运行此同时运行库, 所以为此打开一个新的终端 。 见 [/文档](https://npmcn.com/package/%40caspeco/docs) 需要更多信息. |
| `npm run test` | 运行单元测试. |
| `npm run test:visual` | 在多克使用 Playwright 进行视觉回归测试. 自动开始/停止 Docker 容器 . |
| `npm run test:visual:ui` | 打开 HTML 报告查看器以获取视觉测试结果. |
| `npm run test:visual:update` | 更新视觉回归基线截图 。 故意修改用户界面后运行此功能 . |
| `npm run lint` | 运行嵌入 [@ caspeco/ slint- config](https://github.com/Caspeco/eslint-config)。如果您使用推荐的 [ESLint VSCode 扩展](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) 您可以直接在编辑器中看到您的 eslint 错误, 而无需运行此操作 . |
| `npm run prettier:fix` | 重写所有文件 [@ caspeco/ prettier- config](https://github.com/Caspeco/prettier-config)。如果您使用推荐的 [Pretier VSCode 扩展](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) 您可以在文件保存中自动格式化您的文件. |
| `npm run chakra:types` | 为主题生成 Chakra UI 类型定义 。 如果您修改了组件变体, 想要消除 TS 错误, 例如, 请运行此功能 。 自动发生 `npm install`。 。 。 . |
| `npm run test:all` | 按顺序运行 CI 任务运行的每个检查 : `prettier`, (中文(简体) ), `lint`, (中文(简体) ), `tsc`, (中文(简体) ), `knip` 财务报告和审定财务报表 `test`。在第一次失败时停止。 需要 Playwright 浏览器(`npm exec -- playwright install chromium`用于单位测试. |

### 在另一个工程中本地预览

1.  构建本地开发版(见上文).
2.  在消耗的应用,运行 `npm install --no-save ./relative/path/to/this/directory` (没有后面的斜线).
    -   例如: `npm install --no-save ../../casper-ui-library/packages/casper-ui-library`

现在,当您在组件库中进行更改时,它应该自动重建,消耗的app的HMR应该踢入并重新加载页面(由于整个库被重建,保存状态是不可能的).

要再次解开链接,你只需要运行 `npm install` 在消费应用。 如果失败, 您可能需要删除 `node_modules` 先说.

如果您得到关于重复反应版本的错误, 请确定这是在 `vite.config.ts` 在消费应用程序中:

```ts
import path from "node:path";

export default defineConfig({
    // ...
    resolve: {
        alias: {
            react: path.resolve("./node_modules/react"),
        },
    },
});
```

### 视觉回归测试

视觉回归测试通过将组件变体的截图与承诺的基线进行比较,捕获无意的UI变化 `__screenshots__/`。它们与Playwright在多克运行,以确保在不同的开发环境和CI之间一致的渲染.

**所需资源**:必须安装并运行多克.

**正在测试**数字 :

-   `npm run test:visual` - 进行所有视觉测试
-   `npm run test:visual:ui` - 打开 HTML 报告查看器
-   `npm run test:visual:update` - 在有意UI变化后更新基线截图

> \[TIP\] CI失败了,但是本地通行证?
> 
> 1.  转到 `visual-tests` gitHub 动作中的任务
> 2.  下载并提取 HTML 文物 `Upload visual test report` 步骤
> 3.  运行 `npx vite preview --outDir .` 在提取目录中查看 CI 的 diff 报告

你可能需要调整 [像素匹配比较器选项](https://vitest.dev/api/browser/assertions.html#pixelmatch-comparator-options) 如果您看到假阳性是由于反异形或子像素渲染差异。 例子见现有测试.

## 捐款

1.  确保您的存储器是最新的.
    
    ```bash
    git pull
    ```
    
2.  创建新分支, 并在此进行更改 。 最好使用包含任何相关的Jira问题和一些简短的描述性名称的分支名称.
    
    ```bash
    git checkout -b UTF-837-add-checkbox-component
    ```
    
3.  做你的改变。 别碰 `version` 输入 `package.json`,CI处理它.
4.  打开 a [拉动请求](https://github.com/Caspeco/casper-ui-library/pulls) 使用模板并指定一个审查者.
5.  如果更改应予放行,请添加 **一个** 标签 `bump-patch`, (中文(简体) ), `bump-minor` 或者说 `bump-major` (随后) [语义版本](https://semver.org/)) (中文(简体) ). 该版本只反映API的改变(例如去除道具 → MAJOR,再加道具 → MINOR,没有公共API的改变 → PATCH). 用户界面更改为 **没有** API改变.
6.  如果 PR 对 UI 进行了重大修改(例如更改所有按钮的大小),则在 [最关键频道](https://snack.azure.caspeco.com/default/channels/casper-ui-20)。 。 。 .
7.  经批准后,合并PR. 如果它有一个凸起的标签,CI 撞出版本,承诺它 `main` 并出版到npm. [`@caspeco/casper-ui-css`](https://npmcn.com/package/%40caspeco/casper-ui-css) 以同样的方式释放 `bump-css-*` 标签。 文件网站总是被重建.

### 如何添加新图标

1.  **从图像导出** 在那个 [图像图标文档](https://www.figma.com/file/NE7GL10FbQcEPSL4M0gpNh/Casper-UI-2.0?type=design&node-id=9837-10627&mode=design)选择 **文件 — 导出** 图标导出为 **特别工作组**。 。 。 .
    
2.  **清洁图标资产** 从寄存器根运行 `npm run clean:icons` 删除在 `lib/components/icon/assets` 和生成的 React 图标组件 `lib/components/icon/icons`。 。 。 .
    
3.  **更新资产** 丢入输出的 SVG 。 验证更改 `git diff`。 。 。 .
    
4.  **生成组件** 从寄存器根运行 `npm run generate:icons` 生成每个图标的 React 组件.
    
5.  **格式生成反应图标组件** 生成的图标组件初始格式可能不正确 。 如果这样的话,就快跑 `npm run prettier:fix`。 。 。 .

## 常见问题

### 如何安装 @caspeco/casper-ui-library？

在项目目录运行 npm install @caspeco/casper-ui-library，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.2\.7）、react-dom（^19\.2\.7）、@emotion/cache（^11\.14\.0）、@emotion/react（^11\.14\.0）、@chakra-ui/react（^3\.32\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @caspeco/casper-ui-library 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @caspeco/casper-ui-library 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @caspeco/casper-ui-library 可以商用吗？

@caspeco/casper-ui-library 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @caspeco/casper-ui-library 的下载量有多少？

根据 npm 官方下载统计，@caspeco/casper-ui-library 在 2026/10/09 – 2026/11/07 这 30 天内被下载 7,149 次，日均约 238 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @caspeco/casper-ui-library 还在维护吗？

最新版本 12\.2\.0 发布于 2026/11/06（2 天前）；至今共发布 118 个版本，其中过去 12 个月发布了 86 个；首次发布于 2025/08/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。