# @enonic/react-components 中文文档

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

版本：7\.1\.0
npm 元数据更新时间：2026-11-11T13:30:44.978Z
中文译文更新时间：2026-11-14T06:25:30.540Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：93.7 kB，23 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18 \|\| ^19，prop-types \*，@types/react ^18 \|\| ^19，html-react-parser ^5 \|\| ^6，@enonic-types/core ^7\.15\.0 \|\| ^8，@enonic-types/lib-portal ^7\.15\.0 \|\| ^8，@enonic-types/lib-schema ^7\.15\.0 \|\| ^8
- 首次发布：2022-03-08T11:50:45.823Z
- 最新版本发布：2026-11-11T13:30:44.594Z
- 近 30 天下载量：2255（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 13 个）

## 中文简介

处理 Enonic XP 数据和页面组件的响应组件库

## 安装

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

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

## README

# Enonic 反应组件

处理 Enonic XP 数据的响应组件库 .

## 安装

```console
npm install --save @enonic/react-components
```

### 兼容性

7.1版本支持以下对等依赖性:

| 依赖性 | 支持的版本 |
| --- | --- |
| `react` 财务报告和审定财务报表 `@types/react` | 18或19条 |
| `html-react-parser` | 5或6个 |
| `@enonic-types/core`, (中文(简体) ), `@enonic-types/lib-portal`, (中文(简体) ), `@enonic-types/lib-schema` | `^7.15.0` 或者说 `^8` |
| `prop-types` | 任何版本 |

使用匹配版本的 `react-dom` 用于您的反应安装 。 使用时 `html-react-parser` 6,其DOM依赖性需要20.19节点或更晚. 使用 parser 5 的应用程序不需要升级 parser 来使用此库 .

这套软件提供了无害环境管理和共同JS构建。 从 `@enonic/react-components`编辑 `@enonic/react-components/nashorn` 切入点提供相兼容的 Nashorn 子集;不要将主渲染出入 Nashorn .

## 组件注册

这个 `ComponentRegistry` 用于为部件、版式、页面、宏和内容类型注册视图组件。 注册的组件随后由相应的 `Base*` 组件.

```typescript
import {ComponentRegistry} from '@enonic/react-components';

const componentRegistry = new ComponentRegistry();

componentRegistry.addPart('com.enonic.app.myapp:mypart', {
  View: MyPartView
});

componentRegistry.addLayout('com.enonic.app.myapp:mylayout', {
  View: MyLayoutView
});

componentRegistry.addPage('com.enonic.app.myapp:mypage', {
  View: MyPageView
});

componentRegistry.addMacro('mymacro', {
  View: MyMacroView
});

componentRegistry.addContentType('com.enonic.app.myapp:mycontenttype', {
  View: MyContentTypeView
});
```

登记的组成部分收到 `ComponentProps`数字 :

```typescript
import type {ComponentProps} from '@enonic/react-components';

function MyPartView({component, data, common, meta}: ComponentProps) {
  return <div>{/* render part */}</div>;
}
```

## 基本组件

这个 `BaseComponent` 确定组成部分类型和代表向适当的基础组成部分(`BasePart`, (中文(简体) ), `BaseLayout`, (中文(简体) ), `BasePage`, (中文(简体) ), `BaseText`, (中文(简体) ), `BaseContentType`) (中文(简体) ). 每个基件组件都查看已注册的视图 `ComponentRegistry` 使用组件描述符.

```typescript
import {BaseComponent} from '@enonic/react-components';

<BaseComponent component={component} data={data} meta={meta} common={common} />
```

这个 `meta` 道具上下文,包括 `componentRegistry` 请求 `mode`数字 :

```typescript
import type {MetaData} from '@enonic/react-components';

const meta: MetaData = {
  type: 'portal:site',
  id: 'content-id',
  path: '/mysite',
  mode: 'live',
  componentRegistry,
};
```

## 区域

这个 `Regions` 财务报告和审定财务报表 `Region` 组件生成包含页面组件的 Enonic XP 区域.

```typescript
import {Regions} from '@enonic/react-components';

function MyPageView({component, data, common, meta}: ComponentProps) {
  return (
    <div>
      <Regions component={component} meta={meta} common={common} />
    </div>
  );
}
```

`Region` 也可以直接用于更多的控制 :

```typescript
import {Region} from '@enonic/react-components';

<Region
  name="main"
  data={regionComponents}
  meta={meta}
  as="main"
  className="my-region"
/>
```

## 丰富文本

这个 `RichText` 组件从 Enonic XP 生成已处理的 HTML, 支持自定义图像、 Link 和 Macro 替换器.

```typescript
import type {RichTextData, RichTextMetaData, PartData} from '@enonic/react-components';
import {RichText} from '@enonic/react-components';

const meta: RichTextMetaData = {
  type: 'portal:site',
  id: 'content-id',
  path: '/mysite',
  mode: 'live',
};

const component: PartData = {
  descriptor: 'com.enonic.app.myapp:mypart',
  path: '/main/0',
  type: 'part',
};

const data: RichTextData = {
  processedHtml: '<p>Hello World</p>',
  macros: [],
  images: [],
  links: [],
};

<RichText data={data} meta={meta} component={component} />
```

### 自定义标签和类Name

```typescript
<RichText
  data={data}
  meta={meta}
  component={component}
  tag="article"
  className="rich-text"
/>
```

默认包装是 `section`在没有包装的情况下,通过反应 `Fragment`数字 :

```tsx
import {Fragment} from 'react';

<RichText data={data} meta={meta} component={component} tag={Fragment} />
```

`tag` 也接受自定义 React 组件。 它收到解析的内容为 `children` 和供应 `className`。 。 。 . `className` 当包装是 `Fragment`。 。 。 .

### 自定义图像、链接和宏组件

您可以覆盖默认的图像、 链接和宏组件 。 额外道具通过通用程序传送到自定义组件 `RestProps` 类型参数.

```typescript
import type {
  ImageComponent,
  LinkComponent,
  MacroComponent,
} from '@enonic/react-components';
import {RichText} from '@enonic/react-components';

const MyImage: ImageComponent = ({alt, src, srcSet, sizes, style}) => {
  return <img alt={alt} src={src} srcSet={srcSet} sizes={sizes} style={style} />;
};

const MyLink: LinkComponent = ({href, target, title, children}) => {
  return <a href={href} target={target} title={title}>{children}</a>;
};
// Link is called for every <a> with an href. Referenced links have `data`,
// including `data.content`, `data.media` and `data.uri`.
// Ordinary HTML links (https, mailto, anchors) have `data: undefined`.

interface RestProps {
  myCustomProp: string;
}

const MyMacro: MacroComponent<RestProps> = ({component, meta, children, myCustomProp}) => {
  return <div>{children}</div>;
};

<RichText<RestProps>
  data={data}
  meta={meta}
  component={component}
  Image={MyImage}
  Link={MyLink}
  Macro={MyMacro}
  myCustomProp="value"
/>
```

与宏一样,自定义图像和链接组件通过 `data`。 。 。 . 对于图像, 这是原始的 `ImageData` 条目; 对于引用链接, 是原始 `LinkData` 输入. 普通 HTML 链接有 `data: undefined`。 。 。 . 这些条目可以携带 URL 字符串或 `UrlParts` 对象(`path`选项 `queryString` 财务报告和审定财务报表 `baseUrl`, (中文(简体) ), 反应灵敏的图像候选人,以及链接碎片. 库转发这些值不变:自定义组件决定如何解决其应用. 现有 `href`, (中文(简体) ), `src` 财务报告和审定财务报表 `srcSet` 道具仍然来自HTML,而默认组件继续使这些HTML属性产生.

现有的顶级参考道具仍作为已贬值的别名提供:

| 折旧道具 | 首选替换 |
| --- | --- |
| 图像 `image` | `data.image` |
| 图像 `imageStyle` | `data.style` |
| 链接 `content` | `data.content` |
| 链接 `media` | `data.media` |
| 链接 `uri` | `data.uri` 用于引用链接; `href` 普通 HTML 链接 |

别名保留了原始值;普通的HTML链接仍然收到 `uri: href`。 。 。 . 两种API都是一起提供,因此现有的渲染器可以递增地迁移. 对于未解决的条目,参考内容可能无效;自定义渲染器必须处理该案件. 顶级图像 `style` 道具仍然是元素的CSS,而不是图像处理元数据 `data.style`。 。 。 . 在 HTML 元素上传播道具时,将两者排除在外 `data` 和被贬损的参考道具. 默认组件已经做到这一点 .

### 自定义替换器

为了全面控制DOM节点的替换,请提供 `replacer` 函数 :

```typescript
import type {Replacer} from '@enonic/react-components';

const myReplacer: Replacer = ({el, data, component, meta}) => {
  if (el.attribs?.['class'] === 'custom') {
    return <div className="replaced" />;
  }
};

<RichText data={data} meta={meta} component={component} replacer={myReplacer} />
```

## 升级至7.1

### 自定义链接渲染适用于所有链接

在7.0,习惯 `Link` 组件仅用于链接 `data-link-ref`在7.1中 `<a>` 带有 `href` 通过习惯 `Link`,包括外部URL, `mailto:` 链接和碎片链接。 无锁定元素 `href` 或参考文献继续没有改变.

对于普通的HTML链接, `data`, (中文(简体) ), `content` 财务报告和审定财务报表 `media` 未定义,以及 `uri` 等于 `href`自定义链接渲染器不得假定每次引用都有内容参考。 额外的 HTML 属性, 例如 `class`, (中文(简体) ), `rel` 财务报告和审定财务报表 `data-*`,也可以使用React-compatible属性名称传输到自定义渲染器.

### 引用内容可以是无效的

`ImageData.image`,被贬损的图像渲染器道具 `image`,以及 `LinkDataMedia.content` 现在明确允许 `null` 用于未解决的参考。 TypeScript 消费者使用严格的无效检查,可能需要添加后卫. 图像或媒体参考的存在并不能保证其内容可以得到.

```tsx
import type {ImageComponent, LinkComponent} from '@enonic/react-components';

const MyImage: ImageComponent = ({image, alt, src, srcSet, sizes, style}) => (
  <img alt={alt ?? image?.displayName ?? ''} src={src} srcSet={srcSet} sizes={sizes} style={style} />
);

const MyLink: LinkComponent = ({media, href, children}) => (
  <a href={href} data-media-id={media?.content?._id}>{children}</a>
);
```

新的 `data` 道克会曝光原始的参考,包括结构化的URL值. 它不会自动将这些值解入HTML URL. 继续使用 HTML 源代码 `href`, (中文(简体) ), `src` 财务报告和审定财务报表 `srcSet` 道具,或解析 `data` URL明确用于您的应用程序的路由和媒体配置. 例如,在Guillotine 9 中,媒体 URL 在参考文献中为 `data.media.mediaUrl`; 较旧的有效载荷可能会在其中包含一个 URL 字符串 `data.media.content.mediaUrl`。 。 。 .

被贬低的顶级参考道具在7.1中仍然可用,但其存在并不能消除处理无效参考内容的需要.

## 常见问题

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

处理 Enonic XP 数据和页面组件的响应组件库

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

在项目目录运行 npm install @enonic/react-components，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18 \|\| ^19）、prop-types（\*）、@types/react（^18 \|\| ^19）、html-react-parser（^5 \|\| ^6）、@enonic-types/core（^7\.15\.0 \|\| ^8）、@enonic-types/lib-portal（^7\.15\.0 \|\| ^8）、@enonic-types/lib-schema（^7\.15\.0 \|\| ^8）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

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

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

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

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

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