hookehuyr

docs(rich-text): 添加测试页面说明文档

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 +# 富文本渲染测试页面
2 +
3 +## 📋 概述
4 +
5 +本目录包含两个富文本渲染测试页面,用于验证和对比 Taro 中不同富文本渲染方案的效果。
6 +
7 +## 📁 文件说明
8 +
9 +| 文件 | 渲染方案 | 说明 |
10 +|------|----------|------|
11 +| `index.vue` | `v-html` 指令 | Taro 内置方案,基于 `rich-text` 组件 |
12 +| `index1.vue` | `mp-html` 组件 | 第三方富文本组件 |
13 +
14 +## 🎯 测试功能
15 +
16 +### HTML 实体解析
17 +- `&nbsp;` → 空格
18 +- `&amp;``&`
19 +- `&lt;``<`
20 +- `&gt;``>`
21 +- `&quot;``"`
22 +
23 +### 标签渲染
24 +- ✅ 基础标签:`<h1>` ~ `<h3>`, `<p>`, `<ul>`, `<li>`, `<strong>`, `<em>`
25 +-`<a>` 标签:v-html 不支持,需要替换为 `<div data-href="">`
26 +-`<img>` 标签:支持,但 URL 可能被损坏
27 +
28 +### 图片功能
29 +- 长按预览(使用 `@tarojs/extend``$` 选择器绑定)
30 +
31 +### 文件链接功能
32 +- PDF 文件链接渲染为卡片样式
33 +- 点击打开 PDF(使用 `useFileOperation.viewFile`
34 +
35 +## 🔍 对比结果
36 +
37 +| 特性 | v-html (index.vue) | mp-html (index1.vue) |
38 +|------|-------------------|----------------------|
39 +| `<a>` 标签 | ❌ 不支持,需手动替换 | ✅ 原生支持 |
40 +| `imgtap` 事件 | ❌ 需手动绑定 | ✅ 内置支持 |
41 +| `linktap` 事件 | ❌ 需手动绑定 | ✅ 内置支持 |
42 +| HTML 实体 | ✅ 需手动解析 | ✅ 自动解析 |
43 +| URL 完整性 | ⚠️ 可能损坏 | ✅ 完整保留 |
44 +| 组件大小 | 小(内置) | 大(第三方) |
45 +
46 +## 🚀 使用方式
47 +
48 +### 访问页面
49 +
50 +```bash
51 +# 启动开发服务器
52 +pnpm dev:weapp
53 +
54 +# 在微信开发者工具中访问
55 +# 页面路径:pages/rich-text-test/index
56 +# 或:pages/rich-text-test/index1
57 +```
58 +
59 +### 测试按钮说明
60 +
61 +**index.vue (v-html)**
62 +- 测试1: 纯文本 - 基础 HTML 渲染
63 +- 测试2: HTML标签 - 标题、列表、样式
64 +- 测试3: 图片 - 图片渲染 + 长按预览
65 +- 测试4: 链接 - 普通链接 + PDF 链接
66 +- 清空内容 - 清空测试区域
67 +- 模拟API加载 - 模拟异步数据加载
68 +- 📄 真实API - 加载原始 `<a>` 标签数据
69 +- 📄 真实API(a→div) - 加载 `<a>` 替换为 `<div>` 的数据
70 +
71 +**index1.vue (mp-html)**
72 +- 测试1: 图片 - 图片点击预览
73 +- 测试2: 链接 - 链接点击处理
74 +- 测试3: PDF - PDF 链接点击
75 +
76 +## 💡 结论
77 +
78 +**推荐使用 mp-html 组件** (`index1.vue`) 用于生产环境,原因:
79 +1. 完整支持 `<a>` 标签
80 +2. URL 不会被损坏
81 +3. 内置事件处理(`imgtap`, `linktap`
82 +4. 更好的样式兼容性
83 +
84 +**v-html 方案** (`index.vue`) 仅适用于简单场景,复杂富文本建议使用 mp-html。
85 +
86 +## 🔗 相关依赖
87 +
88 +```json
89 +{
90 + "mp-html": "^2.5.0",
91 + "@tarojs/extend": "latest"
92 +}
93 +```
94 +
95 +## 📝 注意事项
96 +
97 +1. **Taro v-html 限制**
98 + - 不支持 `<a>` 标签,需手动替换为 `<div data-href="">`
99 + - URL 可能被损坏(某些字符被替换)
100 + - `data-*` 属性可能被过滤
101 +
102 +2. **文件链接处理**
103 + - 使用 `useFileOperation.viewFile()` 统一处理文件打开
104 + - PDF 文件会先下载到本地再预览
105 +
106 +3. **图片事件绑定**
107 + - 使用 `@tarojs/extend``$` 选择器
108 + -`nextTick` 中绑定确保 DOM 已渲染