124 lines
5.2 KiB
Markdown
124 lines
5.2 KiB
Markdown
# 【Demo】富文本渲染（RichTextContent：HTML → 题目/解析）
|
||
|
||
> 源文件：`lib/pages/demo/rich_text_demo.dart` ｜ 分类：组件封装
|
||
> 一句话：后端给的 HTML（题目/解析/听力材料）渲染成富文本 —— 还支持字号调节、深色模式、自定义样式。
|
||
|
||
---
|
||
|
||
## 一、这个 Demo 解决什么问题
|
||
|
||
教育 App 的题目/解析是**后端返回的 HTML 字符串**（`<h3>`、`<img>`、`<table>`、`<audio>`…），
|
||
前端要把它渲染成漂亮的可交互富文本。本页演示 `RichTextContent`（`lib/core/components/rich_text_content.dart`）：
|
||
|
||
- 完整渲染：标题、粗体、**上标下标**、`<ul>` 选项、`<table>` 表格；
|
||
- `<audio>` 标签**自动替换成本项目的 AudioPlayerCard**；
|
||
- 学生端能力：**字号 Aa± 实时调节、深色模式切换**（通过 `textStyle` 注入）；
|
||
- 自定义样式：`.answer` 类 → 红色加粗（`customStylesBuilder`）。
|
||
|
||
> 对照 Vue：相当于 `v-html` + 样式定制，但 Flutter 没有浏览器引擎，得用 flutter_html 这类包逐标签渲染。
|
||
|
||
---
|
||
|
||
## 二、怎么运行 / 演示内容
|
||
|
||
```dart
|
||
runApp(const MaterialApp(home: RichTextDemoPage()));
|
||
```
|
||
|
||
- 顶部控制栏：滑块拖字号（12~24）、切深色开关 → 正文实时变化；
|
||
- 页面里：化学方程式上下标、本地图片（`asset://` 协议）、表格、听力音频、视频、红色加粗的答案 B。
|
||
|
||
---
|
||
|
||
## 三、核心知识点（新手向）
|
||
|
||
### 1. 一行渲染 HTML
|
||
```dart
|
||
RichTextContent(
|
||
html: _html, // 后端返回的 HTML 字符串
|
||
// 字号 + 深色模式都通过 textStyle 注入（学生端统一入口）
|
||
textStyle: TextStyle(
|
||
fontSize: _fontSize,
|
||
height: 1.6,
|
||
color: _dark ? Colors.white70 : const Color(0xFF333333),
|
||
),
|
||
)
|
||
```
|
||
**`textStyle` 注入是核心设计**：页面不重建 HTML、不改渲染器，只改一个 TextStyle 就全局换字号/颜色——学生端"无障碍调节"的标准做法。
|
||
|
||
### 2. 自定义样式：customStylesBuilder
|
||
```dart
|
||
customStylesBuilder: (element) {
|
||
if (element.className.contains('answer')) {
|
||
return const {'color': '#EF4444', 'font-weight': 'bold'};
|
||
}
|
||
return null; // 其他元素不特殊处理
|
||
},
|
||
```
|
||
后端 HTML 里写 `<span class="answer">B</span>` → 渲染成红色加粗。**按 class 定制样式**，不用后端改结构。
|
||
|
||
### 3. 本地图片：asset:// 协议
|
||
```html
|
||
<img src="asset://assets/img/luola_logo.png" width="160" height="160"/>
|
||
```
|
||
`asset://` + 资源路径 = 加载本地资源图片（最稳，不受网络影响）。实际后端返回完整 URL 或相对路径（相对路径需业务层拼 baseUrl）。
|
||
|
||
### 4. audio 标签自动替换
|
||
```html
|
||
<audio src="asset://assets/audio/sample-30s.mp3" title="听力材料（30 秒）" controls></audio>
|
||
```
|
||
组件内部检测 `<audio>` → 替换成 `AudioPlayerCard`（见 [audio_player_demo.md](audio_player_demo.md)）——听力题直接能播。
|
||
|
||
---
|
||
|
||
## 四、关键代码剖析
|
||
|
||
```dart
|
||
static const String _html = '''
|
||
<h3>第 1 题 · 阅读理解</h3>
|
||
<p>光合作用是植物利用光能将<strong>二氧化碳</strong>和<strong>水</strong>合成有机物并释放氧气的过程。化学方程式：6CO<sub>2</sub> + 6H<sub>2</sub>O → C<sub>6</sub>H<sub>12</sub>O<sub>6</sub> + 6O<sub>2</sub>，面积用 x<sup>2</sup> 表示。</p>
|
||
<img src="asset://assets/img/luola_logo.png" width="160" height="160"/>
|
||
<ul>
|
||
<li>A. 光合作用只发生在夜间</li>
|
||
<li>B. 光合作用会释放氧气</li>
|
||
</ul>
|
||
<table border="1" cellpadding="6">
|
||
<tr><th>条件</th><th>有光</th><th>黑暗</th></tr>
|
||
<tr><td>释放 O₂</td><td>√</td><td>×</td></tr>
|
||
</table>
|
||
<audio src="asset://assets/audio/sample-30s.mp3" title="听力材料（30 秒）" controls></audio>
|
||
<p><b>【解析】</b>正确答案：<span class="answer">B</span>。</p>
|
||
''';
|
||
```
|
||
|
||
字号控制条（12~24 共 12 档）：
|
||
```dart
|
||
Slider(
|
||
value: _fontSize,
|
||
min: 12,
|
||
max: 24,
|
||
divisions: 12, // 档位数 → 滑块只能停在整数
|
||
activeColor: const Color(0xFF3B82F6),
|
||
onChanged: (v) => setState(() => _fontSize = v),
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 五、踩坑记录
|
||
|
||
1. **textStyle 只影响文本**：图片、表格、AudioPlayerCard 是各自样式——深色模式下卡片白底不随主题变（业务侧需按需适配）；
|
||
2. **内联 CSS 只支持常用属性**，复杂布局会降级（flutter_html 的边界，别拿它当浏览器）；
|
||
3. 公式（LaTeX）本 demo 未含：以后在 `RichTextContent` 的 `customWidgetBuilder` 里扩展（如 flutter_math_fork）；
|
||
4. 相对路径图片要业务层拼 baseUrl，别把裸相对路径直接塞进 html；
|
||
5. 深色模式只是 `_dark` 布尔 + 换色，**页面底色/AppBar 也要跟着换**（本页手动处理了，主题化见 [theme_demo.md](theme_demo.md)）。
|
||
|
||
---
|
||
|
||
## 六、扩展思考
|
||
|
||
- `<audio>` 替换成的播放器组件见 [audio_player_demo.md](audio_player_demo.md)；
|
||
- 富文本在真实考试页的运用见 [exam_demo.md](exam_demo.md)（题干 HTML 渲染）；
|
||
- 学生端"字号调节 + 深色模式"这类**偏好设置**，进阶做法是存进全局状态（Riverpod），见 [exam_architecture.md](../exam_architecture.md) 的 Riverpod 章节；
|
||
- 真实项目：`_html` 换成接口返回的题目 HTML，`asset://` 换成 CDN 完整 URL 即可。
|