Use when adding click-to-speak pronunciation buttons to words in documentation pages built with Zensical/MkDocs Material. Triggers on words like pronunciation, 发音, TTS, speech, voice, read aloud, 朗读.
在 Zensical 文档页面中添加点击即可发音的按钮，基于浏览器原生 Web Speech API，无需外部服务。
项目中已实现一套内联发音按钮系统：
docs/custom/js/pronunciation.js（事件委托 + speechSynthesis）docs/custom/css/pronunciation.css（按钮样式 + 深色模式适配）zensical.toml 中注册，所有页面自动可用在 Markdown 中插入发音按钮：
<button class="md-pronounce-btn" data-word="hello" title="点击发音"><i class="fa fa-volume-up"></i></button>
| 属性 | 必填 | 说明 | 示例 |
|---|---|---|---|
data-word |
| 是* |
| 要朗读的文本 |
"hello"、"good morning" |
data-ipa | 是* | IPA 音标，自动朗读代表单词 | "æ" → 读 cat |
data-lang | 否 | 语言代码，默认 en-US | "en-GB"、"zh-CN" |
data-rate | 否 | 语速，默认 0.8（0.1-2.0） | "0.6"（慢）、"1.0"（正常） |
*
data-word和data-ipa二选一，data-ipa优先级更高。
| IPA | 代表单词 | IPA | 代表单词 |
|---|---|---|---|
æ | cat | ɛ | bed |
ɪ | sit | ɒ | hot |
ʌ | cup | eɪ | day |
iː | see | aɪ | kite |
oʊ | go | juː | cute |
ɑː | father | ɔː | door |
ʊ | book | aʊ | cow |
ɔɪ | boy | ʃ | ship |
tʃ | chip | θ | think |
ð | this | ʒ | vision |
ŋ | sing | j | yes |
w | we | ɜːr | bird |
ɑːr | car | ɔːr | horse |
<!-- 单词发音 -->
`cat` <button class="md-pronounce-btn" data-word="cat" title="点击发音"><i class="fa fa-volume-up"></i></button>
<!-- 音标发音（自动朗读代表单词） -->
/æ/ <button class="md-pronounce-btn" data-ipa="æ" title="听 /æ/ 发音"><i class="fa fa-volume-up"></i></button>
<!-- 短语发音 -->
`good morning` <button class="md-pronounce-btn" data-word="good morning" title="点击发音"><i class="fa fa-volume-up"></i></button>
<!-- 慢速发音（适合初学者） -->
`through` <button class="md-pronounce-btn" data-word="through" data-rate="0.6" title="点击发音"><i class="fa fa-volume-up"></i></button>
<!-- 英式发音 -->
`water` <button class="md-pronounce-btn" data-word="water" data-lang="en-GB" title="点击发音"><i class="fa fa-volume-up"></i></button>
| 场景 | 语法 |
|---|---|
| 美式英语（默认） | data-word="word" |
| 音标发音 | data-ipa="æ"（自动朗读代表单词） |
| 英式英语 | data-word="word" data-lang="en-GB" |
| 慢速朗读 | data-word="word" data-rate="0.6" |
| 短语/句子 | data-word="good morning" |
| 中文发音 | data-word="你好" data-lang="zh-CN" |
document$.subscribe() 兼容 Zensical 的 Instant Navigationdocument.addEventListener('click', ...)），无需手动重新绑定cancel() 上一次朗读，避免叠加.md-pronounce--playing 类），结束后恢复fa-volume-up）[data-md-color-scheme="slate"] 适配| 错误 | 正确做法 |
|---|---|
data-word 为空 | 必须指定要朗读的文本 |
忘记 class="md-pronounce-btn" | 类名是 JS 识别的唯一标识 |
| 放在代码块内 | HTML 在代码块中不会被渲染，放在代码块外 |
用 <a> 标签 | 必须用 <button>，避免链接语义干扰 |