微信小程序怎么写JSON:配置文件的核心语法与实战指南
在微信小程序开发中,JSON(JavaScript Object Notation)扮演着“骨架”角色——它不仅是全局配置、页面声明、组件扩展的核心载体,更直接影响小程序的运行逻辑与用户体验,从全局配置文件 app.json 到页面配置 page.json,再到自定义组件配置 component.json,JSON 文件的规范编写是每个小程序开发者的必备技能,本文将系统讲解微信小程序中 JSON 的核心语法、常见应用场景及实战技巧,帮你快速“怎么写”。
微信小程序中JSON的核心作用与文件类型
微信小程序的 JSON 文件主要用于配置小程序的全局行为、页面样式、组件扩展等,与 .js(逻辑)、.wxml(结构)、.wxss(样式)文件共同构成小程序的“四件套”,常见的 JSON 文件类型包括:
全局配置文件:app.json
位于项目根目录,是小程序的“总开关”,用于配置页面路径、窗口样式、tab 栏、网络超时时间等全局行为。
示例结构:
{
"pages": [
"pages/index/index",
"pages/logs/logs"
],
"window": {
"navigationBarTitleText": "我的小程序",
"navigationBarBackgroundColor": "#ffffff",
"navigationBarTextStyle": "black"
},
"tabBar": {
"color": "#999999",
"selectedColor": "#1aad19",
"list": [
{
"pagePath": "pages/index/index",
"text": "首页",
"iconPath": "images/home.png",
"selectedIconPath": "images/home-active.png"
}
]
}
}
页面配置文件:page.json
位于每个页面目录下(如 pages/index/index.json),用于覆盖 app.json 中该页面的配置,实现页面级别的个性化设置(如导航栏标题、背景色等)。
示例:
{
"navigationBarTitleText": "首页详情",
"backgroundColor": "#f5f5f5"
}
自定义组件配置文件:component.json
位于自定义组件目录下(如 components/my-component/my-component.json),用于声明组件的配置信息,如组件的外部样式类、属性定义等。
示例:
{
"component": true,
"usingComponents": {}
}
工具配置文件:project.config.json
用于记录项目的开发工具配置(如编译设置、开发者信息等),通常由开发者工具自动生成,开发者无需手动修改。
微信小程序JSON的核心语法规范
微信小程序的 JSON 文件遵循标准 JSON 语法,但结合小程序场景做了部分扩展和限制,以下核心语法是正确编写的前提:
基本语法规则
- 数据类型:支持字符串(
"text")、数字(123)、布尔值(true/false)、数组([])、对象()、null。 - 键值对:键必须使用双引号 包裹,值可以是上述任意类型。
- 注释:标准 JSON 不支持注释,但微信小程序的 JSON 文件支持 单行注释和 多行注释(仅限开发工具解析,实际运行时会忽略)。
✅ 正确示例:{ "pages": [ "pages/index/index" // 首页路径 ], "window": { /* 导航栏配置 */ "navigationBarTitleText": "小程序" } }❌ 错误示例:键无双引号、使用单行注释 但实际运行不支持(开发工具可解析,但生产环境可能报错)。
常用配置项详解
(1)pages:页面路由配置
- 作用:声明小程序的所有页面路径,数组类型,第一项为首页。
- 规则:路径需以 分隔,如
"pages/index/index"对应pages/index/index.wxml、index.js、index.wxss、index.json四个文件。 - 示例:
"pages": [ "pages/index/index", // 首页 "pages/user/profile", // 用户页 "pages/goods/detail" // 商品详情页 ]
(2)window:窗口全局配置
- 作用:设置小程序所有页面的导航栏、背景色等窗口样式。
- 常用字段:
navigationBarTitleText:导航栏标题(字符串)。navigationBarBackgroundColor:导航栏背景色(十六进制颜色码,如#1aad19)。navigationBarTextStyle:导航栏标题颜色(仅支持black/white)。backgroundColor:窗口背景色(页面未加载时的背景色)。backgroundTextStyle:下拉 loading 的样式(仅支持dark/light)。
- 示例:
"window": { "navigationBarTitleText": "电商小程序", "navigationBarBackgroundColor": "#ff6600", "navigationBarTextStyle": "white", "backgroundColor": "#f8f8f8", "backgroundTextStyle": "dark" }
(3)tabBar:底部标签栏配置
- 作用:定义小程序底部 tab 栏,实现页面快速切换(最多 5 个,最少 2 个)。
- 核心字段:
color:tab 文字默认颜色(十六进制)。selectedColor:tab 文字选中颜色(十六进制)。backgroundColor:tab 背景色(十六进制)。list:tab 列表(数组类型),每个元素是一个对象,包含:pagePath:页面路径(必须已在pages中声明)。text:tab 名称(字符串,最多 4 个字符)。iconPath:未选中时的图标路径(建议尺寸 81px×81px)。selectedIconPath:选中时的图标路径(建议尺寸 81px×81px)。
- 示例:
"tabBar": { "color": "#999999", "selectedColor": "#ff6600", "backgroundColor": "#ffffff", "list": [ { "pagePath": "pages/index/index", "text": "首页", "iconPath": "images/tab-home.png", "selectedIconPath": "images/tab-home-active.png" }, { "pagePath": "pages/category/category", "text": "分类", "iconPath": "images/tab-category.png", "selectedIconPath": "images/tab-category-active.png" }, { "pagePath": "pages/cart/cart", "text": "购物车", "iconPath": "images/tab-cart.png", "selectedIconPath": "images/tab-cart-active.png" } ] }
(4)usingComponents:组件配置
- 作用:在页面或组件中引入自定义组件,声明后可在
.wxml中直接使用组件标签。 - 规则:键为组件名,值为组件路径(相对于当前目录)。
- 页面级配置示例(
pages/index/index.json):{ "usingComponents": { "my-header": "/components/header/header", "my-button": "/components/button/button" } }在
index.wxml中可直接使用:<my-header title="首页"></my-header> <my-button text="提交"></my-button>
(5)sitemapLocation:索引配置
- 作用:声明
sitemap.json文件的位置,用于微信搜索收录(默认为"sitemap.json")。 - 示例:
"sitemapLocation": "sitemap.json"
JSON配置常见问题与实战技巧
覆盖优先级:页面配置 > 全局配置
app.json 是全局默认配置,而 page.json 可覆盖当前页面的配置。
app.json中设置navigationBarTitleText: "全局标题",pages/index/index.json中设置navigationBarTitleText: "首页标题", 显示为“首页标题”,其他页面仍显示“全局标题”。
数组与对象的嵌套使用
复杂配置需通过数组+对象嵌套实现,如 tabBar.list 是数组,每个元素是对象;window 是对象,其字段可嵌套其他对象或数组。
**示例:多语言配置扩展



还没有评论,来说两句吧...