微信小程序 全局配置

全局配置

小程序根目錄下的 app.json 文件用來對微信小程序進行全局配置。文件內(nèi)容為一個 JSON 對象，有以下屬性：

配置項

entryPagePath

指定小程序的默認啟動路徑（首頁），常見情景是從微信聊天列表頁下拉啟動、小程序列表啟動等。如果不填，將默認為 pages 列表的第一項。不支持帶頁面路徑參數(shù)。

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

pages

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

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

小程序中新增/減少頁面，都需要對 pages 數(shù)組進行修改。

如開發(fā)目錄為：

├── 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

用于設(shè)置小程序的狀態(tài)欄、導(dǎo)航條、標題、窗口背景色。

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

如：

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

tabBar

如果小程序是一個多 tab 應(yīng)用（客戶端窗口的底部或頂部有 tab 欄可以切換頁面），可以通過 tabBar 配置項指定 tab 欄的表現(xiàn)，以及 tab 切換時顯示的對應(yīng)頁面。

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

networkTimeout

各類網(wǎng)絡(luò)請求的超時時間，單位均為毫秒。

debug

可以在開發(fā)者工具中開啟 debug 模式，在開發(fā)者工具的控制臺面板，調(diào)試信息以 info 的形式給出，其信息有 Page 的注冊，頁面路由，數(shù)據(jù)更新，事件觸發(fā)等?？梢詭椭_發(fā)者快速定位一些常見的問題。

functionalPages

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

插件所有者小程序需要設(shè)置這一項來啟用插件功能頁。

subpackages

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

啟用分包加載時，聲明項目分包結(jié)構(gòu)。

寫成 subPackages 也支持。

workers

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

使用 Worker 處理多線程任務(wù)時，設(shè)置 Worker 代碼放置的目錄

requiredBackgroundModes

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

申明需要后臺運行的能力，類型為數(shù)組。目前支持以下項目：

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

如：

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

注：在此處申明了后臺運行的接口，開發(fā)版和體驗版上可以直接生效，正式版還需通過審核。

plugins

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

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

preloadRule

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

聲明分包預(yù)下載的規(guī)則。

resizable

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

在 iPad 上運行的小程序可以設(shè)置支持屏幕旋轉(zhuǎn)。

在 PC 上運行的小程序，用戶可以按照任意比例拖動窗口大小，也可以在小程序菜單中最大化窗口

usingComponents

開發(fā)者工具 1.02.1810190 及以上版本支持

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

permission

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

小程序接口權(quán)限相關(guān)設(shè)置。字段類型為 Object，結(jié)構(gòu)為：

PermissionObject 結(jié)構(gòu)

如：

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

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,
}

style

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

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

本次改動涉及的組件有 button icon radio checkbox switch slider?？汕巴〕绦蚴纠M行體驗。

useExtendedLib

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

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

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

• kbone: 多端開發(fā)框架
• weui: WeUI 組件庫

指定后，相當于引入了對應(yīng)擴展庫相關(guān)的最新版本的 npm 包，同時也不占用小程序的包體積。目前暫不支持在分包中引用。用法如下：

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

entranceDeclare

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

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

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

darkmode

開發(fā)者工具 1.03.2004271 及以上版本支持，基礎(chǔ)庫 2.11.0 及以上版本支持

微信iOS客戶端 7.0.12 版本、Android客戶端 7.0.13 版本正式支持 DarkMode，可通過配置"darkmode": true表示當前小程序可適配 DarkMode，所有基礎(chǔ)組件均會根據(jù)系統(tǒng)主題展示不同的默認樣式，navigation bar 和 tab bar 也會根據(jù)開發(fā)者的配置自動切換。

配置后，請根據(jù)DarkMode 適配指南自行完成基礎(chǔ)樣式以外的適配工作。

{
  "darkmode": true
}

themeLocation

自定義 theme.json 的路徑，當配置"darkmode":true時，當前配置文件為必填項。

{
  "themeLocation": "/path/to/theme.json"
}

lazyCodeLoading

基礎(chǔ)庫 2.11.1 及以上版本支持，2.11.1 以下兼容但無優(yōu)化效果

通常情況下，在小程序啟動期間，所有頁面及自定義組件的代碼都會進行注入，當前頁面沒有使用到的自定義組件和頁面在注入后其實并沒有被使用。

自基礎(chǔ)庫版本 2.11.1 起，小程序支持有選擇地注入必要的代碼，以降低小程序的啟動時間和運行時內(nèi)存。

{
  "lazyCodeLoading": "requiredComponents"
}

當配置了這一項時，小程序僅注入當前頁面需要的自定義組件和頁面代碼，在頁面中必然不會用到的自定義組件不會被加載和初始化。

注意：添加這項配置后，未使用到的代碼文件將不被執(zhí)行。

singlePage

基礎(chǔ)庫 2.11.3 及以上版本支持，目前分享到朋友圈 (Beta) 后打開會進入單頁模式

單頁模式相關(guān)配置