# rich-text

> 基础库 1.4.0 开始支持，低版本需做[兼容处理](1003706)。

> __微信 Windows 版__：支持
> 
> __微信 Mac 版__：支持
> 
> __微信 鸿蒙 OS 版__：支持

渲染框架支持情况：Skyline （使用最新 [Nightly](/miniprogram/dev/devtools/nightly.html) 工具调试）、WebView

## 功能描述

富文本。

1. 自基础库 2.33.0 版本开始支持（3.0.0 除外）。
2. 遵循 skyline 的样式和布局规则，html tag 被映射成类似 text/span/view 节点，因此存在 text 嵌套问题。
3. 不支持 td/tr 等表格布局 tag，也不支持 bdo/bdi 等文字排版 tag。建议完全使用 flex 等 skyline 支持的布局方式来创建富文本内容。
4. 提供了可选的兼容布局模式选项 `mode`，但仍不保证与 WebView 表现 100% 一致。
5. 在 2.33.0 基础库下，请尽可能避免为 html tag 使用 wx-rich-text 开头的类名。

## 通用属性


```json
[
  {
    "属性": "nodes",
    "类型": "array/string",
    "默认值": "[]",
    "必填": "否",
    "说明": "节点列表/HTML String",
    "最低版本": "[1.4.0](1003706)"
  },
  {
    "属性": "space",
    "类型": "string",
    "默认值": "",
    "必填": "否",
    "说明": "显示连续空格",
    "最低版本": "[2.4.1](1003706)",
    "子项": [
      {
        "合法值": "ensp",
        "说明": "中文字符空格一半大小"
      },
      {
        "合法值": "emsp",
        "说明": "中文字符空格大小"
      },
      {
        "合法值": "nbsp",
        "说明": "根据字体设置的空格大小"
      }
    ]
  },
  {
    "属性": "user-select",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "文本是否可选，该属性会使节点显示为 block",
    "最低版本": "[2.24.0](1003706)"
  }
]
```

## Skyline 特有属性


```json
[
  {
    "属性": "mode",
    "类型": "string",
    "默认值": "default",
    "必填": "否",
    "说明": "布局兼容模式",
    "子项": [
      {
        "合法值": "default",
        "说明": "完全遵循 skyline 的默认行为，不对节点树进行任何更改。"
      },
      {
        "合法值": "compat",
        "说明": "尽可能将 tag 映射为 \u0000INLINECODE_1\u0000 的形式。通常最接近 webview 的表现。"
      },
      {
        "合法值": "aggressive",
        "说明": "所有 tag 均被映射为形如 \u0000INLINECODE_2\u0000 的形式。"
      },
      {
        "合法值": "inline-block",
        "说明": "实验性的 inline-block 布局策略，但无法实现折行。"
      },
      {
        "合法值": "web",
        "说明": "使用 webview 渲染富文本，基础库 3.6.0 开始支持。"
      },
      {
        "合法值": "web-static",
        "说明": "使用 webview 截图的方式渲染富文本，基础库 3.7.7 开始支持。"
      }
    ]
  }
]
```

## nodes

现支持两种节点，通过type来区分，分别是元素节点和文本节点，默认是元素节点，在富文本区域里显示的HTML节点

### 元素节点：type = node

| 属性     | 说明       | 类型   | 必填 | 备注                                     |
| -------- | ---------- | ------ | ---- | ---------------------------------------- |
| name     | 标签名     | string | 是   | 支持部分受信任的 HTML 节点               |
| attrs    | 属性       | object | 否   | 支持部分受信任的属性，遵循 Pascal 命名法 |
| children | 子节点列表 | array  | 否   | 结构和 nodes 一致                        |

### 文本节点：type = text

| 属性 | 说明 | 类型   | 必填 | 备注         |
| ---- | ---- | ------ | ---- | ------------ |
| text | 文本 | string | 是   | 支持entities |

## 受信任的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         |                                 |

## Bug & Tip

1. `tip`: nodes 不推荐使用 String 类型，性能会有所下降。
1. `tip`: `rich-text` 组件内屏蔽所有节点的事件。
1. `tip`: attrs 属性不支持 id ，支持 class 。
1. `tip`: name 属性大小写不敏感。
1. `tip`: 如果使用了不受信任的HTML节点，该节点及其所有子节点将会被移除。
1. `tip`: img 标签仅支持网络图片。
1. `tip`: 如果在自定义组件中使用 `rich-text` 组件，那么仅自定义组件的 wxss 样式对 `rich-text` 中的 class 生效。

## 示例代码

[在开发者工具中预览效果](https://developers.weixin.qq.com/s/zPVmpim46wYQ)