:wxref:`全局配置 ` =========================================== 更新: |today| 小程序根目录下的 :file:`app.json` 文件用来对微信小程序进行全局配置。文件内容为一个 JSON 对象，有以下属性： 配置项 +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | 属性 | 类型 | 必填 | 描述 | 最低版本 | +================================+==========+======+=====================================================+======================+ | pages | string[] | 是 | 页面路径列表 | | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | window | Object | 否 | 全局的默认窗口表现 | | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | tabBar | Object | 否 | 底部 tab 栏的表现 | | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | networkTimeout | Object | 否 | 网络超时时间 | | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | debug | boolean | 否 | 是否开启 debug 模式，默认关闭 | | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | functionalPages | boolean | 否 | 是否启用插件功能页，默认关闭 | 2.1.0 | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | subpackages | Object[] | 否 | 分包结构配置 | 1.7.3 | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | workers | string | 否 | Worker 代码放置的目录 | 1.9.90 | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | requiredBackgroundModes | string[] | 否 | 需要在后台使用的能力，如「音乐播放」 | | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | plugins | Object | 否 | 使用到的插件 | 1.9.6 | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | preloadRule | Object | 否 | 分包预下载规则 | 2.3.0 | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | resizable | boolean | 否 | iPad 小程序是否支持屏幕旋转，默认关闭 | 2.3.0 | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | navigateToMiniProgramAppIdList | string[] | 否 | 需要跳转的小程序列表，详见 wx.navigateToMiniProgram | 2.4.0 | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | usingComponents | Object | 否 | 全局自定义组件配置 | 开发者工具 1.02.1810 | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ | permission | Object | 否 | 小程序接口权限相关设置 | 微信客户端 7.0.0 | +--------------------------------+----------+------+-----------------------------------------------------+----------------------+ pages --------------------------------------------------- .. envvar:: pages 用于指定小程序由哪些页面组成，每一项都对应一个页面的 路径（含文件名） 信息。 文件名不需要写文件后缀，框架会自动去寻找对于位置的 ``.json`` , ``.js`` , ``.wxml`` , ``.wxss`` 四个文件进行处理。 1. 数组的 **第一项** 代表小程序的 **初始页面（首页）**。 2. 小程序中 **新增/减少** 页面，都需要对 ``pages`` 数组进行 **修改** 。 如开发目录为:: ├── app.js ├── app.json ├── app.wxss ├── pages │ │── index │ │ ├── index.wxml │ │ ├── index.js │ │ ├── index.json │ │ └── index.wxss │ └── logs │ ├── logs.wxml │ └── logs.js └── utils 则需要在 :file:`app.json` 中写 .. code:: json { "pages": ["pages/index/index", "pages/logs/logs"] } window --------------------------------------------------- .. json:object:: window :showexample: 用于设置小程序的状态栏、导航条、标题、窗口背景色。 :property navigationBarBackgroundColor: 导航栏背景颜色 [1]_，如 #000000 :proptype navigationBarBackgroundColor: HexColor :options navigationBarBackgroundColor: #000000 :property navigationBarTextStyle: 导航栏标题颜色，仅支持 black/white :proptype navigationBarTextStyle: string :options navigationBarTextStyle: white :property string navigationBarTitleText: 导航栏标题文字内容 :property navigationStyle: 导航栏样式，仅支持以下值： default 默认样式 custom 自定义导航栏，只保留右上角胶囊按钮 [2]_ 。 微信客户端 6.6.0 :proptype navigationStyle: string :options navigationStyle: default :property backgroundColor: 窗口的背景色 [1]_ :proptype backgroundColor: HexColor :options backgroundColor: #ffffff :property backgroundTextStyle: 下拉 loading 的样式，仅支持 dark / light :proptype backgroundTextStyle: string :options backgroundTextStyle: dark :property backgroundColorTop: 顶部窗口的背景色，仅 iOS 支持 微信客户端 6.5.16 :proptype backgroundColorTop: string :options backgroundColorTop: #ffffff :property backgroundColorBottom: 底部窗口的背景色，仅 iOS 支持 微信客户端 6.5.16 :proptype backgroundColorBottom: string :options backgroundColorBottom: #ffffff :property enablePullDownRefresh: 是否开启全局的下拉刷新。详见 Page.onPullDownRefresh :proptype enablePullDownRefresh: boolean :options enablePullDownRefresh: false :property onReachBottomDistance: 页面上拉触底事件触发时距页面底部距离，单位为px。详见 Page.onReachBottom :proptype onReachBottomDistance: int :options onReachBottomDistance: 50 :property pageOrientation: 屏幕旋转设置，支持 auto/portrait/landscape 详见 响应显示区域变化 2.4.0 (auto) / 2.5.0 (landscape) :proptype pageOrientation: string :options pageOrientation: portrait :示例: .. code:: json { "window": { "navigationBarBackgroundColor": "#ffffff", "navigationBarTextStyle": "black", "navigationBarTitleText": "微信接口功能演示", "backgroundColor": "#eeeeee", "backgroundTextStyle": "light" } } .. :json:object:`window` .. [1] HexColor（十六进制颜色值），如"#ff00ff" .. [2] 关于navigationStyle - 客户端 7.0.0 以下版本，navigationStyle 只在 app.json 中生效。 - 客户端 6.7.2 版本开始，navigationStyle: custom 对 组件无效 - 开启 custom 后，低版本客户端需要做好兼容。开发者工具基础库版本切到 1.7.0（不代表最低版本，只供调试用）可方便切到旧视觉 tabBar --------------------------------------------------- .. envvar:: tabBar 如果小程序是一个多 tab 应用（客户端窗口的底部或顶部有 tab 栏可以切换页面）， 可以通过 tabBar 配置项指定 tab 栏的表现，以及 tab 切换时显示的对应页面。 +-----------------+----------+------+--------+------------------------------------------------------+ | 属性 | 类型 | 必填 | 默认值 | 描述 | +=================+==========+======+========+======================================================+ | color | HexColor | 是 | | tab 上的文字默认颜色，仅支持十六进制颜色 | +-----------------+----------+------+--------+------------------------------------------------------+ | selectedColor | HexColor | 是 | | tab 上的文字选中时的颜色，仅支持十六进制颜色 | +-----------------+----------+------+--------+------------------------------------------------------+ | backgroundColor | HexColor | 是 | | tab 的背景色，仅支持十六进制颜色 | +-----------------+----------+------+--------+------------------------------------------------------+ | borderStyle | string | 否 | black | tabbar上边框的颜色， 仅支持 black / white | +-----------------+----------+------+--------+------------------------------------------------------+ | list | Array | 是 | | tab 的列表，详见 list 属性说明，最少2个、最多5个 tab | +-----------------+----------+------+--------+------------------------------------------------------+ | position | string | 否 | bottom | tabBar的位置，仅支持 bottom / top | +-----------------+----------+------+--------+------------------------------------------------------+ | custom | boolean | 否 | false | 自定义 tabBar，见详情 2.5.0 | +-----------------+----------+------+--------+------------------------------------------------------+ 其中 list 接受一个数组，只能配置最少 2 个、最多 5 个 tab。tab 按数组的顺序排序，每个项都是一个对象，其属性值如下： +------------------+--------+------+---------------------------------------------------------------------------------+ | 属性 | 类型 | 必填 | 说明 | +==================+========+======+=================================================================================+ | pagePath | string | 是 | 页面路径，必须在 pages 中先定义 | +------------------+--------+------+---------------------------------------------------------------------------------+ | text | string | 是 | tab 上按钮文字 | +------------------+--------+------+---------------------------------------------------------------------------------+ | iconPath | string | 否 | 图片路径，icon 大小限制为40kb，建议尺寸为 81px * 81px，不支持网络图片。 | +------------------+--------+------+---------------------------------------------------------------------------------+ | | | | 当 postion 为 top 时，不显示 icon。 | +------------------+--------+------+---------------------------------------------------------------------------------+ | selectedIconPath | string | 否 | 选中时的图片路径，icon 大小限制为40kb，建议尺寸为 81px * 81px，不支持网络图片。 | +------------------+--------+------+---------------------------------------------------------------------------------+ | | | | 当 postion 为 top 时，不显示 icon。 | +------------------+--------+------+---------------------------------------------------------------------------------+ networkTimeout --------------------------------------------------- .. envvar:: networkTimeout 各类网络请求的超时时间，单位均为毫秒。 +---------------+--------+------+--------+-------------------------------------------+ | 属性 | 类型 | 必填 | 默认值 | 说明 | +===============+========+======+========+===========================================+ | request | number | 否 | 60000 | wx.request 的超时时间，单位：毫秒。 | +---------------+--------+------+--------+-------------------------------------------+ | connectSocket | number | 否 | 60000 | wx.connectSocket 的超时时间，单位：毫秒。 | +---------------+--------+------+--------+-------------------------------------------+ | uploadFile | number | 否 | 60000 | wx.uploadFile 的超时时间，单位：毫秒。 | +---------------+--------+------+--------+-------------------------------------------+ | downloadFile | number | 否 | 60000 | wx.downloadFile 的超时时间，单位：毫秒。 | +---------------+--------+------+--------+-------------------------------------------+ debug --------------------------------------------------- .. envvar:: debug 可以在开发者工具中开启 debug 模式，在开发者工具的控制台面板， 调试信息以 info 的形式给出，其信息有Page的注册，页面路由，数据更新，事件触发等。 可以帮助开发者快速定位一些常见的问题。 functionalPages --------------------------------------------------- .. envvar:: functionalPages .. versionadded:: 2.1.0 低版本需做 :ref:`compatibility` 。 插件所有者小程序需要设置这一项来启用插件功能页。 subpackages --------------------------------------------------- .. envvar:: subpackages 微信客户端 6.6.0 ， .. versionadded:: 1.7.3 及以上版本支持 启用分包加载时，声明项目分包结构。 写成 subPackages 也支持。 workers --------------------------------------------------- .. envvar:: workers .. versionadded:: 1.9.90 低版本需做 :ref:`compatibility` 。 使用 Worker 处理多线程任务时，设置 Worker 代码放置的目录 requiredBackgroundModes --------------------------------------------------- .. envvar:: requiredBackgroundModes 微信客户端 6.7.2 及以上版本支持 申明需要后台运行的能力，类型为数组。目前支持以下项目： audio: 后台音乐播放 如： .. code:: { "pages": ["pages/index/index"], "requiredBackgroundModes": ["audio"] } 注：在此处申明了后台运行的接口，开发版和体验版上可以直接生效，正式版还需通过审核。 plugins --------------------------------------------------- .. envvar:: plugins .. versionadded:: 1.9.6 低版本需做 :ref:`compatibility` 。 声明小程序需要使用的插件。 preloadRule --------------------------------------------------- .. envvar:: preloadRule .. versionadded:: 2.3.0 低版本需做 :ref:`compatibility` 。 声明分包预下载的规则。 resizable --------------------------------------------------- .. envvar:: resizable .. versionadded:: 2.3.0 低版本需做 :ref:`compatibility` 。 在 iPad 上运行的小程序可以设置支持屏幕旋转。 navigateToMiniProgramAppIdList --------------------------------------------------- .. envvar:: navigateToMiniProgramAppIdList .. versionadded:: 2.4.0 低版本需做 :ref:`compatibility` 。 当小程序需要使用 wx.navigateToMiniProgram 接口跳转到其他小程序时， 需要先在配置文件中声明需要跳转的小程序 appId 列表，最多允许填写 10 个。 usingComponents --------------------------------------------------- .. envvar:: usingComponents 开发者工具 1.02.1810190 及以上版本支持 在此处声明的自定义组件视为全局自定义组件，在小程序内的页面或自定义组件中可以直接使用而无需再声明。 permission --------------------------------------------------- .. envvar:: permission 微信客户端 7.0.0 及以上版本支持 小程序接口权限相关设置。字段类型为 Object，结构为： +--------------------+------------------+------+--------+------------------+ | 属性 | 类型 | 必填 | 默认值 | 描述 | +====================+==================+======+========+==================+ | scope.userLocation | PermissionObject | 否 | | 位置相关权限声明 | +--------------------+------------------+------+--------+------------------+ PermissionObject 结构 +------+--------+------+--------+--------------------------------------------------+ | 属性 | 类型 | 必填 | 默认值 | 说明 | +======+========+======+========+==================================================+ | desc | string | 是 | | 小程序获取权限时展示的接口用途说明。最长30个字符 | +------+--------+------+--------+--------------------------------------------------+ 如： .. code:: json { "pages": ["pages/index/index"], "permission": { "scope.userLocation": { "desc": "你的位置信息将用于小程序位置接口的效果展示" } } } 配置示例 --------------------------------------------------- .. code:: json { "pages": ["pages/index/index", "pages/logs/index"], "window": { "navigationBarTitleText": "Demo" }, "tabBar": { "list": [ { "pagePath": "pages/index/index", "text": "首页" }, { "pagePath": "pages/logs/logs", "text": "日志" } ] }, "networkTimeout": { "request": 10000, "downloadFile": 10000 }, "debug": true, "navigateToMiniProgramAppIdList": ["wxe5f52902cf4de896"] } .. todo:: |today| 研究输出json格式