@amazon-devices/asset-resolver-lib

オープンベータ版ドキュメント：本テクニカルドキュメントは、リリース前のオープンベータ版の一部としてAmazonから提供されるものです。ここで説明されている機能は、Amazonがフィードバックを受け取り、機能の開発を繰り返す過程で変更される可能性があります。最新の機能の情報については、リリースノートを参照してください。

アプリでは、AssetResolver APIを使用することで、デバイスのロケールに一致するローカライズされた文字列リソースを取得できます。これにより、ユーザーに適切な言語でUIメッセージを表示できます。これらのアセットは、ロケール、デイ／ナイトモード、UIモードなどのさまざまなシステム修飾子に基づいて解決されます。アセットは、テキストベース、画像、RAWファイルのいずれでもかまいません。

注釈

アセット解決

AssetResolverライブラリは、デバイスのシステム修飾子に従ってアセットをランク付けすることで、シームレスなアセット解決の手段をアプリに提供します。アプリには、画像やテキストなどに使用できるファイルであるアセットを含めることができます。AssetResolverは、画像、RAWファイル、およびテキスト定義ファイルをサポートしています。

アセットはアプリのassetsディレクトリにある必要があり、以下のディレクトリ構造を使用する必要があります。

└── assets
    ├── image
    ├── raw
    └── text

テキストのローカリゼーションの場合、AssetResolverはテキストアセットファイルで文字列と数値の定義にpuff.json形式が使用されていることを想定しています。PUFF-Jファイルは、アプリで使用されるテキストリソースを定義し、AssetResolverのgetString()およびgetNumber()メソッドで使用されます。

設定修飾子

AssetResolverのメソッドは、システムの現在の設定修飾子に基づいてアセットを解決します。これらは、ロケール、UIモードなどの特定のデバイスプロパティを定義する値です。

たとえば、ロケール修飾子は、en-US、es-AR、es-SPなどの値を取ることができます。この修飾子は、どのアセットが解決されるかに直接影響します。次のアセットディレクトリ構造では、strings.puff.jsonファイルが複数のディレクトリで定義されています。ロケールごとに1つずつと、textディレクトリにデフォルトとして機能するものが1つあります。

└── assets
    ├── image
    ├── raw
    └── text
        ├── en
        │   └── strings.puff.json
        ├── en-US
        │   └── strings.puff.json
        ├── es
        │   └── strings.puff.json
        ├── es-AR
        │   └── strings.puff.json
        └── strings.puff.json

現在のシステム設定修飾子に応じて、AssetResolverは最も適切な一致に基づいてテキストを解決します。一致しない場合はデフォルトのファイルが使用されます。

注：アプリがロケール（en-GBなど）をサポートする場合、そのロケールのデフォルト修飾子（この場合はen）のサポートも定義する必要があります。デフォルトのアセットファイルを定義することをお勧めします。これにより、アセットの解決が失敗した場合でも常に一致するアセットが存在することが保証されます。

ロケールのシステム設定修飾子がes-ARの場合、AssetResolver APIを使用するときにassets/text/es-AR/strings.puff.jsonファイルが選択されます。複数のロケールに同じテキストアセットが含まれている場合は、1つのアセットファイルへのシンボリックリンクを使用してデバイスのストレージ容量を節約できます。

注：アセットを解決するための設定修飾子としてサポートされているのはロケールだけです。

アクセス制御

AssetResolverメソッドはアクセス制御されません。AssetResolverメソッドは、アプリに割り当てられたデバイスのファイルシステムのサブセット内でのみ実行されます。さらに、ほかのアプリは別のアプリのアセットを明示的に解決できないため、アプリ間での分離が保証されます。

開始の手順

package.jsonファイルのdependenciesセクションに、以下のライブラリ依存関係を追加します。

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

    "@amazon-devices/asset-resolver-lib": " ~2.0.0"

使用方法

AssetConfiguration型

特定のAPIはAssetConfigurationオブジェクトを受け取ります。このオブジェクトは、アセットの解決時にどの修飾子を使用するかを指定するために使用されます。現在は、ロケールがサポートされています。

国際化された文字列値の取得

国際化された文字列値を取得するには、getString()メソッドを使用します。このメソッドは、クエリ対象の文字列の識別子と、アセットの解決に使用する修飾子を指定する、省略可能な設定オブジェクトを受け取ります。

失敗すると、このメソッドはエラー状態を示すメッセージを含むエラーをスローします。

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

const stringResult = AssetResolver.getString('welcome-string');

console.log('文字列値：{}', stringResult.value);
console.log('書字方向：{}', stringResult.dir);

const config = { locale: 'fr-CA' };
const stringConfigResult = AssetResolver.getString('welcome-string', config);

console.log('文字列値：{}', stringConfigResult.value);
console.log('書字方向：{}', stringConfigResult.dir);

国際化された数値の取得

国際化された数値を取得するには、getNumber()メソッドを使用します。getString()と同様に、このメソッドはクエリ対象の数値の識別子である文字列を受け取ります。さらに、このメソッドは、アセットの解決に使用する修飾子を指定する、省略可能な設定オブジェクトも受け取ります。

このメソッドは、実行中に問題が発生した場合にエラーをスローします。

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

const numberResult = AssetResolver.getNumber('numeral');

console.log('数値：{}', numberResult);

const config = { locale: 'en-US' };
const numberConfigResult = AssetResolver.getNumber('numeral', config);

console.log('数値：{}', numberConfigResult);

モジュール

Last updated: 2025年10月2日