Console

Settings

Sign out

Notifications

Alexa

亚马逊应用商店

Ring

AWS

文档

Support

My Cases

Console

Vega开发者文档

主页

新手入门

设计和开发

应用发布

参考

支持

Vega目标导航器提供方

开放Beta测试文档 作为预发布开放Beta测试的一项内容，亚马逊提供了此技术文档。随着亚马逊收到反馈并对功能进行迭代，所描述的这些功能可能会发生变化。有关最新功能的信息，请参阅发布说明。

Vega目标导航器API将应用内的屏幕或部分作为“目标”，用户可以在其中与主页、设置、配置文件或搜索等输入模式进行交互。

实现目标导航器提供方接口的应用可以执行以下操作。

查询可用目标 — 了解应用提供了哪些可导航的屏幕和部分。
查询当前目标 — 确定用户正在查看哪个屏幕或部分。
导航到目标 — 将应用导航到特定屏幕或部分。

目标导航器提供方API有三个关键组件。

handleGetCurrentTarget — 可返回活动应用目标的回调。
handleGetaVailableTargets — 可返回支持的导航目标的回调。
handleNavigateTargetRequest — 当系统请求特定的目标导航时调用的回调。

提供方必须使用以下方法主动报告状态变化。

updateCurrentTarget — 在当前目标发生变化时通知系统。
updateAvailableTargets — 在可用目标列表发生变化时通知系统。

Vega目标导航器先决条件

在使用此API之前，请更新应用清单以声明您使用Vega目标导航器API的意图。修改清单条目时，将com.amazondeveloper.media.sample替换为应用程序包ID。您的应用必须经过正确配置，才能与Vega目标导航器API交互。

已复制到剪贴板。

schema-version = 1

[package]
title = "<应用标题>"
id = "com.amazondeveloper.media.sample"

[components]

[[components.interactive]]
id = "com.amazondeveloper.media.sample.main"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"
# 类别“com.amazon.category.kepler.media”仅对主要组件是必需的，
# 清单的 [[extras]] 部分中使用“component-id”值对主要组件进行了标识。
categories = ["com.amazon.category.main", "com.amazon.category.kepler.media"]

[processes]

[[processes.group]]
component-ids = ["com.amazondeveloper.media.sample.main"]

[offers]

[[offers.interaction]]
id = "com.amazondeveloper.media.sample.main"

[[offers.interaction.message]]
uri = "pkg://com.amazondeveloper.media.sample.main"
sender-privileges = ["*"]
receiver-privileges = ["self"]

[[offers.module]]
id = "/com.amazondeveloper.media.sample.module@ISomeUri1"
includes-messages = ["pkg://com.amazondeveloper.media.sample.main"]

[[extras]]
key = "interface.provider"
component-id = "com.amazondeveloper.media.sample.main"

[extras.value.application]

# 添加目标导航器界面
[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.ITargetNavigator"

步骤1：安装和设置Vega目标导航器

要使用Vega目标导航器API，请使用以下依赖项更新package.json文件：

已复制到剪贴板。

"dependencies": {
  "@amazon-devices/vega-target-navigator-provider": "~1.0.10"
}

步骤2：定义可用目标

TargetInfo对象使用以下字段表示每个目标：

identifier（数字，必需）— 目标在应用内的唯一数字ID。
name（字符串，可选）— 目标的人类可读名称。
standardId（StandardTargetIdentifier1，可选）— 标准标识符，可映射到已知目的地，使系统能够了解目标的用途。

可用的标准目标标识符为：

StandardTargetIdentifier1	值	描述
HOME	0	应用主屏幕
LOGIN	1	登录屏幕
PROFILE	2	用户配置文件
SETTINGS	3	应用设置
PRIVACY	4	隐私设置
HELP	5	帮助屏幕
ABOUT	6	“关于”屏幕
TERMS	7	服务条款
SEARCH	8	搜索屏幕
RECOMMENDATIONS	9	推荐
TRENDING	10	热门内容
DOWNLOADS	11	下载量
HISTORY	12	观看历史记录

您可以将目标定义为由标识符键控的映射：

已复制到剪贴板。

import {
  TargetNavigatorProvider,
  TargetNavigatorHandler,
  TargetInfo,
  StandardTargetIdentifier1,
} from '@amazon-devices/vega-target-navigator-provider';
...
const availableTargets: { [key: number]: TargetInfo } = {
  0: { identifier: 0, name: 'Home', standardId: StandardTargetIdentifier1.HOME },
  1: { identifier: 1, name: 'Profile', standardId: StandardTargetIdentifier1.PROFILE },
  2: { identifier: 2, name: 'Settings', standardId: StandardTargetIdentifier1.SETTINGS },
};

目标导航器界面还支持没有standardId的自定义目标。

已复制到剪贴板。

const customTarget: TargetInfo = { identifier: 100, name: 'My Custom Screen' };

步骤3：实现目标导航器处理程序

创建可实现三个回调方法的TargetNavigatorHandler对象。

已复制到剪贴板。

const targetNavigatorHandler: TargetNavigatorHandler = {
  handleGetCurrentTarget: (): Promise<TargetInfo[]> => {
    return Promise.resolve([currentTarget]);
  },

  handleGetAvailableTargets: (): Promise<TargetInfo[]> => {
    return Promise.resolve(Object.values(availableTargets));
  },

  handleNavigateTargetRequest: (target: TargetInfo): Promise<string> => {
    // 如果提供，则首选使用standardId进行匹配，回退到标识符
    let matchedTarget: TargetInfo | undefined;
    if (target.standardId !== undefined) {
      matchedTarget = Object.values(availableTargets).find(
        (candidate) => candidate.standardId === target.standardId
      );
    }
    if (matchedTarget === undefined) {
      matchedTarget = availableTargets[target.identifier];
    }
    if (matchedTarget === undefined) {
      return Promise.reject(new Error(`Target not found`));
    }
    currentTarget = matchedTarget;
    TargetNavigatorProvider.updateCurrentTarget(currentTarget);
    return Promise.resolve('Success');
  },
};

处理程序方法详细信息

方法	返回值	描述
`handleGetCurrentTarget()`	`Promise<TargetInfo[]>`	返回当前处于活动状态的目标。如果没有，则返回一个空数组。
`handleGetAvailableTargets()`	`Promise<TargetInfo[]>`	返回所有可导航目标。不得超过256个元素。
`handleNavigateTargetRequest(target)`	`Promise<string>`	导航到目标。成功时使用状态字符串进行解析，失败时`Error`拒绝。

步骤4：注册处理程序

使用useKeplerAppStateManager() 中的IComponentInstance注册处理程序。在调用任何update方法之前，不要在启动时执行此操作。

已复制到剪贴板。

const componentInstance = useKeplerAppStateManager().getComponentInstance();

TargetNavigatorProvider.registerTargetNavigatorHandler(
  targetNavigatorHandler,
  componentInstance
);

重要须知： 挂载时在useEffect中注册。在调用updateCurrentTarget或updateAvailableTargets之前，必须注册处理程序，因为如果未设置任何处理程序，这些调用会失败。

步骤5：报告目标状态变化

注册处理程序后，将当前状态通知系统。启动时同时调用updateCurrentTarget和updateAvailableTargets，如果状态发生变化则再次调用。

更新当前目标

每当用户导航到不同的屏幕时，都会调用应用初始化：

已复制到剪贴板。

TargetNavigatorProvider.updateCurrentTarget(availableTargets[2]);

传递undefined以表明当前没有目标，例如处于过渡状态。

已复制到剪贴板。

TargetNavigatorProvider.updateCurrentTarget(undefined);

更新可用目标

当任何可导航的目的地发生变化时（例如用户登录时），更新目标。

已复制到剪贴板。

TargetNavigatorProvider.updateAvailableTargets(Object.values(availableTargets));

Vega目标导航器故障排除

问题	解决方法
处理器无法收到请求	确认确切的清单`interface_name`为 `"com.amazon.kepler.media.ITargetNavigator"`，且`component-id`与您的交互式组件匹配。
未找到目标的错误	使用`updateAvailableTargets()` 确保可用目标列表保持最新状态。
处理程序注册时间太迟	在收到任何请求之前，于挂载时在`useEffect`中注册。

API参考

类

TargetNavigatorProvider — TargetNavigatorProvider

接口

TargetInfo — 表示导航的目标。
TargetNavigatorHandler — 由目标导航器服务器实现的用于处理请求的接口。

枚举

StandardTargetIdentifier1 — 标准导航目标枚举。

Last updated: 2026年7月15日

Vega目标导航器提供方

Vega目标导航器先决条件

步骤1： 安装和设置Vega目标导航器

步骤2： 定义可用目标

步骤3： 实现目标导航器处理程序

处理程序方法详细信息

步骤4： 注册处理程序

步骤5： 报告目标状态变化

更新当前目标

更新可用目标

Vega目标导航器故障排除

API参考

类

接口

枚举

相关主题

步骤1：安装和设置Vega目标导航器

步骤2：定义可用目标

步骤3：实现目标导航器处理程序

步骤4：注册处理程序

步骤5：报告目标状态变化