docs(rich-text): 添加测试页面说明文档
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Showing
1 changed file
with
108 additions
and
0 deletions
src/pages/rich-text-test/README.md
0 → 100644
| 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 | +- ` ` → 空格 | ||
| 18 | +- `&` → `&` | ||
| 19 | +- `<` → `<` | ||
| 20 | +- `>` → `>` | ||
| 21 | +- `"` → `"` | ||
| 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 已渲染 |
-
Please register or login to post a comment