成语详情字段详解：拼音 / 解释 / 出处 / 示例如何呈现给用户
# 成语详情字段详解：拼音 / 解释 / 出处 / 示例如何呈现给用户
> 接口：成语词典（apiCode=2964） · 接入点：成语详情(2964-2) / 随机成语(2964-3) · 是否免费：是 · 请求方式：POST/GET · 返回格式：JSON · 适用人群：前端、全栈、内容产品 · 阅读时间：约 5 分钟
## 核心要点
- 详情/随机返回五个释义字段：`word`(成语)、`pinyin`(读音)、`explain`(解释)、`derivation`(出处)、`sample`(示例)。
- `explain` 是字面+比喻义，`derivation` 多为古籍出处，`sample` 是用法例句。
- 前端可按「卡片 + 朗读 + 典故展开」呈现，本文给可直接套的模板。
## Why：拿到字段不等于用得好
接口把拼音、解释、出处、示例都给你了，但怎么排布决定了学习体验。教育类产品尤其需要把「读音、意思、从哪来、怎么用」分层展示，而不是一坨文字。本文拆解每个字段含义并给展示建议。
## What：字段含义
| 字段 | 含义 | 呈现建议 |
|------|------|---------|
| `word` | 成语本身 | 标题，大字 |
| `pinyin` | 读音（带声调） | 副标题，可配朗读按钮 |
| `explain` | 解释（字面义+比喻义） | 正文段落 |
| `derivation` | 出处（如《韩非子·五蠹》） | 「典故/出处」折叠块 |
| `sample` | 用法示例句 | 「例句」高亮块 |
## How：前端展示模板
```html
<div class="idiom-card">
<h2>{{word}}</h2>
<p class="pinyin">{{pinyin}} <button onclick="speak(word)">🔊 朗读</button></p>
<p class="explain">{{explain}}</p>
<details>
<summary>出处</summary>
<blockquote>{{derivation}}</blockquote>
</details>
<p class="sample">例句：{{sample}}</p>
</div>
```
```javascript
// 拉详情并填充（id 来自搜索结果）
async function renderDetail(id) {
const d = await fetch("https://route.showapi.com/2964-2", {
method:"POST",
headers:{"content-type":"application/x-www-form-urlencoded"},
body:new URLSearchParams({appKey:"YOUR_APPKEY", id})
}).then(r=>r.json());
const b = d.showapi_res_body;
document.querySelector(".idiom-card").innerHTML =
`<h2>${b.word}</h2><p>${b.pinyin}</p><p>${b.explain}</p><blockquote>${b.derivation}</blockquote><p>${b.sample}</p>`;
}
```
## 返回示例与解析
```json
{
"showapi_res_body": {
"ret_code": 0, "remark": "查询成功！",
"word": "守株待兔", "pinyin": "shǒu zhū dài tù",
"explain": "比喻死守经验，不知变通。",
"derivation": "《韩非子·五蠹》",
"sample": "凡事须主动，不可守株待兔。"
}
}
```
## 进阶 / 边界
- **朗读**：用浏览器 `SpeechSynthesis` 或后端 TTS，对 `pinyin`/`word` 发音；中文本地化需指定 `lang="zh-CN"`。
- **多字段缺失**：文档未保证每个成语五字段都齐全，前端对缺失字段做「不展示该区块」降级，避免空白占位。
- **字段稳定性**：释义类字段极少变动，可配合[缓存策略](https://www.showapi.com/guides/idiom-pagination-cache-2964)长期缓存。
## FAQ
**Q：explain 和 derivation 有什么区别？**
explain 是「什么意思」（现代释义），derivation 是「从哪来的」（古籍出处）。
**Q：sample 是必有的吗？**
文档未保证每个成语都有 sample，前端应缺失不展示。
**Q：pinyin 带声调吗？**
示例中带声调（如 shǒu zhū dài tù），可直接用于展示与朗读。
**Q：能不能只展示解释不要出处？**
可以，按产品需要取舍；建议至少保留 explain，derivation/sample 作为可折叠补充。
## 相关能力 / 下一步阅读
- [成语详情：用 id 还是 word 查询？参数用法与避坑](https://www.showapi.com/guides/idiom-detail-id-or-word-2964)
- [免费接口下如何设计分页缓存，减少重复调用？](https://www.showapi.com/guides/idiom-pagination-cache-2964)
- [儿童成语学习 App 接入指南：查词 + 每日一句 + 测验](https://www.showapi.com/guides/idiom-edu-app-guide-2964)
- **本系列共 15 篇**：查看[成语词典（apiCode=2964）官方指南总目录](https://www.showapi.com/guides/idiom-dictionary-guides-2964)
