微信小程序开发文档

开发者可使用微信客户端(6.7.2 及以上版本)扫码下方小程序码，体验小程序。1 源码查看： 查看小程序示例源码

Canvas 画布 所有在 canvas 中的画图必须用 JavaScript 完成： WXML：（我们在接下来的例子中如无特殊声明都会用这个 WXML 为模板，不再重复） <canvas canvas-id="myCanvas" style="border: 1px solid;"/> JS：（我们在接下来的例子中会将 JS 放在 onReady 中） const ctx = wx.createCanvasContext('myCanvas') ctx.setFillStyle('red') ctx.fillRect(10, 10, 150, 75) ctx.draw() 第一步：创建一个 Canvas 绘图上下文 首先，我们需要创建一个 Canvas 绘图上下文 CanvasContext。 CanvasContext 是小程序内建的一个对象，有一些绘图的方法： const ctx = wx.createCanvasContext('myCanvas') 第二步：使用 Canvas 绘图上下文进行绘图描述 接着，我们来描述要在 Canvas 中绘制什么内容。 设置绘图上下文的填充色为红色： ctx.setFillStyle('red') 用 fillRect(x, y, width, height) 方法画一个矩形，填充为刚刚设置的红色： ctx.fillRect(10, 10, 150, 75) 第三步：画图 告诉 canvas 组件你要将刚刚的描述绘制上去： ctx.draw() 结果： 坐标系 canvas 是在一个二维的网格当中。左上角的坐标为(0, 0)。 在上一节，我们用了这个方法 fillRect(0, 0, 150, 75)。 它的含义为：从左上角(0, 0)开始，画一个150 x 75px 的矩形。 代码示例 我们可以在 canvas 中加上一些事件，来观测它的坐标系 <canvas canvas-id="myCanvas" style="margin: 5px; border:1px solid #d3d3d3;" bindtouchstart="start" bindtouchmove="move" bindtouchend="end"/> <view hidden="{{hidden}}"> Coordinates: ({{x}}, {{y}}) </view> Page({ data: { x: 0, y: 0, hidden: true }, start (e) { this.setData({ hidden: false, x: e.touches[0].x, y: e.touches[0].y }) }, move (e) { this.setData({ x: e.touches[0].x, y:...

目录结构 小程序包含一个描述整体程序的 app 和多个描述各自页面的 page。 一个小程序主体部分由三个文件组成，必须放在项目的根目录，如下： 文件 必需 作用 app.js 是 小程序逻辑 app.json 是 小程序公共配置 app.wxss 否 小程序公共样式表 一个小程序页面由四个文件组成，分别是： 文件类型 必需 作用 js 是 页面逻辑 wxml 是 页面结构 json 否 页面配置 wxss 否 页面样式表 注意：为了方便开发者减少配置项，描述页面的四个文件必须具有相同的路径与文件名。 允许上传的文件 在项目目录中，以下文件会经过编译，因此上传之后无法直接访问到：.js、app.json、.wxml、*.wxss（其中 wxml 和 wxss 文件仅针对在 app.json 中配置了的页面）。除此之外，只有后缀名在白名单内的文件可以被上传，不在白名单列表内文件在开发工具能被访问到，但无法被上传。具体白名单列表如下： wxs png jpg jpeg gif svg json cer mp3 aac m4a mp4 wav ogg silk

五、视觉规范 1. 字体规范 微信内字体的使用与所运行的系统字体保持一致，常用字号为20，18，17，16，14，13，11（pt），使用场景具体如下： 字体颜色 主内容Black黑色，次要内容Grey灰色；时间戳与表单缺省值Light灰色；大段的说明内容而且属于主要内容用Semi黑； 蓝色为链接用色，绿色为完成字样颜色，红色为出错用色Press与Disable状态分别降低透明度为20%与10%； 2. 列表视觉规范 3. 表单输入视觉规范 4. 按钮使用原则 5. 图标使用原则 资源下载 为方便设计师进行设计，微信提供一套可供Web设计和小程序使用的基础控件库；同时提供方便开发者调用的资源。 WeUI_sketch组件库 下载 WeUI_PS组件库 下载 小程序标志 下载 预览地址：https://weui.io

三、便捷优雅 从PC时代的物理键盘鼠标到移动端时代手指，虽然输入设备极大精简，但是手指操作的准确性却大大不如键盘鼠标精确。为了适应这个变化，需要开发者在设计过程中充分利用手机特性，让用户便捷优雅的操控界面。 1. 减少输入 由于手机键盘区域小且密集，输入困难的同时还易引起输入错误，因此在设计小程序页面时因尽量减少用户输入，利用现有接口或其他一些易于操作的选择控件来改善用户输入的体验。 例如下图中，在添加银行卡时，采用摄像头识别接口来帮助用户输入。除此之外微信团队还对外开放例如地理位置接口等多种微信小程序接口，充分利用这些接口将大大提高用户输入的效率和准确性，进而优化体验。 除了利用接口外，在不得不让用户进行手动输入时，应尽量让用户做选择而不是键盘输入。一方面，回忆易于记忆，让用户在有限的选项中做选择通常来说是容易于完全靠记忆输入；另一方面，仍然是考虑到手机键盘密集的单键输入极易造成输入错误。例如图中，在用户搜索时提供搜索历史快捷选项将帮助用户快速进行搜索，而减少或避免不必要的键盘输入。 2. 避免误操作 因为在手机上我们通过手指触摸屏幕来操控界面，手指的点击精确度远不如鼠标，因此在设计页面上需点击的控件时，需要充分考虑到其热区面积，避免由于可点击区域过小或过于密集而造成误操作。当简单的将原本在电脑屏幕上使用的界面不做任何适配直接移植到手机上时，往往就容易出现这样的问题。由于手机屏幕分辨率各不相同，因此最适宜点击像素尺寸也不完全一致，但换算成物理尺寸后大致是在7mm-9mm之间。在微信提供的标准组件库中，各种控件元素均已考虑到了页面点击效果以及不同屏幕的适配，因此再次推荐使用或模仿标准控件尺寸进行设计。 3. 利用接口提升性能 微信设计中心已推出了一套网页标准控件库，包括 sketch设计控件库 和 Photoshop设计控件库，后续还将完善小程序组件，这些控件都已充分考虑了移动端页面的特点，能够保证其在移动端页面上的可用性和操作性能； 同时微信开发团队也在不断完善和扩充微信小程序接口，并提供微信公共库，利用这些资源不但能够为用户提供更加快捷的服务，而且对页面性能的提高有极大作用，无形之中提升了用户体验。

二、清晰明确 一旦用户进入我们的小程序页面，就有责任和义务清晰明确告知用户身在何处、又可以往何处去，确保用户在页面中游刃有余地穿梭而不迷路，这样才能为用户提供安全的愉悦的使用体验。 1. 导航明确，来去自如 导航是确保用户在网页中浏览跳转时不迷路的最关键因素。导航需要告诉用户，当前在哪，可以去哪，如何回去等问题。首先在微信系统内的所有小程序的全部页面，均会自带微信提供的导航栏，统一解决当前在哪，如何回去的问题。在微信层级导航保持体验一致，有助于用户在微信内形成统一的体验和交互认知，无需在各小程序和其他微信页面的切换中新增学习成本或改变使用习惯。 微信导航栏 微信导航栏，直接继承于客户端，除导航栏颜色之外，开发者无需亦不可对其中的内容进行自定义。但开发者需要规定小程序各个页面的跳转关系，让导航系统能够以合理的方式工作。 微信导航栏分为导航区域、标题区域以及操作区域。其中导航区控制程序页面进程。目前导航栏分深浅两种基本配色。 导航区（iOS） 微信进入小程序的第一个页面，导航区通常只有一个操作——“返回”，即返回进入小程序前的微信页面。 进入小程序后的次级页面，导航区的操作为——“返回” 和“关闭”。 “返回”，即返回上一级小程序界面或微信界面。“关闭”，即在当前界面直接退出小程序，回到进入小程序前的微信页面。 导航区（Android） 导航区仅存在唯一操作——直接退出小程序，回到进入小程序前的微信或系统桌面，安卓手机自带的硬件返回键执行返回上一级页面的操作。 安卓导航存在一类特殊情况：当用户通过操作区的菜单将小程序添加至安卓桌面，并从安卓桌面打开小程序时，小程序的首页，不展示导航按钮。仅展示小程序标题和操作区。小程序次级页面，导航区只有返回上一级页面的操作，而点击安卓手机自带的硬件返回键也起到相同作用。 微信导航栏自定义颜色规则（iOS和Android） 小程序导航栏支持基本的背景颜色自定义功能，选择的颜色需要在满足可用性前提下，和谐搭配微信提供的两套主导航栏图标。建议参考以下选色效果： 选色方案示例 页面内导航 开发者可根据自身功能合计需要在页面内添加自有导航。并保持不同页面间导航一致。但是受限于手机屏幕尺寸的限制，小程序页面的导航应尽量简单，若仅为一般线性浏览的页面建议仅使用微信导航栏即可。 开发者可选择小程序页面添加标签分页（Tab）导航。标签分页栏可固定在页面顶部或者底部，便于用户在不同的分页间做切换。标签数量不得少于2个，最多不得超过5个，为确保点击区域，建议标签数量不超过4项。一个页面也不应出现一组以上的标签分页栏。 其中小程序首页可选择微信提供的原生底部标签分页样式，该样式仅供小程序首页使用。开发时可自定义图标样式、标签文案以及文案颜色等，具体设置项如图标尺寸等参考可参考开发文档和WeUI基础控件库。 顶部标签分页栏颜色可自定义。在自定义颜色选择中，务必注意保持分页栏标签的可用性、可视性和可操作性。 2. 减少等待，反馈及时 页面的过长时间的等待会引起用户的不良情绪，使用微信小程序项目提供的技术已能很大程度缩短等待时间。即便如此，当不可避免的出现了加载和等待的时候，需要予以及时的反馈以舒缓用户等待的不良情绪。 启动页加载 小程序启动页是小程序在微信内一定程度上展现品牌特征的页面之一。本页面将突出展示小程序品牌特征和加载状态。启动页除品牌标志（Logo）展示外，页面上的其他所有元素如加载进度指示，均由微信统一提供且不能更改，无需开发者开发。 页面下拉刷新加载 在微信小程序内，微信提供标准的页面下拉刷新加载能力和样式，开发者无需自行开发。 页面内加载反馈 开发者可在小程序里自定义页面内容的加载样式。建议不管是使用在局部还是全局加载，自定义加载样式都应该尽可能简洁，并使用简单动画告知用户加载过程。开发者也可以使用微信提供的，统一的页面加载样式，如图中例所示。 模态加载 模态的加载样式将覆盖整个页面的，由于无法明确告知具体加载的位置或内容将可能引起用户的焦虑感，因此应谨慎使用。除了在某些全局性操作下不要使用模态的加载。 局部加载反馈 局部加载反馈即只在触发加载的页面局部进行反馈，这样的反馈机制更加有针对性，页面跳动小，是微信推荐的反馈方式。例如： 加载反馈注意事项 若载入时间较长，应提供取消操作，并使用进度条显示载入的进度。 载入过程中，应保持动画效果；无动画效果的加载很容易让人产生该界面已经卡死的错觉。 不要再同一个页面使用超过1个加载动画。 结果反馈 除了在用户等待的过程中需予以及时反馈外，对操作的结果也需要予以明确反馈。根据实际情况看，可选择不同的结果反馈样式。对于页面局部的操作，可在操作区域予以直接反馈，对于页面级操作结果，可使用弹出式提示（Toast）、模态对话框或结果页面展示。 页面局部操作结果反馈 对于页面局部的操作，可在操作区域予以直接反馈，例如点击多选控件前后如下图。对于常用控件，微信设计中心已提供控件库及WeUI控件库，其中的控件都已提供完整的操作反馈。 页面全局操作结果——弹出式提示（Toast） 弹出式提示（Toast）适用于轻量级的成功提示，1.5秒后自动消失，并不打断流程，对用户影响较小，适用于不需要强调的操作提醒，例如成功提示。特别注意该形式不适用于错误提示，因为错误提示需明确告知用户，因而不适合使用一闪而过的弹出式提示。 页面全局操作结果——模态对话框 对于需要用户明确知晓的操作结果状态可通过模态对话框来提示，并可附带下一步操作指引。 页面全局操作结果——结果页 对于操作结果已经是当前流程的终结的情况，可使用操作结果页来反馈。这种方式最为强烈和明确的告知用户操作已经完成，并可根据实际情况给出下一步操作的指引。 3. 异常可控，有路可退 在设计任何的任务和流程时，异常状态和流程往往容易被忽略，而这些异常场景往往是用户最为沮丧和需要帮助的时候，因此需要格外注意异常状态的设计，在出现异常时予以用户必要的状态提示，并告知解决方案，使其有路可退。 要杜绝异常状态下，用户莫名其妙又无处可去，停滞在某一个页面的情况。上文中所提到的模态对话框和结果页面都可作为异常状态的提醒方式。除此之外，在表单页面中尤其是表单项较多的页面中，还应明确指出出错项目，以便用户修改。 异常状态——表单出错 表单报错，在表单顶部告知错误原因，并标识出错误字段提示用户修改。

服务平台 API 2.9.4 API 均在 wx.serviceMarket 对象下。invokeService 方法可以通过兼容性配置，无需依赖 2.9.4 即可使用，配置方法见底部 兼容性配置 章节说明。 从 2.11.1 开始，插件内也可以使用 wx.serviceMarket API，在调用时，消耗的是宿主的资源而不是插件方的资源。 invokeService 调用服务提供商提供的 API 入参 接收一个对象，对象下有如下定义的字段： 字段名 类型 必填 默认值 说明 service string 是 服务提供商 ID api string 是 是 服务 API 名 data Object 否 传递给服务 API 的 JSON 数据 返回值 返回一个 Promise，如调用失败，则 reject 一个 Error 对象，如调用成功，则 resolve 结果为如下定义的对象： 字段名 类型 必填 默认值 说明 data Object String 是 在 data 中，如果服务提供商要求其中某个字段为文件 URL、并且此时希望将本地文件/大数据上传成 URL 作为字段值传入，则可以使用我们提供的 CDN 方法对相应值进行标记，微信会自动在调用服务 API 的时候将其转换成 CDN URL 给到服务提供方。 错误码 错误码 含义 -1 入参错误 -2 调用失败 -3 逻辑失败 -6 appid错误 -7 api信息错误 -8 api信息错误 -10 api扣费失败 -11 命中频率 示例代码 1: OCR 从手机选择图片后，调用 OCR 服务。OCR 服务要求调用方传图片，接收图片的方式是图片 URL。OCR 服务要求调用方的 data 结构如下： 字段名 类型 必填 默认值 说明 img_url string 是 图片 URL data_type number 是 固定为 3，表示 URL 形式的图片 ocr_type number 是 OCR 类型，1 为身份证识别 OCR 的接口需要传入图片 URL，如果需要将手机本地选择的图片上传转换成 URL，可以使用 CDN 方法对文件路径进行标记（或用任意的存储服务和自建的存储服务，也可以使用云开发的云文件存储服务，但都没有 CDN 方法便捷），以下给出使用 CDN 方法的示例： // 选择图片 wx.chooseImage({ count: 1, success: async function(res)...

OCR 支持 查看本文档前，建议先阅读《小程序插件文档》 体验工具小程序 —— 该插件完全使用此插件实现。该插件支持身份证识别，行驶证识别和银行卡识别。 小程序码  申请权限 请在小程序后台搜索本插件（AppID=wx4418e3e031e551be） 设置-第三方服务-添加插件 调用限制 来开放社区购买，appid内的额度在插件、API、服务市场是通用的 调用方式 app.json中增加声明引入插件 version选择最新的 "pages": [], "plugins": { "ocr-plugin": { "version": "3.0.2", "provider": "wx4418e3e031e551be" } } } 页面的json也要增加声明 { "usingComponents": { "ocr-navigator": "plugin://ocr-plugin/ocr-navigator" } } 组件 对外暴露自定义组件，UI载体为button（可样式自定义） 封装了 参数 属性名 类型 默认值 是否必填 说明 onSuccess HandleEvent 是 接口调用成功的回调函数 certificateType String idCard 否 证书类型包含四种 身份证：idCard、驾驶证：drivingLicense、银行卡：bankCard、营业执照：businessLicense 返回结果中image_path 是用户证件照片的临时地址，开发者可以通过image_path拿到用户的证件照片 以下具体说明四种证件类型的使用方法 1、身份证 certificateType=’idCard’ 或 无certificateType这个参数 属性名 类型 默认值 是否必填 说明 onSuccess HandleEvent 是 接口调用成功的回调函数 certificateType String idCard 否 证书类型包含四种 身份证：idCard、驾驶证：drivingLicense、银行卡：bankCard、营业执照：businessLicense opposite Boolean true 否 是否显示身份证的反面，默认为 true显示反面 onSuccess 参数 e.detail 参考身份证返回结果实例 示例代码1 <ocr-navigator bind:onSuccess="success" certificateType="idCard" opposite="{{false}}"> <button type="primary">身份证正面识别</button> </ocr-navigator> <ocr-navigator bind:onSuccess="success" certificateType="idCard" opposite="{{true}}"> <button type="primary">身份证反面识别</button> </ocr-navigator> /** wxss **/ /*自定义按钮样式*/ .ocr-wrapper { margin: 40rpx auto; width: 375rpx; } .intro { margin: 40rpx; } 身份证返回结果实例 {"type":0,"name":{"text":"张三","pos":{"left_top":{"x":98.7780914307,"y":40.9823074341},"right_top":{"x":172.311325073,"y":41.2864379883},"right_bottom":{"x":172.190856934,"y":64.9047088623},"left_bottom":{"x":98.6072158813,"y":64.5630187988}},"label":[]},"gender":{"text":"男","pos":{"left_top":{"x":101.035919189,"y":80.7537384033},"right_top":{"x":121.421043396,"y":80.7818603516},"right_bottom":{"x":121.264938354,"y":101.272567749},"left_bottom":{"x":100.882026672,"y":101.244766235}},"label":[]},"nationality":{"text":"汉","pos":{"left_top":{"x":201.881393433,"y":81.7225189209},"right_top":{"x":222.004470825,"y":81.6959762573},"right_bottom":{"x":221.899169922,"y":101.255821228},"left_bottom":{"x":201.765304565,"y":101.291915894}},"label":[]},"address":{"text":"广州市天河区五山路483号xxxxxxxxx","pos":{"left_top":{"x":95.5787811279,"y":150.794250488},"right_top":{"x":310.358947754,"y":151.617507935},"right_bottom":{"x":310.004699707,"y":220.222885132},"left_bottom":{"x":95.1295013428,"y":219.552230835}},"label":[]},"id":{"text":"4452xxxxxxxxxxxx","pos":{"left_top":{"x":176.158676147,"y":244.072860718},"right_top":{"x":453.888336182,"y":244.978515625},"right_bottom":{"x":453.874603271,"y":266.313659668},"left_bottom":{"x":176.066543579,"y":265.342407227}},"label":[]},"card_position":{"pos":{"left_top":{"x":1085.625,"y":621.75},"right_top":{"x":338.125,"y":594.75},"right_bottom":{"x":303.625,"y":99.75},"left_bottom":{"x":1189.125,"y":126.75}},"label":[]},"image_width":1280,"image_height":960,"image_path":"http://tmp/wx4418e3e031e551be.o6zAJs-yC5ByIjnyyy09jKDZquXk.dlrc7P7WlhnGb4aca86b078fc2acb5b08e7a0f438943.jpg"} 2、银行卡 certificateType=’bankCard’ 属性名...

快速入门 概览 miniprogram-i18n 的用法主要分为四部分。分别是：构建脚本与i18配置、i18n文本定义、WXML中的用法及JavaScript中的用法。 安装 该方案目前需要依赖 Gulp 并且对源文件目录结构有一定的要求，需要确保小程序源文件放置在特定目录下（例如 src/ 目录）。 首先在项目根目录运行以下命令安装 gulp 及 miniprogram-i18n 的 gulp 插件。 npm i -D gulp @miniprogram-i18n/gulp-i18n-locales @miniprogram-i18n/gulp-i18n-wxml 在小程序运行环境下安装国际化运行时并在开发工具”构建npm”。 npm i -S @miniprogram-i18n/core 在项目根目录新建 gulpfile.js，并编写构建脚本，可参考 examples/gulpfile.js。 更多 Gulp 相关配置请参考 Gulp插件配置文档。 使用 i18n文本定义 miniprogram-i18n 目前采用 JSON 文件对 i18n 文本进行定义。使用之前，需要在项目源文件下新建 i18n 目录。 目录结构如下： ├── dist // 小程序构建目录 ├── gulpfile.js ├── node_modules ├── package.json └── src // 小程序源文件目录 | ├── app.js | ├── app.json | ├── app.wxss | ├── i18n // 国际化文本目录 | | ├── en-US.json | | └── zh-CN.json i18n 目录可以放置在源文件目录下的任意位置，例如可以跟 Page 或 Component 放在一起。但是需要注意的是，多个 i18n 目录下的文件在构建时会被合并打包，因此如果翻译文本有重复的 key 可能会发生覆盖。如果分开多个 i18n 目录定义需要自行确保 key 是全局唯一的。例如使用 page.index.testKey 这样的能确保唯一的名称。 下面我们定义文本： // i18n/en-US.json { "plainText": "This is a plain text", "withParams": "{value} is what you pass in" } // i18n/zh-CN.json { "plainText": "这是一段纯文本", "withParams": "你传入的值是{value}" } WXML 中的用法 定义好...