EPG

EPG（電子番組表）は、VUICライブラリに含まれているカスタムビューコンポーネントです。EPGコンポーネントでは、TVデバイスのリモコンを使用したD-Padコントロールがサポートされます。このガイドでは、ダウンロード可能なサンプルアプリを紹介し、EPGの使用方法の詳細について説明します。

EPGサンプルアプリ

EPGサンプルアプリはVega SDKを使用して構築されています。このサンプルアプリを使用すると、EPGコンポーネントを実装できます。

package.jsonファイルの更新

EPGコンポーネントはVUICライブラリから利用できます。package.jsonのdependenciesセクションに、次のようにVUICが指定されていることを確認してください。

コードをコピー クリップボードにコピーしました。

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

SemVer式の^は、3.0.0より前の任意の新しいバージョンを自動的に取得できることを示します。

VUICの使用方法の詳細については、Vega UIコンポーネントライブラリを使用した開発の開始を参照してください。

EPGコンポーネントの使用方法とプロパティ

以下のコード例は、EPGの使用方法を示しています。EPGコンポーネントには、updateDataメソッドを使用して、チャンネルと番組のデータを提供する必要もあります。

コードをコピー クリップボードにコピーしました。

<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);

お気に入り機能を使用するには、次の例に示すように、少なくともお気に入りの「オン」アイコン画像をプロパティで指定する必要があります。

例： お気に入りアイコン画像の追加

コードをコピー クリップボードにコピーしました。

<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という2つのオプションのサブオブジェクトが含まれます。
  • startTimeMs（任意）：照会するページの開始時刻を定義するために使用される数値。endTimeMsと共に使用する必要があります。ページ情報で開始時刻と終了時刻が提供される場合、番組情報がない部分はすべて「Unavailable」と表示されます。
  • endTimeMs（任意）：クエリされたページの終了時間を定義するために使用される数値。startTimeMsと共に使用する必要があります。ページ情報で開始時刻と終了時刻が提供される場合、番組情報がない部分はすべて「Unavailable」と表示されます。

updateDataメソッド

パラメーター

• channelData：各要素が異なるチャンネルのデータである配列。各オブジェクトには、チャンネルの識別子（ID）と番組データの配列に関する情報が必要です。このデータ構造の詳細については、データモデルを参照してください。
• page（任意）：チャンネルデータには直接含まれないページ関連情報をEPGに通知するために使用されるブール値。pageには、startTimeMsとendTimeMsという2つのオプションのサブオブジェクトが含まれています。
  • 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時に開いたとします。

1. アプリは、2次元ブロックのタイムライングリッドデータを照会します。この例では、返されるデータの「ページ」は、10チャンネルの12時間分の番組データです。
2. アプリは、午後2時からの最初の10チャンネルのデータを照会して受信します。これをPage-0-0と呼びます。このデータはchannelDataに送信されます。内部で、新しいチャンネルと番組がデータストアに挿入されます。
3. 次にアプリは、同じく午後2時からの次の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時に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内のタイポグラフィを制御できます。フォントにはプライマリとセカンダリの2つの種類があり、両方を指定することも、1つだけ指定することもできます。セカンダリフォントはタイムラインバー（日付／時刻の文字列など）で使用され、プライマリフォントはその他の場所（主にタイル内）で使用されます。フォントは、アプリのassets/fontsディレクトリに配置します。

例： tileStyleプロパティでのプライマリとセカンダリのいずれかまたは両方の指定

コードをコピー クリップボードにコピーしました。

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

フォント名は正確に一致する必要があります。フォント名にスペースが含まれている場合は、プロパティ文字列にもスペースを含める必要があります。

Last updated: 2025年9月30日