APL Image

Imageコンポーネントは画面上にビットマップ画像を描画します。Alexaスキルで良好なユーザーエクスペリエンスを実現するための画像の選択方法については、Alexaデザインガイド–Imageを参照してください。スキルではアニメーション.gifは使用しません。.gifのアニメーションはシミュレーターには表示できますが、画面付きのAlexa搭載デバイスでは動作が異なる場合があります。

プロパティ

Imageコンポーネントには、基本コンポーネントプロパティのほかに次のプロパティがあります。列の意味を参照してください。

Image上のディメンション関連のプロパティでは、「auto」値は使用できません。「auto」を使用すると、イメージをレンダリングできない場合があります。

プロパティ	型	デフォルト	スタイル設定	動的	説明
`align`	`bottom`、`bottom-left`、`bottom-right`、`center`、`left`、`right`、`top`、`top-left`、`top-right`のいずれか	`center`	◯	◯	ボックス内での画像の配置を指定します。
`borderRadius`	負でない絶対ディメンション	0	◯	✕	画像を切り抜く円の半径です。
`filter`、`filters`	フィルターの配列	[ ]	✕	✕	画像に適用するフィルターを指定します。
`onFail`	コマンド配列	[ ]	✕	✕	ソースの読み込みに失敗したときに実行するコマンド（複数可）です。
`onLoad`	コマンド配列	[ ]	✕	✕	すべてのソースが正常に読み込まれた後に実行するコマンド（複数可）です。
`overlayColor`	色	none	◯	◯	設定すると、画像の上にテーマに合ったレイヤーが重ねて表示されます。これにより、画像上に配置したテキストを読みやすくできます。
`overlayGradient`	グラデーション	none	◯	◯	画像にオーバーレイするカラーグラデーションです。
`scale`	スケール	`best-fit`	◯	◯	バウンディングボックスに収まるように画像のサイズを調整する方法を指定します。
`source`、`sources`	URLまたはURLの配列	none	✕	◯	画像のダウンロード元のURL（複数可）です。

すべての画像に、width値とheight値を指定する必要があります。エラーを最小限に抑えるため、Imageコンポーネントの幅と高さはデフォルトで100dpになります。

Imageコンポーネントのsourceプロパティまたはsourcesプロパティは1つ以上の画像URLの配列です。Imageコンポーネントは、配列内のすべてのURLが読み込まれるまでレンダリングされません。すべてのURLが読み込まれたら、コンポーネントはfiltersプロパティで定義されたすべてのフィルターを適用します。filtersプロパティが空白か指定されていない場合、コンポーネントはsources配列の最後の画像をレンダリングします。

フィルターにより、画像配列の画像が変更、拡大、マージされます。フィルター処理の結果は1つの画像となります。フィルター処理の結果の画像は、overlayColorプロパティやoverlayGradientプロパティによってさらに変更できます。

画像フィルターの詳細については、フィルターを参照してください。

Imageがイベントのソースまたはターゲットである場合、以下の値がevent.sourceまたはevent.targetに報告されます。

{
  // Image固有の値
  "type": "Image",
  "url": URL,          // 画像のURLです。複数の画像が提供されている場合は配列を含みます。

  // 一般的なコンポーネントの値
  "bind": Map,         // コンポーネントのデータバインディングコンテキストへのアクセス
  "checked": Boolean,  // チェックの状態
  "disabled": Boolean, // 無効化の状態
  "focused": Boolean,  // フィーカス状態
  "height": Number,    // コンポーネントのdp単位の高さ（パディングを含む）
  "id": ID,            // コンポーネントのID
  "opacity": Number,   // コンポーネントの不透明度[0～1]
  "pressed": Boolean,  // 押された状態
  "uid": UID,          // ランタイムで生成されたコンポーネントの固有ID
  "width": Number      // コンポーネントのdp単位の幅（パディングを含む）
}

align

Container内の画像の位置を指定します。

名前	説明
`bottom`	最下部に水平中央揃えで配置します。
`bottom-left`	左下隅に配置します。
`bottom-right`	右下隅に配置します。
`center`	水平方向および垂直方向の中央に配置します。
`left`	左側に垂直中央揃えで配置します。
`right`	右側に垂直中央揃えで配置します。
`top`	最上部に水平中央揃えで配置します。
`top-left`	左上隅に配置します。
`top-right`	右上隅に配置します。

borderRadius

画像の角を切り抜く円の半径を指定します。borderRadiusに設定する数値を大きくすると、円形に切り抜かれます。

filter、filters

画像に適用する、1つ以上のフィルタリング操作です。フィルターを参照してください。

onFail

sourcesでリクエストされたURLのいずれかが読み込みに失敗したときに実行するコマンドです。イベントには1つのソースが含まれます。たとえばフィルダーを使用している場合など、複数のソースが読み込みに失敗した場合、1つのソースがイベントをトリガーします。

ハンドラーは1回実行されます。ハンドラーが実行されたら、コンポーネントは無効とみなされます。sourcesプロパティに新しい値を設定すると、ハンドラーを再度トリガーできます。onFailハンドラーは、新しいsources値に対して最大1回実行されます。

onFailハンドラーはコンポーネントのdisplayステータスに影響せず、displayステータスはハンドラーに影響しません。たとえば、Imageコンポーネントのdisplayプロパティがinvisibleのとき、コンポーネントはスペースを使いますが表示はされません。画像ソースが読み込みに失敗した場合でも、デバイスは画像の読み込みを試行し、onFailのコマンドを実行します。

コンポーネントのonMountハンドラーは、onFailが実行されるかどうかにかかわらず実行されます。このシナリオでは、コンポーネントを画像ソースの読み込み前後にマウントして表示することが可能なため、onMountハンドラーが実行されます。

onFailハンドラーは、次の形式のイベントを生成します。

"event": {
  "source": {
    "type": "Image",
    "handler": "Fail",
    ...                   // コンポーネントのsourceプロパティ  
  },
  "value": STRING,        // 読み込みに失敗した画像ソースのURL         
  "error": STRING,        // 失敗の理由   
  "errorCode": Number     // エラーID 
}

event.sourceの詳細についてはイベントソースを参照してください。

onFailイベントハンドラーは高速モードで実行されます。

onLoad

sourcesでリクエストされたすべてのURLが読み込まれた後に実行されるコマンドです。

sourcesプロパティに新しい値を設定すると、ハンドラーの実行を再度トリガーできます。onLoadハンドラーは、新しいsources値に対して最大1回実行されます。

onLoadハンドラーはコンポーネントのdisplayステータスに影響せず、displayステータスはハンドラーに影響しません。たとえば、Imageコンポーネントのdisplayプロパティがinvisibleのとき、コンポーネントはスペースを使いますが表示はされません。画像ソースが読み込まれた後も、デバイスは画像の読み込みを試行し、onLoadのコマンドを実行します。

コンポーネントのonMountハンドラーは、onLoadが実行されるかどうかにかかわらず実行されます。Imageコンポーネントは、画像ソースの読み込み前後にマウントして表示することが可能です。

onLoadハンドラーは、次の形式のイベントを生成します。

"event": {
    "source": {
        "type": "Image",
        "handler": "Load",
        ...                   // コンポーネントのsourceプロパティ  
    }
}

event.sourceの詳細についてはイベントソースを参照してください。

onLoadイベントハンドラーは高速モードで実行されます。

overlayColor

画像上のレイヤーの色を指定します。色は、表示する画像の透過コンポーネントを持っている必要があります。たとえば、overlayColorをrgba(white,0.3)に設定して、不透明度30%の白色で画像をオーバーレイします。

overlayColorは、画像を単一カラーでオーバーレイするフィルターの便宜上の名前です。overlayColorフィルターは、filterプロパティで定義されたフィルターの後に適用されます。

scrimは、イメージの描画領域にのみ適用され、イメージのスケール調整と位置合わせの後に残ったパディングや空白スペースには適用されません。

overlayGradient

画像上のレイヤーのグラデーションを指定します。グラデーションは、表示する画像の透過コンポーネントを持っている必要があります。overlayGradientは、グラデーション名を指定して画像にオーバーレイするフィルターと同じです。overlayGradientフィルターは、filterプロパティで定義されたフィルターとoverlayColorプロパティの後に適用されます。

グラデーションは、画像の描画領域にのみ適用され、画像のスケール調整と位置合わせの後に残ったパディングや空白スペースには適用されません。

scale

Container内での画像のサイズを調整します。

名前	説明
`none`	画像のサイズは変更されません。`align`プロパティは、バウンディングボックス内での画像の位置を設定します。バウンディングボックスからはみ出た画像は切り捨てられます。
`fill`	画像の幅がバウンディングボックスの幅に、高さがバウンディングボックスの高さに一致するように不均一にサイズを調整します。
`best-fill`	バウンディングボックスが完全に覆われるように、画像のサイズを均一に拡大または縮小します。`align`プロパティは、バウンディングボックス内でサイズ変更された画像の位置を設定します。
`best-fit`	バウンディングボックス内に画像全体が収まるように、画像のサイズを均一に拡大または縮小します。`align`プロパティは、バウンディングボックス内でサイズ変更された画像の位置を設定します。
`best-fit-down`	`best-fit`と同じように画像のサイズを調整します。ただし、縮小のみで拡大はされません。これにより、画像の表示が荒くならないようにできます。

source、sources

ダウンロードして表示する画像のURLです。

画像ソースURLには、httpではなくhttpsを使います。セキュリティ上の理由から、スキルのAPLドキュメントでhttp方式をサポートしているAlexaデバイスは多くありません。

このプロパティには、1つの文字列の代わりにURLの配列を設定できます。filtersプロパティが空の場合、コンポーネントは配列の最後の画像を表示します。filtersプロパティに1つ以上のフィルターが含まれる場合、フィルターによって配列で使用する画像（複数可）が決まります。フィルターの詳細については、フィルターを参照してください。

画像の配置、倍率、サイズの管理

画像の配置と倍率の設定は複雑です。画像には、規定の高さと幅が設定されているからです。このため、実際の画像は切り抜き、サイズを変更して、Imageコンポーネントのバウンディングボックス内に配置しなければなりません。

バウンディングボックスに合わせて画像のサイズを調整する方法は、scaleモードで制御します。

ボックス内の（サイズ調整後の）画像の配置は、alignモードで制御します。

どのような場合でも、切り抜かれるのはサイズ調整後の画像ではなく、バウンディングボックスです。

画像のサンプル

{
 "type": "Image",
 "source": "https://images.example.com/image/foo.png",
 "scale": "fill",
 "width": 300,
 "height": 300
}

この場合、画像は画面上の300×300のボックスを埋め尽くすように表示されます。