鸿蒙ASCF app.json pages到tabBar配置踩坑

鸿蒙专家

在鸿蒙元服务（ASCF）开发中，app.json 是每个工程最先接触的全局配置文件。页面路由、窗口样式、底部 Tab、分包结构等都由它控制。文档里有些字段写得比较简略，实际配置时容易踩坑。本文结合实践把 app.json 的完整配置项过一遍，并整理需要注意的细节。

一、pages 与 entryPagePath：页面路由表

pages 是必填配置，第一项就是默认启动页面。路径不需要写文件后缀名，系统会自动查找对应的 .hxml 文件。例如：

2. {
3.   "pages": [
4.     "page/index/index",
5.     "page/API/pages/make-phone-call/make-phone-call",
6.     "page/API/pages/share-api/share-api"
7.   ]
8. }

复制代码

如果不想用第一项作为首页，可以通过 entryPagePath 覆盖，但注意不能带页面参数。

需要特别留意的是 pages 数组的顺序。它不只是路由表，第一项直接决定默认启动页。如果不写 entryPagePath，删掉或重排 pages 中的第一项，首页就会跟着变。笔者第一次重排页面顺序时，就把首页搞乱了。

二、window：窗口与导航栏配置

window 控制全局导航栏和窗口样式，常见配置如下：

2. {
3.   "window": {
4.     "navigationBarBackgroundColor": "#0A59F7",
5.     "navigationBarTextStyle": "white",
6.     "navigationBarTitleText": "我的元服务",
7.     "navigationStyle": "default",
8.     "backgroundColor": "#f5f5f5",
9.     "backgroundTextStyle": "dark",
10.     "enablePullDownRefresh": true,
11.     "onReachBottomDistance": 50
12.   }
13. }

复制代码

这里有几个注意点：

navigationBarTextStyle 在 API 12 时限制较多：custom 模式下可以设置 black/white，default 模式只能 black。API 13 及以上才都支持。

navigationStyle 设为 custom 会隐藏导航栏，但右上角的胶囊按钮仍然保留。同时页面顶部会多出状态栏高度的空白区域，需要自己处理，否则页面内容会被状态栏挡住。

onReachBottomDistance 的单位是 px 而不是 dp，在低分辨率设备上触底距离看起来会不一样。

三、tabBar：底部 Tab 栏配置

tabBar 用于配置底部导航，示例：

2. {
3.   "tabBar": {
4.     "color": "#999999",
5.     "selectedColor": "#0A59F7",
6.     "backgroundColor": "#ffffff",
7.     "borderStyle": "black",
8.     "position": "bottom",
9.     "custom": false,
10.     "list": [
11.       {
12.         "pagePath": "page/index/index",
13.         "text": "首页",
14.         "iconPath": "image/tab/home.png",
15.         "selectedIconPath": "image/tab/home-active.png"
16.       },
17.       {
18.         "pagePath": "page/API/index",
19.         "text": "API",
20.         "iconPath": "image/tab/api.png",
21.         "selectedIconPath": "image/tab/api-active.png"
22.       }
23.     ]
24.   }
25. }

复制代码

实际踩坑记录如下：

图标限制 40kb，图片太大不会显示。一开始没有使用工具自带的图标，自己切图结果超了，排查半天。

tabBar 页面必须在主包中，不能放在分包里。文档虽然写了，但很容易忽略。笔者分包写好后发现 tabBar 页面跳转不了，折腾了很久。

颜色支持十六进制，简写（如 #fff）其实也支持，但建议写完整六位，避免不同平台解析差异。

另外，list 中的 pagePath 必须在 pages 数组中有对应路径，否则 tabBar 页面会报错跳转不了。

四、subpackages：分包配置

分包可以把页面按功能拆分，减少首屏加载体积。示例：

2. {
3.   "subpackages": [
4.     {
5.       "resource": "packageMore",
6.       "root": "packageMore",
7.       "pages": [
8.         "more/more",
9.         "detail/detail"
10.       ]
11.     }
12.   ]
13. }

复制代码

分包后的路径写法保持不变，但编译后只会保留 pages 字段，其他字段对齐。注意 tabBar 页面不能被分到子包中。

五、resolveAlias：模块路径别名

当页面层级较深时，长长的相对路径写起来很痛苦。resolveAlias 可以给模块路径起别名：

2. {
3.   "resolveAlias": {
4.     "~/*": "/*",
5.     "~/index/*": "index/*",
6.     "@utils/*": "utils/*",
7.     "subBView/*": "subpackageB/view/*"
8.   }
9. }

复制代码

配置之后，代码里就可以这样引用：

2. // 不用再写 ../../../utils/test.js
3. const { formatDate } = require('@utils/test');

复制代码

使用 resolveAlias 有两点限制：

key 和 value 都必须以 /* 结尾，少了结尾通配符会导致匹配失败。

如果多条规则同时匹配，会选取最长的规则映射，需要注意优先级。

该能力需要 ASCF Toolkit 版本不低于 1.0.4。

六、lazyCodeLoading：代码按需注入

lazyCodeLoading 可以配置自定义组件代码按需注入，目前只支持 requiredComponents：

2. {
3.   "lazyCodeLoading": "requiredComponents"
4. }

复制代码

配置后，只有页面真正用到的组件才会被加载，有助于减少首屏体积。该配置起始版本为 1.0.13，Toolkit 需要不低于 1.0.6。

七、后台运行与隐私保护

如果元服务需要在后台运行（目前仅支持后台音乐播放 audio），可以这样声明：

2. {
3.   "requiredBackgroundModes": ["audio"]
4. }

复制代码

另外，从 2.0.1 版本开始，支持 visualEffectInBackground 配置，用于切入后台时隐藏页面内容，防止敏感信息泄露：

2. {
3.   "visualEffectInBackground": "hidden"
4. }

复制代码

该字段支持 none（不处理）和 hidden（隐藏内容）两个值。金融类元服务建议开启 hidden。

八、实际项目配置示例

下面是一个实际项目中的 app.json 配置，综合了上述常用配置项：

2. {
3.   "pages": [
4.     "page/index/index",
5.     "page/API/index",
6.     "page/API/pages/share-api/share-api",
7.     "page/API/pages/make-phone-call/make-phone-call",
8.     "page/API/pages/battery/battery",
9.     "page/API/pages/accelerometer/accelerometer",
10.     "page/API/pages/gyroscope/gyroscope"
11.   ],
12.   "window": {
13.     "navigationBarBackgroundColor": "#ffffff",
14.     "navigationBarTextStyle": "black",
15.     "navigationBarTitleText": "ASCF 演示",
16.     "backgroundColor": "#f5f5f5",
17.     "backgroundTextStyle": "dark"
18.   },
19.   "tabBar": {
20.     "color": "#999999",
21.     "selectedColor": "#0A59F7",
22.     "backgroundColor": "#ffffff",
23.     "borderStyle": "black",
24.     "list": [
25.       {
26.         "pagePath": "page/index/index",
27.         "text": "首页",
28.         "iconPath": "image/tab/home.png",
29.         "selectedIconPath": "image/tab/home-active.png"
30.       },
31.       {
32.         "pagePath": "page/API/index",
33.         "text": "API",
34.         "iconPath": "image/tab/api.png",
35.         "selectedIconPath": "image/tab/api-active.png"
36.       }
37.     ]
38.   },
39.   "resolveAlias": {
40.     "@utils/*": "utils/*",
41.     "@components/*": "components/*"
42.   }
43. }

复制代码

九、避坑清单总结

结合上述配置，最需要记住的坑有：

pages 顺序决定默认首页，重排时务必确认 entryPagePath。

tabBar 的 pagePath 必须与 pages 对应，且 tabBar 页面必须在主包。

tabBar 图标大小不能超过 40kb，否则不显示。

navigationStyle: custom 会带来状态栏遮挡问题，需要自行适配。

resolveAlias 的 key/value 必须以 /* 结尾，多规则匹配时按最长规则生效。

visualEffectInBackground 只在 2.0.1+ 生效，低版本不报错但不生效。

app.json 的配置项不算复杂，但很多错误不会直接报错，而是表现为页面显示异常，排查起来比较费时间。建议在工程初始化时就把这些字段确认好，避免后期返工。