周记杂货铺-Leo Zhou's Grocery Store

第一个demo

可同步参考官方文档：开始 | 微信开放文档 (qq.com)

注册小程序

需要注意：一个邮箱只能申请一个小程序

小程序管理后台

注册完毕后，会跳转到小程序管理后台

这是后续会经常访问的核心管理页面
在这里，可以做
-【项目人员管理】
-【程序版本控制】
-【用户协议管理】
-【开发配置项配置】
-【开放能力接入】
-【线上运营数据】
-【网页数据/性能分析】
等多个核心操作

刚开始，我们仅需要确认开发设置中的appId

小程序开发工具

官方文档：概览 | 微信开放文档 (qq.com)

访问官方的小程序开发工具页面
下载官方的IDE
安装完成后打开

在本地选择一个空目录，用于初始化创建项目
AppId填写上面我们在管理后台读取到的AppId

如果想开启一个不上线的测试项目，可以使用官方提供的测试号

选择合适的开发模板，即可初始化项目
官方开发工具会自动创建一个本地git
用于代码管理

创建完毕后
进入IDE页面
点击编译后
就可以预览项目效果了

IDE迁移为VSCODE

官方的IDE包含的功能和插件并不完整
代码自动补全也很有限
利用小程序开发工具创建项目后

可以将单纯的代码编写移到VSCODE中去
利用VSCODE的生态提高编码效率
小程序工具则负责模拟器、代码上传等独有的功能

要在VSCODE中开发微信小程序
可以安装以下插件

在VSCODE中移入代码文件夹，即可开始Coding

文件结构

项目创建后
拥有以下目录结构

app.js是整个应用的入口
用于store数据
处理应用声明周期

app.json中
进行程序配置
包含路由的注册、页面风格等配置
具体的配置项可以参考
小程序配置 / 全局配置 (qq.com)

project.config.json
是开发工具的共有配置
记录在开发工具中的一些设置项
比如单页配置等

project.private.config.json
同上，是私有配置
优先级高于公共配置

pages即页面
文件夹与下面标准的四个文件同名，均为短横线命名

pages同级可以创建api、utils等目录
抽取公共基础模块

小程序框架

可同步参考官方文档小程序框架 / 介绍 (qq.com)

多数问题可以参考教程 | 《小程序开发指南》 (qq.com)

运行环境

小程序的渲染层和逻辑层分别由2个线程管理：渲染层的界面使用了WebView 进行渲染；逻辑层采用JsCore线程运行JS脚本。一个小程序存在多个界面，所以渲染层存在多个WebView线程，这两个线程的通信会经由微信客户端（下文中也会采用Native来代指微信客户端）做中转，逻辑层发送网络请求也经由Native转发，小程序的通信模型下图所示。

运行机制

参考官方文档：小程序运行时 / 运行机制 (qq.com)

场景值

微信小程序有多种进入方式
为了区分这些进入方式
官方提供了场景值，来做区分
便于开发者针对不同的场景写对应的产品适配逻辑

部分截图，完整版访问官方文档场景值列表

程序语法

我们通过微信官方提供的模板
以最小案例来学习微信语法的基础

这是一个简单的表单页面
包含【上传头像】、【输入昵称】俩个简单功能

WXML

<!-- index.wxml -->

<navigation-bar title="Weixin" back="{{false}}" color="black" background="#FFF"></navigation-bar>

<scroll-view class="scrollarea" scroll-y type="list">

<view class="container">

<view class="userinfo">

<block>

<button class="avatar-wrapper" open-type="chooseAvatar" bind:chooseavatar="onChooseAvatar">

<image class="avatar" src="{{avatarUrl}}"></image>

</button>

<view class="nickname-wrapper">

<text class="nickname-label">昵称</text>

<input type="nickname" class="nickname-input" placeholder="请输入昵称" bind:change="onInputChange" />

</view>

</block>

</view>

</view>

</scroll-view>

这是上面案例的真实代码
相比HTML，有以下不同

1.WXML舍弃了基础的标签语法
而是通过封装好的组件来拼装页面

2.这些组件往往内置了多种功能和协议
比如button组件，通过添加open-type="chooseAvatar"属性来申明这是一个用于选择头像的按钮
当用户点击这个按钮时，会从页面底部弹出一个抽屉用于选择图片

当用户通过任一途径获取到图片后
通过约定的事件申明字段bind:chooseavatar，来表明是同目录下Page代码中onChooseAvatar来处理

可以看到，一个按钮通过指令关键字，就封装了一个复杂的图片选择功能

所以在开始编码前，了解每个组件的责任范围，是非常消耗学习成本，但不可避免的一件事

否则假如产品提出了上述需求，而你不知道button就可以处理这件事，会花费你很多额外的功夫

3.类似vue的模板语法
同样的，WXML中，通过{{}}符号来引用变量，模板中可以填写任意的变量表达式
也有类似v-if的wx:if语法存在
条件语法和循环语法和vue几乎相同

4.引用
WXML中也有组件的概念

主要有import和include俩种方式

import

<!-- item.wxml -->
<template name="item">
  <text>{{text}}</text>
</template>

<!-- other.wxml -->
<import src="item.wxml"/>
<template is="item" data="{{text: 'forbar'}}"/>

import作用域

<!-- A.wxml -->
<template name="A">
  <text> A template </text>
</template>

<!-- B.wxml -->
<import src="a.wxml"/>
<template name="B">
  <text> B template </text>
</template>

<!-- C.wxml -->
<import src="b.wxml"/>
<template is="A"/>  <!-- Error! Can not use tempalte when not import A. -->
<template is="B"/>

include
include 可以将目标文件除了 <template/> <wxs/> 外的整个代码引入，相当于是拷贝到 include 位置

<!-- index.wxml -->
<include src="header.wxml"/>
<view> body </view>
<include src="footer.wxml"/>

<!-- header.wxml -->
<view> header </view>

<!-- footer.wxml -->
<view> footer </view>

WXSS

和CSS几乎一样
但是还是存在些许差别

WXSS新增的内容
-【尺寸单位】
微信新增了类似rem的新尺寸rpx
-【样式导入】
类别CSS预处理器中的模块导入
便于抽取公共样式

WXSS存在的限制
-WXSS支持的选择器有限
具体列表参考官方文档

Page构造器

所有的页面都是一个page实例
类比vue2中组件选项的写法

有一点需要注意
微信小程序中methods包含的范围非常大
包含以下模块：
-【生命周期】
-【bind事件】
-【自定义子函数】

做好methods的管理是非常重要的
否则methods混乱，会对可读性造成非常大的影响

建议通过长行注释来分割区域
并约定命名方式来做区分
比如这样

同样的，抽取公共模块的重要性也相对提升
因为page中的代码越少
可读性就会显著增加

WXS

WXS是模板化的类JS语言，可以看做是微信中加以限制的JS语法
开发者可以新建一个WXS文件来写具体逻辑
然后在WXML中通过wxs标签引入，可以看做script标签

<!--wxml-->
<wxs module="m1">
var msg = "hello world";

module.exports.message = msg;
</wxs>

<view> {{m1.message}} </view>

通用逻辑可以放在WXS代码中，可以与Page配合使用
比如下面的例子

// page.js
Page({
  data: {
    array: [1, 2, 3, 4, 5, 1, 2, 3, 4]
  }
})

<!--wxml-->
<!-- 下面的 getMax 函数，接受一个数组，且返回数组中最大的元素的值 -->
<wxs module="m1">
var getMax = function(array) {
  var max = undefined;
  for (var i = 0; i < array.length; ++i) {
    max = max === undefined ?
      array[i] :
      (max >= array[i] ? max : array[i]);
  }
  return max;
}

module.exports.getMax = getMax;
</wxs>

<!-- 调用 wxs 里面的 getMax 函数，参数为 page.js 里面的 array -->
<view> {{m1.getMax(array)}} </view>

WXS采用单例模式，如果有多个页面引用，调用的都是一个模块对象

JS

与WXML同样的
微信内置了很多API
便于开发者调用微信功能
比如获取用户的地理位置
可以直接调用

wx.getLocation({
  type: 'wgs84',
  success: (res) => {
    var latitude = res.latitude // 纬度
    var longitude = res.longitude // 经度
  }
})

wx的多数API都是异步的
同步API一般会包含sync关键字
比如wx.setStorage和wx.setStorageSync

异步的API，都会通过success和fail的回调函数来传递调用结
果

很容易出现链式调用
但微信官方默认该种调用方式

需要注意，最好可以申明fail回调函数，或者将操作复杂的API包裹在try-catch中，便于捕获错误

差异&限制

-【运行限制】
基于安全考虑，小程序中不支持动态执行 JS 代码，即：

不支持使用 eval 执行 JS 代码
不支持使用 new Function 创建函数
new Function('return this')除外

-【标准 ECMAScript 支持】
小程序的 JS 执行环境在不同平台上的执行环境存在差异，因此导致不同平台对 ECMAScript 标准的支持存在差异。

小程序基础库为了尽量抹平这些差异，内置了一份 core-js Polyfill。core-js 可以将平台环境缺失的标准 API 补齐。

需要注意的是，平台对 ECMAScript 语法的支持差异无法抹平，当你需要使用一些高级语法时，如 async/await 时，则需要借助代码转换工具来支持这些语法。

-【无法被 Polyfill 的 API】
以下 API 在部分低版本客户端中无法使用，请注意尽量避免使用

Proxy 对象

-【Promise 时序差异】
由于实现原因与 iOS JavaScriptCore 限制，iOS 环境下的 Promise 是一个使用 setTimeout 模拟的 Polyfill。这意味着 Promise 触发的任务为普通任务，而非微任务，进而导致 在 iOS 下的 Promise 时序会和标准存在差异。

var arr = []

setTimeout(() => arr.push(6), 0)
arr.push(1)
const p = new Promise(resolve => {
  arr.push(2)
  resolve()
})
arr.push(3)
p.then(() => arr.push(5))
arr.push(4)
setTimeout(() => arr.push(7), 0)

setTimeout(() => {
  // 应该输出 [1,2,3,4,5,6,7]
  // 在 iOS 小程序环境，这里会输出 [1,2,3,4,6,5,7]
  console.log(arr)
}, 1000)

关于普通任务和微任务的区别可以查看这篇文章

页面栈&路由

小程序正常的页面跳转，上一个页面并不会关闭，而是会被缓存在页面栈中

用户可以通过头部导航栏的返回按钮返回上一个页面

IOS和安卓的返回手势、页面行为会有所区别

页面栈中最多存储10个页面，可以简单理解为一个队列

webview被看做一个页面，即webview内部H5的路由活动与小程序页面的路由活动是分离的

2~5个页面可以用官方提供的tabbar封装为tab页面
微信小程序路由机制.drawio.png

tabbar示例：

微信官方提供了多个路由api，便于开发者设计页面栈行为

wx.switchTab
从其他页面切换到tab页面时，需要使用switchTabAPI
该api会关闭其余所有的非tab页面

wx.reLaunch
关闭所有页面，跳转到某个页面
一般用于重载应用的场景
wx.redirectTo
关闭当前页面，跳转到应用内的某个页面。但是不允许跳转到 tabbar 页面。即只能在非tab页面中跳转。
一般用于销毁中间态的页面，比如【登录确认】页面等场景
wx.navigateTo
跳转到某个页面，保留当前页面在页面栈内，用户可以通过导航栏back按钮返回到跳转前的页面
`wx.navigateBack
手动调用API，返回页面栈的上一个页面

由于页面栈的存在，各个页面跳转时，需要额外考虑页面行为
是否需要关闭页面，或者是否需要重载应用

鉴权&登录

参考官方文档：接口调用凭证 | 微信开放文档 (qq.com)

微信官方对于用户隐私信息是高度敏感的
所以任何用户信息都需要通过微信的登录/鉴权机制来获取
因为前端是绝对不安全的
且几乎全部的小程序都会记录用户信息
所以小程序的开发一定伴随着后端工作量

一类信息的相关接口会被打包为一个scope
小程序需要采集用户的某类信息时
需要用户授权该scope

通用登录流程如下：

为应用配置密钥与公钥，以此来保障开发者应用和微信开放平台交互的安全性。

小程序开发后台

上文已经说过，小程序开发后台是跨越整个项目周期的关键后台
可以在这个后台进行多种关键操作
这里介绍小程序后台的部分关键操作

首页

展示简单的数据分析
详尽的数据可以跳转到微信官方提供的分析页面查看

【重要】管理

版本管理

在微信开发者工具里
点击版本上传后

版本会同步开发版本列表中
在这里，相关管理人员
可以进行【开发版本】、【体验版本】、【线上版本】的管理
【灰度设置】和【上线审核】等关键操作都在本页面进行

成员管理

给项目成员分配权限
设置体验成员名单

体验成员可以访问体验版
且优先适配线上版本的灰度名额

用户反馈

用户的留言、建议、反馈

付费管理

微信的部分官方API服务是需要付费的
这里显示额度和费用

门店管理

略

统计

参考分析页面

分析页面和小程序开发后台的鉴权是俩套单独的体系

功能

使用微信官方提供的功能服务
目前暂未详细体验，后续有经验后补充相关资料

【重要】开发

开发管理

该模块非常重要，涉及小程序发布上线等多个相关操作
详细说明如下

运维中心

目前已经前置We分析页面，此处不单独展开描述

监控告警

同上

开发设置

！！！！！！重要

开发者ID

在这里可以获取AppID，AppID是小程序的身份证，会用在各种地方
AppSecret，小程序密钥可以多次生成，但只有第一次的时候会明文出现，后续【不可查看】，所以一定要保存好

如果密钥丢失，重置后，所有依赖密钥的接口、服务等都需要重新部署

小程序代码上传

服务器域名

所有涉及的资源、接口等域名的白名单

业务域名

如果内嵌了web-view组件，web-view中的url都需要在这里填写

业务域名根目录需要添加校验文件

其他

开发工具

开发能力

开发者工具

云服务

成长

小程序评测

评测优秀有奖励：

违规记录

推广

略

第三方服务

【重要】设置

基本设置

基本信息

账号信息

隐私与安全

服务内容申明

版本设置

第三方设置

关联设置

关注公众号

发布流程

测试

在模拟器和实机上进行测试

IOS和安卓，兼容性测试
基础库版本测试
交互测试
- 页面栈行为
  是否丢失了关键页面，或者用户可以返回中间态页
- 产品功能
- 前后台切换
  比如播放音乐的小程序，手机切换到其他APP上时，音乐是否暂停。切回小程序后，音乐是否继续播放等。

缓存测试
- 老用户是否需要重复授权/加载信息

体验版

模拟器和实机上测试完毕后
可以上传体验版本
让产品参与人员多方位、多机型、多环境的测试功能

信息填写

小程序上线需要填写多个关键信息
总结起来
就是确认以下内容

开发-开发管理-开发设置
设置-基本设置
运营规范

审核

当上述信息填写的7788后
在【版本管理】中，选择【开发版本（包含体验版）】，并提交审核
审核失败后，可以【申诉】或【改正】
直到审核通过

审核是人工审核，标准不一
同样的程序版本，可能偶尔能过，偶尔被卡

上线

版本通过审核后，可以选择发布上线
并选择灰度比例
灰度有限覆盖体验名单
一般会在15个工作日放量完毕
且管理者可以在发布后调整灰度

完全放量完毕后，成功发布版本

经验教训

需要注意以下点

微信的开发文档很简略，有时候会省略关键信息
微信的运营策略更新的很快，会导致上周还能发的功能这周违规
开发社区中的信息很繁杂，有些人是基于旧版本回答的，有些人的回答是片面甚至错误的
审核可能会遇到很多问题，开发周期不要跨太长，可以拆分为多个小版本发布

web-view

鉴权

官方文档中，给出了web-view中，通过JSSDK调用的几个场景
但写的很简短
且遗漏了重要的鉴权内容

JSSDK中虽然有描述鉴权的内容
但是JSSDK的文档是挂在公众号下面的

坑1：部分接口需要鉴权

实际上web-view文档中
【相关接口1】关于路由跳转部分的API是不需要鉴权的
【相关接口2】关于媒体部分的API均需要鉴权
但是这一点并没有在web-view的文档中申明

导致可能会出现以下场景
调用【相关接口1-路由跳转】，成功执行
调用【相关接口2-上传图片】，功能闪退，且没有报错提示！！！

坑2：鉴权的主体是公众号，且需要和小程序关联

从社区中的部分答案中，才能了解到
必须使用wx.configAPI进行鉴权
且JSSDK文档中也阐述了使用步骤

但是！！！！没有地方提到，小程序必须要关联公众号
且wx.config中的AppID参数应该用公众号的，而不能用小程序的
如果用了小程序的AppID，会报错【invalid url domain】
从而误导开发者检查自己的域名设置

总结：使用【相关接口2】的API需要鉴权，鉴权需要挂靠公众号

限制

不允许登录

不允许分享

web-view中不允许调用分享相关的API，所以任何带有分享的页面都应该用原生语法实现
如果是web-view的页面中，携带了一个分享按钮，可以考虑调整分享的交互链路

不允许自定义导航栏

web-view中内嵌的H5，可能是多路由的
用户对于webview和小程序原生是无感知的
从交互习惯上来说，用户期望导航栏左上角的返回按钮同样可以应用到web-view上
但是在微信框架上，web-view实际上是一个页面
且web-view上不允许自定义导航栏
所以web-view需要内嵌新的导航栏或者back按钮

安卓的homebar貌似可以适配web-view的路由，但是IOS没有homebar，所以还是要有实体按钮

不允许调用富媒体

所有关于富媒体的功能，必须要用微信原生实现

案例1：图片上传

正常的H5页面中，给定一个type='file'的input标签，然后在change事件中将文件上传给后端接口即可

但是在web-view中
2019年之前的基础库版本，是允许开发者调用input标签来实现该功能的（即H5的方案）

但是后来的基础库版本中，用户调用input标签会闪退，并重置web-view中内嵌H5的路由。

且不同的设备端表现不一致，安卓机上的表现为，点击input后web-view重置路由，IOS上的表现为，用户点击input可以调起相册，并选择图片，当用户在相册页面点击确认按钮后，web-view才重置路由

虽然社区中，官方多次回复已修正，即允许input的方案，但实际上还是有问题

目前需要使用JSSDK中的chooseImage和getLocalImgDataAPI配合使用来实现图片上传功能

案例2：PDF下载

JSSDK提供的媒体能力有限
比如没有API支持PDF文件的下载
如果想要实现PDF的下载
必须先获取到PDF的base64
然后传递给原生页面
在原生页面中调用wx.writeFileAPI将文件写入本地缓存
然后通过wx.openDocumentAPI打开文档预览页面
用户可以在预览页面的菜单中选择文件下载