camera

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

微信 Mac 版:支持

微信 鸿蒙 OS 版:支持

相关文档: wx.createCameraContext

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)、WebView

功能描述

系统相机。扫码二维码功能,需升级微信客户端至6.7.3。需要用户授权 scope.camera。 2.10.0起 initdone 事件返回 maxZoom,最大变焦范围,相关接口 CameraContext.setZoom。

通用属性

属性 类型 默认值 必填 说明 最低版本
mode string normal 应用模式,只在初始化时有效,不能动态变更 2.1.0
合法值 说明
normal 相机模式
scanCode 扫码模式
resolution string medium 分辨率,不支持动态修改 2.10.0
合法值 说明
low
medium
high
device-position string back 摄像头朝向 1.0.0
合法值 说明
front 前置
back 后置
flash string auto 闪光灯,值为auto, on, off 1.0.0
合法值 说明 最低版本
auto 自动
on 打开
off 关闭
torch 常亮 2.8.0
frame-size string medium 指定期望的相机帧数据尺寸 2.7.0
合法值 说明
small 小尺寸帧数据
medium 中尺寸帧数据
large 大尺寸帧数据
bindstop eventhandle 摄像头在非正常终止时触发,如退出后台等情况 1.0.0
binderror eventhandle 用户不允许使用摄像头时触发 1.0.0
bindinitdone eventhandle 相机初始化完成时触发,e.detail = {maxZoom} 2.7.0
bindscancode eventhandle 在扫码识别成功时触发,仅在 mode=”scanCode” 时生效 2.1.0

Bug & Tip

  1. tip: 同一页面只能插入一个 camera 组件
  2. tip:请注意原生组件使用限制
  3. tip:onCameraFrame 接口根据 frame-size 返回不同尺寸的原始帧数据,与 Camera 组件展示的图像不同,其实际像素值由系统决定

示例代码

在开发者工具中预览效果

<!-- camera.wxml -->
<camera device-position="back" flash="off" binderror="error" style="width: 100%; height: 300px;"></camera>
<button type="primary" bindtap="takePhoto">拍照</button>
<view>预览</view>
<image mode="widthFix" src="{{src}}"></image>
// camera.js
Page({
  takePhoto() {
    const ctx = wx.createCameraContext()
    ctx.takePhoto({
      quality: 'high',
      success: (res) => {
        this.setData({
          src: res.tempImagePath
        })
      }
    })
  },
  error(e) {
    console.log(e.detail)
  }
})

audio

从基础库 1.6.0 开始,本接口停止维护,请使用 wx.createInnerAudioContext 代替

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

相关文档: wx.createAudioContext

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)、WebView

功能描述

音频。

属性说明

属性 类型 默认值 必填 说明 最低版本
id string 微信小程序 audio 组件的唯一标识符 1.0.0
src string 要播放音频的资源地址 1.0.0
loop boolean false 是否循环播放 1.0.0
controls boolean false 是否显示默认控件 1.0.0
poster string 默认控件上的音频封面的图片资源地址,如果 controls 属性值为 false 则设置 poster 无效 1.0.0
name string 未知音频 默认控件上的音频名字,如果 controls 属性值为 false 则设置 name 无效 1.0.0
author string 未知作者 默认控件上的作者名字,如果 controls 属性值为 false 则设置 author 无效 1.0.0
binderror eventhandle 当发生错误时触发 error 事件,detail = {errMsg:MediaError.code} 1.0.0
bindplay eventhandle 当开始或继续播放时触发 play 事件 1.0.0
bindpause eventhandle 当暂停播放时触发 pause 事件 1.0.0
bindtimeupdate eventhandle 当播放进度改变时触发 timeupdate 事件,detail = {currentTime, duration} 1.0.0
bindended eventhandle 当播放到末尾时触发 ended 事件 1.0.0

MediaError.code

返回错误码 描述
1 获取资源被用户禁止
2 网络错误
3 解码错误
4 不合适资源

示例代码

在开发者工具中预览效果

navigator

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

微信小程序插件:支持,需要微信小程序基础库版本不低于 2.1.0

微信 Windows 版:支持

微信 Mac 版:支持

微信 鸿蒙 OS 版:支持

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)、WebView

功能描述

页面链接。

  1. navigator 在 Skyline 下视为文本节点,只能嵌套文本节点(如 text),不能嵌套 view、button 等普通节点,如 <button> <navigator>foo</navigator> </button>
  2. 新增 span 组件用于内联文本和图片,如 <span> <image> </image> <navigator>bar</navigator> </span>

通用属性

属性 类型 默认值 必填 说明 最低版本
target string self 在哪个目标上发生跳转,默认当前微信小程序 2.0.7
合法值 说明
self 当前微信小程序
miniProgram 其它微信小程序
url string 当前微信小程序内的跳转链接 1.0.0
open-type string navigate 跳转方式 1.0.0
合法值 说明 最低版本
navigate 对应 wx.navigateTo 或 wx.navigateToMiniProgram 的功能
redirect 对应 wx.redirectTo 的功能
switchTab 对应 wx.switchTab 的功能
reLaunch 对应 wx.reLaunch 的功能 1.1.0
navigateBack 对应 wx.navigateBack 或 wx.navigateBackMiniProgram (基础库 2.24.4 版本支持)的功能 1.1.0
exit 退出微信小程序,target="miniProgram"时生效 2.1.0
delta number 1 当 open-type 为 ‘navigateBack’ 时有效,表示回退的层数 1.0.0
app-id string target="miniProgram"open-type="navigate"时有效,要打开的微信小程序 appId 2.0.7
path string target="miniProgram"open-type="navigate"时有效,打开的页面路径,如果为空则打开首页 2.0.7
extra-data object target="miniProgram"open-type="navigate/navigateBack"时有效,需要传递给目标微信小程序的数据,目标微信小程序可在 App.onLaunch()App.onShow() 中获取到这份数据。详情 2.0.7
version string release target="miniProgram"open-type="navigate"时有效,要打开的微信小程序版本 2.0.7
合法值 说明
develop 开发版
trial 体验版
release 正式版,仅在当前微信小程序为开发版或体验版时此参数有效;如果当前微信小程序是正式版,则打开的微信小程序必定是正式版。
short-link string target="miniProgram"时有效,当传递该参数后,可以不传 app-id 和 path。链接可以通过【微信小程序菜单】->【复制链接】获取。 2.18.1
hover-class string navigator-hover 指定点击时的样式类,当hover-class="none"时,没有点击态效果 1.0.0
hover-stop-propagation boolean false 指定是否阻止本节点的祖先节点出现点击态 1.5.0
hover-start-time number 50 按住后多久出现点击态,单位毫秒 1.0.0
hover-stay-time number 600 手指松开后点击态保留时间,单位毫秒 1.0.0
bindsuccess string target="miniProgram"open-type="navigate/navigateBack"时有效时有效,跳转微信小程序成功 2.0.7
bindfail string target="miniProgram"open-type="navigate/navigateBack"时有效时有效,跳转微信小程序失败 2.0.7
bindcomplete string target="miniProgram"open-type="navigate/navigateBack"时有效时有效,跳转微信小程序完成 2.0.7

使用限制

  1. 需要用户确认跳转 从 2.3.0 版本开始,在跳转至其他微信小程序前,将统一增加弹窗,询问是否跳转,用户确认后才可以跳转其他微信小程序。如果用户点击取消,则回调 fail cancel
  2. 从2020年4月24日起,跳转其他微信小程序将不再受数量限制,使用此功能时请注意遵守运营规范。

关于调试

  • 在开发者工具上调用此 API 并不会真实的跳转到另外的微信小程序,但是开发者工具会校验本次调用跳转是否成功。详情
  • 开发者工具上支持被跳转的微信小程序处理接收参数的调试。详情

Bug & Tip

  1. tipnavigator-hover 默认为 {background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}, navigator 的子节点背景色应为透明色

示例代码

在开发者工具中预览效果

.navigator-hover {
  color:blue;
}
.other-navigator-hover {
  color:red;
}
<!-- sample.wxml -->
<view class="btn-area">
  <navigator url="/page/navigate/navigate?title=navigate" hover-class="navigator-hover">跳转到新页面</navigator>
  <navigator url="../../redirect/redirect/redirect?title=redirect" open-type="redirect" hover-class="other-navigator-hover">在当前页打开</navigator>
  <navigator url="/page/index/index" open-type="switchTab" hover-class="other-navigator-hover">切换 Tab</navigator>
  <navigator target="miniProgram" open-type="navigate" app-id="" path="" extra-data="" version="release">打开绑定的微信小程序</navigator>
</view>
<!-- navigator.wxml -->
<view style="text-align:center"> {{title}} </view>
<view> 点击左上角返回回到之前页面 </view>
<!-- redirect.wxml -->
<view style="text-align:center"> {{title}} </view>
<view> 点击左上角返回回到上级页面 </view>
Page({
  onLoad: function(options) {
    this.setData({
      title: options.title
    })
  }
})

functional-page-navigator

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

微信 Windows 版:支持

微信 Mac 版:支持

微信 鸿蒙 OS 版:支持

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)、WebView

功能描述

仅在插件中有效,用于跳转到插件功能页。

通用属性

属性 类型 默认值 必填 说明 最低版本
version string release 跳转到的微信小程序版本,**线上版本必须设置为 release** 2.1.0
合法值 说明
develop 开发版
trial 体验版
release 正式版
name string 要跳转到的功能页 2.1.0
合法值 说明 最低版本
loginAndGetUserInfo 用户信息功能页 2.1.0
requestPayment 支付功能页 2.1.0
chooseAddress 收货地址功能页 2.4.0
chooseInvoice 获取发票功能页 2.14.1
chooseInvoiceTitle 获取发票抬头功能页 2.14.1
args object 功能页参数,参数格式与具体功能页相关 2.1.0
bindsuccess eventhandler 功能页返回,且操作成功时触发, detail 格式与具体功能页相关 2.1.0
bindfail eventhandler 功能页返回,且操作失败时触发, detail 格式与具体功能页相关 2.1.0
bindcancel eventhandler 因用户操作从功能页返回时触发 2.4.1

Bug & Tip

  1. tip: 功能页是插件所有者微信小程序中的一个特殊页面,开发者不能自定义这个页面的外观。
  2. tip: 在功能页展示时,一些与界面展示相关的接口将被禁用(接口调用返回 fail )。
  3. tip: 这个组件本身可以在开发者工具中使用,但功能页的跳转目前不支持在开发者工具中调试,请在真机上测试。

示例代码

<!-- sample.wxml -->
<functional-page-navigator name="loginAndGetUserInfo" bind:success="loginSuccess">
  <button>登录到插件</button>
</functional-page-navigator>
// redirect.js navigator.js
Component({
  methods: {
    loginSuccess: function(e) {
      console.log(e.detail.code) // wx.login 的 code
      console.log(e.detail.userInfo) // wx.getUserInfo 的 userInfo
    }
  }
})

sticky-section

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

相关文档: Skyline 渲染引擎、Skyline 迁移起步

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

吸顶布局容器,仅支持作为 <scroll-view type="custom"> 模式的直接子节点

属性说明

属性 类型 默认值 必填 说明 最低版本
push-pinned-header boolean true 吸顶元素重叠时是否继续上推
padding Array [0, 0, 0, 0] 长度为 4 的数组,按 top、right、bottom、left 顺序指定内边距 3.0.0

示例代码

在开发者工具中预览效果

sticky-header

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

相关文档: Skyline 渲染引擎、Skyline 迁移起步

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

吸顶布局容器,仅支持作为 <scroll-view type="custom"> 模式的直接子节点或 sticky-section 组件直接子节点

属性说明

属性 类型 默认值 必填 说明 最低版本
offset-top number 0 吸顶时与视窗顶部的距离(px) 3.0.0
allow-overlapping bool false 是否允许与前一个 sticky-header 重叠 3.7.11
padding Array [0, 0, 0, 0] 长度为 4 的数组,按 top、right、bottom、left 顺序指定内边距(px) 3.0.0
bind:stickontopchange eventhandle 吸顶状态变化事件,仅支持非 worklet 的组件方法作为回调。event.detail = { isStickOnTop },当 sticky-header 吸顶时为 true,否则为 false。 3.6.2

示例代码

在开发者工具中预览效果

span

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

用于支持内联文本和 image / navigator 的混排

snapshot

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

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

截图组件。 支持将其子节点的渲染结果导出成图片,该组件需配合 snapshot 接口使用。 目前仅在 Skyline 渲染引擎 下支持。

通用属性

属性 类型 默认值 必填 说明
mode string view 渲染模式
合法值 说明 最低版本
view 以真实节点渲染。 3.1.0
picture 对子节点生成的内容截图渲染。 3.1.0

Bug & Tip

  1. tip:如需离屏渲染导出,可将 snapshot 组件移动到屏幕外或设置 width: 100%; position: absolute; transform: scale(0) 即可,但不能设置为 display: none 或 visibility: hidden
  2. tip:子节点不能包含原生组件,其他任意组件均可使用
  3. tip:支持对任意大小的区域导出图片,即导出图片没有尺寸限制
  4. tip: 如需实现长列表截图,不建议直接嵌在 scroll-view 内(即 <scroll-view><snapshot></snapshot></scroll-view>),会影响列表滚动性能,建议将 snapshot 组件放在 scroll-view 外,与 scroll-view 加载同一批列表数据,要截图时再将 snapshot 渲染出来

渲染模式

Skyline 下对节点进行 transform: scale() rotate() 动画时,若子节点内容比较复杂,动画性能可能不佳。为解决该问题,可利用 snapshot 组件改变渲染模式。

<snapshot mode="view">
 <view></view>
</snapshot>

view 模式渲染时,snapshot 组件与普通的 view 无差别,对子节点设置样式,变化会体现在界面上。 以 picture 模式渲染时,snapshot 组件会对当下渲染的子节点进行截图,后续子节点被替换为图片进行渲染,此时对子节点设置样式,变化不会体现在界面上。

picture 模式下进行 transform: scale() rotate() 动画时,性能较好。此时通过 setData 等对子节点进行的修改,当再次切换为 view 模式时,界面会立刻改变为最终样式。

通常在对大范围节点进行 scalerotate 动画时,可在动画开始设置为 picture 模式,动画结束设置为 view 模式,以提高动画表现。如子节点内容会发生改变,则不适用该模式切换。

示例代码

  <snapshot id="target">
    <view>content</view>
  </snapshot>
Page({
  onReady() {
    this.createSelectorQuery()
      .select("#target")
      .node()
      .exec(res => {
        const node = res[0].node
        node.takeSnapshot({
          type: 'arraybuffer',
          format: 'png',
          success: (res) => {},
          fail(res) {}
        })
  }
})

示例代码片段

在开发者工具中预览效果

share-element

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

微信 Windows 版:支持

微信 Mac 版:支持

微信 鸿蒙 OS 版:支持

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)、WebView

功能描述

共享元素。

共享元素是一种动画形式,类似于 Flutter 的 Hero 动画,表现为元素像是在页面间穿越一样。该组件需与 page-container 组件结合使用。

使用时需在当前页放置 share-element 组件,同时在 page-container 容器中放置对应的 share-element 组件,对应关系通过属性值 key 映射。当设置 page-container 显示时,transform 属性为 true 的共享元素会产生动画。当前页面容器退出时,会产生返回动画。

  1. 使用 worklet 函数需要开启开发者工具 “将 JS 编译成 ES5” 或 “编译 worklet 函数” 选项。

通用属性

属性 类型 默认值 必填 说明 最低版本
key string 映射标记,页面内唯一 2.29.2
transform boolean false 是否进行动画 2.16.0
duration number 300 动画时长,单位毫秒 2.16.0
easing-function string ease-out css缓动函数 2.16.0

Skyline 特有属性

属性 类型 默认值 必填 说明 最低版本
transition-on-gesture boolean false 手势返回时是否进行动画 2.29.2
shuttle-on-push string to 指定 push 阶段的飞跃物 2.30.2
合法值 说明
from push 阶段采用源页面节点作为飞跃物
to push 阶段采用目标页面节点作为飞跃物
from pop 阶段采用源页面节点作为飞跃物
to pop 阶段采用目标页面节点作为飞跃物
shuttle-on-pop string to 指定 pop 阶段的飞跃物 2.30.2
worklet:onframe callback 动画帧回调 2.30.2
rect-tween-type string materialRectArc 动画插值曲线 2.30.2
合法值 说明
materialRectArc 矩形对角动画
materialRectCenterArc 径向动画
linear
elasticIn
elasticOut
elasticInOut
bounceIn
bounceOut
bounceInOut
cubic-bezier(x1, y1, x2, y2 )

WebView 示例代码

在开发者工具中预览效果

Skyline 示例代码

在开发者工具中预览效果

open-data-list

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

相关文档: 聊天工具模式、Skyline 渲染引擎、Skyline 迁移起步

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)

功能描述

展示微信开放数据。

通用属性

属性 类型 默认值 必填 说明
type string 开放数据类型
合法值 说明
groupMembers 群成员信息
members Array.<string> 群成员group_openid列表

示例代码

<open-data-list type="groupMembers" members="{{members}}">
  <view class="userinfo" slot:index>
    <open-data-item class="avatar " type="userAvatar" index="{{index}}" />
    <open-data-item class="" type="userNickName" index="{{index}}" />
  </view>
</open-data-list>