---
name: "RichText"
mode: "component"
versionRequirements:
  - { name: "@ray-js/ray", version: "0.5.10" }
title: "RichText - 富文本"
---

## RichText

> [VERSION] @ray-js/ray >= 0.5.10

### 描述

富文本组件，用于渲染富文本内容。

### 属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `nodes` | `string \| RichTextNode[]` | 否 | - | 节点列表（元素/文本节点数组）或 HTML 字符串 |
| `onSelect` | `(event: RichTextSelectEvent) => void` | 否 | - | 点击富文本内标签时触发 |

### 引用对象

##### `interface` RichTextNode

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `name` | `string` | 标签名 |
| `attrs` | `Record<string, string>` | 节点属性 |
| `children` | `RichTextNode[]` | 子节点列表 |

##### `interface` RichTextSelectEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `detail` | `RichTextSelectDetail` | 事件数据 |

##### `interface` RichTextSelectDetail

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `name` | `string` | 标签名 |
| `attrs` | `Record<string, string>` | 标签属性 |

##### `interface` BaseEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `string` | 事件类型 |
| `timeStamp` | `number` | 页面打开到触发事件所经过的毫秒数 |
| `target` | `Target` | 触发事件的源组件 |
| `currentTarget` | `Target` | 当前组件的一些属性值集合 |
| `mark` | `any` | 事件标记数据 |

##### `interface` Target

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `id` | `string` | 事件源组件的id |
| `dataset` | `Record<string, unknown>` | 事件源组件上的 `dataset` 自定义属性组成的集合 |


### 示例代码

#### 基础用法

```tsx
import React from 'react';
import { View, RichText } from '@ray-js/ray';

export default function Demo() {
  return (
    <View style={{ padding: 20 }}>
      <RichText
        nodes='<div><h2 style="color: #333;">标题</h2><p style="color: #666; line-height: 1.6;">这是一段富文本内容</p></div>'
      />
    </View>
  );
}
```

#### HTML String 格式

```tsx
import React from 'react';
import { View, RichText } from '@ray-js/ray';

export default function Demo() {
  const htmlString = `
    <div style="padding: 10px;">
      <h1 style="color: #007aff; margin-bottom: 10px;">欢迎使用 RichText</h1>
      <p style="color: #333; line-height: 1.8;">
        Life is <i>like</i> a box of <b style="color: red;">chocolates</b>.
      </p>
      <p style="color: #666; margin-top: 10px;">
        You never know what you are gonna get.
      </p>
    </div>
  `;

  return (
    <View style={{ padding: 20 }}>
      <RichText nodes={htmlString} />
    </View>
  );
}
```

#### 文本节点列表格式

```tsx
import React from 'react';
import { View, RichText } from '@ray-js/ray';

export default function Demo() {
  const nodes = [
    { type: 'text' as const, text: '这是第一段文本。' },
    { type: 'text' as const, text: '这是第二段文本，支持 &amp; 等 HTML 实体。' },
  ];

  return (
    <View style={{ padding: 20 }}>
      <RichText nodes={nodes} />
    </View>
  );
}
```

#### 点击标签事件

```tsx
import React from 'react';
import { View, RichText } from '@ray-js/ray';

export default function Demo() {
  const html = `
    <div style="padding: 10px;">
      <p>点击下方链接文字查看控制台输出：</p>
      <a style="color: #007aff; text-decoration: underline;">可点击的链接</a>
    </div>
  `;

  return (
    <View style={{ padding: 20 }}>
      <RichText
        nodes={html}
        onSelect={(e) => console.log('点击标签:', e.detail.name, e.detail.attrs)}
      />
    </View>
  );
}
```


### 受信任的 HTML 节点及属性

全局支持 class 和 style 属性，**不支持 id 属性**。

| 节点       | 属性                            |
| :--------- | ------------------------------- |
| a          |                                 |
| abbr       |                                 |
| address    |                                 |
| article    |                                 |
| aside      |                                 |
| b          |                                 |
| bdi        |                                 |
| bdo        | dir                             |
| big        |                                 |
| blockquote |                                 |
| br         |                                 |
| caption    |                                 |
| center     |                                 |
| cite       |                                 |
| code       |                                 |
| col        | span，width                     |
| colgroup   | span，width                     |
| dd         |                                 |
| del        |                                 |
| div        |                                 |
| dl         |                                 |
| dt         |                                 |
| em         |                                 |
| fieldset   |                                 |
| font       |                                 |
| footer     |                                 |
| h1         |                                 |
| h2         |                                 |
| h3         |                                 |
| h4         |                                 |
| h5         |                                 |
| h6         |                                 |
| header     |                                 |
| hr         |                                 |
| i          |                                 |
| img        | alt，src，height，width         |
| ins        |                                 |
| label      |                                 |
| legend     |                                 |
| li         |                                 |
| mark       |                                 |
| nav        |                                 |
| ol         | start，type                     |
| p          |                                 |
| pre        |                                 |
| q          |                                 |
| rt         |                                 |
| ruby       |                                 |
| s          |                                 |
| section    |                                 |
| small      |                                 |
| span       |                                 |
| strong     |                                 |
| sub        |                                 |
| sup        |                                 |
| table      | width                           |
| tbody      |                                 |
| td         | colspan，height，rowspan，width |
| tfoot      |                                 |
| th         | colspan，height，rowspan，width |
| thead      |                                 |
| tr         | colspan，height，rowspan，width |
| tt         |                                 |
| u          |                                 |
| ul         |                                 |
| iframe     |                                 |
| pre        |                                 |