📚 课程目录第1章 Android TV 项目骨架搭建与 Leanback 依赖配置

1. Android TV 项目骨架搭建与 Leanback 依赖配置

从零搭建可运行的 Android TV 工程

Android TV 应用与手机应用最大的工程差异在于三处：Leanback 支持库、TV 专用主题、横屏启动模式。本节先建立一个最小可运行骨架，把这三项配置一次性落实，再在电视模拟器上验证启动效果。

工程结构与依赖配置

使用 Android Studio 创建 Empty Views Activity 工程后，模块级 build.gradle 需要引入 Leanback 库。Leanback 提供 BrowseFragment、DetailsFragment、PlaybackSupportFragment 等电视专用组件，是后续所有 TV 界面的基础。

// app/build.gradle
android {
    compileSdk 34
    defaultConfig {
        applicationId "com.example.tvapp"
        minSdk 21          // Android TV 最低 API 21
        targetSdk 34
        versionCode 1
        versionName "1.0"
    }
}

dependencies {
    implementation "androidx.leanback:leanback:1.0.0"
    implementation "androidx.appcompat:appcompat:1.6.1"
}

Leanback 1.0.0 是稳定版本，兼容 API 21 及以上。若后续需要卡片视图、图片加载等扩展能力，可再追加 leanback-preference 或 glide，但最小骨架只需核心库。

TV 主题与横屏启动模式

电视应用必须使用 Theme.Leanback 系列主题，它默认关闭 ActionBar、放大焦点态、适配 10 英尺观看距离。在 AndroidManifest.xml 中同时声明 Leanback 特性与横屏方向。

<!-- AndroidManifest.xml -->
<uses-feature
    android:name="android.software.leanback"
    android:required="true" />
<uses-feature
    android:name="android.hardware.touchscreen"
    android:required="false" />

<application
    android:theme="@style/Theme.Leanback">
    <activity
        android:name=".MainActivity"
        android:screenOrientation="landscape"
        android:exported="true">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
        </intent-filter>
    </activity>
</application>

LEANBACK_LAUNCHER 是电视启动器的入口类别，与手机的 LAUNCHER 不同。若只写 LAUNCHER，应用不会出现在 Android TV 主屏上。touchscreen required=false 表示不强制要求触摸屏，否则电视设备会被过滤掉。

最小可运行界面

骨架阶段先用一个 FrameLayout 承载文本，确认主题与启动模式生效。布局文件 activity_main.xml：

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="#101820">

    <TextView
        android:id="@+id/tv_title"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="center"
        android:text="Android TV 骨架已启动"
        android:textColor="#FFFFFF"
        android:textSize="32sp" />
</FrameLayout>

MainActivity 继承 Activity 即可，Leanback 主题已处理窗口装饰：

class MainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }
}

启动验证与判读

在 Android Studio 的 Device Manager 中创建 Android TV (1080p) 模拟器，运行应用后按以下顺序判读：

应用出现在 TV 主屏的“应用”行中，图标可被遥控器选中；
点击后界面以横屏铺满，无 ActionBar、无状态栏遮挡；
中央文本“Android TV 骨架已启动”清晰可见，背景为深色；
按遥控器返回键可退出到主屏，不出现崩溃或黑屏。

若应用未出现在 TV 主屏，优先检查 LEANBACK_LAUNCHER 是否写对、uses-feature leanback required=true 是否声明。若启动后是竖屏或出现 ActionBar，检查 screenOrientation 与主题是否为 Theme.Leanback。

骨架检查清单

检查项	期望值	不通过时的排查方向
Leanback 依赖	1.0.0 已同步	Gradle Sync 是否报错、仓库是否可访问
minSdk	≥ 21	低于 21 时 Leanback 无法编译
启动类别	LEANBACK_LAUNCHER	写成 LAUNCHER 则 TV 主屏不显示
屏幕方向	landscape	未声明时模拟器可能竖屏
主题	Theme.Leanback	用 AppCompat 主题会出现 ActionBar
触摸屏特性	required=false	required=true 会过滤掉电视设备

完成以上配置后，工程已具备 TV 应用的基本形态。下一阶段即可在此基础上接入焦点导航与 D-pad 按键处理，让界面真正响应遥控器操作。