小程序官方组件

组件

原生组件说明

小程序中的部分组件是由客户端创建的原生组件，这些组件有：

• camera
• canvas
• input（仅在focus 时表现为原生组件）
• live-player
• live-pusher
• map
• textarea
• video

原生组件的使用限制

由于原生组件脱离在 WebView 渲染流程外，因此在使用时有以下限制：

• 原生组件的层级是最高的，所以页面中的其他组件无论设置z-index为多少，都无法盖在原生组件上。
  • 后插入的原生组件可以覆盖之前的原生组件
• 原生组件还无法在<picker-view>中使用
  • 基础库 2.4.4 以下版本，原生组件不支持在<scroll-view>、<swiper>、<movable-view> 中使用。
• 部分CSS样式无法应用于原生组件，例如：
  • 无法对原生组件设置 CSS动画
  • 无法定义原生组件为position: fixed
  • 不能在父级节点使用overflow: hidden来裁剪原生组件的显示区域
• 原生组件的事件监听不能使用bind: eventname的写法，只支持bindeventname。原生组件也不支持 catch 和 capture 的事件绑定方式。
• 原生组件会遮挡 vConsole 弹出的调试面板。

在工具上，原生组件是用 web 组件模拟的，因此很多情况并不能很好的还原真机的表现，建议开发者在使用到原生组件时尽量在真机上进行调试。

cover-view 与 cover-image

为了解决原生组件层级最高的限制，小程序专门提供了cover-view和cover-image组件，可以覆盖在部分原生组件上面。这两个组件也是原生组件，但是使用限制与其他原生组件有所不同。

视图容器

基础内容

表单组件

导航

---

媒体组件

audio 音频

注意：1.6.0 版本开始，该组件不再维护。建议使用能力更强的wx.createInnerAudioContext 接口，相关api：wx.createAudioContext。

<!-- audio.wxml -->
<audio
  poster='{{poster}}'
  name='{{name}}'
  author='{{author}}'
  src='{{src}}'
  id='myAudio'
  controls
  loop
></audio>

<button type='primary' bindtap='audioPlay'>播放</button>
<button type='primary' bindtap='audioPause'>暂停</button>
<button type='primary' bindtap='audio14'>设置当前播放事件为14s</button>
<button type='primary' bindtap='audioStart'>回到开头</button>

Page({
  onReady(e) {
    // 使用 wx.createAudioContext 获取 audio 上下文 context
    this.audioCtx = wx.createAudioContext('myAudio')
  },
  data: {
    poster: 'http://y.gtimg.cn/music/photo_new/T002R300x300M000003rsKF44GyaSk.jpg?max_age=2592000',
    name: '此时此刻',
    author: '许巍',
    src: 'http://ws.stream.qqmusic.qq.com/M500001VfvsJ21xFqb.mp3?guid=ffffffff82def4af4b12b3cd9337d5e7&uin=346897220&vkey=6292F51E1E384E06DCBDC9AB7C49FD713D632D313AC4858BACB8DDD29067D3C601481D36E62053BF8DFEAF74C0A5CCFADD6471160CAF3E6A&fromtag=46'

  },
  audioPlay() {
    this.audioCtx.play()
  },
  audioPause() {
    this.audioCtx.pause()
  },
  audio14() {
    this.audioCtx.seek(14)
  },
  audioStart() {
    this.audioCtx.seek(0)
  }
})

image 图片

• image 组件默认宽度300px、高度225px
• image 组件中二维码 / 小程序码图片不支持长按识别。
• 仅在 wx.previewImage 中支持长按识别
  

<!-- image -->
<view class='page'>
  <view class='page_hd'>
    <text class='page_title'>image</text>
    <text class='page_desc'>图片</text>
  </view> 
</view>

<view class='page_bd'>
  <view class='section section_gap' wx:for="{{array}}" wx:for-item="item">
    <view class='section_title'>{{item.text}}</view>
    <view class='section_ctn'>
      <image
        style='width: 200px; height: 200px; background-color: #eeeeee;'
        mode='{{item.mode}}'
        src='{{src}}'
      ></image>
    </view>
  </view>
</view>

Page({
  data: {
    array: [{
      mode: 'scaleToFill',
      text: 'scaleToFill：不保持纵横比缩放图片，使图片完全适应'
    }, {
      mode: 'aspectFit',
      text: 'aspectFit：保持纵横比缩放图片，使图片的长边能完全显示出来'
    }, {
      mode: 'aspectFill',
      text: 'aspectFill：保持纵横比缩放图片，只保证图片的短边能完全显示出来'
    }, {
      mode: 'top',
      text: 'top：不缩放图片，只显示图片的顶部区域'
    }, {
      mode: 'bottom',
      text: 'bottom：不缩放图片，只显示图片的底部区域'
    }, {
      mode: 'center',
      text: 'center：不缩放图片，只显示图片的中间区域'
    }, {
      mode: 'left',
      text: 'left：不缩放图片，只显示图片的左边区域'
    }, {
      mode: 'right',
      text: 'right：不缩放图片，只显示图片的右边边区域'
    }, {
      mode: 'top left',
      text: 'top left：不缩放图片，只显示图片的左上边区域'
    }, {
      mode: 'top right',
      text: 'top right：不缩放图片，只显示图片的右上边区域'
    }, {
      mode: 'bottom left',
      text: 'bottom left：不缩放图片，只显示图片的左下边区域'
    }, {
      mode: 'bottom right',
      text: 'bottom right：不缩放图片，只显示图片的右下边区域'
    }],
    src: 'https://developers.weixin.qq.com/miniprogram/dev/image/cat/0.jpg?t=19022220'
  },
  imageError(e) {
    console.log('image3发生error事件，携带值为', e.detail.errMsg)
  }
})

video 视频

该组件是原生组件。
<video>默认宽度300px，高度225px，可通过wxss设置宽高。
相关api：wx.createVideoContext

<view class="section tc">
  <video src="{{src}}" controls></video>
  <view class="btn-area">
    <button bindtap="bindButtonTap">获取视频</button>
  </view>
</view>

<view class="section tc">
  <video
    id="myVideo"
    src="http://wxsnsdy.tc.qq.com/105/20210/snsdyvideodownload?filekey=30280201010421301f0201690402534804102ca905ce620b1241b726bc41dcff44e00204012882540400&bizid=1023&hy=SH&fileparam=302c020101042530230204136ffd93020457e3c4ff02024ef202031e8d7f02030f42400204045a320a0201000400"
    danmu-list="{{danmuList}}"
    enable-danmu
    danmu-btn
    controls
  ></video>
  <view class="btn-area">
    <button bindtap="bindButtonTap">获取视频</button>
    <input bindblur="bindInputBlur" />
    <button bindtap="bindSendDanmu">发送弹幕</button>
  </view>
</view>

function getRandomColor() {
  const rgb = []
  for (let i = 0; i < 3; ++i) {
    let color = Math.floor(Math.random() * 256).toString(16)
    color = color.length == 1 ? '0' + color : color
    rgb.push(color)
  }
  return '#' + rgb.join('')
}

Page({
  onReady(res) {
    this.videoContext = wx.createVideoContext('myVideo')
  },
  inputValue: '',
  data: {
    src: '',
    danmuList: [
      {
        text: '第 1s 出现的弹幕',
        color: '#ff0000',
        time: 1
      },
      {
        text: '第 3s 出现的弹幕',
        color: '#ff00ff',
        time: 3
      }]
  },
  bindInputBlur(e) {
    this.inputValue = e.detail.value
  },
  bindButtonTap() {
    const that = this
    wx.chooseVideo({
      sourceType: ['album', 'camera'],
      maxDuration: 60,
      camera: ['front', 'back'],
      success(res) {
        that.setData({
          src: res.tempFilePath
        })
      }
    })
  },
  bindSendDanmu() {
    this.videoContext.sendDanmu({
      text: this.inputValue,
      color: getRandomColor()
    })
  }
})

---

地图

---

画布

canvas

该组件是原生组件。相关api：wx.createCanvasContext

canvas 属性：

注：

1. canvas 标签默认宽度 300px、高度 150px
2. 同一页面中的 canvas-id 不可重复，如果使用一个已经出现过的 canvas-id，该 canvas 标签对应的画布将被隐藏并不再正常工作。

<!-- canvas.wxml -->
<canvas style='width: 300px; height: 200px;' canvas-id='firstCanvas'></canvas>
<!-- 当使用绝对定位时，文档流后边的 canvas 的显示层级高于前边的 canvas -->
<canvas style='width: 400px; height: 500px;' canvas-id='secondCanvas'></canvas>
<!-- 因为 canvas-id 与前一个 canvas 重复，该 canvas 不会显示，并会发送一个错误事件到 AppService -->
<canvas
  style='width:400px; height: 500px;'
  canvas-id='secondCanvas'
  binderror='canvasIdErrorCallback' 
></canvas>

Page({
  canvasErrorCallback(e) {
    console.log(e.detail.errMsg)
  },
  onReady(e) {
    // 使用 wx.createContext 获取绘图上下文 context
    const context = wx.createCanvasContext('firstCanvas')

    context.setStrokeStyle('#00ff00')
    context.setLineWidth(5)
    context.rect(0,0,200,200)
    context.stroke()
    context.setStrokeStyle('#ff0000')
    context.setLineWidth(2)
    context.moveTo(160,100)
    context.arc(100,100,60,0,2 * Math.PI, true)
    context.moveTo(140,100)
    context.arc(100, 100, 40, 0, Math.PI, false)
    context.moveTo(85, 80)
    context.arc(80, 80, 5, 0, 2 * Math.PI, true)
    context.moveTo(125, 80)
    context.arc(120, 80, 5, 0, 2 * Math.PI, true)
    context.stroke()
    context.draw()
  }
})

开放能力

无障碍访问

为了更好地满足视障人士对于小程序的访问需求，基础库自2.5.0起，支持部分ARIA标签。

无障碍特性在读屏模式下可以访问，iOS可通过设置->通用->辅助功能->旁白打开。

以<view>组件为例，增加了aria-role（表示组件的角色）和aria-label属性（表示组件附带的额外信息，聚焦后系统会自动朗读出来）。

• aria-role设置为img时，读屏模式下聚焦后系统会朗读出’图像’；
• aria-role设置为button时，聚焦后后系统朗读出‘按钮’。

小程序内置组件已经预埋了一些无障碍的属性，以下组件开发者可以补充相关的属性：

• button
• input
• textarea
• checkbox
• switch
• radio
• slider
• picker-view
• scroll-view
• progress
• navigator
• image
• icon
• view
• cover-view
• cover-image
• map

1. 安卓和iOS读屏模式下设置aria-role后朗读的内容不同系统之间会有差异
2. 可设置的aria-role可参看 Using Aria 中的Widget Roles，部分role的设置在移动端可能无效。