app.json
用于对小程序进行全局配置,设置页面文件的路径、窗口表现、多 tab、分包、插件等。以下是一个基本配置示例:
{ "pages": ["pages/index/index", "pages/logs/logs"], "window": { "defaulttitle": "demo" } }
完整配置项如下:
requirepolyfill
boolean
否
要求基础库注入 polyfill。
","id":"952e9d3b","rows":16,"cols":4,"hideborder":false}" id="952e9d3b">属性 | 类型 | 必填 | 描述 |
entrypagepath | string | 否 | 小程序默认启动凯发k8官方网娱乐官方首页。 |
pages | array | 是 | 设置页面路径。 |
window | object | 否 | 设置默认页面的窗口表现。 |
tabbar | object | 否 | 设置底部 tabbar 的表现。 |
subpackages | object[] | 否 | 分包结构描述。 |
preloadrule | object | 否 | 分包预加载规则。 |
plugins | object | 否 | 静态插件配置规则。 |
usedynamicplugins | boolean | 否 | 动态插件配置规则。 |
usingcomponents | object | 否 | 设置全局自定义组件声明。 |
lazycodeloading | string | 否 | 是否开启代码按需执行。 |
permission | object | 否 | 小程序接口权限相关配置。 |
behavior | object | 否 | 修改小程序运行行为的相关设置。 |
workers | array | 否 | 设置 worker 代码文件列表。 |
loadingpages | object | 否 | 设置骨架屏。 |
requirepolyfill | boolean | 否 | 要求基础库注入 polyfill。 |
指定小程序的默认启动路径(凯发k8官方网娱乐官方首页)。如果不填,将默认为 pages 列表的第一项。不支持带页面路径参数。
注意:此特性从基础库 2.7.20,ide 3.1.2 开始支持。若强依赖此特性,建议设置最低基础库版本号为 2.7.20。否则,在低版本的基础库,会因为无法识别正确的凯发k8官方网娱乐官方首页而导致渲染出 返回凯发k8官方网娱乐官方首页 图标。
app.json
中的 pages
为数组属性,数组中每一项都是字符串,用于指定小程序的页面。在小程序中新增或删除页面,都需要对 pages
数组进行修改。
pages
数组的每一项代表对应页面的路径信息,其中,第一项代表小程序的凯发k8官方网娱乐官方首页。
页面路径不需要写任何后缀,框架会自动去加载同名的 .json
、.js
、.axml
、.acss
文件。举例来说,如果开发目录为:
├── pages │ ├──index │ │ ├── index.json │ │ ├── index.js │ │ ├── index.axml │ │ └── index.acss │ ├──logs │ │ ├── logs.json │ │ ├── logs.js │ │ └── logs.axml ├── app.json ├── app.js └── app.acss
app.json
中应当如下配置:
{ "pages": ["pages/index/index", "pages/logs/logs"] }
在 app.json 中声明的自定义组件将会认为成全局自定义组件,在小程序各页面或自定义组件中可以直接使用无需额外声明。
{ "usingcomponents": { "com1": "/components/com1/index", "com2": "./components/com2/index" } }
注意:ide3.1.2 及以上开始支持。该功能声明的组件将要被所有页面和组件依赖,可能会影响性能,且会占用主包大小,建议开启 app.lazycodeloading。
window
用于设置小程序的状态栏、导航条、标题、窗口背景色等。示例代码:
{ "window": { "defaulttitle": "支付宝接口功能演示" } }
yes
, 支持 yes
/ no
-backgroundcolorhexcolor否窗口的背景色。例:白色 \"#ffffff\"。-backgroundimagecolorhexcolor否下拉露出显示背景图的底色。例:白色 \"#ffffff\"。仅安卓下有效,ios 下页面背景图底色会使用 backgroundcolor 的值-backgroundimageurlstring否下拉露出显示背景图的链接。-defaulttitlestring否页面默认标题。-enablescrollbarstring否仅支持 android,是否显示 webview
滚动条。默认 yes
,支持 yes
/ no
。-gesturebackstring否仅支持 ios,是否支持手势返回。默认 yes
,支持 yes
/ no
。-onreachbottomdistancenumber否页面上拉触底时触发时距离页面底部的距离,单位为 px
,详情可查看 。 ,目前ios
在page.json
下设置无效,只能全局设置。pullrefreshboolean否是否允许下拉刷新,默认 false
。说明:
1.下拉刷新生效的前提是 allowsbouncevertical 值为 yes。
2.window 全局配置后全局生效,但是如果单个页面配置了该参数,以页面的配置为准。-responsiveboolean否
rpx
单位是否宽度自适应 ,默认 true,当设置为 false
时,2 rpx 将恒等于 1 px,不再根据屏幕宽度进行自适应,注意,此时 750 rpx 将不再等于 100% 宽度。showtitleloadingstring否是否进入时显示导航栏的 loading。默认 no
,支持 yes
/ no
。-transparenttitlestring否导航栏透明设置。默认 none
,支持 always
一直透明 / auto
滑动自适应 / none
不透明。-titlepenetratestring否是否允许导航栏点击穿透。默认 no
,支持 yes
/ no
。-titleimagestring否导航栏图片地址。-titlebarcolorhexcolor否导航栏背景色。例:白色 \"#ffffff\"。-navigationbarfrontcolorstring否导航栏前景色。只支持配置 black
或者 white
。","id":"a1fd7e3e","rows":17,"cols":5}" id="a1fd7e3e">属性 | 类型 | 必填 | 描述 | 最低版本 |
allowsbouncevertical | string | 否 | 是否允许向下拉拽。默认 yes , 支持 yes / no | - |
backgroundcolor | hexcolor | 否 | 窗口的背景色。例:白色 "#ffffff"。 | - |
backgroundimagecolor | hexcolor | 否 | 下拉露出显示背景图的底色。例:白色 "#ffffff"。仅安卓下有效,ios 下页面背景图底色会使用 backgroundcolor 的值 | - |
backgroundimageurl | string | 否 | 下拉露出显示背景图的链接。 | - |
defaulttitle | string | 否 | 页面默认标题。 | - |
enablescrollbar | string | 否 | 仅支持 android,是否显示 webview 滚动条。默认 yes ,支持 yes / no 。 | - |
gestureback | string | 否 | 仅支持 ios,是否支持手势返回。默认 yes ,支持 yes / no 。 | - |
onreachbottomdistance | number | 否 | 页面上拉触底时触发时距离页面底部的距离,单位为 px ,详情可查看 页面事件处理函数。 | 1.19.0 ,目前ios 在page.json 下设置无效,只能全局设置。 |
pullrefresh | boolean | 否 | 是否允许下拉刷新,默认 false 。说明: 1.下拉刷新生效的前提是 allowsbouncevertical 值为 yes。 2.window 全局配置后全局生效,但是如果单个页面配置了该参数,以页面的配置为准。 | - |
responsive | boolean | 否 | rpx 单位是否宽度自适应 ,默认 true,当设置为 false 时,2 rpx 将恒等于 1 px,不再根据屏幕宽度进行自适应,注意,此时 750 rpx 将不再等于 100% 宽度。 | 1.23.0 |
showtitleloading | string | 否 | 是否进入时显示导航栏的 loading。默认 no ,支持 yes / no 。 | - |
transparenttitle | string | 否 | 导航栏透明设置。默认 none ,支持 always 一直透明 / auto 滑动自适应 / none 不透明。 | - |
titlepenetrate | string | 否 | 是否允许导航栏点击穿透。默认 no ,支持 yes / no 。 | - |
titleimage | string | 否 | 导航栏图片地址。 | - |
titlebarcolor | hexcolor | 否 | 导航栏背景色。例:白色 "#ffffff"。 | - |
navigationbarfrontcolor | string | 否 | 导航栏前景色。只支持配置 black 或者 white 。 | 支付宝客户端 10.5.30 |
如果开发的小程序是一个多 tab 应用(客户端窗口的底部栏可以切换页面),那么可以通过 tabbar
配置项指定 tab 栏的表现,以及 tab 切换时显示的对应页面。 tabbar
与 pages
、 window
配置同级,配置项如下:
属性 | 类型 | 必填 | 描述 |
textcolor | hexcolor | 否 | 文字颜色。 |
selectedcolor | hexcolor | 否 | 选中文字颜色。 |
backgroundcolor | hexcolor | 否 | 背景色。 |
items | array | 是 | 每个 tab 配置。 |
每个 item 配置:
属性 | 类型 | 必填 | 描述 |
pagepath | string | 是 | 设置页面路径。 |
name | string | 是 | 名称。 |
icon | string | 否 | 平常图标路径(非选中状态)。 |
activeicon | string | 否 | 高亮图标路径(选中状态)。 |
icon 图标推荐大小为 81px * 81px,系统会对传入的非推荐尺寸的图片进行非等比拉伸或缩放。带有 tabbar
的 app.json
示例如下:
{ "pages": ["pages/index/index", "pages/logs/logs"], "window": { "defaulttitle": "demo" }, "tabbar": { "textcolor": "#dddddd", "selectedcolor": "#49a9ee", "backgroundcolor": "#ffffff", "items": [ { "pagepath": "pages/index/index", "name": "凯发k8官方网娱乐官方首页" }, { "pagepath": "pages/logs/logs", "name": "日志" } ] } }
代码中,开发者可通过 my.settabbaritem 动态设置 tabbar
中指定 item
的内容。
各类网络请求的超时时间,单位均为毫秒。
属性 | 类型 | 必填 | 默认值 | 说明 |
request | number | 否 | 30000 | my.request 的超时时间,单位:毫秒。 |
connectsocket | number | 否 | 30000 | my.connectsocket 的超时时间,单位:毫秒。 |
uploadfile | number | 否 | 60000 | my.uploadfile 的超时时间,单位:毫秒。 |
downloadfile | number | 否 | 60000 | my.downloadfile 的超时时间,单位:毫秒。 |
启用 分包加载 时,声明项目分包结构。
声明 分包预下载 的规则。
基础库 1.22.4 及以上,支付宝客户端 10.1.85 及以上开始支持。声明小程序需要使用的 静态插件。
基础库 1.22.4 及以上,支付宝客户端 10.1.85 及以上开始支持。声明小程序需要使用 动态插件。
小程序应用的启动过程中,除了下载阶段以外,默认会执行所有代码(包括当前页面未使用到的所有页面、自定义组件),会对启动耗时有一定影响。基础库 2.7.0 及以上 ,支持配置以下 lazycodeloading 参数,仅执行当前页面所必须的页面脚本和自定义组件脚本,其他脚本则不会被执行。
{ "lazycodeloading": "requiredcomponents" }
注意: 由于开启该配置后,当前页面未使用到的代码将不会被执行,可能对某些依赖默认脚本执行先后顺序的逻辑产生影响。
使用 worker 处理多线程任务时,设置 worker 代码文件列表。如:
"workers": [ "workers/index.js" ]
小程序接口权限相关设置。字段类型为 object,结构为:
属性 | 类型 | 必填 | 描述 |
scope.album | permissionobject | 否 | 相册(访问)相关权限声明,相关 api:my.chooseimage、my.choosevideo(sourcetype 包含 album)。 |
scope.writephotosalbum | permissionobject | 否 | 相册(保存)相关权限声明,相关 api:my.saveimage、my.saveimagetophotosalbum、my.savevideotophotosalbum。 |
scope.camera | permissionobject | 否 | 相机相关权限声明,相关 api:my.chooseimage、my.choosevideo(sourcetype 包含 camera)。 |
scope.record | permissionobject | 否 | 麦克风相关权限声明,相关 api:my.getrecordermanager。 |
scope.userlocation | permissionobject | 否 | 位置相关权限声明,相关 api:my.getlocation。 |
permissionobject 结构
属性 | 类型 | 必填 | 描述 |
desc | string | 是 | 小程序获取权限时展示的接口用途说明。 |
使用示例
{ "permission": { "scope.album": { "desc": "读取照片用于提供美颜服务" }, "scope.camera" : { "desc" : "访问你的摄像头,用于扫描二维码" }, "scope.record" : { "desc" : "访问你的麦克风,用于识别歌曲" }, "scope.userlocation": { "desc": "你的位置信息将用于匹配您的服务城市" }, "scope.writephotosalbum" : { "desc" : "用于保存美颜后的照片" } } }
用于改变小程序若干运行行为。字段类型为 object,结构请见下方说明。
使用小程序默认分享功能时(即不显式设置 ),当设置此字段后,会使客户端生成的用于分享的
scheme
带上当前用户打开的页面所携带的 query 参数。基础库 及以上开始支持,同时需使用 及以上版本进行构建。decodequerystring否可选值:disable。
小程序在解析全局参数、页面参数时默认会对键/值做
encodeuricomponent
。当设置为 disable
后,则不再对键/值做encodeuricomponent
,解析规则详情可查看 ,基础库 及以上开始支持,同时需使用 及以上版本进行构建。","id":"b11608dc","rows":3,"cols":4}" id="b11608dc">属性 | 类型 | 必填 | 描述 |
shareappmessage | string | 否 | 可选值:appendquery。 使用小程序默认分享功能时(即不显式设置 page.onshareappmessage),当设置此字段后,会使客户端生成的用于分享的 scheme 带上当前用户打开的页面所携带的 query 参数。基础库 2.7.10 及以上开始支持,同时需使用 ide 2.7.0 及以上版本进行构建。 |
decodequery | string | 否 | 可选值:disable。 小程序在解析全局参数、页面参数时默认会对键/值做 encodeuricomponent 。当设置为 disable 后,则不再对键/值做encodeuricomponent ,解析规则详情可查看 小程序全局/页面参数设置以及解析细节,基础库 2.7.19 及以上开始支持,同时需使用 ide 3.0.0 及以上版本进行构建。 |
使用示例
{ "behavior": { "shareappmessage": "appendquery", // 通过此配置,可选择默认分享功能是否带上 query 参数。 "decodequery": "disable" // 设置为disable后,基础库不再对全局/页面参数的键/值做 encodeuricomponent } }
开启和声明 骨架屏 的规则。
q:a 页面(列表页)设置允许下拉刷新,b 页面(详情页)设置禁止下拉 allowsbouncevertical: no
, a 页面跳转 b 页面后再点左上角返回 a 页面,此时 a 页面无法下拉刷新。
a:a 页面设置下拉刷新的同时设置 allowsbouncevertical: yes
,即可解决该问题。
注意:设置下拉刷新的时候一定要设置允许下拉。