多音字简繁混排不能靠自动映射解决，因同一简体字（如「乾」）在不同语境读音和对应繁体不同（qián/乾、gān/乾或幹），静态映射无法识别语义；ruby须逐字标注且lang严格匹配字形体系（zh-Hans/zh-Hant），禁用斜杠分隔、禁注可编辑内容。
多音字在简繁混排中为什么不能靠自动映射解决
因为「乾」在「乾坤」里读 qián，转繁体是「乾」；但在「乾燥」里读 gān，对应繁体是「乾」或「幹」——同一个简体字，不同语境要转不同繁体，而拼音标注又必须匹配实际读音。traditionalMap 和 simplifiedMap 是静态双向映射，不带语义上下文，强行用它做拼音绑定，必然出现「乾」却转成「幹燥」这种错配。
ruby 标签必须按字粒度拆分，不能跨字共享 rt
多音字本质是单字多读，ruby 的设计逻辑就是一对一：一个 rb（或隐式基字）对应一个 rt。常见错误是把词包一层然后塞多个拼音，比如：<ruby>否极泰来<rt>pǐ jí tài lái</rt></ruby>——这违反规范，屏幕阅读器会把整段当一个语音单元处理，声调错乱、停顿丢失。
正确做法是逐字包裹，且拼音只写当前语境下的读音：
<ruby>否<rt>pǐ</rt></ruby><ruby>极<rt>jí</rt></ruby><ruby>泰<rt>tài</rt></ruby><ruby>来<rt>lái</rt></ruby>- 如果页面需支持切换读音（如教学场景），得用 JS 动态替换
rt内容，而不是预埋多音选项 - 避免在
rt里用斜杠分隔（如fǒu/pǐ），语音合成器无法解析
lang 属性必须与 ruby 拼音严格对齐
简繁混排常伴随语言变体切换，比如一段简体正文里嵌入台湾出版的引文。此时若只设 lang="zh-Hans"，而引文内有「著」字（简体为「着」），其拼音应标 zhù 而非 zhe——但屏幕阅读器若未识别该段 lang="zh-Hant"，仍可能按简体规则读成 zhe。
立即学习“前端免费学习笔记（深入）”；
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
所以必须：
- 每个
ruby所在元素，其父容器lang值要匹配该字实际所属字形体系（zh-Hans或zh-Hant） - 禁止在
html根标签统一写lang="zh"，它不是合法 IETF 标签，AT 会降级处理 -
ruby内的拼音字符（如ü、ē）需确保字体支持 Unicode 声调符，否则 fallback 为u、e，读音失真
input/textarea 里的用户输入不能被 ruby 或 lang 干扰
动态简繁转换脚本若无差别遍历 DOM，很容易误操作表单控件。典型现象是：用户正在 input 里打「着火了」，脚本把 value 改成「著火了」并试图加 ruby，结果拼音标成 zhù，而用户本意是读 zháo。
安全边界必须明确：
- 跳过所有
input、textarea、contenteditable元素的子节点处理 -
ruby只用于静态展示文本，绝不插入到可编辑区域内部 - 若需为用户输入实时注音（如拼音输入法辅助），必须走独立逻辑，基于输入事件监听 + 分词 API，而非 DOM 替换
最易被忽略的是 placeholder 和 title 属性里的文字——它们虽不显眼，但会被读屏软件捕获，且同样受 lang 和 ruby 影响。没声明 lang 的 placeholder，哪怕内容是简体字，也可能被读成粤语发音。
