目录结构

微信小程序包含一个描述整体程序的 app 和多个描述各自页面的 page

一个微信小程序主体部分由三个文件组成,必须放在项目的根目录,如下:

文件 必需 作用
app.js 微信小程序逻辑
app.json 微信小程序公共配置
app.wxss 微信小程序公共样式表

一个微信小程序页面由四个文件组成,分别是:

文件类型 必需 作用
js 页面逻辑
wxml 页面结构
json 页面配置
wxss 页面样式表

注意:为了方便开发者减少配置项,描述页面的四个文件必须具有相同的路径与文件名。

允许上传的文件

在项目目录中,以下文件会经过编译,因此上传之后无法直接访问到:.js、app.json、.wxml、*.wxss(其中 wxml 和 wxss 文件仅针对在 app.json 中配置了的页面)。除此之外,只有后缀名在白名单内的文件可以被上传,不在白名单列表内文件在开发工具能被访问到,但无法被上传。具体白名单列表如下:

  1. wxs
  2. png
  3. jpg
  4. jpeg
  5. gif
  6. svg
  7. json
  8. cer
  9. mp3
  10. aac
  11. m4a
  12. mp4
  13. wav
  14. ogg
  15. silk
  16. wasm
  17. br
  18. cert

全局配置

微信小程序根目录下的 app.json 文件用来对微信小程序进行全局配置,决定页面文件的路径、窗口表现、设置网络超时时间、设置多 tab 等。

完整配置项说明请参考微信小程序全局配置

以下是一个包含了部分常用配置选项的 app.json

{
  "pages": [
    "pages/index/index",
    "pages/logs/index"
  ],
  "window": {
    "navigationBarTitleText": "Demo"
  },
  "tabBar": {
    "list": [{
      "pagePath": "pages/index/index",
      "text": "首页"
    }, {
      "pagePath": "pages/logs/index",
      "text": "日志"
    }]
  },
  "networkTimeout": {
    "request": 10000,
    "downloadFile": 10000
  },
  "debug": true
}

完整配置项说明请参考微信小程序全局配置

页面配置

每一个微信小程序页面也可以使用同名 .json 文件来对本页面的窗口表现进行配置,页面中配置项会覆盖 app.jsonwindow 中相同的配置项。

完整配置项说明请参考微信小程序页面配置

例如:

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

目录结构

微信小程序包含一个描述整体程序的 app 和多个描述各自页面的 page

一个微信小程序主体部分由三个文件组成,必须放在项目的根目录,如下:

文件 必需 作用
app.js 微信小程序逻辑
app.json 微信小程序公共配置
app.wxss 微信小程序公共样式表

一个微信小程序页面由四个文件组成,分别是:

文件类型 必需 作用
js 页面逻辑
wxml 页面结构
json 页面配置
wxss 页面样式表

注意:为了方便开发者减少配置项,描述页面的四个文件必须具有相同的路径与文件名。

允许上传的文件

在项目目录中,以下文件会经过编译,因此上传之后无法直接访问到:.js、app.json、.wxml、*.wxss(其中 wxml 和 wxss 文件仅针对在 app.json 中配置了的页面)。除此之外,只有后缀名在白名单内的文件可以被上传,不在白名单列表内文件在开发工具能被访问到,但无法被上传。具体白名单列表如下:

  1. wxs
  2. png
  3. jpg
  4. jpeg
  5. gif
  6. svg
  7. json
  8. cer
  9. mp3
  10. aac
  11. m4a
  12. mp4
  13. wav
  14. ogg
  15. silk
  16. wasm
  17. br
  18. cert

全局配置

微信小程序根目录下的 app.json 文件用来对微信小程序进行全局配置,决定页面文件的路径、窗口表现、设置网络超时时间、设置多 tab 等。

完整配置项说明请参考微信小程序全局配置

以下是一个包含了部分常用配置选项的 app.json

{
  "pages": [
    "pages/index/index",
    "pages/logs/index"
  ],
  "window": {
    "navigationBarTitleText": "Demo"
  },
  "tabBar": {
    "list": [{
      "pagePath": "pages/index/index",
      "text": "首页"
    }, {
      "pagePath": "pages/logs/index",
      "text": "日志"
    }]
  },
  "networkTimeout": {
    "request": 10000,
    "downloadFile": 10000
  },
  "debug": true
}

完整配置项说明请参考微信小程序全局配置

页面配置

每一个微信小程序页面也可以使用同名 .json 文件来对本页面的窗口表现进行配置,页面中配置项会覆盖 app.jsonwindow 中相同的配置项。

完整配置项说明请参考微信小程序页面配置

例如:

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

框架

微信小程序开发框架的目标是通过尽可能简单、高效的方式让开发者可以在微信中开发具有原生 APP 体验的服务。

整个微信小程序框架系统分为两部分:逻辑层(App Service)和 视图层(View)。微信小程序提供了自己的视图层描述语言 WXMLWXSS,以及基于 JavaScript 的逻辑层框架,并在视图层与逻辑层间提供了数据传输和事件系统,让开发者能够专注于数据与逻辑。

响应的数据绑定

框架的核心是一个响应的数据绑定系统,可以让数据与视图非常简单地保持同步。当做数据修改的时候,只需要在逻辑层修改数据,视图层就会做相应的更新。

通过这个简单的例子来看:

在开发者工具中预览效果

<!-- This is our View -->
<view> Hello {{name}}! </view>
<button bindtap="changeName"> Click me! </button>
// This is our App Service.
// This is our data.
var helloData = {
  name: 'Weixin'
}

// Register a Page.
Page({
  data: helloData,
  changeName: function(e) {
    // sent data change to view
    this.setData({
      name: 'MINA'
    })
  }
})
  • 开发者通过框架将逻辑层数据中的 name 与视图层的 name 进行了绑定,所以在页面一打开的时候会显示 Hello Weixin!
  • 当点击按钮的时候,视图层会发送 changeName 的事件给逻辑层,逻辑层找到并执行对应的事件处理函数;
  • 回调函数触发后,逻辑层执行 setData 的操作,将 data 中的 nameWeixin 变为 MINA,因为该数据和视图层已经绑定了,从而视图层会自动改变为 Hello MINA!

页面管理

框架 管理了整个微信小程序的页面路由,可以做到页面间的无缝切换,并给以页面完整的生命周期。开发者需要做的只是将页面的数据、方法、生命周期函数注册到 框架 中,其他的一切复杂的操作都交由 框架 处理。

基础组件

框架 提供了一套基础的组件,这些组件自带微信风格的样式以及特殊的逻辑,开发者可以通过组合基础组件,创建出强大的微信小程序

丰富的 API

框架 提供丰富的微信原生 API,可以方便的调起微信提供的能力,如获取用户信息,本地存储,支付功能等。

场景值

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

场景值用来描述用户进入微信小程序的路径。完整场景值的含义请查看场景值列表。

由于Android系统限制,目前还无法获取到按 Home 键退出到桌面,然后从桌面再次进微信小程序的场景值,对于这种情况,会保留上一次的场景值。

获取场景值

开发者可以通过下列方式获取场景值:

  • 对于微信小程序,可以在 ApponLaunchonShow,或wx.getLaunchOptionsSync 中获取上述场景值。
  • 对于小游戏,可以在 wx.getLaunchOptionsSync 和 wx.onShow 中获取上述场景值

返回来源信息的场景

部分场景值下还可以获取来源应用、公众号或微信小程序的appId。获取方式请参考对应API的参考文档。

场景值 场景 appId含义
1020 公众号 profile 页相关微信小程序列表 来源公众号
1035 公众号自定义菜单 来源公众号
1036 App 分享消息卡片 来源App
1037 微信小程序打开微信小程序 来源微信小程序
1038 从另一个微信小程序返回 来源微信小程序
1043 公众号模板消息 来源公众号
1069 移动应用 来源App

逻辑层 App Service

微信小程序开发框架的逻辑层使用 JavaScript 引擎为微信小程序提供开发 JavaScript 代码的运行环境以及微信小程序的特有功能。

逻辑层将数据进行处理后发送给视图层,同时接受视图层的事件反馈。

开发者写的所有代码最终将会打包成一份 JavaScript 文件,并在微信小程序启动的时候运行,直到微信小程序销毁。这一行为类似 ServiceWorker,所以逻辑层也称之为 App Service。

JavaScript 的基础上,我们增加了一些功能,以方便微信小程序的开发:

  • 增加 AppPage 方法,进行程序注册和页面注册。
  • 增加 getAppgetCurrentPages 方法,分别用来获取 App 实例和当前页面栈。
  • 提供丰富的 API,如微信用户数据,扫一扫,支付等微信特有能力。
  • 提供模块化能力,每个页面有独立的作用域。

注意:微信小程序框架的逻辑层并非运行在浏览器中,因此 JavaScript 在 web 中一些能力都无法使用,如 windowdocument 等。

注册微信小程序

每个微信小程序都需要在 app.js 中调用 App 方法注册微信小程序实例,绑定生命周期回调函数、错误监听和页面不存在监听函数等。

详细的参数含义和使用请参考 App 参考文档 。

// app.js
App({
  onLaunch (options) {
    // Do something initial when launch.
  },
  onShow (options) {
    // Do something when show.
  },
  onHide () {
    // Do something when hide.
  },
  onError (msg) {
    console.log(msg)
  },
  globalData: 'I am global data'
})

整个微信小程序只有一个 App 实例,是全部页面共享的。开发者可以通过 getApp 方法获取到全局唯一的 App 实例,获取App上的数据或调用开发者注册在 App 上的函数。

// xxx.js
const appInstance = getApp()
console.log(appInstance.globalData) // I am global data