# @cruk/cruk-react-components 中文文档

规范地址：https://npmcn.com/package/%40cruk/cruk-react-components/

版本：8\.0\.0
npm 元数据更新时间：2026-10-26T16:25:30.098Z
中文译文更新时间：2026-11-11T02:09:10.903Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cruk/cruk-react-components
原文对照：https://npmcn.com/package/%40cruk/cruk-react-components/?lang=original
项目主页：https://github.com/CRUKorg/cruk-react-components#readme
源码仓库：https://github.com/CRUKorg/cruk-react-components

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

- 包体积（解压后）：1.5 MB，125 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react ^19，react-dom ^19
- 首次发布：2021-02-04T11:12:39.836Z
- 最新版本发布：2026-10-26T16:25:29.658Z
- 近 30 天下载量：2687（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：126（近 12 个月 26 个）

## 中文简介

执行 CRUK、RFL、SU2C和Bowelbabe 设计的反应组件

## 安装

```sh
npm install @cruk/cruk-react-components
```

也可以使用：`pnpm add @cruk/cruk-react-components`、`yarn add @cruk/cruk-react-components`、`bun add @cruk/cruk-react-components`

## README

# 克-反应-组件

CRUK设计系统的回放执行只使用回放HTML和CSS. 包含所有组件的下列主题

-   克鲁克
-   法语
-   SU2C 双管
-   鲍尔巴贝

## 查看故事书

cruk-react-inform- storybook site 演示所有组件及其不同的变体和主题: [https://master.d28a8la187lo73.amplifyapp.com/ (中文(中国大陆) )](https://master.d28a8la187lo73.amplifyapp.com/)

## 开始

添加 cruk- react- 组件及其对等的依赖关系 对您的 package.json 文件的反应、 反应大小和样式的组件 .

```sh
"dependencies": {
  "react": "^19",
  "react-dom": "^19"
}
```

之后 `npm i @cruk/cruk-react-components --save`,您可以从库中导入组件 :

```js
// Ideally you would import the css on the top level entry point on you app
// because you only need to import this once
import "@cruk/cruk-react-components/lib/index.css";
import { Button } from "cruk-react-components";

const MyComponent = () => (
  <div>
    <Button />
  </div>
);
```

## 以自定义样式扩展您的组件

### 使用样式道具

```js
import { Button } from "cruk-react-components";

const MyComponent = () => (
  <div>
    <Button style={{ color: "#ff0000" }} />
  </div>
);
```

### 使用自己的 css 类

让我们说,我们想要预留和使用组件上存在的API,我们想要添加我们自己的CSS类,但我们不想覆盖已经样式组件的CSS类 溶液很简单,因为每个组件 CSS 在导入索引时已经曝光

```js
import "@cruk/cruk-react-components/lib/index.css";
```

总是跟随同样的命名对流

`.component-{componentName}`

举个例子

-   `.component-button`
-   `.component-link`
-   `.component-text-field`
-   `.component-textarea-field`

因此,我们需要包括组件类 和我们新的CSS类

```js
import { Button } from "cruk-react-components";

const MyComponent = () => (
  <div>
    <Button
      appearance="primary"
      className={["component-button", "my-other-class-name"].join(" ")}
    />
  </div>
);
```

### 公用事业类

目前共有3个通用CCS类

-   `color-props`
-   `spacing-props`
-   `text-props`

此功能 CSS 类可以像这样使用

```js
const MyComponent = () => (
  <div className="color-props" data-bg-color="primary">
    <Button
      appearance="primary"
      className={["component-button", "spacing-props"].join(" ")}
      data-margin-bottom="s"
    />
  </div>
);
```

##### 颜色道具

此 CSS 类将在主题中取出名称颜色并将其应用到以下数据属性

-   `data-color`: 文本和 svg 颜色
-   `data-bg-color`: 背景颜色
-   `data-border-color`: 边框颜色

##### 文本道具

CSS 类将选择命名字体权重( vlight, light, medum, 普通, 重) , 命名字体家族( 碱基, 按钮, 链接, 标题, 标签) 和每个主题指定的字体大小( xs, s, m, l, xl, xxl, xxl, xxl) 等主题, 以及数据属性之后的文字包, 外溢包等

-   `data-word-break`: 断字
-   `data-overflow-wrap`: 溢出错误
-   `data-text-font-family`: 使用命名字体类别设置字体家族
-   `data-text-weight`: 使用名称权重类别设置字体权重, 匹配 HTML 常规
-   `data-text-size`: 使用来自主题的命名字体大小设置字体大小

##### 间距道具

此 CSS 类将设置以下命名的相距值为不同的相距 CSS 属性 . 名称间隔值为:

-   `none`:0; (中文(简体) );
-   `auto`: 自动;
-   `xxxs`: 0.25雷姆; / 4px / (中文(简体) )
-   `xxs`: 0.5雷姆; / 8px / (中文(简体) )
-   `xs`: 1rem; / 16px (中文(简体) )
-   `s`: 1.5雷姆; / 24px / (中文(简体) )
-   `m`: 2rem; / 32px (中文(简体) )
-   `l`: 2.5雷姆; / 40px /
-   `xl`: 3rem; / 48px (中文(简体) )
-   `xxl`: 3.5雷姆;/ 56px /
-   `full`:100%;

现有属性为:

-   `data-margin`: 所有边距
-   `data-margin-vertical`: 上下边距
-   `data-margin-horizontal`: 左右边距
-   `data-margin-top`: 上边距
-   `data-margin-bottom`: 下边距
-   `data-margin-left`: 左边距
-   `data-margin-right`: 右边距
-   `data-padding`: 所有粘贴
-   `data-padding-vertical`: 上下粘贴
-   `data-padding-horizontal`: 左右绑定
-   `data-padding-top`: 上贴
-   `data-padding-bottom`: 垫底
-   `data-padding-left`: 左侧粘贴
-   `data-padding-right`: 右补丁

## 从V5和V6迁移到V7

样式组件已进入维护模式 .

-   第一阶段是使用HTML元素上的CSS变量和数据属性来进行它们,而不是使用"样式组件"主题和"主题提供".
-   第二阶段是将用Styled组件所写的组件转换为html和css模块并去掉Styled组件.

### 主题

所以,代替主题 这样

```tsx
import { Button, crukTheme } from "cruk-react-components";
import { ThemeProvider } from "styled-components";

const MyComponent = () => (
<ThemeProvider theme={crukTheme}>
  <Button/>
<ThemeProvider />
);

```

您只需要使用 html 元素 `data-theme="cruk"`,具有数据主题的最内在元素将覆盖外包元素.

```tsx
const MyComponent = () => (
  <span data-theme="su2c">
    <Button/>
  <span/>
);
```

### 有主题依赖内容的组件

由于新的主题策略只影响CSS而不是内容,因此具有主题特定内容的组件现在拥有"主题名"的必备属性. 使用这些组件的应用程序必须输入此道具 。 下列组件需要主题Name prop :

-   有远见
-   页眉
-   页脚
-   用户锁定
-   套期报告\*

\* Modal是一个特殊的案例,它需要主题 命名道具是因为任何主题提供者都不会工作. Modals使用将元素置于全新html上下文的回放门户.

### 主题变量命名公约

因为主题名称现在来自 CSS 变量而不是主题对象, 主题名称是骆驼案例, 现在被蛇案例 `textDark` 现在变成 `text-dark`

## 从V4向V5的迁移

因为现在Styped Parties在绝对Typed项目上依靠社区的努力来管理自己的类型,所以你可能需要在风格上Conceptents componets内部使用通用软件而不是内置道具类型定义.

### 在此之前:

```tsx
export const StyledButton = styled(Button)`
  border-radius: ${({ theme }: StyledButtonProps) => theme.button.borderRadius};
`;
```

### 现在:

```tsx
export const StyledButton = styled(Button)<StyledButtonProps>`
  border-radius: ${({ theme }) => theme.button.borderRadius};
`;
```

样式组件 6 也不再过滤出自定义道具, 所以为了阻止道具向子组件或基本的 html 元素出血, 在道具名称上加一美元前请参见下面的大小道具 :

### 在此之前:

```tsx
<StyledAvatar
  {...rest}
  size={theme.avatar[size || "m"]}
  src={avatarUrl()}
  alt={alt}
/>
```

### 现在:

```tsx
<StyledAvatar
  {...rest}
  $size={theme.avatar[size || "m"]}
  src={avatarUrl()}
  alt={alt}
/>
```

## 从V0到V1的迁移

1.  查找所有 RadioGroup 实例并将其更改为 Radio Conservation 的新组件名称
2.  旧按钮外观="tertiary"已去掉并被替换为旧按钮外观的变体="text"

建议的解决方案是找到所有外观实例="tertiary",取而代之的是外观实例="二级",并找到所有外观实例="text",取而代之的是外观实例="ttertiary"

## 发展

克隆此寄存器

```sh
git clone git@github.com:CRUKorg/cruk-react-components.git
```

通过故事书进行开发

```sh
npm run storybook
```

您可能需要运行

```sh
npm run build-storybook
```

## 测试

节点:单位测试, Playwright: 组件函数, 可访问性 Chromatic:图像快照比较服务,这在CI中发生,人们可以通过他们的Github登录获得这一服务.

运行所有测试单元和 Playwright

```sh
 npm run test
```

运行 Playright 交互测试套件( 功能测试和访问测试) 您可能需要运行 `npx playwright install` 第一次使用 Playwright 时

```sh
test-ct:ui
```

## 维持

### 依赖关系

如果你改编成故事书 请在合并前在本地运行 如果你改编成卷

```bash
npm run rollup:build-lib
```

并查看它是否能够在运行发行脚本前成功构建库

### 释放

#### 释放前

请更新软件包中的版本编号. json并遵循版本编号的 semver 标准. 运行 `nvm use` 确保您在正确的节点版本. 运行 `npm i` 以确保锁文件中的正确版本. 更新 ChangeGELOG.md 应列出发布时的更改, 指令位于文件底部 . 这些更改需要合并为主.

#### 释放

确定您有正确的权限 。 @ cruk org 在国家预防机制. 运行发行脚本 `npm run release` 这应该使用 `release-it` 允许您选择与套件 JSON 中描述的相同的版本编号,它应该照顾其余的:

-   它运行 npm ci
-   它的建设
-   它制造和推出标签
-   释放了国家防范机制
-   如果您想要在 github 上记录释放内容, 并自动生成释放笔记, 它会请求.

同意所有这些步骤 释放它走过, 当Github打开 释放点击 `Publish` 按钮。 如果有什么不对的释放 - 它应该退后.

## 常见问题

### @cruk/cruk-react-components 是什么？

执行 CRUK、RFL、SU2C和Bowelbabe 设计的反应组件

### 如何安装 @cruk/cruk-react-components？

在项目目录运行 npm install @cruk/cruk-react-components，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19）、react-dom（^19）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cruk/cruk-react-components 支持 TypeScript 吗？

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

### @cruk/cruk-react-components 支持 ESM 还是 CommonJS？

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

### @cruk/cruk-react-components 可以商用吗？

@cruk/cruk-react-components 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cruk/cruk-react-components 的下载量有多少？

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

### @cruk/cruk-react-components 还在维护吗？

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