组件库

模块化的 UI 组件，清晰的 API 定义

TV OS 组件库包含 30+ 基础组件，每个组件都有清晰的 API 定义、使用场景和代码示例。所有组件遵循设计原则和 Design Tokens，确保一致性和可维护性。

组件分类

🔘

基础组件

按钮、输入框、标签、徽章等最小单元

📦

容器组件

卡片、列表、网格、对话框等布局组件

🧭

导航组件

顶部导航、侧边栏、面包屑、标签页

📹

媒体组件

视频播放器、图片查看器、音频控制

💬

反馈组件

Toast、对话框、进度条、骨架屏

🤖

AI 组件

语音输入、推荐卡片、流式输出

按钮（Button）

用户触发操作的主要交互元素，支持遥控器焦点和点击。

变体（Variants）

变体 使用场景 视觉特征
Primary
主按钮		 页面主要操作（播放、确认、提交） 品牌色填充 + 白色文字
获焦时加深 10%
Secondary
次按钮		 次要操作（取消、返回） 透明背景 + 白色描边
获焦时填充半透明白色
Ghost
幽灵按钮		 不强调的操作（更多、展开） 纯文字 + 无背景
获焦时显示背景
Icon
图标按钮		 单个图标操作（收藏、分享） 圆形或方形 + 图标
48×48px 最小触摸区域

尺寸（Sizes）

尺寸 高度 内边距 字号 使用场景
Large 64px 24px 48px 24px 详情页主要操作按钮
Medium 48px 16px 32px 20px 默认按钮尺寸
Small 40px 12px 24px 18px 卡片内的操作按钮

状态（States）

  • Default：默认状态
  • Focused：获焦状态（遥控器移动到按钮上），6 维度强化焦点
  • Pressed：按下状态（用户按下确认键），scale(0.95) 缩放
  • Disabled：禁用状态，opacity: 0.4，不接受焦点
  • Loading：加载状态，显示 spinner，禁止交互

API 定义

<Button
  variant="primary | secondary | ghost | icon"
  size="large | medium | small"
  disabled={boolean}
  loading={boolean}
  icon={ReactNode}
  onClick={function}
>
  按钮文字
</Button>

卡片（Card）

内容容器，展示视频、音频、图文等信息，是 TV UI 最常用的组件。

卡片类型

类型 宽高比 使用场景 内容结构
Poster
海报卡片		 2:3 电影、电视剧 封面 + 标题 + 标签
Landscape
横版卡片		 16:9 视频、综艺 封面 + 标题 + 时长 + 标签
Square
方形卡片		 1:1 专辑、歌单 封面 + 标题 + 副标题
Avatar
头像卡片		 1:1（圆形） 用户、明星 头像 + 昵称 + 标签

卡片状态

  • Default：默认状态，opacity: 0.7（未获焦时降低对比度）
  • Focused：获焦状态
    • 放大到 scale(1.1)
    • opacity: 1.0
    • 阴影增强（shadow-lg）
    • 显示更多信息（评分、简介、按钮）
  • Playing：播放中（进度条、播放时长）
  • Watched：已观看（灰度滤镜 + "已看"标记）

AI 推荐卡片特殊设计

  • 视觉标识：渐变边框（从左上到右下，品牌色渐变）
  • Badge：右上角显示 "AI 推荐" badge
  • 推荐理由：获焦时底部显示"因为你看过《xxx》"
  • 反馈入口：长按菜单键，显示"不感兴趣" / "喜欢"

输入（Input）

文本输入、语音输入、虚拟键盘等输入组件。

虚拟键盘（Virtual Keyboard）

  • 布局：QWERTY 布局，4 行键盘
  • 按键尺寸：64×64px，间距 8px
  • 快捷输入：
    • 常用搜索词（最近搜索、热门搜索）
    • 语音输入按钮（唤起语音识别）
    • 数字快捷键（遥控器数字键直接输入）

语音输入（Voice Input）

详见 AI 交互模式 - 语音搜索

  • 5 状态设计：Idle → Listening → Processing → Searching → Results
  • 实时文本显示 + 波形动画
  • 错误兜底：识别失败时降级为虚拟键盘

视频播放器（Video Player）

核心媒体组件，支持播放、暂停、快进、字幕、清晰度切换等功能。

控制条（Control Bar）

  • 位置：屏幕底部，3 秒无操作自动隐藏
  • 结构：
    • 左侧：播放/暂停、上一集、下一集
    • 中间：进度条（拖拽支持、缩略图预览）
    • 右侧：音量、字幕、清晰度、倍速、全屏
  • 快捷键：
    • 左右键：快退/快进 10 秒
    • 上下键：调整音量
    • 确认键：播放/暂停
    • 返回键：退出播放

特殊状态

状态 UI 表现 触发条件
Buffering 中央显示 loading spinner + "加载中" 网络卡顿
Error 显示错误码 + "重试"按钮 播放失败
Ended 显示推荐内容 + "重播"按钮 播放完毕
Paused 显示暂停图标 + 控制条常驻 用户暂停

组件开发规范

1. 使用 Design Tokens

所有组件必须使用 Token 定义颜色、间距、圆角、动效，禁止硬编码数值。

/* ✅ 正确 */
.button {
  padding: var(--spacing-md) var(--spacing-lg);
  background: var(--color-primary);
  border-radius: var(--radius-md);
}

/* ❌ 错误 */
.button {
  padding: 16px 24px;
  background: #0066ff;
  border-radius: 8px;
}

2. 焦点管理

  • 所有可交互组件必须支持遥控器焦点
  • 获焦状态必须满足 6 维度清晰原则
  • 焦点顺序遵循从左到右、从上到下
  • 提供 focusable prop 控制是否接受焦点

3. 性能优化

  • 组件支持 lazy 懒加载
  • 长列表使用虚拟滚动（只渲染可见区域）
  • 图片使用懒加载 + 占位图
  • 根据芯片性能自动降级动效

4. 可访问性

  • 所有组件支持键盘导航
  • 提供语义化的 ARIA 属性
  • 颜色对比度 ≥ 4.5:1（WCAG AA）
  • 支持屏幕阅读器（用于视障用户）