微信小程序——代码构成

JSON 配置

项目的根目录有一个app.json 和 project.config.json，此外在pages/logs目录下还有一个logs.json

小程序配置 app.json

app.json 是当前小程序的全局配置，包括了小程序的所有页面路径、页面表现、网络超时时间、底部Tab等。
QuickStart项目里的app.json配置内容如下：

{
	"pages": ["pages/index/index","pages/logs/logs"],
	"window":{
		"backgroundTextStyle": "light",
		"navigationBarBackgroundColor": "white",
		"navigationBarTitleText": "titlename", // the name of navigationBar
		"navigationBarTextStyle": "black"  // the color of titlename
	}
}

app.json 配置项列表

属性	类型	必填	描述	最低版本
pages	String Array	是	页面路径列表
window	Object	否	全局的默认窗口表现
tabBar	Object	否	底部tab栏的表现
networkTimeout	Object	否	网络超时时间
debug	Boolean	否	是否开启debug模式，默认关闭
functionalPages	Boolean	否	是否启用插件功能页，默认关闭	2.1.0
subpackages	Object Array	否	分包结构配置	1.7.3
workers	String	否	worker代码放置的目录	1.9.90
requiredBackgroundModes	String Array	否	需要在后台使用的能力，如【音乐播放】
plugins	Object	否	使用到的插件	1.9.6
preloadRule	Object	否	分包预下载规则	2.3.0
resizable	Boolean	否	iPad小程序是否支持屏幕旋转，默认关闭	2.3.0
navigateToMiniProgramAppIdList	String Array	否	需要跳转的小程序列表	2.4.0
usingComponents	Object	否	全局自定义组件配置	开发者工具1.02.1810190
permission	Object	否	小程序接口权限相关设置	微信客户端7.0.0

Pages

用于指定小程序由哪些页面组成。数组的第一项代表小程序的初始页面（首页）。小程序中新增/减少页面，都需要对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 自定义导航栏，只保留右上角胶囊按钮。	微信客户端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	是否开启当前页面的下拉刷新。
onReachBottomDistance	Number	50	页面上拉触底事件触发时距页面底部距离，单位为px。
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 对 组件无效
  • 开启 custom后，低版本客户端需要做好兼容。开发者工具基础库版本切到1.7.0（不代表最低版本，只供调试用）可方便切到旧视觉

tabBar

如果小程序是一个多tab应用（客户端窗口的底部或顶部有tab栏可以切换页面），可以通过 tabBar 配置项指定tab栏的表现，以及tab切换时显示的对应页面。

属性	类型	必填	默认值	描述	最低版本
color	HexColor	是		tab上的文字默认颜色，仅支持十六进制颜色
selectedColor	HexColor	是		tab上的文字选中时的颜色，仅支持十六进制颜色
backgroundColor	HexColor	是		tab的背景色，仅支持十六进制颜色
borderStyle	String	否	black	tabbar上边框的颜色，仅支持black/white
list	Array	是		tab的列表，最少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

启用插件功能页时，插件所有者小程序需要设置其functionalPages为true

subpackages

启用分包加载时，声明项目分包结构。

写成 subPackages 也支持。

workers

使用Worker处理多线程任务时，设置worker代码放置的目录

requiredBackgroundModes

申明需要后台运行的能力，类型为数组。目前支持以下项目：

• audio：后台音乐播放

{
	"pages": ["pages/index/index"],
	"requireBackgroundModes":["audio"]
}

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

plugins

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

preloadRule

声明分包预下载的规则

resizable

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

navigateToMiniProgramAppIdList

当小程序需要使用 wx.navigateToMiniProgram 接口跳转到其他小程序时，需要先在配置文件中声明需要跳转的小程序 appId 列表，最多允许填写 10 个。

usingComponents

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

permission

小程序接口权限相关设置。字段类型为 Object，结构为：

属性	类型	必填	默认值	描述
scope.userLocation	PermissionObject	否		位置相关权限声明

permissionObject结构

属性	类型	必填	默认值	描述
desc	String	是		小程序获取权限时展示的接口用途说明。最长30个字符

{
	"pages": ["pages/index/index"],
	"permission": {
		"scope.userLocation": {
			"desc": "你的位置信息将用于小程序位置接口的效果展示"
		}
	}
}

---

页面配置

每个小程序页面也可以使用.json文件对本页面的窗口表现进行配置。
页面的配置只能设置app.json中部分window配置项的内容，页面中配置项会覆盖app.json的window中相同的配置项。

属性	类型	必填	描述	最低版本
navigationBarBackgroundColor	HexColor	#000000	导航栏背景颜色，如#000000
navigationBarTextStyle	String	white	导航栏标题颜色，仅支持black/white
navigationBarTitleText	String		导航栏标题文字内容
navigationStyle	String	default	导航栏样式，仅支持以下值： default默认样式 custom自定义导航栏，只保留右上角胶囊按钮	微信客户端7.0.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	是否全局开启下拉刷新
onReachBottomDistance	Number	50	页面上拉触底事件触发时距页面底部距离，单位为px
pageOrientation	String	portrait	屏幕旋转设置，支持auto/portrait/landscape	2.4.0(auto)/2.5.0(landscape)
disableScroll	Boolean	false	设置为true则页面整体不能上下滚动。 只在页面配置中有效，无法在app.json中设置
disableSwipeBack	Boolean	false	禁止页面右滑手势返回	微信客户端7.0.0
usingComponents	Object	否	页面自定义组件设置	1.6.3

页面的.json只能设置window相关的配置项，以决定本页面的窗口表现，所以无需写`

---

工具配置 project.config.json

小程序开发者工具在每个项目的根目录都会生成一个project.config.json，你在工具上做的任何配置都会写入到这个文件，当你重新安装工具或者换电脑工作时，只要载入同一个项目的代码，开发者工具就自动会帮你恢复到当时你开发项目时的个性化设置，其中会包括编辑器的颜色、代码上传时自动压缩等等一系列选项。

packOptions

packOptions用以配置项目在打包过程中的选项。打包是预览、上传时对项目进行的必须步骤。

目前可以指定packOptions.ignore字段，用以配置打包时对符合指定规则的文件或文件夹进行忽略，以跳过打包的过程，这些文件或文件夹将不会出现在预览或上传的结果内。

packOptions.ignore为一对象数组，对象元素类型如下：

字段名	类型	说明
value	string	路径[^1] 或取值
type	string	类型

其中，type可以取的值为false、file、suffix、prefix、regexp[^2] 、glob[^2]，分别对应文件夹、文件、后缀、前缀、正则表达式、Glob规则。所有规则值都会自动忽略大小写。

[^1] ：value字段的值若表示文件或文件夹路径，以小程序目录（miniprogramRoot）为根目录
[^2] : regexp、glob仅1.02.1809260及以上版本工具支持

示例配置如下：

{
  "packOptions": {
    "ignore": [
      {
        "type": "file",
        "value": "test/test.js"
      },
      {
        "type": "folder",
        "value": "test"
      },
      {
        "type": "suffix",
        "value": ".webp"
      },
      {
        "type": "prefix",
        "value": "test-"
      },
      {
        "type": "glob",
        "value": "test/**/*.js"
      },
      {
        "type": "regexp",
        "value": "\\.jsx$"
      }
    ]
  }
}

注：这部分设置的更改可能需要重新打开项目才能生效

debugOptions

debugOptions用以配置在对项目代码进行调试的选项。

目前可以指定debugOptions.hideInDevtools字段，用以配置调试时于调试器Sources面板隐藏源代码的文件。

hideInDevtools的配置规则和packOptions.ignore是一致的。
当某个JS文件符合此规则时，调试器Sources面板中此文件源代码正文内容将被隐藏，显示为：

// xxx.js has been hided by project.config.json

注：配置此规则后，可能需要关闭并重新打开项目才能看到效果

{
  "miniprogramRoot": "./src",
  "qcloudRoot": "./svr",
  "setting": {
    "postcss": true,
    "es6": true,
    "minified": true,
    "urlCheck": false
  },
  "packOptions": {
    "ignore": []
  },
  "debugOptions": {}
}

---

WXML 模板

WXML充当的类似HTML（用来描述当前这个页面的结构）的角色。
和HTML非常相似，WXML由标签、属性等等构成。但是也有很多不一样的地方：

1. 标签名不一样
   HTML用的是div、p、span等，但是小程序的WXML用的标签是view、button、text等，这些标签就是小程序给开发者包装好的基本能力。
2. 多了一些wx: if这样的属性以及{{ }}这样的表达式
   在网页的一般开发流程中，通常会通过JS操作DOM，以引起界面的一些变化响应用户的行为。

WXSS 样式

WXSS 具有 CSS 大部分的特性，小程序在 WXSS 也做了一些扩充和修改。

1. 新增了尺寸单位。在写 CSS 样式时，开发者需要考虑到手机设备的屏幕会有不同的宽度和设备像素比，采用一些技巧来换算一些像素单位。WXSS 在底层支持新的尺寸单位 rpx ，开发者可以免去换算的烦恼，只要交给小程序底层来换算即可，由于换算采用的浮点数运算，所以运算结果会和预期结果有一点点偏差。

2. 提供了全局的样式和局部样式。和前边 app.json, page.json 的概念相同，你可以写一个 app.wxss 作为全局样式，会作用于当前小程序的所有页面，局部页面样式 page.wxss 仅对当前页面生效。

此外 WXSS 仅支持部分 CSS 选择器

JS 交互逻辑

一个服务仅仅只有界面展示是不够的，还需要和用户做交互：响应用户的点击、获取用户的位置等等。在小程序里边，我们就通过编写 JS 脚本文件来处理用户的操作。

此外你还可以在 JS 中调用小程序提供的丰富的 API，利用这些 API 可以很方便的调起微信提供的能力，例如获取用户信息、本地存储、微信支付等。