唐诗宋词元曲查询：搭一个带原文/译文/注释的古诗文学习卡片
# 唐诗宋词元曲查询：搭一个带原文/译文/注释的古诗文学习卡片
> 接口：唐诗宋词元曲等诗词查询（apiCode=1620）· 免费 · 请求方式 POST/GET · 返回 JSON · 适用：教育内容运营、前端开发者、国学 App 团队 · 阅读约 7 分钟
## 核心要点
- 学习卡片的核心数据来自 1620-5 的 `contentlist`：每项含 `original`（原文）、`translation`（译文）、`annotation`（注释）
- 配合 1620-4 的 `biography`（生平简介）可一并展示诗人小传
- 一首诗可能有多段 `contentlist`，渲染时务必两层遍历
## Why：把「死」的诗词变成「可学」的卡片
国学/语文场景里，光给原文不够，学生还要看译文、抠注释。ShowAPI 的诗词返回已经把这三件套准备好了。本篇教你用最少代码，搭一个「原文 + 译文 + 注释 + 诗人小传」的学习卡片组件，可直接塞进小程序、H5 或课堂大屏。
## What：所需接口与字段
| 项目 | 说明 |
|------|------|
| 接口编码 | 1620 |
| 主要接入点 | 1620-5 名称查询诗词列表（取 `contentlist`）、1620-4 人名或朝代查询诗人（取 `biography`） |
| 关键字段 | `contentlist[].original / translation / annotation`、`poetInfo[].biography`、`poemInfo[].note` |
| 计费 | 免费（有使用档次限制） |
## How：三步渲染学习卡片
### 步骤 1 · 取诗词数据
以 `poetId` 或精确 `title` 调 1620-5，拿到 `poemInfo[0]` 及其 `contentlist`。
### 步骤 2 · 取诗人小传（可选）
以 `poetId` 或 `poet` 调 1620-4，取 `biography`。
### 步骤 3 · 渲染卡片
**Node.js（fetch，取数据与聚合）**
```javascript
const APP_KEY = "YOUR_APPKEY";
const H = { "content-type": "application/x-www-form-urlencoded" };
async function getPoem(title) {
const resp = await fetch(`https://route.showapi.com/1620-5?appKey=${APP_KEY}`, {
method: "POST", headers: H,
body: new URLSearchParams({ title, page: 1 }),
});
const body = (await resp.json()).showapi_res_body;
if (body.ret_code !== "0") throw new Error(body.remark);
return body.poemInfo[0];
}
const poem = await getPoem("前赤壁赋");
const card = {
title: poem.title,
poet: poem.poet,
dynasty: poem.dynasty,
tags: poem.note, // 如「辞赋精选，高中文言文…」
segments: poem.contentlist.map(s => ({
original: s.original,
translation: s.translation,
annotation: s.annotation,
})),
};
console.log(JSON.stringify(card, null, 2));
```
**前端组件思路（伪 JSX）**
```jsx
function PoemCard({ poem }) {
return (
<div className="card">
<h2>{poem.title} <small>{poem.dynasty}·{poem.poet}</small></h2>
<p className="tags">{poem.note}</p>
{poem.contentlist.map((s, i) => (
<section key={i}>
<p className="original">{s.original}</p>
<p className="translation">{s.translation}</p>
<details><summary>注释</summary><p>{s.annotation}</p></details>
</section>
))}
</div>
);
}
```
**cURL（取单首）**
```bash
curl -X POST "https://route.showapi.com/1620-5?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "title=%E5%89%8D%E8%B5%A4%E5%A3%81%E8%B5%8B&page=1"
```
## 返回示例与解析
```json
{
"showapi_res_body": {
"ret_code": "0",
"poemInfo": [
{
"title": "前赤壁赋",
"dynasty": "宋代",
"poet": "苏轼",
"note": "辞赋精选，高中文言文，古文观止，写景，饮酒，感叹，哲理",
"contentlist": [
{
"original": "壬(rén)戌(xū)之秋，七月既望……",
"translation": "壬戌年秋，七月十六日……",
"annotation": "壬戌：宋神宗元丰五年……"
}
]
}
]
}
}
```
| 字段 | 用途 |
|------|------|
| `note` | 可作为卡片标签/难度提示（含「高中文言文」等） |
| `contentlist[].original` | 原文，注意含生僻字注音如「壬(rén)戌(xū)」 |
| `contentlist[].translation` | 白话译文 |
| `contentlist[].annotation` | 词语注释，适合折叠展示 |
## 进阶 / 边界
- **注音展示**：原文中已带「字(拼音)」形式的注音（如「壬(rén)戌(xū)」），前端可直接展示，或按正则拆出拼音做悬浮提示。
- **长文分段**：`contentlist` 是数组，辞赋类可能分成多段，每段独立原文/译文/注释，建议逐段渲染并可独立收起。
- **标签利用**：`note` 字段含「高中文言文」「古文观止」等标签，可按学段筛选卡片，无需自己维护分类。
- **空字段兜底**：`translation` / `annotation` 偶尔可能为空，展示前判空，避免页面出现「undefined」。
## FAQ
**Q1：一首诗为什么会有多个 contentlist 元素？**
原文较长的辞赋/长诗会被分段，每段是一个 `contentlist` 元素，各自带原文/译文/注释。渲染时务必遍历，不要只取第一个。
**Q2：能不能按「高中文言文」这种标签反查诗词？**
不能。`note` 是返回字段，不是查询参数；接入点不支持按标签检索。需要的话，可先拉取批量诗词、再用 `note` 在本地筛选。
**Q3：biography 太长，卡片里放不下怎么办？**
`biography` 是完整生平，卡片可只显示前 N 字 + 「展开全文」，或单独做诗人详情页承载全文。
**Q4：译文和注释能直接给学生用吗？**
可作为辅助学习材料。注意这是数据源提供的参考译文/注释，正式教学场景建议由专业老师核对后再发布。
## 相关能力 / 下一步阅读
- [唐诗宋词元曲查询：原文/译文/注释三件套结构解读与前端排版建议](https://www.showapi.com/guides/poem-contentlist-1620) — contentlist 结构与排版细节
- [唐诗宋词元曲查询：国学/教育类 App 集成方案，一键查诗人自动生成赏析](https://www.showapi.com/guides/poem-edu-solution-1620) — 教育场景整体方案
- **本系列共 12 篇**：查看[唐诗宋词元曲查询指南总目录](https://www.showapi.com/guides/poem-guides-1620)
