简介
restool是应用资源编译工具，会解析应用资源文件生成资源索引文件和资源二进制文件等产物，生成的产物由打包工具打包到应用包中，在应用运行阶段开发者可以通过资源管理接口获取应用包中的资源。
restool工具存放在SDK安装目录下的toolchains文件夹中。
[h2]restool支持的命令选项
| 选项 | 是否可缺省 | 是否存在入参 | 描述 |
|---|---|---|---|
| -i/--inputPath | 不可缺省 | 带参数 | 指定需要构建的资源目录或者资源中间件。 在资源目录中支持指定一个编译好的HAP/HSP资源目录（解压态），在此HAP/HSP的基础上完成叠加编译。 具体可参考如下编译资源命令。 |
| -j/--json | 不可缺省 | 带参数 | 指定config.json或者module.json文件路径。 |
| -o/--outputPath | 不可缺省 | 带参数 | 指定已编译资源的输出路径。 |
| -p/--packageName | 不可缺省 | 带参数 | 指定编译资源的bundle名称。 |
| -r/--resHeader | 不可缺省 | 带参数 | 指定资源的头文件生成路径，文件内容为资源名称与资源ID的映射表，支持4种格式：“.txt”、“.js”、“.h”、“.ts”。 说明： - “.txt”、“.js”、“.h”格式的文件包含-i指定的所有资源目录下的资源映射表。 - 从API version 23开始，支持“.ts”格式，文件内容仅包含-i指定的HAR编译产物的资源目录下的资源映射表。 |
| -e/--startId | 可缺省 | 带参数 | 指定生成资源的起始ID值，例如：0x01000000，范围[0x01000000, 0x06FFFFFF) 或 [0x08000000, 0xFFFFFFFF)。 |
| -f/--forceWrite | 可缺省 | 不带参数 | 如果输出路径已经存在，强制删除，重新生成。 |
| -h/--help | 可缺省 | 不带参数 | 查看工具帮助信息。 |
| -m/--modules | 可缺省 | 带参数 | 多模块联合编译时，指定多个模块名。用“,”连接。 |
| -x/--append | 可缺省 | 带参数 | 指定生成中间文件的资源目录或单个资源路径。同一个命令可以多次指定。 |
| -z/--combine | 可缺省 | 不带参数 | 针对资源中间文件目录，生成编译结果。 |
| -l/--fileList | 可缺省 | 带参数 | 指定命令选项的集合json文件，例如：resConfig.json。详细格式请查看下方-l/--fileList参数说明。 |
| -v/--version | 可缺省 | 不带参数 | 查看工具版本号。 |
| --ids | 可缺省 | 带参数 | 指定生成id_defined.json的输出目录。 |
| --defined-ids | 可缺省 | 带参数 | 指定id_defined.json文件路径，一般都是通过--ids生成。 id_defined.json包含资源类型、名称及其ID的列表。 开发者可以自定义id_defined.json中的资源ID。 |
| --dependEntry | 可缺省 | 带参数 | FA模型下单独编译feature时，指定entry模块的编译结果目录。 |
| --icon-check | 可缺省 | 不带参数 | 开启icon和startWindowIcon的PNG图片校验功能。 |
| --compressed-config | 可缺省 | 带参数 | 指定需要进行纹理压缩的json配置文件。例如：opt-compression.json，json配置文件的详细格式请查看下方--compressed-config参数说明。 |
| --thread | 可缺省 | 带参数 | 指定资源编译时开启的子线程数量。 说明： 从API version 18开始，支持该选项。 |
| --target-config | 可缺省 | 带参数 | 与“-i”命令同时使用，支持选择编译。 具体可参考如下target-config参数说明。 |
| --ignored-file | 可缺省 | 带参数 | 指定资源文件和资源目录的忽略规则，格式为正则表达式，多个规则之间以“:”分隔。文件、目录的名称与正则表达式匹配的会被忽略。 例如：“\.git:\.svn”可以忽略所有名称为“.git”、“.svn”的文件和目录。 说明： 从API version 19开始，支持该选项。 |
| --ignored-path | 可缺省 | 带参数 | 指定资源文件和资源目录的忽略规则，格式为正则表达式，多个规则之间以“:”分隔。文件、目录的名称或路径与正则表达式匹配的会被忽略。 例如：“.+/rawfile/\.git:\.svn”中第一个正则包含指定路径“.+/rawfile/”，可以忽略rawfile目录下的“.git”文件和目录，不会忽略其他目录下的“.git”文件和目录；第二个规则不包含任何指定路径，可以忽略所有名称为“.svn”的文件和目录。 说明： 从API version 23开始，支持该选项。 |
target-config参数说明
支持参数配置类型：MccMnc、Locale、Orientation、Device、ColorMode、Density。
参数格式说明：配置之间用“;”分割，配置中的值用“[]”封装，并使用“,”分割。
MccMnc匹配规则：Mcc（国家码）必须相同；Mnc（网络码）不存在时默认匹配，否则Mnc须相同才匹配。
Locale匹配规则：Locale匹配需满足以下三条规则。
-
语言须相同。
-
脚本（文字）不存在时默认匹配，否则必须相同。
-
国家或地区不存在时默认匹配，否则必须相同。
参数举例说明：Locale[zh_CN,en_US];Device[phone]，该参数过滤其他语言，保留能匹配上zh_CN和en_US的语言；过滤其他设备，保留phone；其他参数（如MccMnc、Orientation等）配置不过滤均保留。
-l/--fileList参数说明
用于指定命令选项集合的json文件，json文件包含的字段与命令选项的对应关系如下。
| 字段名称 | 类型 | 命令选项 | 描述 |
|---|---|---|---|
| configPath | string | -j/--json | 请参考-j/--json的说明。 |
| packageName | string | -p/--packageName | 请参考-p/--packageName的说明。 |
| output | string | -o/--outputPath | 请参考-o/--outputPath的说明。 |
| startId | string | -e/--startId | 请参考-e/--startId的说明。 |
| moduleNames | string | -m/--modules | 请参考-o/--outputPath的说明。 |
| ResourceTable | string[] | -r/--resHeader | 可以包含多个路径，相当于多次指定-r/--resHeader。 |
| applicationResource | string | -i/--inputPath | 指定AppScope的资源目录。 |
| moduleResources | string[] | -i/--inputPath | 指定当前模块的资源目录，可以包含多个目录，相当于多次指定-i/--inputPath。 |
| dependencies | string[] | -i/--inputPath | 指定依赖模块的资源目录，可以包含多个目录，相当于多次指定-i/--inputPath。 |
| entryCompiledResource | string | --dependEntry | 请参考--dependEntry的说明。 |
| iconCheck | boolean | --icon-check | 是否启用icon和startWindowIcon的PNG图片校验功能。 - true：启用。 - false（缺省默认值）：不启用。 |
| ids | string | --ids | 请参考--ids的说明。 |
| definedIds | string | --defined-ids | 请参考--defined-ids的说明。 |
| compression | string | --compressed-config | 请参考--compressed-config的说明。 |
| thread | integer | --thread | 请参考--thread的说明。 |
| ignoreResourcePattern | string[] | --ignored-file | 请参考--ignored-file的说明。 |
| ignoreResourcePathPattern | string[] | --ignored-path | 请参考--ignored-path的说明。 |
| qualifiersConfig | object | --target-config | 指定选择编译的参数配置，格式为json，支持的字段与--target-config的配置类型一致，字段类型为字符串数组，表示一个配置类型下可以配置多个值。举例说明：{"Locale":["zh_CN","en_US"], "Device":["phone"]}等同于--target-config的配置Locale[zh_CN,en_US];Device[phone]。 说明： 从API version 23开始，支持该字段。 |
--compressed-config参数说明
在DevEco Studio配置纹理压缩的编译配置参数，编译后会在模块的build\default\intermediates\res\default下生成restool的纹理压缩配置文件opt-compression.json，文件结构如下：
{
"context": {
// 纹理压缩库的绝对路径
"extensionPath": "xxx\\xxx\\libimage_transcoder_shared.dll"
},
"compression": {
// 是否对预置media图片资源启用纹理压缩。true：启用，false：不启用。
"media": {
"enable": true
},
// filters是预置media图片资源的过滤配置参数
"filters": [
{
// 纹理压缩的方式，type为转换类型，支持"astc"、"sut"
// block为转换扩展参数，决定画质和压缩率，当前仅支持"4x4"
"method": {
"blocks": "4x4",
"type": "astc"
},
// 需要压缩的media图片资源文件绝对路径
"path": [
"xxx\\MyApplication\\entry\\src\\main\\resources\\base\\media\\startIcon.png",
"xxx\\MyApplication\\entry\\src\\main\\resources\\base\\media\\icon.png",
],
// 需要过滤的media图片资源文件绝对路径
"exclude_path": [],
// 按大小和分辨率匹配path中的图片资源文件路径，符合条件的文件将被压缩
"rules_origin": {
// 二维数组，数组中每个元素表示一个大小范围，单位为字节
"size": [
[
0,
10485760
]
],
// 二维数组，数组中每个元素表示一个分辨率范围，如下表示分辨率从0x0到1024x1024
"resolution": [
[
{
"height": 0,
"width": 0
},
{
"height": 1024,
"width": 1024
}
]
]
},
// 按大小和分辨率匹配exclude_path中的图片资源文件，符合条件的文件将被过滤
"rules_exclude": {
"size": [
[
0,
1048576
]
],
"resolution": [
[
{
"height": 0,
"width": 0
},
{
"height": 64,
"width": 64
}
]
]
}
}
]
}
} [h2]restool支持的子命令
| 命令 | 描述 |
|---|---|
| dump | 以json的格式输出HAP包中resource的内容。 |
dump命令
restool dump [-h] [config] filePath
dump命令参数列表：
| 参数 | 是否可缺省 | 是否存在入参 | 描述 |
|---|---|---|---|
| -h | 可缺省 | 不带参数 | 帮助信息。 |
| config | 可缺省 | 不带参数 | 只打印HAP包中资源的限定词信息。 |
示例：
# 打印HAP包中所有的资源信息 restool dump entry.hap # 打印HAP包中资源的限定词信息 restool dump config entry.hap
使用实例
例如，entry目录结构如下：
entry/src/main | |----resource | | |----base | | | |----element | | | |----media | | | |----profile | | |----rawfile | | |----resfile | |----config.json/module.json
[h2]编译资源
编译资源的方式有三种，分别是全量资源编译、增量资源编译和叠加资源编译。其中增量编译仅预览模式可用，用于预览开发阶段的组件效果；全量编译用于构建工程的资源文件；叠加编译支持将工程中的资源叠加进已有的HAP模板资源中，复用已编译的资源项。
-
全量资源编译，命令如下：
restool -i entry/src/main -j entry/src/main/module.json -p com.ohos.demo -o out -r out/ResourceTable.txt -f
-
增量资源编译，具体步骤如下：
步骤一：生成资源中间件，命令如下:
restool -x entry/src/main/resource -o out
步骤二：编译资源中间件，命令如下:
restool -i out1 -i out2 -o out -p com.ohos.demo -r out/ResourceTable.txt -j entry/src/main/module.json -f -z
-
叠加资源编译，命令如下：
# hapResource为解压后的HAP包路径 restool -i entry/src/main -i hapResource -j entry/src/main/module.json -p com.ohos.demo -o out -r out/ResourceTable.txt -f
[h2]固定资源ID
固定资源ID，具体步骤如下：
步骤一：创建id_defined.json文件。创建方式有两种，分别是通过命令行和自定义。
- 方式一：通过命令行生成此文件，命令如下：
restool -i entry/src/main -j entry/src/main/module.json -p com.ohos.demo -o out -r out/ResourceTable.txt --ids out -f
- 方式二：自定义文件，文件名必须是id_defined.json，文件内容如下：
{
"record" :
[
{
"id" : "0x01000000", // 资源需要固定的ID值
"name" : "app_name", // 资源名称
"type" : "string" // 资源类型
}
]
} 步骤二：完成资源ID固定。完成固定的方式有两种，通过命令一完成固定或者将自定义的id_defined.json放在resource/base/element/目录下后通过命令二完成固定。
- 命令一：
restool -i entry/src/main -j entry/src/main/module.json -p com.ohos.demo -o out1 -r out1/ResourceTable.txt --defined-ids out/id_defined.json -f
- 命令二：
restool -i entry/src/main -j entry/src/main/module.json -p com.ohos.demo -o out1 -r out1/ResourceTable.txt -f
[h2]11201001 加载依赖库失败
错误信息
Failed to load the library 'xxx.dll'.
错误描述
加载依赖库失败。
可能原因
- 依赖库路径错误或路径无访问权限。
- 三方依赖库未安装，或路径错误，或路径无访问权限。
- 出现Windows系统报错，由于在用户环境变量和系统环境变量中，排在xxx.dll路径之前的路径文件无法被访问，导致加载依赖库时搜索环境变量错误。
处理步骤
- 检查依赖库路径是否准确且有访问权限。
- 按照错误信息提示安装缺失的三方依赖库，并保证三方依赖库路径准确且有访问权限。
- 将SDK下的xxx/HarmonyOS/previewer/common/bin路径及依赖库所在路径添加至环境变量Path的前两行，两者先后顺序无限制。
[h2]11203001 JSON文件打开失败
错误信息
Failed to open the JSON file 'xxx.json'.
错误描述
JSON文件打开失败。
可能原因
JSON文件路径错误，或无访问权限。
处理步骤
检查JSON文件路径是否准确且有访问权限。
[h2]11203002 JSON文件解析失败
错误信息
Failed to parse the JSON file: incorrect format.
错误描述
JSON文件格式错误，解析失败。
可能原因
JSON文件格式错误，如包含多余的逗号等。
处理步骤
检查JSON文件格式，可参考JSON。
[h2]11203003 JSON节点的类型与预期不匹配
错误信息
The value type of node 'xxx' does not match. Expected type: xxx.
错误描述
JSON中xxx节点的类型错误。
可能原因
JSON中对应节点的类型错误，如预期类型是string，实际类型为number。
处理步骤
检查JSON中xxx节点的类型。
[h2]11203004 JSON中缺少必需节点
错误信息
The required node 'xxx' is missing.
错误描述
JSON中缺少必需的xxx节点。
可能原因
JSON中没有配置对应的必需节点，如name、value等。
处理步骤
检查JSON中是否缺少xxx节点。
[h2]11203005 JSON中存在空object或空数组
错误信息
The array or object node 'xxx' cannot be empty.
错误描述
JSON中xxx节点为空object或空数组。
可能原因
JSON中对应节点为空，如object配置为{}，或数组配置为[]。
处理步骤
检查JSON中xxx节点是否为空。
[h2]11203006 JSON中包含多个子节点
错误信息
The node 'xxx' in the JSON file can have only one member.
错误描述
JSON中xxx节点仅能包含一个子节点。
可能原因
JSON中对应节点包含了多个子节点。
处理步骤
检查xxx节点是否仅包含一个子节点。
[h2]11203007 无效的JSON节点名称
错误信息
Invalid node name 'xxx'. Valid values: ["boolean","color","float","id","intarray","integer","pattern","plural","strarray","string","symbol","theme"].
错误描述
无效的JSON节点名称xxx。
可能原因
JSON中对应节点的名称错误，不在指定的名称["boolean","color","float","id","intarray","integer","pattern","plural","strarray","string","symbol","theme"]范围内。
处理步骤
检查JSON中xxx节点的名称是否在指定的范围内。
[h2]11204001 创建文件失败
错误信息
Failed to create the directory or file 'xxx'.
错误描述
创建文件失败。
可能原因
文件路径错误，或无访问权限。
处理步骤
- 检查文件路径是否准确。
- 检查文件权限。若文件权限为只读，修改文件权限为可读可写。具体操作如下：
- Windows：选中文件，点击鼠标右键，选择属性，取消勾选"只读"属性。
- Linux/MacOS：执行chmod命令"chmod 644 文件路径"。
若报错的文件路径为编译产物build目录下的路径，需先手动删除报错的文件，再修改其对应的源文件的权限。如报错路径为"entry\build\default\intermediates\res\default\resources\base\profile\form_config.json"，则修改对应的源文件"entry\src\main\resources\base\profile\form_config.json"的权限。
[h2]11204003 删除文件失败
错误信息
Failed to delete the directory or file 'xxx'.
错误描述
删除文件失败。
可能原因
文件路径错误，或无访问权限。
处理步骤
- 检查文件路径是否准确。
- 检查文件权限。若文件权限为只读，修改文件权限为可读可写。具体操作如下：
- Windows：选中文件，点击鼠标右键，选择属性，取消勾选"只读"属性。
- Linux/MacOS：执行chmod命令"chmod 644 文件路径"。
若报错的文件路径为编译产物build目录下的路径，需先手动删除报错的文件，再修改其对应的源文件的权限。如报错路径为"entry\build\default\intermediates\res\default\resources\base\profile\form_config.json"，则修改对应的源文件"entry\src\main\resources\base\profile\form_config.json"的权限。
[h2]11204004 拷贝文件失败
错误信息
Failed to copy the file from 'xxx' to 'xxx'.
错误描述
拷贝文件失败。
可能原因
文件路径错误，或无访问权限。
处理步骤
- 检查文件路径是否准确。
- 检查文件权限。若文件权限为只读，修改文件权限为可读可写。具体操作如下：
- Windows：选中文件，点击鼠标右键，选择属性，取消勾选"只读"属性。
- Linux/MacOS：执行chmod命令"chmod 644 文件路径"。
若报错的文件路径为编译产物build目录下的路径，需先手动删除报错的文件，再修改其对应的源文件的权限。如报错路径为"entry\build\default\intermediates\res\default\resources\base\profile\form_config.json"，则修改对应的源文件"entry\src\main\resources\base\profile\form_config.json"的权限。
[h2]11204005 打开文件失败
错误信息
Failed to open the file 'xxx'.
错误描述
打开文件失败。
可能原因
文件路径错误，或无访问权限。
处理步骤
- 检查文件路径是否准确。
- 检查文件权限。若文件权限为只读，修改文件权限为可读可写。具体操作如下：
- Windows：选中文件，点击鼠标右键，选择属性，取消勾选"只读"属性。
- Linux/MacOS：执行chmod命令"chmod 644 文件路径"。
若报错的文件路径为编译产物build目录下的路径，需先手动删除报错的文件，再修改其对应的源文件的权限。如报错路径为"entry\build\default\intermediates\res\default\resources\base\profile\form_config.json"，则修改对应的源文件"entry\src\main\resources\base\profile\form_config.json"的权限。
[h2]11204006 读取文件失败
错误信息
Failed to read the file 'xxx'.
错误描述
读取文件失败。
可能原因
- 文件路径错误，或无访问权限。
- 文件内容为空。
处理步骤
- 检查文件路径是否准确且有访问权限。
- 检查文件内容是否为空。
[h2]11210001 未知命令选项
错误信息
Unknown option 'xxx'.
错误描述
未知命令选项。
可能原因
不支持对应命令选项。
处理步骤
检查命令是否准确，可使用-h查看命令帮助信息，输入正确的命令选项和参数。
[h2]11210002 选项缺少必需参数
错误信息
Option 'xxx' requires an argument.
错误描述
选项缺少必需的参数。
可能原因
选项缺少必需的参数，如-i/--inputPath没有指定输入路径。
处理步骤
检查命令是否准确，可使用-h查看命令帮助信息，输入正确的命令选项和参数。
[h2]11210003 无效参数
错误信息
Invalid argument value 'xxx'.
错误描述
无效的参数。
可能原因
命令选项均需带有前缀短划线-，选项对应的参数无短划线，若输入选项时遗漏了短划线，该选项将被当作参数处理，无法生效，如输入restool inputPath。
处理步骤
检查命令是否准确，可使用-h查看命令帮助信息，输入正确的命令选项和参数。
[h2]11210004 无效的输入路径
错误信息
Invalid input path 'xxx'.
错误描述
无效的输入路径。
可能原因
-i/--inputPath选项指定的路径参数错误，或无访问权限。
处理步骤
检查路径参数是否准确且有访问权限。
[h2]11210005 重复的输入路径
错误信息
Duplicated input path 'xxx'.
错误描述
重复的输入路径。
可能原因
多个-i/--inputPath选项指定了相同的输入路径。
处理步骤
检查-i/--inputPath选项指定的路径是否重复。
[h2]11210006 包名存在冲突
错误信息
The package names 'xxx' and 'xxx' conflict.
错误描述
包名存在冲突。
可能原因
多次指定了-p/--packageName选项。
处理步骤
检查是否多次指定-p/--packageName选项。
[h2]11210007 无效的输出路径
错误信息
Invalid output path 'xxx'.
错误描述
无效的输出路径。
可能原因
-o/--outputPath指定的输出路径不存在，或无访问权限。
处理步骤
检查路径参数是否准确且有访问权限。
[h2]11210008 输出路径存在冲突
错误信息
The output paths 'xxx' and 'xxx' conflict.
错误描述
输出路径存在冲突。
可能原因
多次指定了-o/--outputPath选项。
处理步骤
检查是否多次指定-o/--outputPath选项。
[h2]11210009 重复的资源头文件路径
错误信息
Duplicated resource header path 'xxx'.
错误描述
重复的资源头文件路径。
可能原因
多个-r/--resHeader选项指定了相同的资源头文件路径。
处理步骤
检查-r/--resHeader选项指定的资源头文件路径是否重复。
[h2]11210010 模块名称存在冲突
错误信息
The module names 'xxx' and 'xxx' conflict.
错误描述
模块名称存在冲突。
可能原因
多次指定了-m/--modules选项。
处理步骤
检查是否多次指定-m/--modules选项。
[h2]11210011 重复的模块名称
错误信息
Duplicated module name 'xxx'.
错误描述
重复的模块名称。
可能原因
-m/--modules选项指定了重复的模块名称，如-m entry,entry。
处理步骤
检查-m/--modules选项指定的模块名称是否重复。
[h2]11210012 应用配置文件存在冲突
错误信息
The paths 'xxx' and 'xxx' of the module.json (in the stage model) or config.json (in the FA model) file conflict.
错误描述
应用配置文件module.json（Stage模型）或config.json（FA模型）的路径存在冲突。
可能原因
多次指定了-j/--json选项。
处理步骤
检查是否多次指定-j/--json选项。
[h2]11210013 无效的资源起始id
错误信息
Invalid start ID 'xxx'. It is out of range.
错误描述
无效的资源起始id。
可能原因
通过-e/--startId指定的资源起始id不在指定范围内。
处理步骤
检查资源起始id是否在[0x01000000, 0x06FFFFFF) 或 [0x08000000, 0xFFFFFFFF)的范围内。
[h2]11210014 重复的增量资源文件路径
错误信息
Duplicated append path 'xxx'.
错误描述
重复的增量资源文件路径。
可能原因
多个-x/--append选项指定了相同的增量资源文件路径。
处理步骤
检查-x/--append指定的增量资源文件路径是否重复。
[h2]11210015 target-config存在冲突
错误信息
The target configurations 'xxx' and 'xxx' conflict.
错误描述
多个target-config选项指定的参数存在冲突。
可能原因
多次指定了--target-config选项。
处理步骤
检查是否多次指定--target-config选项。
[h2]11210016 无效的target-config
错误信息
Invalid target configuration argument 'xxx'. The argument format for option --target-config should be like 'Locale[zh_CN,en_US];Device[phone]'.
错误描述
无效的target-config参数。
可能原因
--target-config选项指定的参数格式错误。
处理步骤
检查--target-config选项对应参数格式是否准确，如：Locale[zh_CN,en_US];Device[phone]，具体格式信息可以参考restool支持的命令选项中关于target-config的说明。
[h2]11210017 无效的系统资源id_defined.json路径
错误信息
Invalid system id_defined.json path 'xxx'.
错误描述
无效的系统资源id_defined.json路径。
可能原因
通过--defined-sysids指定的系统资源的id_defined.json路径错误或无访问权限。
处理步骤
检查系统资源的id_defined.json路径是否准确且有访问权限。
[h2]11210018 重复的系统资源id_defined.json路径
错误信息
Duplicated system id_defined.json path 'xxx'.
错误描述
--defined-sysids选项指定的文件路径重复。
可能原因
多个--defined-sysids选项指定了相同的系统资源id_defined.json路径。
处理步骤
检查--defined-sysids选项指定的系统资源id_defined.json文件路径是否重复。
[h2]11210019 compressed-config存在冲突
错误信息
The compression JSON paths 'xxx' and 'xxx' conflict.
错误描述
多个--compressed-config选项指定的参数存在冲突。
可能原因
多次指定了--compressed-config选项。
处理步骤
检查是否多次指定--compressed-config选项。
[h2]11210020 参数非ASCII值
错误信息
The argument value 'xxx' is not an ASCII value.
错误描述
参数非ASCII值。
可能原因
输入、输出路径等参数中存在中文或其他非ASCII字符。
处理步骤
检查参数中是否存在中文或者其他非ASCII字符。
[h2]11210021 选项之间存在互斥
错误信息
Options 'xxx' and 'xxx' cannot be used together.
错误描述
不能同时指定两个互斥的选项。
可能原因
同时指定了两个互斥的选项，如-x和--target-config。
处理步骤
检查命令是否准确，避免指定互斥的选项，可以使用-h查看命令帮助信息，输入正确的命令选项和参数。
[h2]11210022 包名为空
错误信息
The package name is empty. It should be specified with option -p/--packageName.
错误描述
包名为空。
可能原因
未指定-p/--packageName选项。
处理步骤
检查是否通过-p/--packageName选项指定包名。
[h2]11210023 资源头文件路径为空
错误信息
The resource header path (for example, ./ResourceTable.js, ./ResourceTable.h) is empty. It should be specified with option -r/--resHeader.
错误描述
资源头文件的路径为空。
可能原因
未通过-r/--resHeader选项指定资源头文件路径。
处理步骤
检查是否通过-r/--resHeader选项指定资源头文件路径。
[h2]11210024 dump命令缺少HAP包路径
错误信息
The HAP path of the resource dump command is missing.
错误描述
dump命令缺少HAP包路径。
可能原因
dump命令未指定HAP包路径。
处理步骤
检查dump命令是否指定HAP包路径，如：restool dump xxx/entry.hap。
[h2]11210025 dump命令指定的HAP包路径无效
错误信息
Invalid HAP path 'xxx' in the resource dump command.
错误描述
dump命令指定HAP包路径无效。
可能原因
dump命令指定的HAP包路径错误或无访问权限。
处理步骤
检查dump命令指定的HAP包路径是否准确且有访问权限。
[h2]11210026 无效的子线程数量
错误信息
Invalid thread count 'xxx'. It should be an integer greater than 0.
错误描述
无效的子线程数量。
可能原因
--thread选项指定的子线程数量为负数或小数。
处理步骤
检查--thread选项的参数是否为大于0的整数。
[h2]11211001 输出路径已存在
错误信息
The output path exists. Specify option -f/--forceWrite to overwrite.
错误描述
输出路径已存在。
可能原因
通过-o/--outputPath指定的输出路径下已存在文件，无法直接覆盖。
处理步骤
检查输出路径下是否已有文件，可手动删除或指定-f/--forceWrite选项强制覆盖。
[h2]11211002 缺少模块配置文件路径
错误信息
There are multiple input paths, but the path of the module.json (in the stage model) or config.json (in the FA model) file is not specified with option -j/--json.
错误描述
缺少应用配置文件module.json（Stage模型）或config.json（FA模型）的路径。
可能原因
当通过-i/--inputPath仅指定了单个输入路径时，restool默认从输入路径的父目录读取应用配置文件；当指定了多个输入路径时，如restool -i xxx\AppScope -i xxx\entry\main，需要通过-j/--json明确指定应用配置文件的路径。
处理步骤
检查是否通过-j/--json明确指定应用配置文件路径。
[h2]11211003 无效的模块类型
错误信息
Invalid module type 'xxx'. Valid values: ["entry", "har", "shared", "feature"].
错误描述
无效的模块类型。
可能原因
应用配置文件module.json（Stage模型）或config.json（FA模型）中指定的模块类型错误，取值不在["entry", "har", "shared", "feature"]范围内。
处理步骤
检查模块类型是否在指定的范围内。
[h2]11211004 资源起始id与id_defined.json存在冲突
错误信息
The start ID 'xxx' specified by option -e/--startId conflict with the IDs in the id_defined.json file.
错误描述
通过-e/--startId指定的资源起始id与id_defined.json文件存在冲突。
可能原因
默认情况下，资源起始id为0x01000000，编译时资源id依次递增，同时restool提供了两种方式自定义资源id：
- 选项-e/--startId：可以在[0x01000000, 0x06FFFFFF) 或 [0x08000000, 0xFFFFFFFF)的范围内指定资源起始id。
- 固定资源ID：通过id_defined.json文件指定资源id。
若同时使用两种方式，可能导致同一个资源在两种方式下计算得到的资源id值不一致，存在冲突。
处理步骤
检查是否同时使用上述两种方式自定义资源id。
[h2]11211007 id_defined.json中的资源类型无效
错误信息
Invalid resource type 'xxx' in the id_defined.json file. Valid values: ["boolean","color","float","id","intarray","integer","pattern","plural","strarray","string","symbol","theme"].
错误描述
id_defined.json中的资源类型无效。
可能原因
id_defined.json中资源类型type的取值不在["boolean","color","float","id","intarray","integer","pattern","plural","strarray","string","symbol","theme"]范围内。
处理步骤
检查资源类型是否在指定范围内。
[h2]11211008 id_defined.json中的资源id无效
错误信息
Invalid ID value 'xxx' in the id_defined.json file. It should be a hexadecimal string, match the pattern ^0[xX][0-9a-fA-F]{8}, and be in the scope [0x01000000,0x06FFFFFF] or [0x08000000,0xFFFFFFFF].
错误描述
id_defined.json中资源id无效。
可能原因
- id_defined.json中资源id非十六进制数。
- id取值不在[0x01000000,0x06FFFFFF] 或 [0x08000000,0xFFFFFFFF]的范围内。
处理步骤
检查资源id是否为十六进制格式且取值在[0x01000000,0x06FFFFFF] 或 [0x08000000,0xFFFFFFFF]范围内。
[h2]11211012 id_defined.json定义了重复的id
错误信息
The names 'xxx' and 'xxx' in the id_defined.json file define the same ID.
错误描述
id_defined.json中两个资源定义了同一个资源id值。
可能原因
id_defined.json中两个资源定义了同一个资源id值。
处理步骤
检查id_defined.json中的资源id是否唯一且取值在[0x01000000,0x06FFFFFF] 或 [0x08000000,0xFFFFFFFF]范围内。
[h2]11211014 错误的模块名称
错误信息
The module name 'xxx' is not found in ["yyy","zzz"], which is specified by -m/--modules.
错误描述
应用配置文件中的模块名称不在-m/--modules指定的模块名称列表内。
可能原因
- -m/--modules指定的模块名称列表错误。
- 应用配置文件module.json（Stage模型）或config.json（FA模型）中name指定的模块名称错误。
处理步骤
检查-m/--modules指定的模块名称列表中是否包含应用配置文件中name指定的模块名称。
[h2]11211101 无效的资源文件
错误信息
Failed to scan resources: invalid path 'xxx'.
错误描述
扫描资源失败，无效的资源文件。
可能原因
资源文件不符合要求，比如：
- rawfile应该是一个文件夹，实际是文件。
- base/element下应该都是JSON文件，实际存在文件夹。
处理步骤
检查资源文件的类型是否正确，可参考资源分类与访问-资源分类中关于各类资源文件的说明。
[h2]11211103 无效的限定词目录
错误信息
Invalid qualifier key 'xxx'. It should match the pattern of the qualifiers directory, for example zh_CN or en_US.
错误描述
无效的限定词目录。
可能原因
限定词目录名称错误。
处理步骤
检查限定词目录名称是否准确，限定词目录命名规则可参考资源分类与访问-限定词目录。
[h2]11211104 无效的资源组目录
错误信息
Invalid resource directory name 'xxx'. Valid values: ["element","media","profile"].
错误描述
无效的资源组目录名称。
可能原因
限定词目录下的资源组目录名称错误，不在["element","media","profile"]范围内。
处理步骤
检查限定词目录下是否仅包含资源组目录：element，media和profile。
[h2]11211106 无效的翻译状态
错误信息
Invalid translation priority value 'xxx'. Valid values: ["code","translate","LT","customer"].
错误描述
无效的翻译状态。
可能原因
字符串或单复数资源的可翻译属性attr下的翻译状态属性priority配置错误，不在["code","translate","LT","customer"]范围内。
处理步骤
检查翻译状态priority的值是否准确，可参考资源可翻译特性中关于priority的说明。
[h2]11211107 不支持的element资源类型
错误信息
Unsupported element resource type 'xxx'. Valid values: ["integer","string","strarray","intarray","boolean","color","theme","plural","float","pattern","symbol"].
错误描述
不支持的element资源类型。
可能原因
element目录下json资源文件支持的资源类型为["integer","string","strarray","intarray","boolean","color","theme","plural","float","pattern","symbol"]，不支持"id"。
处理步骤
检查element资源的类型是否准确，可参考资源组目录中关于element资源的说明。
[h2]11211108 无效的颜色值
错误信息
Invalid color value 'xxx' of the resource 'xxx'. It can only reference '$color:xxx' or be '#rgb', '#argb', '#rrggbb', or '#aarrggbb'.
错误描述
无效的颜色值。
可能原因
color资源只支持以下两种格式：
- 引用其他color资源，如$color:xxx引用应用自身color资源，或$ohos:color:xxx引用系统color资源。
- 以#开头的rgb颜色值格式，如#rgb,#argb,#rrggbb,#aarrggbb。
处理步骤
检查color资源是否为正确的引用格式或rgb格式。
[h2]11211109 无效的资源引用
错误信息
Invalid resource reference $xxx:xxx. Supported reference: $(ohos:)?xxx:xxx.
错误描述
无效的资源引用。
可能原因
资源引用只适用于同类型资源之间，如string.json中的字符串资源可以用$string:xxx引用应用自身的字符串资源，或使用$ohos:string:xxx引用系统字符串资源，但不能通过$integer:xxx引用整数资源。
处理步骤
检查资源引用方式是否正确。
[h2]11211110 theme资源的parent为空
错误信息
The parent value of resource 'xxx' is empty. It should be a valid resource name.
错误描述
theme资源的parent值为空。
可能原因
theme资源的parent属性是可选的，其值需配置为其他theme资源的名称，不能是空字符串。如下正确示例：
{
"theme": [
{
"name": "base",
"value": [
{
"name": "width",
"value": "wrap_content"
},
{
"name": "height",
"value": "wrap_content"
},
{
"name": "size",
"value": "25dp"
}
]
},
{
"name": "child",
"parent": "base",
"value": [
{
"name": "noTitle",
"value": "yes"
}
]
}
]
} 其中声明了两个theme资源base和child，base不包含parent属性，child的parent配置为"base"。
处理步骤
检查theme资源的parent是否为空，如无需parent属性，可以将其移除。
[h2]11211111 数组类型的资源超长
错误信息
The array resource 'xxx' is too large. The total length of the value of the array elements cannot exceed 65535.
错误描述
数组类型的资源超长。
可能原因
单个数组类型资源总长度超过了65535个字节。
处理步骤
检查数组类型资源是否超长，可以将其拆分为多个数组资源。
[h2]11211112 无效的单复数资源类别
错误信息
Invalid quantity 'xxx' of the plural resource 'xxx'. Valid values: ["zero","one","two","few","many","other"].
错误描述
无效的单复数资源类别。
可能原因
单复数资源的类别属性quantity配置错误，不在["zero","one","two","few","many","other"]范围内。
处理步骤
检查单复数的类别是否准确，可参考支持单复数中关于单复数类别的说明。
[h2]11211113 单复数资源的类别重复
错误信息
Duplicated quantity 'xxx' of the plural resource 'xxx'.
错误描述
单复数资源的类别重复。
可能原因
单复数资源中重复声明了相同的类别，如下错误示例中eat_apple重复声明了类别one：
{
"plural": [
{
"name": "eat_apple",
"value": [
{
"quantity": "one",
"value": "%d apple"
},
{
"quantity": "one",
"value": "%d apple"
},
{
"quantity": "other",
"value": "%d apples"
}
]
}
]
} 处理步骤
检查单复数资源声明的类别是否重复，可参考支持单复数中关于单复数类别的说明。
[h2]11211114 单复数资源缺少other类别
错误信息
The plural resource 'xxx' should contain the 'other' quantity.
错误描述
单复数资源应该包含other类别。
可能原因
单复数资源缺少other类别的声明。
处理步骤
检查单复数资源是否包含other类别的声明，可参考支持单复数中关于单复数类别的说明。
[h2]11211115 无效的symbol资源
错误信息
Invalid value 'xxx' of the symbol resource 'xxx'. It should be in the scope [0xF0000,0xFFFFF] or [0x100000,0x10FFFF].
错误描述
无效的symbol资源值。
可能原因
symbol资源的值不在[0xF0000,0xFFFFF] 或 [0x100000,0x10FFFF]范围内。
处理步骤
检查symbol资源的值是否在指定范围内。
[h2]11211116 无效的资源名称
错误信息
Invalid resource name 'xxx'. It should match the pattern [a-zA-Z0-9_].
错误描述
无效的资源名称。
可能原因
资源名称需要与规则[a-zA-Z0-9_]匹配，只能包含大小写字母、数字和下划线。
处理步骤
检查资源名称与规则[a-zA-Z0-9_]是否匹配。
[h2]11211117 资源重复定义
错误信息
Resource 'xxx' conflict. It is first declared at 'xxx' and declared again at 'xxx'.
错误描述
资源重复定义。
可能原因
在多处定义了同类型同名的资源，存在冲突。
处理步骤
检查资源是否重复定义，可以修改资源名称或删除重复资源。
[h2]11211118 资源id超过最大值
错误信息
The resource ID 'xxx' exceeds the maximum ID 'xxx'.
错误描述
资源id超过最大值。
可能原因
应用资源id的范围为[0x01000000,0x06FFFFFF] 或 [0x08000000,0xFFFFFFFF]，资源过多，或指定了较大的资源起始id，可能导致id溢出超过最大值0x06FFFFFF 或 0xFFFFFFFF。
处理步骤
- 删除无用资源。
- 指定较小的资源起始id。
[h2]11211120 引用的资源未定义
错误信息
The resource reference '$xxx:xxx' is not defined.
错误描述
引用的资源未定义。
可能原因
- 引用的资源不存在，如资源已被删除或重命名。
- 引用的资源所在的目录未通过-i/--inputPath指定为输入路径。
处理步骤
- 检查报错的资源是否存在。
- 检查资源所在的resources的父目录是否通过-i/--inputPath指定为输入路径，如报错信息中的资源定义在xxx/entry/src/main/resources/base/element/string.json中，则需指定xxx/entry/src/main为输入路径。