various

[TOC]

微信小程序笔记

微信小程序的一些笔记，很多在官方文档中都可找到

但是与官网有所不同，一些是从实际的角度出发而记录的

本笔记在线版本：https://letmefly.xyz/Notes/WXminiProgram/

安装

下载页面

项目目录ㅤ

.
│  app.js                  ------------------------ 项目的全局文件
│  app.json                ------------------------ 项目的全局文件
│  app.wxss                ------------------------ 项目的全局文件
│  project.config.json     ------------------------ 项目的配置信息
│  sitemap.json            ------------------------ 哪些页面可以被索引
│
├─pages                    ------------------------ 存放页面的文件夹
│  ├─index                 ------------------------ 页面index(下面有4个文件)
│  │      index.js         ------------------------ index页面的函数脚本
│  │      index.json       ------------------------ index页面的配置信息
│  │      index.wxml       ------------------------ index页面的页面代码
│  │      index.wxss       ------------------------ index页面的样式
│  │
│  └─logs                  ------------------------ logs页面
│          logs.js         ------------------------ (同index页面下的4个文件)
│          logs.json
│          logs.wxml
│          logs.wxss
│
└─utils                    ------------------------ 其他的包
        util.js

app.json

属性	类型	必填	描述	最低版本
entryPagePath	string	否	小程序默认启动首页
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	否	PC 小程序是否支持用户任意改变窗口大小（包括最大化窗口）；iPad 小程序是否支持屏幕旋转。默认关闭	2.3.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
darkmode	boolean	否	小程序支持 DarkMode	2.11.0
themeLocation	string	否	指明 theme.json 的位置，darkmode为true为必填	开发者工具 1.03.2004271
lazyCodeLoading	string	否	配置自定义组件代码按需注入	2.11.1
singlePage	Object	否	单页模式相关配置	2.12.0
supportedMaterials	Object	否	聊天素材小程序打开相关配置	2.14.3
serviceProviderTicket	string	否	定制化型服务商票据
embeddedAppIdList	string[]	否	半屏小程序 appId	2.20.1
halfPage	Object	否	视频号直播半屏场景设置	2.18.0

entryPagePathㅤ

微信小程序的主页(启动的页面)。

若无此项，则会以"pages"中的第一个为准。

pagesㅤ

如项目目录中共有两个页面，则pages应写为：

"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。	iOS/Android 微信客户端 6.6.0，Windows 微信客户端不支持
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)
restartStrategy	string	homePage	重新启动策略配置	2.8.0
initialRenderingCache	string		页面初始渲染缓存配置，支持 static / dynamic	2.11.1
visualEffectInBackground	string	none	切入系统后台时，隐藏页面内容，保护用户隐私。支持 hidden / none	2.15.0

restartStrategyㅤ

基础库 2.8.0 开始支持，低版本需做兼容处理。

重新启动策略配置

可选值	含义
homePage	（默认值）如果从这个页面退出小程序，下次将从首页冷启动
homePageAndLatestPage	如果从这个页面退出小程序，下次冷启动后立刻加载这个页面，页面的参数保持不变（不可用于 tab 页）

例：

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

tabBarㅤ

小程序底部或顶部可以有tab栏指定切换页面

属性	类型	必填	默认值	描述	最低版本
color	HexColor	否	black	tab 上的文字默认颜色，仅支持十六进制颜色
selectedColor	HexColor	否	#1aad19	tab 上的文字选中时的颜色，仅支持十六进制颜色
backgroundColor	HexColor	否	white	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ㅤ

网络请求的Timeout(超时时间)，单位ms

属性	类型	必填	默认值	说明
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: 后台定位

如：

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

注：在此处申明了后台运行的接口，开发版和体验版上可以直接生效，正式版还需通过审核。

pluginsㅤ

基础库 1.9.6 开始支持，低版本需做兼容处理。

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

preloadRuleㅤ

基础库 2.3.0 开始支持，低版本需做兼容处理。

声明分包预下载的规则。

resizableㅤ

基础库 2.3.0 开始支持，低版本需做兼容处理。

在 iPad 上运行的小程序可以设置支持屏幕旋转。

在 PC 上运行的小程序，用户可以按照任意比例拖动窗口大小，也可以在小程序菜单中最大化窗口

usingComponentsㅤ

开发者工具 1.02.1810190 及以上版本支持

在 app.json 中声明的自定义组件视为全局自定义组件，在小程序内的页面或自定义组件中可以直接使用而无需再声明。

注意：全局声明的自定义组件会视为被所有页面依赖，会在所有页面启动时进行初始化，且会占用主包大小。只被个别页面或分包引用的自定义组件应尽量在页面配置中声明。

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 文件

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 包，同时也不占用小程序的包体积。rc工具版本支持分包引用。用法如下：

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

entranceDeclareㅤ

微信客户端 7.0.9 及以上版本支持，iOS 暂不支持

聊天位置消息用打车类小程序打开，详情参考。

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

darkmodeㅤ

开发者工具 1.03.2004271 及以上版本支持，基础库 2.11.0 及以上版本支持

微信iOS客户端 7.0.12 版本、Android客户端 7.0.13 版本正式支持 DarkMode，可通过配置”darkmode”: true表示当前小程序可适配 DarkMode，所有基础组件均会根据系统主题展示不同的默认样式，navigation bar 和 tab bar 也会根据开发者的配置自动切换。

配置后，请根据DarkMode 适配指南自行完成基础样式以外的适配工作。

{
    "darkmode": true
}

themeLocationㅤ

自定义 theme.json 的路径，当配置"darkmode":true时，当前配置文件为必填项。

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

lazyCodeLoadingㅤ

目前仅支持值 requiredComponents，代表开启小程序「按需注入」特性。

{
    "lazyCodeLoading": "requiredComponents"
}

singlePageㅤ

基础库 2.11.3 及以上版本支持，目前分享到朋友圈 (Beta) 后打开会进入单页模式

单页模式相关配置

属性	类型	必填	默认值	描述
navigationBarFit	String	否	默认自动调整，若原页面是自定义导航栏，则为 float，否则为 squeezed	导航栏与页面的相交状态，值为 float 时表示导航栏浮在页面上，与页面相交；值为 squeezed 时表示页面被导航栏挤压，与页面不相交

embeddedAppIdListㅤ

指定小程序可通过wx.openEmbeddedMiniProgram打开的小程序名单。

{
    "embeddedAppIdList": ["wxe5f52902cf4de896"]
}

halfPageㅤ

属性	类型	必填	默认值	描述
firstPageNavigationStyle	string	否		视频号直播打开的第一个页面的全屏状态使用自定义顶部，支持 default / custom

{
    "halfPage": {
        "firstPageNavigationStyle": "custom"
    }
}

This site is open source. Improve this page.