全局配置

小程序根目錄下的app.json文件用來對小程序進行全局配置。文件內容為一個JSON對象，有以下内容：

配置項

内容	類型	必填	描述
entryPagePath	string	否	小程序默認啟動首頁
pages	string[]	是	頁面路徑清單
window	Object	否	全域的默認視窗表現
tabBar	Object	否	全域的默認視窗表現
debug	Object	否	底部tab欄的表現
subpackages	Object	否	是否開啟debug模式，默認關閉
workers	Object	否	分包結構配置
navigateToMiniProgramAppIdList	Object	否	Worker代碼放置的目錄
preloadRule	Object	否	需要跳轉的小程序清單，詳見 Cwx.navigateToMiniProgram
usingComponents	Object	否	全域自定義組件配置
permission	Object	否	小程序接口許可權相關設定
darkmode	Object	否	小程序支持DarkMode
themeLocation	Object	否	指明 theme.json 的位置，darkmode為true為必填
disableSlideCloseGesture	Object	否	是否禁用側滑關閉小程序的手勢，默認為false。

entryPagePath

指定小程序的默認啟動路徑（首頁），如果不填，將默認為pages清單的第一項。不支持帶頁面路徑參數。

{
  "entryPagePath": "pages/index/index"
}

pages

用於指定小程序由哪些頁面組成，每一項都對應一個頁面的路徑（含檔名）資訊。檔名不需要寫文件尾碼，框架會自動去尋找對應位置的.json，. js，.wxml，.wxss四個文件進行處理。

未指定entryPagePath時，數組的第一項代表小程序的初始頁面（首頁）。

小程序中新增/减少頁面，都需要對pages數組進行修改

如開發目錄為：

├── app.js
├── app.json
├── app.wxss
├── pages
│   │── index
│   │   ├── index.wxml
│   │   ├── index.js
│   │   ├── index.json
│   │   └── index.wxss
│   └── logs
│       ├── logs.wxml
│       └── logs.js
└── utils

則需要在app.json中寫：

{
  "pages": ["pages/index/index", "pages/logs/logs"]
}

window

用於設定小程序的狀態列、導航條、標題、視窗背景色。

内容

類型

預設值

描述

navigationBarBackgroundColor

HexColor

#000000

導航欄背景顏色，如#000000

navigationBarTextStyle

string

white

導航欄標題、狀態列顏色，僅支持： black / white

navigationBarTitleText

string

導航欄標題文字內容

navigationStyle

string

default

導航欄樣式，僅支持以下值：

default默認樣式
custom自定義導航欄，只保留右上角膠囊按鈕
hide自定義導航欄，可以支持隱私導航欄和膠囊按鈕。參見表格後緊接的注2

backgroundColor

HexColor

#ffffff

視窗的背景色

backgroundTextStyle

string

#dark

下拉loading的樣式，僅支持dark / light

backgroundColorTop

string

#dark

頂部視窗的背景色，僅iOS支持

backgroundColorBottom

string

#dark

頂部視窗的背景色，僅iOS支持

enablePullDownRefresh

boolean

false

是否開啟全域的下拉刷新

詳見 Page.onPullDownRefresh

onReachBottomDistance

number

頁面上拉觸底事件觸發時距頁面底部距離，單位為px

詳見 Page.onReachBottom

customNavigateBack

Boolean

false

是否需要攔截頁面的默認返回（按一下tabBar返回或側滑或back鍵返回）結合Page.onCustomBack使用

pageOrientation

string

portrait

荧幕旋轉設定，支持auto / portrait / landscape

詳見響應顯示區域變化

注1:HexColor（十六進位顏色值），如'#ff00ff'

注2：關於navigationStyle

navigationStyle只在app.json中生效。
navigationStyle: custom對 web-view 組件無效

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，詳情請參見自定義tabBar

其中list接受一個數組，只能配置最少2個、最多5個tab，tab按數組的順序排序，每個項都是一個對象，其屬性值如下：

内容	類型	必填	說明
pagePath	string	是	頁面路徑，必須在pages中先定義
text	string	是	tab上按鈕文字
iconPath	string	否	圖片路徑，icon大小限制為40kb，建議尺寸為81px * 81px，不支持網絡圖片
selectedIconPath	string	否	當position為top時，不顯示icon

debug

可以在開發者工具中開啟debug模式，在開發者工具的控制台面板，調試資訊以info的形式給出，其資訊有Page的注册，頁面路由，數據更新，事件觸發等。可以幫助開發者快速定位一些常見的問題。

subpackages

啟用分包加載時，聲明項目分包結構。

TIP

寫成subPackages也支持。

workers

使用 worker 處理多執行緒任務時，設定Worker代碼放置的目錄。

navigateToMiniProgramAppIdList

當小程序需要使用 navigateToMiniProgram 接口跳轉到其他小程序時，需要先在設定檔中聲明需要跳轉的小程序appId清單，最多允許填寫10個。

preloadRule

聲明分包預下載的規則。

usingComponents

在app.json中聲明的usingComponents欄位視為全域自定義組件，在小程序內的頁面或自定義組件中可以直接使用而無需再聲明。

TIP

全域自定義組件會視為被所有頁面依賴，會在所有頁面啟動時進行初始化，影響啟動效能且會佔用主包大小，只被個別頁面或分包引用的自定義組件應儘量在頁面配置中聲明。

permission

小程序接口許可權相關設定，欄位類型為Object，結構為：

内容	類型	必填	說明	描述
scope.userLocation	PermissionObject	否	-	位置相關許可權聲明

PermissionObject結構

内容	類型	必填	說明	描述
desc	string	是	-	小程序獲取許可權時展示的接口中文用途說明，最長80個字元
desc-en	string	是	-	小程序獲取許可權時展示的接口英文用途說明，最長80個字元
desc-adesc-ar	string	是	-	小程序獲取許可權時展示的接口阿語用途說明，最長80個字元

如：

{
  "pages": ["pages/index/index"],
  "permission": {
    "scope.userLocation": {
      "desc": "Your location information will be used to display the effects of the Mini Program location interface." // Continuous Background Positioning for Freeway Driving
    }
  }
}

scope清單

scope	對應接口	描述
scope.userinfo	wx.getUserInfo	用戶資訊
scope.userLocation	wx.getLocation	獲取地理位置資訊。
scope.userFuzzyLocation	wx.getFuzzyLocation	獲取模糊地理位置資訊。
scope.record	live-pusher or wx.startRecord	直播或者錄音
scope.camera	camera	相機組件
scope.addPhoneCalendar	wx.addPhoneCalendar	添加日誌
scope.writePhotosAlbum	wx.saveImageToPhotosAlbum	保存圖片到相册
scope.bluetooth	wx.openBluetoothAdapter	藍牙

darkmode

可通過配置'darkmode'：true表示當前小程序可適配DarkMode，所有基礎組件均會根據系統主題展示不同的默認樣式，navigation bar和tab bar也會根據開發者的配置自動切換。

配置後，請根據 DarkMode適配指南自行完成基礎樣式以外的適配工作。

{
  "darkmode": true
}

themeLocation

自定義 theme.json 的路徑，當配置'darkmode'：true時，當前設定檔為必填項。

disableSlideCloseGesture

小程序根目录下的app.json文件用来对小程序进行全局配置

apiVersion

用於 API（例如： wx.login 版本控制，未配置時預設調用最新版本。

{
  "apiVersion": "v1"
}

配置示例：

{
  "pages": ["pages/index/index", "pages/logs/index"],
  "window": {
    "navigationBarTitleText": "Demo"
  },
  "tabBar": {
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "index"
      },
      {
        "pagePath": "pages/logs/logs",
        "text": "logs"
      }
    ]
  },
  "debug": true
}

了解小程序

配置小程序

小程序框架

基礎能力

小程序配置

框架接口

wxml語法參考

wxs語法參考

界面

網絡

畫布

媒體

設備

遊戲引擎

運行時

基礎能力

渲染

設備

全局配置

配置項

entryPagePath

pages

window

tabBar

debug

subpackages

workers

navigateToMiniProgramAppIdList

preloadRule

usingComponents

permission

PermissionObject結構

scope清單

darkmode

themeLocation

disableSlideCloseGesture

apiVersion

配置示例：

全局配置 ​

配置項 ​

entryPagePath ​

pages ​

window ​

tabBar ​

debug ​

subpackages ​

workers ​

navigateToMiniProgramAppIdList ​

preloadRule ​

usingComponents ​

permission ​

PermissionObject結構 ​

scope清單 ​

darkmode ​

themeLocation ​

disableSlideCloseGesture ​

apiVersion ​

配置示例： ​

全局配置

配置項

entryPagePath

pages

window

tabBar

debug

subpackages

workers

navigateToMiniProgramAppIdList

preloadRule

usingComponents

permission

PermissionObject結構

scope清單

darkmode

themeLocation

disableSlideCloseGesture

apiVersion

配置示例：