小程序開發全局配合屬性

全局配置

小程序根目錄下的 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.1810190
permission	Object	否	小程序接口權限相關設置	微信客戶端 7.0.0
sitemapLocation	string	是	指明 sitemap.json 的位置
style	string	否	指定使用升級後的weui樣式	2.8.0
useExtendedLib	Object	否	指定需要引用的擴展庫	2.2.1
entranceDeclare	Object	否	微信消息用小程序打開	微信客戶端7.0.9

# pages

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

數組的第一項代表小程序的初始頁面（首頁）。小程序中新增/減少頁面，都需要對 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 自定義導航欄，只保留右上角膠囊按鈕。參見注 2。	微信客戶端 6.6.0
backgroundColor	HexColor	#ffffff	窗口的背景色
backgroundTextStyle	string	dark	下拉 loading 的樣式，僅支持 dark / light
backgroundColorTop	string	#ffffff	頂部窗口的背景色，僅 iOS 支持	微信客戶端 6.5.16
backgroundColorBottom	string	#ffffff	底部窗口的背景色，僅 iOS 支持	微信客戶端 6.5.16
enablePullDownRefresh	boolean	false	是否開啓全局的下拉刷新。 詳見 Page.onPullDownRefresh
onReachBottomDistance	number	50	頁面上拉觸底事件觸發時距頁面底部距離，單位爲 px。 詳見 Page.onReachBottom
pageOrientation	string	portrait	屏幕旋轉設置，支持 auto / portrait / landscape 詳見 響應顯示區域變化	2.4.0 (auto) / 2.5.0 (landscape)

• 注 1：HexColor（十六進制顏色值），如"#ff00ff"
• 注 2：關於navigationStyle
  • 客戶端 7.0.0 以下版本，navigationStyle 只在 app.json 中生效。
  • 客戶端 6.7.2 版本開始，navigationStyle: custom 對 web-view 組件無效
  • 開啓 custom 後，低版本客戶端需要做好兼容。開發者工具基礎庫版本切到 1.7.0（不代表最低版本，只供調試用）可方便切到舊視覺

如：

{
  "window": {
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "微信接口功能演示",
    "backgroundColor": "#eeeeee",
    "backgroundTextStyle": "light"
  }
}

# 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，不支持網絡圖片。 當 position 爲 top 時，不顯示 icon。
selectedIconPath	string	否	選中時的圖片路徑，icon 大小限制爲 40kb，建議尺寸爲 81px * 81px，不支持網絡圖片。 當 position 爲 top 時，不顯示 icon。

# networkTimeout

各類網絡請求的超時時間，單位均爲毫秒。

屬性	類型	必填	默認值	說明
request	number	否	60000	wx.request 的超時時間，單位：毫秒。
connectSocket	number	否	60000	wx.connectSocket 的超時時間，單位：毫秒。
uploadFile	number	否	60000	wx.uploadFile 的超時時間，單位：毫秒。
downloadFile	number	否	60000	wx.downloadFile 的超時時間，單位：毫秒。

# debug

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

# functionalPages

基礎庫 2.1.0 開始支持，低版本需做兼容處理。

插件所有者小程序需要設置這一項來啓用插件功能頁

 

插件所有者小程序需要設置這一項來啓用插件功能頁。

subpackages

微信客戶端 6.6.0 ，基礎庫 1.7.3 及以上版本支持

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

寫成 subPackages 也支持。

# workers

基礎庫 1.9.90 開始支持，低版本需做兼容處理。

使用 Worker 處理多線程任務時，設置 Worker 代碼放置的目錄

# requiredBackgroundModes

微信客戶端 6.7.2 及以上版本支持

申明需要後臺運行的能力，類型爲數組。目前支持以下項目：

• audio: 後臺音樂播放
• location: 後臺定位

如：

{
  "pages": ["pages/index/index"],
  "requiredBackgroundModes": ["audio", "location"]
}

注：在此處申明瞭後臺運行的接口，開發版和體驗版上可以直接生效，正式版還需通過審覈。

# plugins

基礎庫 1.9.6 開始支持，低版本需做兼容處理。

聲明小程序需要使用的插件。

# preloadRule

基礎庫 2.3.0 開始支持，低版本需做兼容處理。

聲明分包預下載的規則。

# resizable

基礎庫 2.3.0 開始支持，低版本需做兼容處理。

在 iPad 上運行的小程序可以設置支持屏幕旋轉。

# navigateToMiniProgramAppIdList

基礎庫 2.4.0 開始支持，低版本需做兼容處理。

當小程序需要使用 wx.navigateToMiniProgram 接口跳轉到其他小程序時，需要先在配置文件中聲明需要跳轉的小程序 appId 列表，最多允許填寫 10 個。

# usingComponents

開發者工具 1.02.1810190 及以上版本支持

在此處聲明的自定義組件視爲全局自定義組件，在小程序內的頁面或自定義組件中可以直接使用而無需再聲明。

# permission

微信客戶端 7.0.0 及以上版本支持

小程序接口權限相關設置。字段類型爲 Object，結構爲：

 

屬性	類型	必填	默認值	描述
scope.userLocation	PermissionObject	否		位置相關權限聲明

PermissionObject 結構

屬性	類型	必填	默認值	說明
desc	string	是		小程序獲取權限時展示的接口用途說明。最長 30 個字符

如：

{
  "pages": ["pages/index/index"],
  "permission": {
    "scope.userLocation": {
      "desc": "你的位置信息將用於小程序位置接口的效果展示" // 高速公路行駛持續後臺定位
    }
  }
}

# sitemapLocation

指明 sitemap.json 的位置；默認爲 'sitemap.json' 即在 app.json 同級目錄下名字的 sitemap.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"]
}

# style

基礎庫 2.8.0 開始支持，低版本需做兼容處理。

微信客戶端 7.0 開始，UI 界面進行了大改版。小程序也進行了基礎組件的樣式升級。app.json 中配置 "style": "v2"可表明啓用新版的組件樣式。

本次改動涉及的組件有 button icon radio checkbox switch slider。可前往小程序示例進行體驗。

# useExtendedLib

基礎庫 2.2.1 開始支持，低版本需做兼容處理。

最新的 nightly 版開發者工具開始支持，同時基礎庫從支持 npm 的版本（2.2.1）起支持

指定需要引用的擴展庫。目前支持以下項目：

• kbone: 多端開發框架
• weui: WeUI 組件庫

指定後，相當於引入了對應擴展庫相關的最新版本的 npm 包，同時也不佔用小程序的包體積。目前暫不支持在分包中引用。用法如下：

{
  "useExtendedLib": {
    "kbone": true,
    "weui": true
  }
}

# entranceDeclare

微信客戶端 7.0.9 及以上版本支持，iOS 暫不支持

聊天位置消息用打車類小程序打開，詳情參考。

"entranceDeclare": {
    "locationMessage": {
        "path": "pages/index/index",
        "query": "foo=bar"
    }
}