EPG

电子节目指南 (EPG) 是VUIC库中的自定义视图组件。EPG组件支持使用电视设备遥控器上的方向键进行控制。本指南包括您可以下载的示例应用以及如何使用EPG的详细信息。

EPG示例应用

EPG示例应用使用Vega SDK构建而成。使用此示例应用，您可以实现EPG组件。

更新package.json文件

EPG组件可通过VUIC库获得。确保您的package.json在其依赖项部分列出VUIC，如下所示。

复制代码 已复制到剪贴板。

"dependencies": {
    // ...
    "@amazon-devices/kepler-ui-components": "^2.0.0",
}

语义化版本表达式中的^说明可以自动采用3.0.0之前的任何新版本。

要了解有关开始使用VUIC的更多信息，请参阅开始使用Vega用户界面组件库。

EPG组件用法和属性

以下代码示例示出了EPG的用法。还必须通过updateData为EPG组件提供频道和节目数据。

复制代码 已复制到剪贴板。

<EPG
    ref={epg}
    onScroll={({ row, timeMs }: EPGScrollEvent) => {
        // 此处为处理程序代码
    }}
    onTileFocus={({ payload, title }: EPGTileFocusEvent) => {
        // 此处为处理程序代码
    }}
    onTilePress={({ payload, title }: EPGTilePressEvent) => {
        // 此处为处理程序代码
    }}
    onMenu={({ payload, title }: EPGMenuEvent) => {
        // 此处为处理程序代码
    }}
    focusBorder={{
        enabled: true,
        color: '#E4E4E7',
    }}
    tileStyle={{
        backgroundColor: '#191E25',
        foregroundColor: '#E4E4E7',
        focusedForegroundColor: '#E4E4E7',
        elapsedBackgroundColor: '#3D3D3D',
        pendingBackgroundColor: '#191E25',
    }}
    logoStyle={{
        backgroundColor: '#FF0E25',
        width: 340,
    }}
/>

下图表展示了哪些属性对应于颜色。

使用timelineStyle属性自定义时间线

timelineStyle属性允许您自定义位于EPG网格上方的时间线。您可以自定义以下元素：

• 进度条： 以红色突出显示的时间线部分，表示自EPG开始以来已经过去的时长。

• 播放头： 标记当前时间的视觉指示器。播放头的图像必须位于assets/images文件夹中。

示例：timelineStyle结构

复制代码 已复制到剪贴板。

TimelineStyle {
  progressBar?: {
    hidden?: boolean;
  };
  playhead?: {
    hidden?: boolean;
    source?: "string"
    height?: number;
    width?: number;
    verticalOffset?: number;
  };
}

要查看有关timelineStyle属性的详细信息，请参阅组件用法和属性部分。

收藏频道功能

EPG组件支持在频道标志单元格的左侧显示“收藏”频道的视觉指示器。您可以使用专属标志来表示“关闭”“开启”收藏状态，例如心形图标或星形图标。

示例： 收藏图标

要指定收藏频道，您可以在频道对象中设置isFavorite: true。对于初始的指南显示方式，您还可以使用isFavorite: false来显示您的自定义off图标，从而将某个频道指定为非收藏频道。如果需要在运行时更改收藏状态，您可以使用命令式方法updateFavorite进行操作，如以下示例所示。

示例：updateFavorite方法

复制代码 已复制到剪贴板。

epg.current?.updateFavorite(channelId, true);

要使用收藏功能，您必须为属性中的收藏项至少提供一个“on”图标图像，如以下示例所示。

示例： 添加收藏图标图像

复制代码 已复制到剪贴板。

<EPG ...
    favoriteStyle={{
        imageOn: 'small_heart.png',
    }}
...

如果未在频道对象中指定imageOff，对于isFavorite设置为false或未指定的行，会呈现“空白”图像。您必须将收藏的图像放在应用程序包源的assets/image文件夹中。

命令式方法

EPG组件比许多React Native组件更为复杂，因此需要使用特定的命令式方法。

示例： 如何获得引用以调用命令式方法

复制代码 已复制到剪贴板。

import { EPG, EPGActions } from '@amazon-devices/kepler-ui-components';

const epg = useRef<EPGActions>(null);
...
<EPG
  ref={epg}
  ...
 />
 ...
 epg.current?.updateGridStartTime(newGridStartTime);

resetData方法

使用resetData方法，您可以将指南的现有数据替换为新数据。resetData方法等同于清除所有数据，然后再次调用updateData方法。

参数

• channelData：一个数组，其中每个元素都是不同频道的数据。每个对象都应包含频道标识符（即ID）相关信息和一个节目数据数组。有关此数据的结构的更多详细信息，请参阅数据模型。
• page（可选）：一个布尔值，用于通知EPG组件与页面相关的信息，但这些信息不是频道数据的直接组成部分。page包含两个可选的子对象：startTimeMs和endTimeMs。
  • startTimeMs（可选）：用于定义查询页面开始时间的数字。仅与endTimeMs一起使用。当开始和结束时间与页面信息一起提供时，任何节目信息差都会显示为Unavailable（不可用）。
  • endTimeMs（可选）：用于定义查询页面结束时间的数字。仅与startTimeMs一起使用。当开始和结束时间与页面信息一起提供时，任何节目信息差都会显示为Unavailable（不可用）。

updateData方法

参数

• channelData：一个数组，其中每个元素都是不同频道的数据。每个对象都应包含频道标识符（即id）相关信息和一个节目数据数组。有关此数据的结构的更多详细信息，请参阅数据模型。
• page（可选）：一个布尔值，用于通知EPG与页面相关的信息，但这些信息不是频道数据的直接组成部分。page包含两个可选的子对象：startTimeMs和endTimeMs。
  • startTimeMs（可选）：用于定义查询页面开始时间的数字。仅与endTimeMs一起使用。当开始和结束时间与页面信息一起提供时，任何节目信息差都会显示为Unavailable（不可用）。
  • endTimeMs（可选）：用于定义查询页面结束时间的数字。仅与startTimeMs一起使用。当开始和结束时间与页面信息一起提供时，任何节目信息差都会显示为Unavailable（不可用）。

描述

EPG组件用于在内部管理频道和节目的数据，因此无法通过属性传递数据。更新数据的方式改为使用updateData () 函数。此函数的输入是一个频道数据数组，其中每个元素都是不同频道的数据，包括频道的节目。然后，该输入数据会与EPG内部的现有EPG数据合并。EPG会遵循以下步骤来合并数据：

1. 检查频道的数据是否已存在于EPG数据中。频道由id属性进行唯一标识。如果EPG数据中存在相同id的频道，则表示正在添加的频道已存在。
   1. 如果频道存在：
      1. 访问该频道的数据记录
   2. 如果频道不存在：
      1. 为该频道创建新记录
2. 将输入频道数据中的节目添加到EPG数据。
   1. 对于每个节目，EPG都会检查该节目的数据是否已经存在。系统通过所属频道和startTime对节目进行标识。如果某个节目的startTime和目标节目相同，则说明待添加的节目已经存在。
      1. 如果节目数据已经存在：
         1. 新节目数据会覆盖旧节目数据。
      2. 如果节目数据不存在：
         1. 检查新节目的时间跨度/时间长度是否与任何现有节目重叠。
            1. 如果该频道的新节目与现有节目之间没有重叠，则会将新节目添加到EPG中的相应时间。
            2. 如果新节目的startTime与现有节目的endTime冲突，则会缩短现有节目，以便将新节目添加到恰当的startTime。换句话说，如果newProgram.startTime < existingProgram.endTime，则更新existingProgram，以便让existingProgram.endTime = newProgram.startTime。
            3. 如果新节目的endTime大于按时间顺序排列的下一个节目的startTime，则该新节目的时间长度会缩短。

用法示例

以下是应用使用updateData方法的示例。应用在下午2:00打开。

1. 应用查询二维数据块中的时间线网格数据。在此示例中，返回的一“页”数据包含了10个频道12小时的节目数据。
2. 应用进行查询并收到从下午2:00开始前10个频道的数据。我们称之为Page-0-0。这些数据被发送到channelData。在内部，新频道和新节目被插入到数据存储中。
3. 接下来，应用查询也是从下午2:00开始的接下来10个频道，收到Page-1-0，然后将其发送到updateData，后者在内部插入新频道和新节目。
4. 用户向右滚动一点，应用收到一个onScroll事件，并确定有必要向右查询下一页。假设这一页包含了前10个频道，但开始时间是下午2点过后12小时，即凌晨2点。Page-0-1被发送到updateData，然后在内部，这些节目被附加到数据存储中的现有频道。

updateFavorite

有关updateFavorite方法的更多信息，请参阅收藏频道功能部分。

updateGridStartTime(gridStartTimeMs: number)

此函数设置开始时间，即网格上可见的最早时间。最初，开始时间设为当前时间，四舍五入到最接近的30分钟间隔。开始时间是静态的，不会自行更新。用户可以改为使用updateGridStartTime方法来设置开始时间。此函数接受以毫秒为单位表示的时间。建议使用30分钟的倍数作为输入时间（例如2:00、2:30、3:00、3:30）。运行updateGridStartTime后，EPG组件移除所有在新的开始时间之前结束的节目。新时间位于网格最左边。

用法示例

设想一下用户在下午2:00打开EPG应用的场景。用户让应用保持打开状态，直到下午5:30，则当他们在网格中浏览时，会看到大量“过期”的节目。进行调用的应用中设置了定时器，例如设为每30分钟发生一次，并且如果调用此方法，网格就会自行自动更新。

数据模型

以下是对频道和节目数据的描述，调用方必须发送这些数据才能在网格中填充内容。如前所述，虽然某些字段是必填字段，但调用方发送的额外字段会被保留。因此，如果回调使用了进行调用的应用所需的任何特定元数据，则会自动支持此元数据。

示例： 节目

复制代码 已复制到剪贴板。

interface Program {
  programId: string;
  title: string;
  startTime: number;
  endTime: number;
  shortDescription?: string;
  extras?: any;
}

示例： 频道

复制代码 已复制到剪贴板。

interface Channel {
    id: string;
    displayName: string;
    groupId: string;
    groupName: string;
    logoUrl: string;
    programs: Program[];
    extras?: any;
}

事件回调

该部分描述了调用方可订阅的EPG组件触发的事件。所需的事件处理程序为：onTileFocus和onTilePress。

onScroll: (event: EPGScrollEvent) => void;

滚动动画结束时触发事件。

示例： 有效负载

复制代码 已复制到剪贴板。

{
   "timeMs":1724131800000,
   "row":1
}

onTileFocus: (event: EPGTileFocusEvent) => void;

此事件表示用户将焦点放在给定的磁贴上。焦点在磁贴上停留250毫秒，就会触发此事件。

示例： 有效负载

复制代码 已复制到剪贴板。

EPGFocusEventPayload {
     program: Program;
     channel: Channel;
     nextProgramTitle?: string;
}

onTilePress: (event: EPGTilePressEvent) => void;

焦点在某个磁贴上时，如果按下选择按钮（中央按钮），会触发事件。

示例： 有效负载

复制代码 已复制到剪贴板。

EPGPressEventPayload {
    program: Program;
    channel: Channel
}

onMenu: (event: EPGMenuEvent) => void;

按下菜单按钮（带有3条横线的按钮）时会触发事件。

示例： 有效负载

复制代码 已复制到剪贴板。

EPGMenuEventPayload {
    program: Program;
    channel: Channel
}

onMetricEmit: (event: EPGMetricsEmitEvent) => void;

此属性表示目前为占位符的功能。在未来版本中，将发出可能与调用方相关的指标。此属性可以省略。

示例： 有效负载

复制代码 已复制到剪贴板。

EPGMetricsEmitEventPayload {
  durationMs: number;
}

自定义字体支持

EPG可以支持自定义字体，因此您可以控制EPG中的排版。有两种字体可供选择：主要字体和辅助字体。您既可以同时指定两种字体，也可以只指定一种字体。辅助字体用于时间线栏（例如日期/时间字符串），而主要字体可用于其他任何地方（主要是磁贴内部）。将字体放在应用的assets/fonts目录中。

示例： 在tileStyle属性中指定主要字体、次要字体或两者

复制代码 已复制到剪贴板。

<EPG
    ...
    tileStyle={{
        fontFamilyPrimary: 'Merriweather-Light',
        fontFamilySecondary: 'Merriweather-Bold',
    }}
/>

字体名称必须完全匹配。如果字体名称包含空格，则空格也应存在于属性字符串中。

Last updated: 2025年9月30日