篮球赛程、比分与比赛状态：从接口目录到清晰可读的展示设计

篮球比赛列表不只是把两支球队和一个比分放在一起。用户需要辨认比赛时间、对阵关系以及当前进程，开发者则需要避免把未取得的数据呈现为确定事实。本文先列出百查数据体育 API 已核验的相关入口，再讨论通用展示方案；布局、状态模型和异常处理均为工程建议，不代表接口承诺。

一、先划清接口事实与页面职责

已核验目录包含比赛-赛程赛果、比赛-即时比分和赛季-比赛，三者请求方法均为 GET。国家、联赛、赛季、阶段、球队、球员及场馆列表也在目录中。目录确认了接口名称、地址和方法，但没有给出请求参数、响应字段、状态码含义或更新频率，不能据此补写这些内容。

接口名称	请求方法	已核验地址
比赛-赛程赛果	GET	https://api.superscore.cn/basketball/change/matchList
比赛-即时比分	GET	https://api.superscore.cn/basketball/change/live
赛季-比赛	GET	https://api.superscore.cn/basketball/change/matchSeason

工程上可将赛程页、比分视图和赛季比赛页分别作为信息组织入口，但实际调用关系必须由正式字段说明和响应样本确认。筛选控件可以预留联赛、赛季等维度；是否存在可关联标识、是否支持筛选参数，不能仅凭接口名称判断。

二、比分卡片优先保证可辨认

以下属于一般设计建议：列表按所选日期分组，卡片保留球队名称、比赛时间、比分区域和状态区域。两侧球队与各自得分应稳定对应，不要因领先方变化而交换位置。长队名可以截断，但需提供查看完整名称的方式；移动端优先保留对阵、比分和状态。

• 时间展示明确页面采用的时区；只有确认源时间格式与时区后才进行转换。
• 比分使用等宽数字，避免数值变化造成卡片宽度跳动。
• 缺失比分显示“—”或“暂无数据”，不要自动补成 0。
• 状态同时使用文字与视觉标记，避免仅靠颜色表达含义。

比赛时间与比分不应互相代替：到达计划开赛时间，并不证明比赛已经开始；取得比分，也不必然证明比赛已经结束。节次、剩余时间或特殊状态只有在响应数据及其含义得到确认后才应展示，无法判断时应保留中性提示。

三、建立前端状态模型，不猜测接口枚举

建议增加独立适配层，把已确认的源数据转换为页面模型。下面的字段和状态均为自定义示例，不是百查数据接口字段；映射规则应依据正式说明编写。尤其要区分比赛状态与请求状态：请求失败不等于比赛取消，数据暂缺也不等于尚未开赛。

// 通用前端示例：不是接口响应结构或官方状态枚举
const labels = {
  scheduled: '未开始',
  playing: '进行中',
  finished: '已结束',
  unknown: '状态待确认'
};

function presentMatch(viewModel) {
  const score = Number.isFinite(viewModel.homeScore)
    && Number.isFinite(viewModel.awayScore)
    ? `${viewModel.homeScore} : ${viewModel.awayScore}`
    : '—';
  return {
    score,
    status: labels[viewModel.phase] ?? labels.unknown
  };
}

四、刷新策略与验收一起设计

刷新方式应在确认调用限制和业务需求后确定，本文不假定轮询间隔或传输机制。可在请求失败时保留上次成功结果，并提示其尚未刷新；显示本地获取时间时，应标为“页面获取时间”，不能写成官方数据更新时间。异步请求还应防止旧结果覆盖新筛选条件。

上线前至少检查零分、缺失值、未知状态、跨日比赛、长队名和请求失败等情形。验收重点不是动画效果，而是用户能否区分已确认信息与暂不可确认信息。将目录事实、字段映射和展示规则分别维护，才能减少误读，并让后续接口适配更容易复核。

查看接口文档 · 了解数据产品