最直接有效的方案是用 ruby 标签包裹汉字与 rt 注音，浏览器原生支持、语义正确、读屏可识别；关键是以词为单位绑定上下文读音，而非单字标注，需依赖结构化词典数据实现语义消歧。
用 ruby 标签包裹汉字 + rt 注音是最直接有效的方案
浏览器原生支持，无需 JS，语义正确，读屏软件可识别，且符合 W3C 推荐用法。关键不是“加拼音”，而是把多音字的**上下文读音绑定到该字上**，让渲染和辅助技术都明确知道此处该读哪个音。
常见错误是用 span + title 或纯注释，这类写法对屏幕阅读器无效，也不能被搜索引擎或语音合成引擎可靠解析。
-
<ruby>重<rt>zhòng</rt></ruby>—— 表示此处读第四声（如“重要”） -
<ruby>重<rt>chóng</rt></ruby>—— 表示此处读第二声（如“重复”） - 若需标注声调，必须用数字（
zhòng），不能用符号（zhòng）——后者在多数字体/引擎中无法正常渲染或朗读 - 连续多个多音字，每个都要独立套
ruby，不要合并；否则语音引擎可能跳过或错连
遇到多音词（如“银行”“长处”）必须按词切分，不能只标单字
“行”在“银行”里读 xíng，但在“行业”里读 háng；“长”在“长度”读 cháng，在“长辈”读 zhǎng。单标一个字无法传达词义依赖关系，必须以**词为单位**加 ruby。
DeepBI DHTML 页面生成器
下载
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
- 错误：
<ruby>银<rt>yín</rt></ruby><ruby>行<rt>xíng</rt></ruby>—— 这会误导为“银-行”，而非“银行”一词 - 正确：
<ruby>银行<rt>yín háng</rt></ruby>—— 两个字共用一个rt，体现词级读音 - 注意空格：拼音之间必须用半角空格分隔，
yín háng✅，yínháng❌（后者会被识别为一个音节）
动态场景下避免硬编码，优先走数据驱动方式
如果页面内容来自 CMS、API 或用户输入，手动加 ruby 不现实。此时应把拼音映射逻辑前置到后端或构建时，例如：
立即学习“前端免费学习笔记（深入）”；
- 词典源必须含多音字词性与语境标注（如《汉语词典大全5万多数据.rar》中每个词条带拼音+词性字段）
- 前端接收结构化数据，如
{ text: "行长", pinyin: "háng zhǎng", type: "noun" }，再由模板自动渲染为<ruby>行长<rt>háng zhǎng</rt></ruby> - 切忌在 JS 里用规则库临时查拼音（如 pinyin-pro），多音字歧义率高，离线词典匹配更稳
- 若必须前端处理，至少缓存已解析结果，避免重复调用影响首屏性能
兼容性与可访问性容易被忽略的点
ruby 在现代浏览器中支持良好（Chrome 30+、Firefox 31+、Safari 5+、Edge 12+），但老版本 IE 完全不支持，且部分安卓 WebView（尤其旧版 UC、QQ 浏览器）会忽略 rt 内容或样式错位。
- 降级方案不是隐藏拼音，而是用
aria-label补充：<span aria-label="yín háng">银行</span>，确保读屏可用 - CSS 中务必重置
ruby默认样式：某些浏览器默认给rt加粗或改变字号，影响排版一致性 - 移动端双击放大时，
ruby可能被截断，建议限制rt字体大小不超过主文字的 60% - 别依赖颜色区分读音（如红字标轻声），色觉障碍用户无法识别；声调数字本身已是足够明确的提示
