将 TVML App 迁移到 SwiftUI

将 TVML App 迁移到 SwiftUI

SwiftUI 可帮助你在所有 Apple 平台上打造出色的 App，更是利用 Apple tvOS 18 将你的内容引入客厅环境的首选工具包。了解如何使用 SwiftUI 通过 TVMLKit 创建熟悉的布局和控件，并获取相关技巧和推荐做法。

章节
- 0:00 - Introduction
- 3:54 - Lockups
- 5:12 - Shelves
- 7:35 - Catalogs
- 11:07 - Search
资源
相关视频

WWDC24
下载

大家好欢迎观看 “将 TVML App 迁移到 SwiftUI” 我叫 Jim 是 SwiftUI for Apple tvOS 团队的工程师我很高兴能向大家展示 SwiftUI 中适用于 Apple tvOS App 的出色功能并介绍如何使用它构建以前使用 TVML 构建的 App 在 Apple tvOS 18 中 SwiftUI 拥有为你喜爱的机顶盒平台构建丰富多样、功能齐全的媒体目录和流媒体 App 所需要的一切正是因为这样 Apple 正式弃用 TVMLKit 它仍然在 Apple tvOS 中提供但不会再随平台更新 Apple 在 2015 年推出 Apple tvOS 当时的流媒体与今天的流媒体相去甚远流媒体 App 基本上以网页形式实现内容提供商的开发资源也以网页为中心 Apple 提供了 TVMLKit 用于利用这些资源和专业知识为 Apple TV 打造出色的 App
如今我们在各种设备上消费内容比如 iPhone 或 iPad、使用机顶盒的电视机、电脑以及 Apple Vision Pro 等设备我们通过原生 App 访问流媒体目录这些 App 是使用专为这些平台量身定制的工具构建的这些 App 可为顾客提供更熟悉、更个性化的体验既能展现自己独特的风格又能保持这些设备流畅的互动体验和展示风格 SwiftUI 提供了一个工具包可针对这些平台量身打造原生代码和 UI 全部使用同一种语言采用相同的组件构建其中使用的开发资源和专业知识可以清晰地转换为任何其他平台
在 Apple TV 上它生成原生的 Apple tvOS UI 各种设计线索旨在打造出色的 Apple tvOS App TVMLKit 能做的事现在都可以在 SwiftUI 中实现灵活性更高并且不断推出新功能 App 代码使用 Swift 编写这种语言也用于开发 iOS、iPadOS、macOS、watchOS 和 visionOS 上的 App
因此它能够充分利用现有的原生开发资源为 iPad 开发 App 而使用的工具和技术也可用于为 Apple TV 开发 App 现在你还可以轻松地将其他 App 的代码直接用于开发 Apple tvOS App
我将介绍在 SwiftUI 中搭建内容目录 App 的基础做法你将了解到用于为任何 Apple 平台构建 App 的相同组件可用于创建 Apple TV 的所有用户都会立即感到很熟悉的界面和行为首先我们来了解 Apple tvOS 媒体 App 的典型设计语言
打开媒体目录时一般首先显示主页主页针对观看者进行定制页面的上半部分通常显示一些推广内容漂浮在屏幕边缘
这些推广内容通常提供一些快速操作以方便用户快速访问推广内容区域下方显示货架中的更多内容
每个项目都显示为一个色彩缤纷的动态组合其中展示项目的插图最后标签页栏位于屏幕顶部可让用户直接访问 App 的不同部分包括搜索功能
在这个视频中我将介绍如何构建 Apple Music 和 Apple TV 等 App 使用的类似组合我将介绍一些有用的技巧来构建这些内容组合的悬浮货架我将介绍一种简单的方式来为 App 的着陆页面设计令人印象深刻的布局并展示如何仅用几行代码就能打造流畅的搜索体验
首先我们来了解如何进行之前提到的组合设计
Apple tvOS 上最常见的组合类型是一张图片悬浮在文字上方图片具有圆润的边角被选中时会升起并微微转动显示镜面反光效果旁边的文字会下滑以避免被图片遮挡这些效果都可以使用 SwiftUI 来实现基本布局很容易实现图片位于文字上方这已经很接近我们的设计但我们希望它是交互式的所以把它放到按钮中
Apple tvOS 中的按钮默认使用有边框的 buttonStyle 它们会获得一个背景盘在获得焦点时会升起并变色为实现我们想要的外观我们将使用无边框 buttonStyle
现在图片和标题方向正确图片具有圆角和轻微的投影获得焦点时图像升起文字下移然后显示镜面反光效果当手指在遥控器的触控表面上移动时整个图片会微微转动这段代码在其他平台上也按原样运行并采用相应平台特有的交互机制
我们已完成基本的内容组合可以继续创建货架我们来回顾一下内容货架的标准外观以确定想要实现的效果
我们的内容应该水平滚动并且应该与屏幕的安全区域边界对齐这样可以使它与周围的元素保持协调
它还应该允许屏幕外的内容在屏幕边缘微露来表示这个方向有更多内容
我们使用水平滚动的堆栈来开始构建理想情况下这应是嵌入 ScrollView 中的 LazyHStack 我们将使用无边框 buttonStyle 来获取组合并确保停用 ScrollView 上的滚动修剪这样获得焦点的组合就可以变大并把投影投射到 ScrollView 本身的边界之外货架中的每个项目都将由一个按钮表示虽然你可以直接指定某个项目的海报图像的确切大小但使用根据这个大小计算出的 aspectRatio 可能效果更好这样 SwiftUI 就可以进行调整为你提供理想的布局在这个例子中我的 aspectRatio 提供电影海报的形状而实际的点尺寸将由屏幕上显示的项目数决定
布局的魔法发生在 containerRelativeFrame 修饰符中这个修饰符告诉 SwiftUI 它应该为我们确定这个项目的边框并提供了一些有用的信息这会自动调整内容使它与前面和后面的安全区域嵌入对齐并为当前滚动横幅之外的项目提供足够的空间这些额外项目会在屏幕的两侧微露
首先项目的边框应取决于最近的父级容器视图的水平边界在这个例子中为 ScrollView 单独使用这个视图会让这个按钮的图像拉伸到 ScrollView 的边界但还有另外两个属性可以更改这个行为
在这里我们要求在容器的宽度内有六个项目我们提供了一点帮助说明了项目之间相隔的的空间大小这个值与提供给水平堆栈的间距值匹配这两个值必须相同同样的你可以使用完全相同的代码在其他平台上打造类似的体验只需要调整间距和项目数量等
只需几行简短的代码你现在就复制了 Apple 自身的媒体 App 的外观和使用体验就像在 Apple tvOS 9 中使用 TVML 一样这是一个非常灵活的组件可通过多种方式使用只需进行非常小的改动
例如移除按钮标题并稍微调整 containerRelativeFrame 修饰符你会得到题图大小的组合的轮播界面
更改插图的宽高比和每个 containerRelativeFrame 的项目数量你会得到适合专辑封面的完美尺寸
如果你需要更高的信息密度可以使用 .card buttonStyle 来构建与 TV App 中的搜索结果类型相同的组合
卡片 buttonStyle 提供圆角背景盘来支撑你的内容它的升起和移动幅度比无边框 buttonStyle 更小同样你只需要附加 .card buttonStyle 即可实现这一行为
有了货架之后我们可以开始组装起始页面
分组视图会为每个货架提供标题当组合获得焦点时标题会自动移开以避免被遮挡就像按钮上的标题一样
为了正确引入主页视图我们希望宽屏背景图像填充屏幕的每个边缘我们可以首先添加一个简单视图包含标题和一些按钮按钮之间有一定的间距以显示背景图像
现在我们可以添加一个背景将它附加到外层 ScrollView 即可我们将确保图片可根据需要调整大小但它不会扩展到屏幕边缘忽略安全区域就可以快速解决这个问题
这样看起来已经好多了内容一直显示到显示屏边缘就像我们想要的那样但它显示在货架后面有点让人分心
简单的渐变遮罩可以使按钮后的图片淡出你只需要应用线性渐变和遮罩修饰符现在图片淡出显示它后面的背景
这样看起来好多了很接近我们最终的应用程序理想情况下我们希望当没有获得焦点时图像会完全消失
Apple tvOS 18.0 中新增了许多专用于 ScrollView 的视图修饰符我们可以利用这些修饰符来移除背景图像适用的情况是标题部分滚动到屏幕之外以及内容移动 belowFold
这里我将 onScrollVisibilityChange 修饰符附加到标题视图当它移出屏幕时我将更改一些状态
然后我选择基于状态显示背景
我还将 scrollTargetBehavior 设置为 viewAligned 以便让过渡更明确
将所有这些组合到一起我们就得到了着陆页面你可以下载本视频的示例代码以获得一些其他示例了解如何使用更高级的方法实现这种视图样式要进一步了解 Apple tvOS 18 和一致版本中新的 ScrollView 修饰符请观看“解密 SwiftUI 容器”
到目前为止一切都很棒但还有一项功能是出色的内容交付服务必备的这就是搜索功能下面我们来了解如何利用已经构建好的东西来快速提供出色的搜索界面在这之前你需要提供访问搜索窗格的方法
典型的做法是使用 TabView 还有一个新的表达能力强的类型安全语法用于在 Apple tvOS 18 中组装 TabView 我将现有内容堆栈放入名为 StackView 的新视图中并已将 SearchView 添加到新标签页让我们来看看 SearchView 中应该有什么
搜索视图通常允许同时在大量内容中进行搜索所以货架布局好像不太合适我们将使用网格布局来显示结果
我们从与其他视图相同的基本结构开始但在其中放入一个 LazyVGrid
我将它设置为创建四列间距为 40 点且大小灵活同样我将让宽高比修饰符和 SwiftUI 的布局机制来确定项目的实际大小
组合本身是熟悉的按钮但它现在是垂直滚动我使用了一张横向图像以沿这个轴显示更多内容为了使这些内容可搜索我将添加两个东西首先我将向视图添加 state 属性这将会更新从而包含正在输入的任何搜索词我们可以用它来筛选传递到 for-each 视图的内容从而缩小在结果中显示的内容范围
接下来我将添加 .searchable 修饰符向它传递 searchTerm 状态属性的绑定
呈现搜索视图只需要这一个修饰符在这里 App 用户可以键入搜索词你可以使用搜索词状态属性来滤除任何不匹配的项目
用户可以搜索包含他们最喜欢的机器人植物学家的视频也可以直接挥洒自己的植物学灵感你可能有很多内容可供用户搜索你的内容项目的一些潜在搜索词和关键词可能会很长如果能提供一些补全建议会很有帮助这也很容易做到只需添加 .searchSuggestions 修饰符即可这里有一个包含当前搜索词的关键词列表我将根据这个列表创建一系列文本视图结果如下选择任何一个补全文本都会将它的值自动放入搜索栏中选中某一个建议会在搜索栏内提供屏幕预览表明操作和建议都会执行以及这个词与当前输入的匹配程度同样这些代码也可以在其他平台上使用可通过同样的方法向 iPad、Mac 或 Apple Vision Pro App 添加搜索栏
现在你应该清楚如何轻松使用 SwiftUI 为 Apple TV 构建精美的 App 以及我们所构建的所有东西都可以在 Apple 的其他平台上运行几乎不需要更改将原生 SwiftUI App 带到客厅环境从未如此简单
我们致力于提供简洁明了的方法从 SwiftUI 采用最新的平台功能我还想向你们展示一个功能 TV App 中的悬浮式边栏这项功能现已推出可通过 SwiftUI 在 Apple tvOS 18 中使用它同样拥有美丽的半透明外观并且可以收起以显示 TV App 中的紧凑指示图标如果你在构建自己的边栏不妨考虑在你的 App 中采用这个新的外观你可使用现有的导航分屏浏览 API 来构建它如果你的 App 目前使用标签页栏你可以立即试用这个外观只需使用一行代码只需将 tabViewStyle 设置为 sidebarAdaptable 标签页栏就会显示为边栏你也可以在 iPad 上使用这个修饰符在 iPadOS 18 中获得新的标签页栏外观它还允许用户在标签页栏和边栏之间互相切换在 Apple tvOS 中它提供边栏和所有相关行为只需要一行代码
新的 TabView API 支持各种不同类型的内容你可以构建功能完备的边栏同时保持最小标签页栏外观这意味着 iPad App 可以采用简约的标签页栏形式并可扩展为包含详细信息和丰富功能的边栏同样的边栏内容在 Apple tvOS 上看起来也很棒你可以观看“提升 iPad 中的标签页和边栏使用体验” 详细了解新的标签页栏 API
如果你想要在 Apple TV 上构建 App 现在就是最好的时机 SwiftUI 可帮助你轻松构建 Apple tvOS App 它们拥有精美的外观并且大部分代码可以用于 iPhone、iPad、Mac 和 Apple Vision Pro App 如果你目前有 TVML App 现在是时候考虑做出改变了
你已了解如何轻松使用 SwiftUI 构建出色的 Apple TV App 无边框 buttonStyle 提供获取平台标准内容组合外观和交互所需要的一切使用容器相对框架可以消除搭建内容货架时的所有臆测请观看“SwiftUI 的新功能” 了解 Apple tvOS 18 和一致版本中强大的新功能要进一步了解新的容器 API 请观看“解密 SwiftUI 容器” 要了解如何打造出色的跨平台顶层 App 导航 UI 请观看“提升 iPad 中的标签页和边栏使用体验”
查看本视频中的示例项目获取完整的示例代码以及更多示例和建议要查看一个功能全面的跨平台 App 的示例它在 Apple TV 上表现出色不妨查看 Destination Video 示例项目 SwiftUI for Apple tvOS 团队期待看到你构建的出色 App 在运行 Apple tvOS 18 的 Apple TV 中大放异彩

Button {} label: {
    Image("discovery_landscape")
        .resizable()
        .frame(width: 250, height: 375)
    Text("Borderless Portrait")
}
.buttonStyle(.borderless)

5:38 - Standard content shelf

ScrollView(.horizontal) {
    LazyHStack(spacing: 40) {
        ForEach(Asset.allCases) { asset in
            Button {} label: {
                asset.portraitImage
                    .resizable()
                    .aspectRatio(250/375, contentMode: .fit)
                    .containerRelativeFrame(.horizontal, count: 6, spacing: 40)
                Text(asset.title)
            }
        }
    }
}
.scrollClipDisabled()
.buttonStyle(.borderless)

8:19 - Card button

ScrollView(.horizontal) {
    LazyHStack(spacing: 48) {
        ForEach(Asset.allCases) { asset in
            Button {} label: {
                HStack(alignment: .top, spacing: 10) {
                    asset.landscapeImage
                        .resizable()
                        .aspectRatio(contentMode: .fit)
                        .clipShape(RoundedRectangle(cornerRadius: 12))

                    VStack(alignment: .leading) {
                        Text(asset.title)
                            .font(.body)
                        Text("Subtitle text goes here, limited to two lines")
                            .font(.caption2)
                            .foregroundStyle(.secondary)
                            .lineLimit(2)
                        Spacer(minLength: 0)
                        HStack(spacing: 4) {
                            ForEach(1..<4) { _ in
                                Image(systemName: "ellipsis.rectangle.fill")
                            }
                        }
                        .foregroundStyle(.secondary)
                    }
                }
                .padding([.leading, .top, .bottom], 12)
                .padding(.trailing, 20)
                .frame(maxWidth: .infinity)
            }
            .containerRelativeFrame(.horizontal, count: 3, spacing: 48)
        }
    }
}
.scrollClipDisabled()
.buttonStyle(.card)

8:39 - Landing page

ScrollView(.vertical) {
    LazyVStack(alignment: .leading, spacing: 26) {
        VStack(alignment: .leading) {
            Text("tvOS with SwiftUI")
                .font(.largeTitle).bold()

            Spacer(minLength: 300)

            HStack {
                Button("Show") {}
                Button(“More Info…”) {}
                Spacer()
            }
            .padding(.bottom, 100)

            Spacer()
        }
        .onScrollVisibilityChange { visible in
            withAnimation {
                belowFold = !visible
            }
        }

        Section("Movie Shelf") {
            MovieShelf()
        }

        Section("TV and Music Shelf") {
            TVMusicShelf()
        }

        Section("Content Cards") {
            CardShelf()
        }
    }
    .scrollTargetLayout()
}
.scrollClipDisabled()
.background(alignment: .top) {
    if !belowFold {
        Image("beach_landscape")
            .resizable()
            .aspectRatio(contentMode: .fill)
            .ignoresSafeArea()
            .mask {
                LinearGradient(stops: [
                    .init(color: .black, location: 0.0),
                    .init(color: .black, location: 0.45),
                    .init(color: .black.opacity(0), location: 0.8)
                ], startPoint: .top, endPoint: .bottom)
            }
    }
}
.scrollTargetBehavior(.viewAligned)

11:13 - Tab view

TabView {
    Tab("Stack", systemImage: "line.3.horizontal") {
        StackView()
    }

    // Other Tabs...

    Tab("Search", systemImage: "magnifyingglass") {
        SearchView()
    }
}

11:50 - Search page

@State var searchTerm: String = ""

let columns: [GridItem] = Array(repeating: .init(.flexible(), spacing: 40), count: 4)

ScrollView(.vertical) {
    LazyVGrid(columns: columns) {
        ForEach(sortedMatchingAssets) { asset in
            Button {} label: {
                asset.landscapeImage
                    .resizable()
                    .aspectRatio(16 / 9, contentMode: .fit)
                Text(asset.title)
            }
        }
    }
}
.scrollClipDisabled()
.buttonStyle(.borderless)
.searchable(text: $searchTerm)
.searchSuggestions {
    ForEach(suggestedSearchTerms, id: \.self) { suggestion in
        Text(suggestion)
    }
}

14:59 - Sidebar adaptable tab view style

TabView {
    Tab("Stack", systemImage: "line.3.horizontal") {
        StackView()
    }

    // Other Tabs...

    Tab("Search", systemImage: "magnifyingglass") {
        SearchView()
    }
}
.tabViewStyle(.sidebarAdaptable)

正在查找特定内容？在上方输入一个主题，就能直接跳转到相应的精彩内容。

提交你查询的内容时出现错误。请检查互联网连接，然后再试一次。

章节

资源

相关视频

WWDC24