Enonic 反应组件

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

安装

npm install --save @enonic/react-components

兼容性

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

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

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

组件注册

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

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数字 :

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 使用组件描述符.

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

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

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

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 区域.

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

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

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

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

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

丰富文本

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

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

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

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

import {Fragment} from 'react';

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

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

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

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

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属性产生.

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

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

自定义替换器

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

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 消费者使用严格的无效检查,可能需要添加后卫. 图像或媒体参考的存在并不能保证其内容可以得到.

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中仍然可用,但其存在并不能消除处理无效参考内容的需要.