# @hcl-software/enchanted-react-components 中文文档

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

版本：3\.0\.3
npm 元数据更新时间：2026-11-02T13:35:38.919Z
中文译文更新时间：2026-11-17T18:05:32.299Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.4 MB，430 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：13 个
- peer 依赖：react ^19\.2\.7，react-dom ^19\.2\.7
- 首次发布：2024-04-22T07:20:20.391Z
- 最新版本发布：2026-11-02T13:35:38.558Z
- 近 30 天下载量：4845（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 16 个）

## 中文简介

Conclated React Inception是HCL软件产品所使用组件的集合.

## 安装

```sh
npm install @hcl-software/enchanted-react-components
```

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

## README

# @hcl-software/魔法反应-组件

Conclated React Cuplics是一款正在HCL软件产品中使用的ui组件的集合. 此软件包取决于 [材料 UI 组件库](https://github.com/mui-org/material-ui/tree/master/packages/material-ui)。 。 。 .

(C) 2024 HCL美国公司Apache-2.0许可证 [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)

[![npm](https://nodei.co/npm/@hcl-software/enchanted-react-components.png)](https://www.npmjs.com/package/@hcl-software/enchanted-react-components)

## 使用量

```sh
npm install @hcl-software/enchanted-react-components
```

```typescript
import Button, { ButtonVariants } from '@hcl-software/enchanted-react-components/dist/Button/Button';

...

return (
  <Button
    id="button-id"
    variant={ButtonVariants.CONTAINED}
    onClick={() => {
      console.log('click');
    }}
  >
    Button
  </Button>,
);

```

## 发展

### 国家预防机制目标

我们提供以下公用事业开发命令:

| 塔克语name | 命令 | 说明 |
| --- | --- | --- |
| `install` | `npm ci` | 项目依赖性的初步安装。 运行这个开始. |
| `clean` | `rm -rf node_modules` 财务报告和审定财务报表 `rm -rf dist` | 删除所有节点等 |
| `build lib` | `npm run build` | 构建软件包 |
| `lint` | `npm run lint` | 运行 Linting 任务 |
| `build storybook` | `npm run build-storybook` | 构建故事书 |
| `storybook` | `npm run storybook` | 运行故事书实例 |
| `unit and integration` | `npm run test` | 运行单元和整合测试 |
| `storyshots` | `npm run test-storyshots` | 运行故事拍摄测试。 env 参数 `DONT_EXIT_ON_DIFF=true` 提供了一种特性,即如果检测到某些偏差,测试不会失败. |

### 构成部分结构

#### 原子成分

原子元件是一个元件的最小单位. 例如:按钮或面板.

#### 复合部分

复合元件是原子元件的组合来创造出更大的元件. 例如,具体的表格.

#### 必要组成部分

一个先决条件组成部分是只存在于更高一级部件中的部件。 这一组成部分不应单独使用.

### 输出最佳做法的模块

-   每个组件文件夹结构都有自己的index.ts文件作为本地模块,用于导出默认并命名导出.
-   这个 `src` 文件夹包含一个全局索引.ts文件,将组件输出全球,并指向每个组件文件夹的本地索引.ts文件.
-   在整个项目中使用“魔法反应组件”库时,确保将新创建的组件输出到全球,用于简洁和可读出口.

### 他们

图书馆支持 `LightNeutralGrey` 财务报告和审定财务报表 `LightCoolGrey` 主题。 未来a `DarkNeutralGrey` 财务报告和审定财务报表 `DarkCoolGrey` 还应支持主题. 这个 `LightNeutralGrey` 财务报告和审定财务报表 `LightCoolGrey` 主题可以通过 `createEnchantedTheme()` 方法.

```typescript
// e.g.
createEnchantedTheme(ThemeDirectionType.RTL, ThemeModeType.LIGHT_COOL_GREY);
// or
createEnchantedTheme(ThemeDirectionType.LTR, ThemeModeType.LIGHT_NEUTRAL_GREY);
```

"主题提供者"需要成为组件等级中的第一个组件.

```typescript
import { ThemeProvider } from '@mui/material/styles';
import { ThemeDirectionType, ThemeModeType, createEnchantedTheme } from '@hcl-software/enchanted-react-components/dist/theme';

const enchantedTheme = createEnchantedTheme(ThemeDirectionType.LTR, ThemeModeType.LIGHT_NEUTRAL_GREY);

return (
  <ThemeProvider theme={enchantedTheme}>
    ...
  </ThemeProvider>
)
```

### RTL 支持

库完全支持RTL模式. 每个新的实施部分也需要支持RTL模式.

* * *

**_注:_**

图书馆使用 `stylis-plugin-rtl` 财务报告和审定财务报表 `stylis` 实现RTL支持。 我们锁定了这个图书馆的依赖性要求 `stylis` 4.0.13 应付 `stylis`维护问题 请确保这是您项目依赖树上的依赖的解析版本 .

-   确定你的项目 `stylis` 版本为 4.0.13,第一,运行 `npm ls stylis` 以下列表具有子依赖性的依赖 `stylis`。 。 。 .
-   接下来, 解开并重新安装这些依赖关系, 这样在重置时, 包就会被覆盖 `stylis` 时间为4.0.13。 例如,依赖性 `stylis-plugin-rtl` 具有子依赖性 `stylis`运行 `npm uninstall stylis-plugin-rtl`。 。 。 .
-   程е禲 `npm install stylis-plugin-rtl`,为了安全起见,您可能要指定此方块的 semver 到软件包中的 `npm install stylist-plugin-rtl@{insert-semantic-version-here}`。 。 。 .

* * *

A 类 `ltr` 财务报告和审定财务报表 `rtl` 主题可以通过 `createEnchantedTheme()` 方法.

对于“ trl” 支持 `DirectionStyleProvider` 还有必要。 此组件应当将 `ThemeProvider`。这里有一个简短的例子:

```typescript
import { ThemeProvider } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline';

import DirectionStyleProvider from '@hcl-software/enchanted-react-components/dist/DirectionStyleProvider';
import { ThemeDirectionType, ThemeModeType, createEnchantedTheme } from '@hcl-software/enchanted-react-components/dist/theme';

const themeDirection = ThemeDirectionType.LTR;
const enchantedTheme = createEnchantedTheme(themeDirection, ThemeModeType.LIGHT_NEUTRAL_GREY);

return (
  <DirectionStyleProvider direction={themeDirection}>
    <ThemeProvider theme={enchantedTheme}>
      <div dir={themeDirection}>
        <CssBaseline />
        <App />
      </div>
    </ThemeProvider>
  </DirectionStyleProvider>
)
```

**说明**数字 : `<CssBaseline />` 将会在页面中注入一些全局样式。 如果不需要,请将您的应用程序包入 `<ScopedCssBaseline>` 换句话说.  
例如:

```
import ScopedCssBaseline from '@mui/material/ScopedCssBaseline';
...
  <DirectionStyleProvider direction={themeDirection}>
    <ThemeProvider theme={enchantedTheme}>
      <div dir={themeDirection}>
        <ScopedCssBaseline>
          <App />
        </ScopedCssBaseline>
      </div>
    </ThemeProvider>
  </DirectionStyleProvider>
```

### 调试 - 类型和颜色

#### 类型

默认的材料UI Typography变体被扩展为另外四个变体. 打字变体名称与设计打字名称一致.

默认物质 UI 变体 :

-   (单位:千美元)
-   页:1
-   h3 (韩语)
-   h4 (中文(简体) )
-   h5 (韩语)
-   小时6
-   字幕1
-   字幕2
-   体质1
-   车体1粗体
-   体质
-   机构2
-   车体2粗体
-   体型2斜体
-   标题

扩展变体 :

-   车体1粗体
-   体质
-   车体2粗体
-   体型2斜体

这个 `Inter, sans-serif` 目前配置为所有打字机的默认字体家族.

#### 颜色

所有被使用过的颜色都带有了特定的名称。 这些彩色标志与设计彩色标志一致.

### 样式覆盖

材料UI提供了四种不同的方式来覆盖组件特定样式:

-   [一次性定制](https://mui.com/material-ui/customization/how-to-customize/#1-one-off-customization)
-   [可重复使用的组件](https://mui.com/material-ui/customization/how-to-customize/#2-reusable-component)
-   [全球主题覆盖](https://mui.com/material-ui/customization/how-to-customize/#3-global-theme-overrides)
-   [全球CSS 覆盖](https://mui.com/material-ui/customization/how-to-customize/#4-global-css-override)

在魔法反应组件库中,我们将这些选项限制在以下三个:

-   一次性定制 > sx道具
-   可重复使用的组件
-   全球主题覆盖

CSS定制的首选和强制性方法是: `Global theme override`替代品只应在下列情况下使用: `Global theme override` 无法解决具体问题.

#### 一次性定制

更多关于 `sx prop` 可见 [这里](https://mui.com/system/getting-started/the-sx-prop/)。 。 。 .

#### 可重复使用的组件

更多关于 `styled() method` 可见 [这里](https://mui.com/system/styled/)。 。 。 .

```typescript
export const StyledInputLabel = styled(MuiInputLabel)((theme) => {
  return {
    ...theme.theme.typography.subtitle2,
    color: theme.theme.palette.text.secondary,
    margin: '0px',
    span: {
      paddingRight: '4px',
    },
    ...
  };
});
```

#### 全球主题覆盖

更多关于 `theme components override` 可见 [这里](https://mui.com/material-ui/customization/theme-components/)。 。 。 .

基本想法是在每个组成部分中增加一种具体的方法(`getMui<COMP-NAME>ThemeOverrides`)正在收集所有所需的CSS调整。 这种方法应该有这样的逻辑:

```typescript
/**
 * Override out of the box styling from mui to align with designer theme
 * @returns override <COMP-NAME> component styles and prop
 */
export const getMui<COMP-NAME>ThemeOverrides = (): Components<Omit<Theme, 'components'>> => {
  return {
    Mui<COMP-NAME>: {
      styleOverrides: {
        root: ({ ownerState, theme }) => {
          return ({
            backgroundColor: 'red', // this is only an example
          });
        },
      },
    },
  };
};
```

输出不能添加到 `components` 属性 `ThemeOptions` 就这样.

```typescript
  const themeOptions: ThemeOptions = {
    components: {
      ...getMui<COMP-NAME>ThemeOverrides(),
    },
    ...
  };
```

> **_注:_** 每个MUI组件只能是一次宣布,因为Global主题覆盖接受每个MUI组件一个密钥值.

### 故事书

对于孤立的构建 魔法反应组件库,我们正在使用 [故事书](https://storybook.js.org/)故事书帮助我们以工业标准的方式提供、测试、记录和审查被魔法化的部分。 故事书是开源和免费的,被上千支队伍使用.

目前,我们已经将我们的构成部分分成了五个不同的部分。 在每个组别下,将各部分放在一组内.

-   导航
-   反馈
-   投入
-   数据显示
-   表面

简介页也是每个故事书实例的一部分.

每个组成部分应有两个具体组成部分的例子:

-   交互式示例 > 控制部分是启用的,组件可以在不同的变相/通量中测试.
-   视觉测试 > 控制区已禁用 。 此示例仅被视觉测试(storyshots)所使用,用于识别造型变化. 这一例子提供了单个页上某一部分的多数合理变化/变化.

#### 视觉测试(弹片测试)

这个过程正在检测一些UI的分化,并将产生一些比较截图.

##### 本地运行

-   清除故事截图图像文件夹 `./src/__tests__/unit/__image_snapshots__`
    
-   本地运行故事书.
    
    ```
    npm run storybook
    ```
    
-   创建基准集 。 所有图像将存储在文件夹下 `./src/__tests__/unit/__image_snapshots__`
    
    ```
    npm run test-storyshots
    ```
    
-   做一些UI修改,比如: 调整主色调或者增加边框的大小, 绑定, 边框.
    
-   运行 `test-storyshots` 再次命令以获取所有 UI 偏移 。 检测到的偏差将存储在文件夹下 `./src/__tests__/unit/__image_snapshots__/__diff_output__`
    
    ```
    npm run test-storyshots
    ```

## 常见问题

### @hcl-software/enchanted-react-components 是什么？

Conclated React Inception是HCL软件产品所使用组件的集合\.

### 如何安装 @hcl-software/enchanted-react-components？

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

### @hcl-software/enchanted-react-components 支持 TypeScript 吗？

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

### @hcl-software/enchanted-react-components 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @hcl-software/enchanted-react-components 可以商用吗？

@hcl-software/enchanted-react-components 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @hcl-software/enchanted-react-components 的下载量有多少？

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

### @hcl-software/enchanted-react-components 还在维护吗？

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

