小程序日记：基础篇

一、全局配置

小程序根目录下的 app.json 文件用来对微信小程序进行全局配置。文件内容为一个 JSON 对象，有以下属性：

配置项

属性	类型	必填	描述
pages	string[]	是	页面路径列表
window	Object	否	全局的默认窗口表现
tabBar	Object	否	底部 tab 栏的表现
networkTimeout	Object	否	网络超时时间
debug	boolean	否	是否开启 debug 模式，默认关闭
functionalPages	boolean	否	是否启用插件功能页，默认关闭
subpackages	Object[]	否	分包结构配置
workers	string	否	Worker 代码放置的目录
requiredBackgroundModes	string[]	否	需要在后台使用的能力，如「音乐播放」
plugins	Object	否	使用到的插件
preloadRule	Object	否	分包预下载规则
resizable	boolean	否	PC 小程序是否支持用户任意改变窗口大小（包括最大化窗口）；iPad 小程序是否支持屏幕旋转。默认关闭
usingComponents	Object	否	全局自定义组件配置
permission	Object	否	小程序接口权限相关设置
sitemapLocation	string	是	指明 sitemap.json 的位置
style	string	否	指定使用升级后的weui样式
useExtendedLib	Object	否	指定需要引用的扩展库
entranceDeclare	Object	否	微信消息用小程序打开
darkmode	boolean	否	小程序支持 DarkMode
themeLocation	string	否	指明 theme.json 的位置，darkmode为true为必填

1、pages

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

数组的第一项代表小程序的初始页面（首页）。小程序中新增/减少页面，都需要对 pages 数组进行修改。

如开发目录为：

├── app.js
├── app.json
├── app.wxss
├── pages
│   │── index
│   │   ├── index.wxml
│   │   ├── index.js
│   │   ├── index.json
│   │   └── index.wxss
│   └── logs
│       ├── logs.wxml
│       └── logs.js
└── utils

2、window

用于设置小程序的状态栏、导航条、标题、窗口背景色。

属性	类型	默认值	描述
navigationBarBackgroundColor	HexColor	#000000	导航栏背景颜色，如 #000000
navigationBarTextStyle	string	white	导航栏标题颜色，仅支持 black / white
navigationBarTitleText	string		导航栏标题文字内容
navigationStyle	string	default	导航栏样式，仅支持以下值： default 默认样式 custom 自定义导航栏，只保留右上角胶囊按钮。参见注 2。
backgroundColor	HexColor	#ffffff	窗口的背景色
backgroundTextStyle	string	dark	下拉 loading 的样式，仅支持 dark / light
backgroundColorTop	string	#ffffff	顶部窗口的背景色，仅 iOS 支持
backgroundColorBottom	string	#ffffff	底部窗口的背景色，仅 iOS 支持
enablePullDownRefresh	boolean	false	是否开启全局的下拉刷新。 详见 Page.onPullDownRefresh
onReachBottomDistance	number	50	页面上拉触底事件触发时距页面底部距离，单位为 px。 详见 Page.onReachBottom
pageOrientation	string	portrait	屏幕旋转设置，支持 auto / portrait / landscape 详见 响应显示区域变化

3、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，见详情

3.1：list的属性

​ 其中 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。

二、页面配置 page.json

每一个小程序页面也可以使用 .json 文件来对本页面的窗口表现进行配置。页面中配置项在当前页面会覆盖 app.json 的 window 中相同的配置项。文件内容为一个 JSON 对象，有以下属性：

配置项

属性	类型	默认值	描述	最低版本
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	是否开启当前页面下拉刷新。 详见 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
style	string	default	启用新版的组件样式	2.10.2

页面配置中只能设置 app.json 中 window 对应的配置项，以决定本页面的窗口表现，所以无需写 window 这个属性。

配置示例

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

三、sitemap 配置

小程序根目录下的 sitemap.json 文件用于配置小程序及其页面是否允许被微信索引，文件内容为一个 JSON 对象，如果没有 sitemap.json ，则默认为所有页面都允许被索引；sitemap.json 有以下属性：

配置项

属性	类型	必填	描述
rules	Object[]	是	索引规则列表

rules

rules 配置项指定了索引规则，每项规则为一个JSON对象，属性如下所示：

属性	类型	必填	默认值	取值	取值说明
action	string	否	“allow”	“allow”、“disallow”	命中该规则的页面是否能被索引
page	string	是		“*”、页面的路径	* 表示所有页面，不能作为通配符使用
params	string[]	否	[]		当 page 字段指定的页面在被本规则匹配时可能使用的页面参数名称的列表（不含参数值）
matching	string	否	“inclusive”	参考 matching 取值说明	当 page 字段指定的页面在被本规则匹配时，此参数说明 params 匹配方式
priority	Number	否			优先级，值越大则规则越早被匹配，否则默认从上到下匹配

matching 取值说明

值	说明
exact	当小程序页面的参数列表等于 params 时，规则命中
inclusive	当小程序页面的参数列表包含 params 时，规则命中
exclusive	当小程序页面的参数列表与 params 交集为空时，规则命中
partial	当小程序页面的参数列表与 params 交集不为空时，规则命中

配置示例

示例1

{
   
  "rules":[{
   
    "action": "allow",
    "page": "path/to/page",
    "params": ["a", "b"],
    "matching": "exact"
  }, {
   
    "action": "disallow",
    "page": "path/to/page"
  }]
}

• path/to/page?a=1&b=2 => 优先索引
• path/to/page => 不被索引
• path/to/page?a=1 => 不被索引
• path/to/page?a=1&b=2&c=3 => 不被索引
• 其他页面都会被索引

示例2

{
   
  "rules":[{
   
    "action": "allow",
    "page": "path/to/page",
    "params": ["a", "b"],
    "matching": "inclusive"
  }, {
   
    "action": "disallow",
    "page": "path/to/page"
  }]
}

• path/to/page?a=1&b=2 => 优先索引
• path/to/page?a=1&b=2&c=3 => 优先索引
• path/to/page => 不被索引
• path/to/page?a=1 => 不被索引
• 其他页面都会被索引

示例3

{
   
  "rules":[{
   
    "action": "allow",
    "page": "path/to/page",
    "params": ["a", "b"],
    "matching": "exclusive"
  }, {
   
    "action": "disallow",
    "page": "path/to/page"
  }]
}

• path/to/page => 优先索引
• path/to/page?c=3 => 优先索引
• path/to/page?a=1 => 不被索引
• path/to/page?a=1&b=2 => 不被索引
• 其他页面都会被索引

示例4

{
   
  "rules":[{
   
    "action": "allow",
    "page": "path/to/page",
    "params": ["a", "b"],
    "matching": "partial"
  }, {
   
    "action": "disallow",
    "page": "path/to/page"
  }]
}

• path/to/page?a=1 => 优先索引
• path/to/page?a=1&b=2 => 优先索引
• path/to/page => 不被索引
• path/to/page?c=3 => 不被索引
• 其他页面都会被索引

注：没有 sitemap.json 则默认所有页面都能被索引

注：{"action": "allow", "page": "\*"} 是优先级最低的默认规则，未显式指明 “disallow” 的都默认被索引

WXML语法

四、数据绑定

WXML中的动态数据均来自对应 Page 的 data。

1、简单绑定

数据绑定使用 Mustache 语法（双大括号）将变量包起来，可以作用于：

1.1、内容

<!--  
	text  相当于html中的行内标签：space标签
	view  相当于htnl中的块标签： div标签
-->
<view> {
  { message }} </view>
Page({
  data: {
    message: 'Hello MINA!'
  }
})

1.2、组件属性(需要在双引号之内)

<view id="item-{
    {id}}"> </view>
Page({
  data: {
    id: 0
  }
})

1.3、控制属性(需要在双引号之内)

<view wx:if="{
    {condition}}"> </view>
Page({
  data: {
    condition: true
  }
})

1.4、关键字(需要在双引号之内)

true：boolean 类型的 true，代表真值。

false： boolean 类型的 false，代表假值。

<checkbox checked="{
    {false}}"> </checkbox>

特别注意：不要直接写 checked="false"，其计算结果是一个字符串，转成 boolean 类型后代表真值。

2、运算

可以在 { {}} 内进行简单的运算，支持的有如下几种方式：

2.1、三元运算

<view hidden="{
    {flag ? true : false}}"> Hidden </view>

2.2、算数运算

<view> {
  {a + b}} + {
  {c}} + d </view>
Page({
  data: {
    a: 1,
    b: 2,
    c: 3
  }
})

view中的内容为 3 + 3 + d。

2.3、逻辑判断

<view wx:if="{
    {length > 5}}"> </view>

2.4、字符串运算

<view>{
  {"hello" + name}}</view>
Page({
  data:{
    name: 'MINA'
  }
})

2.5、数据路径运算

<view>{
  {object.key}} {
  {array[0]}}</view>
Page({
  data: {
    object: {
      key: 'Hello '
    },
    array: ['MINA']
  }
})

3、组合

也可以在 Mustache 内直接进行组合，构成新的对象或者数组。

3.1、数组

<view wx:for="{
    {[zero, 1, 2, 3, 4]}}"> {
  {item}} </view>
Page({
  data: {
    zero: 0
  }
})

最终组合成数组[0, 1, 2, 3, 4]。

3.2、对象

<template is="objectCombine" data="{
    {for: a, bar: b}}"></template>
Page({
  data: {
    a: 1,
    b: 2
  }
})

最终组合成的对象是 {for: 1, bar: 2}

也可以用扩展运算符 ... 来将一个对象展开

<template is="objectCombine" data="{
    {...obj1, ...obj2, e: 5}}"></template>
Page({
  data: {
    obj1: {
      a: 1,
      b: 2
    },
    obj2: {
      c: 3,
      d: 4
    }
  }
})

最终组合成的对象是 {a: 1, b: 2, c: 3, d: 4, e: 5}。

如果对象的 key 和 value 相同，也可以间接地表达。

<template is="objectCombine" data="{
    {foo, bar}}"></template>
Page({
  data: {
    foo: 'my-foo',
    bar: 'my-bar'
  }
})

最终组合成的对象是 {foo: 'my-foo', bar:'my-bar'}。

注意：上述方式可以随意组合，但是如有存在变量名相同的情况，后边的会覆盖前面，如：

<template is="objectCombine" data="{
    {...obj1, ...obj2, a, c: 6}}"></template>
Page({
  data: {
    obj1: {
      a: 1,
      b: 2
    },
    obj2: {
      b: 3,
      c: 4
    },
    a: 5
  }
})

最终组合成的对象是 {a: 5, b: 3, c: 6}。

注意： 花括号和引号之间如果有空格，将最终被解析成为字符串

<view wx:for="{
    {[1,2,3]}} ">
  {
  {item}}
</view>

等同于

<view wx:for="{
    {[1,2,3] + ' '}}">
  {
  {item}}
</view>

五、列表渲染

1、wx:for

在组件上使用 wx:for 控制属性绑定一个数组，即可使用数组中各项的数据重复渲染该组件。

默认数组的当前项的下标变量名默认为 index，数组当前项的变量名默认为 item

<view wx:for="{
    {array}}">
  {
  {index}}: {
  {item.message}}
</view>
Page({
  data: {
    array: [{
      message: 'foo',
    }, {
      message: 'bar'
    }]
  }
})

使用 wx:for-item 可以指定数组当前元素的变量名，

使用 wx:for-index 可以指定数组当前下标的变量名：

<view wx:for="{
    {array}}" wx:for-index="idx" wx:for-item="itemName">
  {
  {idx}}: {
  {itemName.message}}
</view>

wx:for 也可以嵌套，下边是一个九九乘法表

<view wx:for="{
    {[1, 2, 3, 4, 5, 6, 7, 8, 9]}}" wx:for-item="i">
  <view wx:for="{
    {[1, 2, 3, 4, 5, 6, 7, 8, 9]}}" wx:for-item="j">
    <view wx:if="{
    {i <= j}}">
      {
  {i}} * {
  {j}} = {
  {i * j}}
    </view>
  </view>
</view>

2、block wx:for

类似 block wx:if，也可以将 wx:for 用在<block/>标签上，以渲染一个包含多节点的结构块。例如：

<block wx:for="{
    {[1, 2, 3]}}">
  <view> {
  {index}}: </view>
  <view> {
  {item}} </view>
</block>

3、wx:key

如果列表中项目的位置会动态改变或者有新的项目添加到列表中，并且希望列表中的项目保持自己的特征和状态（如 input 中的输入内容，switch 的选中状态），需要使用 wx:key 来指定列表中项目的唯一的标识符。

wx:key 的值以两种形式提供

1. 字符串，代表在 for 循环的 array 中 item 的某个 property，该 property 的值需要是列表中唯一的字符串或数字，且不能动态改变。
2. 保留关键字 *this 代表在 for 循环中的 item 本身，这种表示需要 item 本身是一个唯一的字符串或者数字。

当数据改变触发渲染层重新渲染的时候，会校正带有 key 的组件，框架会确保他们被重新排序，而不是重新创建，以确保使组件保持自身的状态，并且提高列表渲染时的效率。

如不提供 wx:key࿰