微信小程序配置项

全局配置

https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html#entryPagePath

小程序根目录下的 app.json 文件用来对微信小程序进行全局配置。文件内容为一个 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[]	否	需要在后台使用的能力，如「音乐播放」
requiredPrivateInfos	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
debugOptions	Object	否	调试相关配置	2.22.1
enablePassiveEvent	Object或boolean	否	touch 事件监听是否为 passive	2.24.1
resolveAlias	Object	否	自定义模块映射规则
renderer	string	否	全局默认的渲染后端	2.30.4
rendererOptions	Object	否	渲染后端选项	2.31.1
componentFramework	string	否	组件框架，详见相关文档	2.30.4
miniApp	Object	否	多端模式场景接入身份管理服务时开启小程序授权页相关配置，详见相关文档
static	Object	否	正常情况下默认所有资源文件都被打包发布到所有平台，可以通过 static 字段配置特定每个目录/文件只能发布到特定的平台(多端场景) 相关文档
convertRpxToVw	boolean	否	配置是否将 rpx 单位转换为 vw 单位，开启后能修复某些 rpx 下的精度问题	3.3.0

以下简单列举了一部分, 其他未列举可以在官方文档中查看

entryPagePath

指定小程序的默认启动路径（首页），常见情景是从微信聊天列表页下拉启动、小程序列表启动等。如果不填，将默认为 pages 列表的第一项。不支持带页面路径参数。

pages

用于指定小程序由哪些页面组成，每一项都对应一个页面的 路径（含文件名） 信息。文件名不需要写文件后缀，框架会自动去寻找对应位置的 .json, .js, .wxml, .wxss 四个文件进行处理。

未指定 entryPagePath 时，数组的第一项代表小程序的初始页面（首页）。

小程序中新增/减少页面，都需要对 pages 数组进行修改。

则需要在 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。	iOS/Android 微信客户端 6.6.0，Windows 微信客户端不支持
homeButton	boolean	default	在非首页、非页面栈最底层页面或非tabbar内页面中的导航栏展示home键	微信客户端 8.0.24
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
handleWebviewPreload	string	static	控制预加载下个页面的时机。支持 static / manual / auto	2.15.0

如：

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

img

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。

img

以下是一个简单示例

"tabBar": {
	"color": "#00A95E",
	"selectedColor": "#FA8072",
	"backgroundColor": "#f5f5f5",
	"borderStyle": "black",
	"list": [
		{
			"pagePath": "pages/index/index",
			"text": "Index",
			"iconPath": "icon/_home.png",
			"selectedIconPath": "icon/home.png"
		},
		{
			"pagePath": "pages/logs/logs",
			"text": "Logs",
			"iconPath": "icon/_search.png",
			"selectedIconPath": "icon/search.png"
		},
		{
			"pagePath": "pages/demo/demo",
			"text": "Demo",
			"iconPath": "icon/_videocamera.png",
			"selectedIconPath": "icon/videocamera.png"
		}
	]
}

image-20240120160151572

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 的注册，页面路由，数据更新，事件触发等。可以帮助开发者快速定位一些常见的问题。

页面配置

app.json 中的部分配置，也支持对单个页面进行配置，可以在页面对应的 .json 文件来对本页面的表现进行配置。

页面中配置项在当前页面会覆盖 app.json 中相同的配置项（样式相关的配置项属于 app.json 中的 window 属性，但这里不需要额外指定 window 字段），具体的取值和含义可参考全局配置文档中说明。

文件内容为一个 JSON 对象，有以下属性：

属性	类型	默认值	描述	最低版本
navigationBarBackgroundColor	HexColor	#000000	导航栏背景颜色，如 #000000
navigationBarTextStyle	string	white	导航栏标题、状态栏颜色，仅支持 black / white
navigationBarTitleText	string		导航栏标题文字内容
navigationStyle	string	default	导航栏样式，仅支持以下值： default 默认样式 custom 自定义导航栏，只保留右上角胶囊按钮。	iOS/Android 微信客户端 7.0.0，Windows 微信客户端不支持
homeButton	boolean	false	在非首页、非页面栈最底层页面或非tabbar内页面中的导航栏展示home键	微信客户端 8.0.24
backgroundColor	HexColor	#ffffff	窗口的背景色
backgroundColorContent	HexColor	#RRGGBBAA	页面容器背景色，点击查看设置背景色详情
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)
disableScroll	boolean	false	设置为 true 则页面整体不能上下滚动。 只在页面配置中有效，无法在 app.json 中设置
usingComponents	Object	否	页面自定义组件配置	1.6.3
initialRenderingCache	string		页面初始渲染缓存配置，支持 static / dynamic	2.11.1
style	string	default	启用新版的组件样式	2.10.2
singlePage	Object	否	单页模式相关配置	2.12.0
restartStrategy	string	homePage	重新启动策略配置	2.8.0
handleWebviewPreload	string	static	控制预加载下个页面的时机。支持 static / manual / auto	2.15.0
visualEffectInBackground	string	否	切入系统后台时，隐藏页面内容，保护用户隐私。支持 hidden / none，若对页面单独设置则会覆盖全局的配置，详见 全局配置	2.15.0
enablePassiveEvent	Object或boolean	否	事件监听是否为 passive，若对页面单独设置则会覆盖全局的配置，详见 全局配置	2.24.1
renderer	string	否	渲染后端	2.30.4
rendererOptions	Object	否	渲染后端选项，详情相关文档	3.1.0
componentFramework	string	否	组件框架，详情相关文档	2.30.4

• 注：并不是所有 app.json 中的配置都可以在页面覆盖或单独指定，仅限于本文档包含的选项。
• 注：iOS/Android 客户端 7.0.0 以下版本，navigationStyle 只在 app.json 中生效。

image-20240120160819935

WXSS

WXSS (WeiXin Style Sheets)是一套样式语言，用于描述 WXML 的组件样式。

WXSS 用来决定 WXML 的组件应该怎么显示。

为了适应广大的前端开发者，WXSS 具有 CSS 大部分特性。同时为了更适合开发微信小程序，WXSS 对 CSS 进行了扩充以及修改。

与 CSS 相比，WXSS 扩展的特性有：

• 尺寸单位
• 样式导入

尺寸单位

• rpx（responsive pixel）: 可以根据屏幕宽度进行自适应。规定屏幕宽为750rpx。如在 iPhone6 上，屏幕宽度为375px，共有750个物理像素，则750rpx = 375px = 750物理像素，1rpx = 0.5px = 1物理像素。

设备	rpx换算px (屏幕宽度/750)	px换算rpx (750/屏幕宽度)
iPhone5	1rpx = 0.42px	1px = 2.34rpx
iPhone6	1rpx = 0.5px	1px = 2rpx
iPhone6 Plus	1rpx = 0.552px	1px = 1.81rpx

建议： 开发微信小程序时设计师可以用 iPhone6 作为视觉稿的标准。

注意： 在较小的屏幕上不可避免的会有一些毛刺，请在开发时尽量避免这种情况。

样式导入

使用@import语句可以导入外联样式表，@import后跟需要导入的外联样式表的相对路径，用;表示语句结束。

示例代码：

/** common.wxss **/
.small-p {
  padding:5px;
}
/** app.wxss **/
@import "common.wxss";
.middle-p {
  padding:15px;
}

内联样式

框架组件上支持使用 style、class 属性来控制组件的样式。

• style：静态的样式统一写到 class 中。style 接收动态的样式，在运行时会进行解析，请尽量避免将静态的样式写进 style 中，以免影响渲染速度。

<view style="color:{{color}};" />

• class：用于指定样式规则，其属性值是样式规则中类选择器名(样式类名)的集合，样式类名不需要带上.，样式类名之间用空格分隔。

<view class="normal_view" />

选择器

目前支持的选择器有：

选择器	样例	样例描述
.class	.intro	选择所有拥有 class="intro" 的组件
#id	#firstname	选择拥有 id="firstname" 的组件
element	view	选择所有 view 组件
element, element	view, checkbox	选择所有文档的 view 组件和所有的 checkbox 组件
::after	view::after	在 view 组件后边插入内容
::before	view::before	在 view 组件前边插入内容

全局样式与局部样式

定义在 app.wxss 中的样式为全局样式，作用于每一个页面。在 page 的 wxss 文件中定义的样式为局部样式，只作用在对应的页面，并会覆盖 app.wxss 中相同的选择器。