リソース(APL for Audio)



リソース(APL for Audio)

リソースとは、データバインディングと値の解決によりアクセスできる名前付きエンティティのことです。APL for Audioドキュメント内でリソースブロックを定義します。environmentプロパティ内の値に基づいて、条件付きリソースを作成できます。

リソースブロック

APLドキュメントは、読み込みの際にリソースを評価します。ドキュメントがコンポーネントのインフレートを開始した後は、リソースが静的となり、変更できなくなります。

以下は、fixedVolumeという数値の変数に、ユーザーのデバイスが画面付きかキャラクターディスプレイかに応じた値を設定するリソース定義の例です。

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

{
  "resources": [
    {
      "number": {
        "fixedVolume": 0.5
      },
      "boolean": {
        "isHeadless": "${!environment.aplVersion && !environment.apltVersion}"
      }
    },
    {
      "when": "${@isHeadless}",
      "number": {
        "fixedVolume": 1.0
      }
    }
  ]
}

例には、2つのリソースブロックがあります。1つ目のブロックはfixedVolumeにデフォルト値(0.5)を設定し、isHeadlessにユーザーのデバイスが画面付きかどうかを表すブール値を設定します。デバイスが画面付きかキャラクターディスプレイの場合、isHeadless変数はfalseになります。デバイスが一切ディスプレイのないスピーカーの場合はtrueになります。

isHeadlesstrueの場合、2つ目のブロックは再度fixedVolumeを設定します。このブロックの結果は、元のfixedVolume値を上書きします。

ドキュメントでリソースを使用するには、@構文を使用します。以下は、fixedVolumeリソースを使用するVolumeを持つ、Audioコンポーネントの例です。

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

{
    "type": "Audio",
    "source": "https://amazon.com/rainforestSoundEffect.mp3"
    "filter": [
        {
            "type": "Volume",
            "amount": "@fixedVolume"
        }
    ],
}

画面もキャラクターディスプレイもないデバイスでは、上の例はVolumeフィルターのamount1.0を設定します。画面かキャラクターディスプレイを持つデバイスでは、上の例はVolumeフィルターのamountプロパティに0.5を設定します。

リソースのプロパティ

APLドキュメントのresourcesプロパティでリソースを定義します。resourcesプロパティはリソースブロックの配列を受け取ります。各ブロックは、任意のwhen句と型のセットを持つオブジェクトです。

以下の表は、リソースブロックのプロパティを示しています。

プロパティ 必須 説明
booleanbooleans ブール値のマップ ブール値の名前をブール値にマッピングします。
description 文字列 リソースのブロックの説明です。
numbernumbers 数値のマップ 名前を数値にマッピングします。
stringstrings 文字列の配列 名前を文字列にマッピングします。
when ブール値 trueの場合、このリソースブロックの定義を使用します。デフォルトはtrueです。

リソースブロックは配列順で処理されます。後のブロックで定義されたリソースが、前に定義された同じ名前のリソースを上書きします。

リソースブロック内では、プロパティは次の順序で評価されます。

  • when
  • boolean
  • booleans
  • number
  • numbers
  • string
  • strings

リソースの定義内で、前のブロックで定義されたリソースを参照するには、@name構文を使用します。

boolean、booleans

ブール型リソースは、trueまたはfalseの値です。ブール型以外をブール型リソースに割り当てると、「truthy」ルールにより変換されます。ルールの詳細については、Truthyと強制を参照してください。

"boolean": {
  "bool1": true,       // true
  "bool2": 23.4,       // true
  "bool3": "hello!",   // true
  "bool4": false,      // false
  "bool5": 0,          // false
  "bool6": ""          // false
}

number、numbers

数値のリソースは、倍精度浮動小数点数値として格納されます。

数値以外の値が数値に変換される方法については、数値の強制を参照してください。

"numbers": {
  "myNum1": null,       // 0
  "myNum2": false,      // 0
  "myNum3": true,       // 1
  "myNum4": 150         // 150 
  "myNum5": 0.5         // 0.5
}

string、strings

文字列値は文字列として格納されます。ほかの型が文字列に変換される方法については、文字列の強制を参照してください。

"strings": {
   "string1": null,          // ""
   "string2": "",            // ""
   "string3": false,         // "false"
   "string4": 23             // "23"
}