数据、API 与阅读交互组件
本轮参考 Mintlify 组件目录、Fumadocs 类型表、Starlight 和 VitePress 后，补充当前组件库的缺口。已有卡片、提醒、步骤和标签页继续复用。本页所有实现都是本站的 Vue 组件，可以写入 docs 或 blog。
集中体验见 进阶组件演示，组合示例见 用交互组件写一份技术说明。
DataTable：搜索、排序与分页
适合设备清单、统计明细和工具列表。短小的静态对照继续使用普通 Markdown 表格。
| 属性 | 类型 | 说明 |
|---|---|---|
| title | string | 默认“数据表”，用于 caption 与可访问名称 |
| columns | array | 必填，每项 key、label，可设 sortable:false |
| rows | array | 必填，键与 columns.key 对应；值为 string/number/boolean/null |
| searchable | boolean | 默认 true，搜索可见列的显示文本 |
| pageSize | number | 默认 10，正整数，上限 100；无效值恢复默认 |
::data-table
---
title: 示例设备
pageSize: 2
columns:
- key: name
label: 名称
- key: ports
label: 端口数
rows:
- name: 核心交换机
ports: 48
- name: 接入交换机
ports: 24
- name: 测试交换机
ports: 8
---
::
点击列名切换升序/降序；数值按数值比较，字符串使用自然排序，空值放在末尾，相等项保留原顺序。搜索或排序后回到第一页，分页不截断后续数据。布尔值显示“是/否”，空值显示“—”。手机上只有表格区域横向滚动，该区域也可键盘聚焦。组件不进行服务端查询。
ParameterTable：结构化参数说明
适合 API 请求/响应、配置文件和组件 props。相比逐个 ::field，一份 YAML 可以同时表达类型、默认值、必填、弃用与枚举。
title 默认“参数说明”；parameters 为必填数组，支持以下字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| name / type | string | 必填参数名与类型文字 |
| description / location | string | 描述与 query/path/body 等位置 |
| required / deprecated | boolean | 默认 false |
| default | string/number/boolean/null | 可选，0、false、null 均正确显示 |
| enum | string/number 数组 | 可选值列表 |
::parameter-table
---
title: 查询参数
parameters:
- name: deviceId
type: string
location: query
required: true
description: 要查询的设备标识
- name: limit
type: number
default: 10
enum: [10, 20, 50]
description: 每页记录数
---
::
类型与默认值由作者填写，不自动解析 OpenAPI/TypeScript。空数组显示“无需参数”。
ApiEndpoint：接口说明与示例插槽
展示 HTTP 方法、路径、认证文字和状态，用命名插槽并排呈现请求与响应。组件仅用于说明，不发请求或代理任意 URL。
| 属性 | 类型 | 说明 |
|---|---|---|
| path | string | 必填，作为文字显示的接口路径 |
| method | string | 默认 GET，显示为大写 |
| title / auth | string | 可选标题与认证说明 |
| status | number | 可选的示例响应状态 |
默认插槽可放说明和 ParameterTable；request / response 插槽接收 Markdown 或代码：
:::api-endpoint{title="查询示例报告" method="GET" path="/api/reports/{id}" auth="演示认证" :status="200"}
这是一个说明用的示例接口。
#request
```http
GET /api/reports/demo HTTP/1.1
```
#response
```json
{ "id": "demo", "status": "ready" }
```
:::
ImageCompare：图片前后对比
参考 图片对比滑杆的交互模式，本站用原生 range 输入实现，支持拖动、触摸、方向键、Home 和 End。两张图应具有相同尺寸和构图；滑杆改变左侧“之前”图的可见比例。
| 属性 | 类型 | 说明 |
|---|---|---|
| beforeSrc / afterSrc | string | 必填，站内或 HTTP(S) 图片 |
| beforeAlt / afterAlt | string | 必填，两张图的替代文字 |
| beforeLabel / afterLabel | string | 默认“之前/之后” |
| title | string | 默认“图片对比”，用于滑杆标签 |
| initialPosition | number | 默认 50，限制到 0～100，无效值为 50 |
::image-compare
---
title: 工作流图示对比
beforeSrc: /images/mdc/render-flow.svg
afterSrc: /images/mdc/publish-flow.svg
beforeAlt: 内容渲染流程图
afterAlt: 文档发布流程图
beforeLabel: 渲染流程
afterLabel: 发布流程
initialPosition: 50
---
::
上例仅演示交互，不表示两张图存在升级关系。无效图片地址不会渲染，组件保留图像全貌，不裁切内容。
GlossaryTerm：行内术语解释
两个必填 string 属性：term 与 definition。适合在缩略词首次出现时解释含义。
页面通过 :glossary-term{term="SSR" definition="服务端渲染：由服务器生成页面的初始 HTML。"} 生成初始内容。
点击或键盘激活打开原生 popover；Esc、再次点击或点击外部关闭，aria-expanded 同步更新。说明显示在顶层，避免被父容器裁切。使用 Popover API，在不支持的浏览器中展开为普通说明文字。定义为文本，不执行 HTML。
ContentQuiz：阅读自测
question（string）、choices（string 数组）和 answer（从 0 开始的正确选项索引）必填，explanation 可选。选择后点“检查答案”显示结果和解析；更换选项清除旧结果，“重新作答”清空选择。
::content-quiz
---
question: 哪种数据应该写在前端示例里？
choices:
- 真实生产密码
- 无敏感信息的示例数据
answer: 1
explanation: 使用示例数据，避免发布真实凭据。
---
::
状态仅存在于当前组件，多个题目互不影响，不上传成绩。答案在公开页面数据中，适合学习自查，不能用于保密考试或可信评分。无效索引显示配置错误并禁用提交。
DownloadCard：下载入口
title、href 必填；filename、description、version、size 可选。站内绝对路径使用原生下载属性；HTTP(S) 外链在新窗口打开，不承诺跨域链接会被强制下载。
::download-card{title="设备清单示例" href="/examples/devices.example.json" filename="devices.example.json" version="1.0" description="仅含文档示例地址，不含账号密码。"}
::
大小与版本是作者提供的说明，不是实时文件校验。下载链接仅支持 HTTP(S) 或站内路径，不安全地址显示错误文字。示例 JSON 只用于展示下载，需要按实际工具格式调整。