@amazon-devices/asset-resolver-lib

开放Beta测试文档 作为预发布开放Beta测试的一项内容，亚马逊提供了此技术文档。随着亚马逊收到反馈并对功能进行迭代，所描述的这些功能可能会发生变化。有关最新功能的信息，请参阅发布说明。

AssetResolver API允许应用检索与设备区域设置相匹配的本地化字符串资源，以便用户看到采用预期语言的用户界面消息。会根据各种系统限定符（例如区域设置、日间/夜间模式以及用户界面模式）解析这些资产。资产可以基于文本，可以是图像，也可以是原始文件。

备注

资产解析

AssetResolver库为应用提供了一种无缝资产解析手段，可以根据设备系统限定符对资产进行排序。应用可以包含资产，这些资产是可用于图像和文本等内容的文件。AssetResolver支持图像、原始文件和文本定义文件。

资产必须位于应用程序的assets目录中，并且必须遵照以下目录结构。

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

对于文本本地化，Asset Resolver需要文本资产文件使用puff.json格式来定义字符串值和数值。PUFF-J文件定义了应用程序中使用的文本资源，Asset Resolver会在其getString() 和getNumber() 方法中使用这些文件。

配置限定符

AssetResolver的方法会根据系统当前的配置限定符来进行资产解析。这些值定义了某些设备属性，例如区域设置、用户界面模式等。

例如，区域设置限定符可以采用诸如en-US、es-AR或es-SP之类的值。此限定符直接影响系统会解析哪些资产。在以下资产目录结构中，多个目录中都定义了strings.puff.json文件：每个区域设置都有一个，text中也有一个，用作默认文件。

└── 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文件。如果多个区域设置包含相同的文本资产，则可以使用指向单个资产文件的符号链接来节省设备存储空间。

注意： 解析各处的资产时，仅支持将区域设置作为配置限定符。

访问控制

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日