多音字拼音标注必须用 pinyin-pro 的 html() 函数自动判断上下文，不可手写 ruby 标签；需对每个 li 内容单独调用、仅包裹纯汉字、重置 line-height、顶层声明 lang="zh-CN"、英文术语显式标 lang="en"、预处理缓存结果、验证教学语境读音。
多音字拼音标注必须用 pinyin-pro 的 html 函数生成
直接手写 <ruby><rt></rt></ruby> 无法处理多音字上下文判断。浏览器不解析语义，<rt>zhāo</rt> 和 <rt>cháo</rt> 完全靠你猜——而“朝”在“朝阳”和“朝拜”里读音不同，人工标注错误率极高。
pinyin-pro 的 html() 函数会调用内置词典+上下文模型，自动选择最可能读音。它不是简单查表，而是基于前后字组合做概率推断（比如“朝+阳”→ 92% 匹配 “zhāo”，“朝+拜”→ 98% 匹配 “cháo”）。
- 必须传入完整词语或短句，单字调用会退化为默认读音（如
html("朝")总返回zhāo） - 不能把整段列表文本一次性喂给
html()，否则会把标点、空格、HTML 标签也当语义参与分析，导致拼音错位 - 推荐对每个
<li>内容单独调用，例如：html("朝阳公园")→<ruby>朝<rt>zhāo</rt></ruby><ruby>阳<rt>yáng</rt></ruby><ruby>公<rt>gōng</rt></ruby><ruby>园<rt>yuán</rt></ruby>
<li> 中混排文字、图标、按钮时怎么保拼音结构不崩
常见错误是把 <ruby></ruby> 套在带内联元素的 <li> 外层，比如：<li>
<ruby>朝<rt>zhāo</rt></ruby><i class="icon"></i>
</li>。这会导致 <rt></rt> 在视觉上被图标撑开、换行错位，甚至部分浏览器渲染成两行。
正确做法是只对纯汉字内容包裹 <ruby></ruby>，其他元素保持平级：
立即学习“前端免费学习笔记（深入）”；
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
<li> <ruby>朝<rt>zhāo</rt></ruby><ruby>阳<rt>yáng</rt></ruby>公园 <button type="button">听发音</button> <i class="icon"></i> </li>
- CSS 必须重置
ruby默认行高：ruby { line-height: 1.2; }，否则拼音和汉字间距过大 - 禁止给
<ruby></ruby>设display: inline-block或float，会破坏浏览器原生注音定位逻辑 - 如果列表项用了
flex布局，<ruby></ruby>要加white-space: nowrap防止单字被强行折行
为什么 lang="zh-CN" 必须写在 <li> 或 <ul></ul>
屏幕阅读器（如 NVDA、VoiceOver）只认 这一处声明。你在 <li lang="zh-CN"> 里重复写，它根本不理——但更严重的是，<title></title>、<meta name="description"> 这些关键标签的语言归属，全靠顶层 lang 决定。漏掉它，多音字就算标对了拼音，TTS 引擎也可能按英文规则硬读“行”为 /hæŋ/。
-
是强制要求，不是可选项 -
<li>里嵌英文术语（如 API、URL）要显式加lang="en"，否则中文 TTS 会把 “API” 拆成 “A-P-I” 逐字母念 - 不要信“浏览器能自动识别”的说法：Chrome 地址栏不出现翻译按钮，大概率就是
lang缺失或写错位置
动态渲染列表时，pinyin-pro 的 html() 要防重复执行
如果用 JavaScript 循环生成 <li>，每次调用 html() 都会重新解析整段文本。对长列表（比如 50 个带多音字的词），CPU 占用明显升高，滚动卡顿。
解决方案是预处理：把所有待标注文本先批量过一遍 pinyin-pro，缓存结果再插入 DOM：
const words = ["朝三暮四", "朝令夕改", "朝拜"];
const htmlList = words.map(word => html(word)); // 一次解析，避免循环内重复调用
listEl.innerHTML = htmlList.map(h => <li>${h}</li>).join('');
- 别在
for循环里反复 import{ html }，模块加载开销比拼音计算还大 - 服务端渲染（SSR）场景下，优先在 Node.js 端调用
html()，避免客户端重复计算 - 如果列表支持搜索过滤，记得对原始文本（非 HTML 字符串）做匹配，否则搜“zhao”永远找不到已转成
<ruby></ruby>的结果
fā 没问题，但在“头发”里标成 fā 就是错的。pinyin-pro 默认策略偏向书面语，口语高频词（如“啥”“咋”）需要手动覆盖词典，这点容易被忽略。 
