历史上的今天：needContent 参数与图文详情的正确打开方式
# 历史上的今天：needContent 参数与图文详情的正确打开方式
> 接口：历史上的今天（apiCode=119，接入点 119-42）· 免费 · 请求参数 `needContent`（可选）· 阅读时间：约 5 分钟
## 核心要点
- `needContent` 控制是否返回**详情**：`1` = 需要详情（`content` + `img`），`0` = 不需要（仅标题列表）。
- 不传时默认 `0`，只给 `title/year/month/day`，最省返回体积。
- 列表展示用 `0`，详情页/弹窗/分享卡再用 `1`——按场景开关，免费额度更耐用。
## Why：不是每次都要详情
如果你的页面只是滚动展示"今天发生了什么"的标题流，拉一大段 `content` 纯属浪费带宽和解析时间；用户点开某条要看正文时，再用 `needContent=1` 单独取。把开关用对，体验与成本双赢。
## What：needContent 参数速览
| 参数 | 类型 | 必填 | 取值 | 说明 |
|------|------|------|------|------|
| `needContent` | String | 否 | `1` / `0` | `1` 返回详细内容；`0` 不返回。默认 `0` |
> `content` 与 `img` 两个字段**仅在 `needContent=1` 时出现在 `list` 项里**；`needContent=0` 时这两项键不存在。
## How：两种模式的代码
### 模式一：列表流（needContent=0，默认）
```bash
curl -X POST "https://route.showapi.com/119-42?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "date=0220&needContent=0"
```
返回示例（无 content/img）：
```json
{ "showapi_res_body": { "list": [
{ "year": "2008", "month": 2, "day": 20, "title": "2008年2月20日 韩国一军用直升机坠毁造成7人死亡" }
], "ret_code": 0 } }
```
### 模式二：详情（needContent=1）
```python
import requests
url = "https://route.showapi.com/119-42"
params = {"appKey": "YOUR_APPKEY"}
data = {"date": "0220", "needContent": "1"}
resp = requests.post(url, params=params, data=data, timeout=10)
body = resp.json()["showapi_res_body"]
for it in body["list"]:
print(it["title"])
print(it.get("content", "")) # needContent=1 时一定有
print("图:", it.get("img") or "无")
```
**Node.js**
```javascript
const url = "https://route.showapi.com/119-42?appKey=YOUR_APPKEY";
const body = new URLSearchParams({ date: "0220", needContent: "1" });
const resp = await fetch(url, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body });
const resBody = (await resp.json()).showapi_res_body;
for (const it of resBody.list) {
console.log(it.title, "\n", it.content || "", "\n图:", it.img || "无");
}
```
## 返回示例与解析
`needContent=1` 时每条多出 `content`（长文）与 `img`（链接或 `""`）：
```json
{
"year": "2008", "month": 2, "day": 20,
"title": "2008年2月20日 韩国一军用直升机坠毁造成7人死亡",
"content": "2008年2月20日，韩国国防部确认，一架陆军直升机当天凌晨在京畿道杨平附近山区坠毁，机上7名军人全部死亡。",
"img": "http://static1.showapi.com/app2/history_img/3cde348c8e484b5e8b7d708d145be1f3.jpg"
}
```
## 进阶 / 边界
- **前端联动**：列表用 `needContent=0` 渲染卡片；用户点击卡片时，用同一 `date` + `needContent=1` 取该天全部详情（一次请求拿全天，不必逐条查）。
- **`img` 空值**：即便 `needContent=1`，部分事件仍无图，`img` 返回 `""`，展示时做无图占位。
- **默认行为**：忘记传 `needContent` 等同于 `0`，拿到的是标题列表——别误以为接口"没返回内容"。
## FAQ
**Q1：needContent 不传等于几？**
等于 `0`（不返回详情）。文档以"1 表示需要，0 表示不需要"描述，不传按不返回详情处理。
**Q2：列表模式能拿到图片吗？**
不能。`img` 仅在 `needContent=1` 时返回。列表展示建议用文字卡片，详情再拉图。
**Q3：详情模式会不会慢很多？**
属正常同步返回，差异主要在返回体大小。列表流用 `0` 更轻量。
**Q4：怎么同时做列表+详情最省？**
列表 `needContent=0`；点开时用 `date` + `needContent=1` 一次取全天详情缓存到前端，点哪条展示哪条。
## 相关能力 / 下一步阅读
- [历史上的今天返回字段全解：list / title / year / content / img 一文读懂](https://www.showapi.com/guides/history-today-response-fields-119) — `content`/`img` 字段类型与缺失条件。
- [历史上的今天：img 图片字段处理（空字符串、防盗链、懒加载）指南](https://www.showapi.com/guides/history-today-image-handle-119) — 详情图怎么落地。
- [历史上的今天：免费接口下如何做本地缓存与更新频率设计？](https://www.showapi.com/guides/history-today-cache-119) — 列表/详情的缓存配合。
- **本系列共 10 篇**：查看[历史上的今天指南总目录](https://www.showapi.com/guides/history-today-guides-119)
