tvOS：使用 Focus Engine 开发 Apple TV 应用

什么是 tvOS？

tvOS —— 苹果公司为 Apple TV 机顶盒开发的操作系统，基于与 iOS 相同的 Darwin XNU 内核。2015 年 10 月 30 日与第四代 Apple TV 一同首次发布。tvOS 取代了旧的 Apple TV 软件（基于 iOS，没有 App Store 和 SDK）。该系统针对电视进行了优化，支持高达 4K HDR（杜比视界）分辨率和杜比全景声。

根据苹果公司（WWDC 2025）的数据，tvOS 安装在 Apple TV HD（2015）、Apple TV 4K（2017、2021、2022）上，并通过 AirPlay 集成到部分智能电视型号中。Apple TV 使用 A8（HD）、A10X Fusion（第一代 4K）、A12 Bionic（第二代 4K）和 A15 Bionic（第三代 4K）芯片。所有型号均支持 tvOS 17。tvOS 没有摄像头、麦克风（遥控器除外）、触摸屏或 GPS。

tvOS 的关键特性是 Focus Engine，它用焦点导航取代了触摸控制。用户使用 Siri Remote 在 UI 元素之间移动选择。开发者使用 Swift/SwiftUI（原生）或 JavaScript/TVML（媒体应用，如 Netflix、Hulu）创建应用。

tvOS 版本历史

tvOS 9（2015）—— 首个包含 SDK 和 App Store 的版本。tvOS 10（2016）—— 有线电视订阅的单点登录（SSO）。tvOS 11（2017）—— 支持 Amazon Prime Video 和自动模式。tvOS 12（2018）—— 杜比全景声。tvOS 13（2019）—— 多用户模式。tvOS 17（2023）—— FaceTime、VPN、通过 HDMI 的音频配置文件。

tvOS 架构及与 iOS 的区别

tvOS 架构基于与 iOS 相同的技术栈：XNU 内核、Core Services 系统服务、Media 层和 Cocoa Touch 用户层。然而，由于电视平台的特性，存在显著差异。

硬件限制

第三代 Apple TV 4K 采用 A15 Bionic 芯片，配备 6 核 CPU（2 个性能核、4 个能效核）和 5 核 GPU。内存 —— 4 GB（内部 SSD 存储从 64 GB 起）。该系统没有传统意义上的永久本地存储：当空间不足时，tvOS 可能会删除所有应用数据（可清除）。开发者必须使用 iCloud 键值存储或 CloudKit 来保存状态。

TVMLKit 与 TVJS

TVMLKit —— 一个 tvOS 独有的框架，允许使用 JavaScript 和 TVML（苹果特有的类 XML 语言）创建界面。TVMLKit 从服务器加载 JSON/XML 并渲染原生 UI 组件。这是流媒体服务的主要技术：Netflix、Hulu、Amazon Prime Video 都使用 TVMLKit。TVJS —— 在隔离环境中运行的 JavaScript 运行时。

缺乏永久存储

tvOS 自动管理磁盘空间：当空间不足时，系统可能会删除缓存、下载的资源甚至应用本身（保留图标）。重新打开时，应用必须恢复其状态。iCloud NSUbiquitousKeyValueStore 是唯一保证的设置永久存储（每个应用最多 1 MB）。

import Foundation

// // 在 tvOS 中保存和恢复状态
final class StateManager {

    private let store = NSUbiquitousKeyValueStore.default
    private let coder = JSONEncoder()
    private let decoder = JSONDecoder()

    // 正在保存观看进度
    func saveProgress<T: Codable>(_ value: T, for key: String) {
        if let data = try? coder.encode(value) {
            store.set(data, for: key)
            store.synchronize()
        }
    }

    // 正在恢复删除缓存后的状态
    func restoreProgress<T: Codable>(_ type: T.Type, for key: String) -> T? {
        guard let data = store.data(for: key) else { return nil }
        return try? decoder.decode(type, from: data)
    }

    // 处理其他设备上的变更通知
    init() {
        NotificationCenter.default.addObserver(
            self,
            selector: #selector(ubiquitousKeyValueStoreDidChange),
            name: NSUbiquitousKeyValueStore.didChangeExternallyNotification,
            object: store
        )
    }

    @objc
    private func ubiquitousKeyValueStoreDidChange(_ notification: Notification) {
        print("其他设备上的数据已更改")
    }
}

StateManager 使用 NSUbiquitousKeyValueStore 在 tvOS 上保存应用状态。由于本地存储可能被系统清除，只有 iCloud 能保证数据持久性。store.synchronize() 立即将数据发送到服务器，而 didChangeExternallyNotification 通知应用来自用户其他设备的变更。

Focus Engine：导航与焦点

Focus Engine —— tvOS 的关键机制，用焦点导航取代触摸事件。用户使用 Siri Remote（触摸表面或按钮）在 UI 元素之间移动选择。系统根据距离和移动方向自动计算下一个焦点元素。

UIFocusEnvironment 与焦点层级

每个能够接收焦点的 UI 元素都实现了 UIFocusEnvironment 协议。UIKit 根据元素几何形状自动确定导航顺序。开发者可以通过 preferredFocusEnvironments 覆盖首选焦点，指定子 focusEnvironment 数组，并通过 UIFocusHeading（上、下、左、右）控制移动。UIFocusGuide 允许为非平凡布局设置自定义路径。

UIFocusEffect 与视差效果

tvOS 会自动为聚焦的元素添加 UIFocusEffect：阴影、高亮和视差效果（倾斜遥控器时的偏移）。开发者可以通过 focusedValue 禁用该效果，或通过 UIFocusEffect.transform 自定义。在 SwiftUI 中，视差效果通过 .hoverEffect(.highlight) 修饰符添加。

import SwiftUI

// // 具有自定义焦点的 tvOS 组件
struct MovieCardView: View {
    let movie: Movie
    @State private var isFocused = false
    @Environment(\.isFocused) var envFocused

    var body: some View {
        VStack(spacing: 8) {
            AsyncImage(url: movie.posterURL) { phase in
                if let image = phase.image {
                    image
                        .resizable()
                        .aspectRatio(contentMode: .fill)
                        .frame(width: 320, height: 180)
                        .cornerRadius(8)
                        .overlay(
                            RoundedRectangle(cornerRadius: 8)
                                .stroke(isFocused ? Color.blue : Color.clear, lineWidth: 3)
                        )
                        .scaleEffect(isFocused ? 1.08 : 1.0)
                }
            }

            Text(movie.title)
                .font(.caption)
                .lineLimit(2)
                .foregroundStyle(isFocused ? .white : .gray)
        }
        .onHover { hovering in
            withAnimation(.spring(response: 0.35)) {
                isFocused = hovering
            }
        }
        .onPlayPauseCommand {
            // 处理遥控器上的 Play/Pause 按钮
            startPlayback()
        }
        .focusable()
        .focusEffect { phase in
            // 自定义焦点效果
            phase == .active ?
                AnyView(self.scaleEffect(1.08)) :
                AnyView(self.scaleEffect(1.0))
        }
    }

    private func startPlayback() {
        print("正在播放：\(movie.title)")
    }
}

// // 带有电影网格的主屏幕
struct MovieGridScreen: View {
    let movies: [Movie]

    var body: some View {
        ScrollView {
            LazyVGrid(columns: [GridItem(.adaptive(minimum: 320, maximum: 400))], spacing: 24) {
                ForEach(movies) { movie in
                    MovieCardView(movie: movie)
                }
            }
            .padding(60)
        }
        .focusSection() // 用于导航的分组
    }
}

MovieCardView 展示了 SwiftUI 中的 Focus Engine：.focusable() 修饰符使元素可聚焦，.onHover 跟踪状态变化，.focusEffect 允许自定义焦点动画。.onPlayPauseCommand 处理 Siri Remote 上 Play/Pause 按钮的按下。focusSection 将网格分组以进行循环导航。

Siri Remote：手势与按钮

第二代 Siri Remote（2021）具有触摸表面、5 个按钮和麦克风。tvOS 支持手势：滑动（导航）、轻点（选择）、双击（居中）、捏合缩放（图像）、长按（上下文菜单）。UIPress 类型 .select、.playPause、.menu、.upArrow、.downArrow、.leftArrow、.rightArrow —— 预定义的按压类型。遥控器的麦克风用于 Siri 和语音搜索。

Top Shelf 与应用屏幕

Top Shelf 是 Apple TV 主屏幕上的一个区域，当应用位于顶部行时显示动态内容。在 tvOS 17 中，Top Shelf 支持最多 8 个 widget，可自定义背景和交互元素。开发者实现 TVTopShelfProvider 来提供内容。

Top Shelf 样式

三种 Top Shelf 样式可用：Sectioned —— 分类列表（按类型分系列）、Inset —— 带有详细描述的中央元素（推荐电影）、Photo —— 图片网格（相册）。系统通过 BGTaskScheduler 在后台更新 Top Shelf，类似于 watchOS。提供者必须快速返回内容 —— tvOS 将数据缓存 24 小时。

应用屏幕

tvOS 主屏幕由 Top Shelf 行和应用网格组成。用户可以重新排列图标和创建文件夹。当资源不足时，tvOS 会自动从内存中卸载应用，因此开发者必须正确处理 UISceneDidDisconnectNotification 并在重启时恢复状态。

面向 Apple TV 的 SwiftUI

SwiftUI 从 tvOS 13 开始完全支持 tvOS。苹果公司推荐所有新项目使用 SwiftUI。相同的 SwiftUI 代码可在 iOS、iPadOS、macOS 和 tvOS 上运行，只需针对 Focus Engine 进行少量适配。tvOS 的 SwiftUI 提供了 .focusable()、.focusSection()、.onPlayPauseCommand 和 .onExitCommand 修饰符。

适配 tvOS

将 iOS 应用移植到 tvOS 时，需要：用带焦点导航的 NavigationView 替换 TabView，增大字号（标题至少 30pt，正文至少 22pt），添加边距（距边缘至少 40pt —— 电视上的安全区域）。tvOS 不支持带文本字段的 UIAlertController、UIWebView 和 MFMailComposeViewController。

设计建议

苹果公司针对 tvOS 的 HIG：最小触摸区域大小为 60×60 点，文本在 3 米距离内可读（正文字号不小于 22pt），文本对比度 4.5:1，深色背景（浅色背景会在 OLED 电视上产生眩光），所有元素无需复杂手势即可访问。分辨率：Apple TV 4K 以 60 FPS 输出 3840×2160（4K）或 1920×1080（HD）。所有图片应为 @2x（用于 1080p）和 @4x（用于 4K）。

TVMLKit 与媒体应用

TVMLKit —— 一个用于在 tvOS 上使用 Web 技术（JavaScript (TVJS) 和 TVML（苹果特有的 XML））创建媒体应用的框架。TVMLKit 应用无需编译 —— 界面从服务器加载，允许在不经过 App Review 的情况下更新内容。主要流媒体服务将其用于内容轮播。

TVML：模板结构

TVML 提供了现成的模板：CatalogTemplate（带分段的目录）、ProductTemplate（内容详情页面）、FormTemplate（登录表单）、LoadingTemplate（加载指示器）。模板用 XML 描述，通过类似 CSS 的属性进行样式化。TVJS 代码处理点击并调用原生 API。

<!-- CatalogTemplate — TVML 上的电影目录 -->
<document>
  <catalogTemplate>
    <banner>
      <title>最新电影</title>
      <description>最新首映和独家内容</description>
    </banner>
    <section>
      <header>
        <title>热门</title>
      </header>
      <items>
        <lockup>
          <img src="https://cdn.example.com/movie1.jpg" width=300 height=450/>
          <title>星际穿越</title>
        </lockup>
        <lockup>
          <img src="https://cdn.example.com/movie2.jpg" width=300 height=450/>
          <title>盗梦空间</title>
        </lockup>
      </items>
    </section>
  </catalogTemplate>
</document>

TVML CatalogTemplate 包含一个带标题的横幅和带 lockup 元素的分段。每个 lockup 是一个带图片和标题的电影卡片。Focus Engine 自动管理 lockup 元素之间的导航。点击时，TVJS 处理程序接收 select 事件，并可以通过 ProductTemplate 显示详情页面。

TVJS：事件处理

TVJS 是一个与主应用隔离的 JavaScript 环境。TVJS 代码在加载 TVML 模板和处理事件时被调用。TVJS 可以通过 Appliance 和 Player 访问原生 API 以控制视频播放。苹果公司建议仅对内容更新频繁的媒体应用使用 TVMLKit。对于游戏和交互式应用，SwiftUI 是首选。

发布 tvOS 应用

发布 tvOS 应用 需要 Apple Developer Program 订阅（每年 99 美元）。应用通过 App Store Connect 作为独立产品或作为通用二进制文件（iOS + tvOS）的一部分上传。App Review 检查稳定性、HIG 合规性和 4 GB 大小限制。

构建与分发

Xcode 创建扩展名为 .app 的 tvOS 目标（.ipa 包）。架构 —— arm64（Apple TV 使用 Apple Silicon ARM 芯片）。tvOS 不支持包含 i386 或 x86_64 的框架。应用使用 Apple Development 证书（测试）或 Apple Distribution 证书（发布）进行签名。可以通过 Volume Purchase Program 向企业客户分发。

App Review 要求

tvOS 的特殊要求：所有界面元素必须通过 Focus Engine 访问，无需使用触摸屏或键盘。需要授权的应用必须通过 iTunes Store 支持单点登录（SSO）。广告内容不得在未获得用户同意的情况下中断播放。上传的二进制文件大小不得超过 4 GB。