微信小程序~基礎組件

時間  2021-04-14
標籤 javascript css html java node git github web canvas 小程序 欄目 JavaScript 简体版
原文   原文鏈接

 （1）視圖容器javascript

名稱 功能說明
movable-view 可移動的視圖容器，在頁面中能夠拖拽滑動
cover-image 覆蓋在原生組件之上的圖片視圖
cover-view 覆蓋在原生組件之上的文本視圖
movable-area movable-view的可移動區域
scroll-view 可滾動視圖區域
swiper 滑塊視圖容器
swiper-item 僅可放置在swiper組件中，寬高自動設置爲100%
view 視圖容器
   
    ①movable-view

可移動的視圖容器，在頁面中能夠拖拽滑動。movable-view必須在 movable-area 組件中，而且必須是直接子節點，不然不能移動。css

屬性 類型 默認值 必填 說明 最低版本
direction string none 否 movable-view的移動方向，屬性值有all、vertical、horizontal、none 1.2.0
inertia boolean false 否 movable-view是否帶有慣性 1.2.0
out-of-bounds boolean false 否 超過可移動區域後，movable-view是否還能夠移動 1.2.0
x number   否 定義x軸方向的偏移，若是x的值不在可移動範圍內，會自動移動到可移動範圍；改變x的值會觸發動畫 1.2.0
y number   否 定義y軸方向的偏移，若是y的值不在可移動範圍內，會自動移動到可移動範圍；改變y的值會觸發動畫 1.2.0
damping number 20 否 阻尼係數，用於控制x或y改變時的動畫和過界回彈的動畫，值越大移動越快 1.2.0
friction number 2 否 摩擦係數，用於控制慣性滑動的動畫，值越大摩擦力越大，滑動越快中止；必須大於0，不然會被設置成默認值 1.2.0
disabled boolean false 否 是否禁用 1.9.90
scale boolean false 否 是否支持雙指縮放，默認縮放手勢生效區域是在movable-view內 1.9.90
scale-min number 0.5 否 定義縮放倍數最小值 1.9.90
scale-max number 10 否 定義縮放倍數最大值 1.9.90
scale-value number 1 否 定義縮放倍數，取值範圍爲 0.5 - 10 1.9.90
animation boolean true 否 是否使用動畫 2.1.0
bindchange eventhandle   否 拖動過程當中觸發的事件，event.detail = {x, y, source} 1.9.90
bindscale eventhandle   否 縮放過程當中觸發的事件，event.detail = {x, y, scale}，x和y字段在2.1.0以後支持 1.9.90
htouchmove eventhandle   否 初次手指觸摸後移動爲橫向的移動時觸發，若是catch此事件，則意味着touchmove事件也被catch 1.9.90
vtouchmove eventhandle   否 初次手指觸摸後移動爲縱向的移動時觸發，若是catch此事件，則意味着touchmove事件也被catch 1.9.90

bindchange 返回的 source 表示產生移動的緣由

值 說明
touch 拖動
touch-out-of-bounds 超出移動範圍
out-of-bounds 超出移動範圍後的回彈
friction 慣性
空字符串 setData

Bug & Tip

  1. tip: movable-view 必須設置width和height屬性，不設置默認爲10px
  2. tip: movable-view 默認爲絕對定位，top和left屬性爲0px

   

    ②movable-areahtml

movable-view的可移動區域。java

屬性 類型 默認值 必填 說明 最低版本
scale-area Boolean false 否 當裏面的movable-view設置爲支持雙指縮放時，設置此值可將縮放手勢生效區域修改成整個movable-area 1.9.90

Bug & Tip

  1. tip: movable-area 必須設置width和height屬性，不設置默認爲10px**
  2. tip: 當movable-view小於movable-area時，movable-view的移動範圍是在movable-area內；
  3. tip: 當movable-view大於movable-area時，movable-view的移動範圍必須包含movable-area（x軸方向和y軸方向分開考慮）

示例代碼

<view class="section">
  <view class="section__title">movable-view區域小於movable-area</view>
  <movable-area style="height: 200px; width: 200px; background: red;">
    <movable-view style="height: 50px; width: 50px; background: blue;" x="{{x}}" y="{{y}}" direction="all">
    </movable-view>
  </movable-area>
  <view class="btn-area">
    <button size="mini" bindtap="tap">click me to move to (30px, 30px)</button>
  </view>
  <view class="section__title">movable-view區域大於movable-area</view>
  <movable-area style="height: 100px; width: 100px; background: red;">
    <movable-view style="height: 200px; width: 200px; background: blue;" direction="all">
    </movable-view>
  </movable-area>
  <view class="section__title">可放縮</view>
  <movable-area style="height: 200px; width: 200px; background: red;" scale-area>
    <movable-view style="height: 50px; width: 50px; background: blue;" direction="all" bindchange="onChange" bindscale="onScale" scale scale-min="0.5" scale-max="4" scale-value="2">
    </movable-view>
  </movable-area>
</view>
Page({
  data: {
    x: 0,
    y: 0
  },
  tap: function(e) {
    this.setData({
      x: 30,
      y: 30
    });
  },
  onChange: function(e) {
    console.log(e.detail)
  },
  onScale: function(e) {
    console.log(e.detail)
  }
}) 

 

    ③cover-imagenode

    覆蓋在原生組件之上的圖片視圖git

覆蓋在原生組件之上的圖片視圖。可覆蓋的原生組件同cover-view，支持嵌套在cover-view裏。github

屬性 類型 默認值 必填 說明 最低版本
src string   否 圖標路徑，支持臨時路徑、網絡地址（1.6.0起支持）、雲文件ID（2.2.3起支持）。暫不支持base64格式。 1.4.0
bindload eventhandle   否 圖片加載成功時觸發 2.1.0
binderror eventhandle   否 圖片加載失敗時觸發 2.1.0

 

    ④cover-viewweb

    覆蓋在原生組件之上的文本視圖canvas

可覆蓋的原生組件包括 map、video、canvas、camera、live-player、live-pusher小程序

只支持嵌套 cover-view、cover-image，可在 cover-view 中使用 button。組件屬性的長度單位默認爲px，2.4.0起支持傳入單位(rpx/px)。

屬性 類型 默認值 必填 說明 最低版本
scroll-top number/string   否 設置頂部滾動偏移量，僅在設置了 overflow-y: scroll 成爲滾動元素後生效 2.1.0

Bug & Tip

  1. tip: cover-view和cover-image的aria-role僅可設置爲button，讀屏模式下才能夠點擊，並朗讀出「按鈕」；爲空時能夠聚焦，但不可點擊
  2. tip: 基礎庫 2.2.4 起支持 touch 相關事件，也可以使用 hover-class 設置點擊態
  3. tip: 基礎庫 2.1.0 起支持設置 scale rotate 的 css 樣式，包括 transition 動畫
  4. tip: 基礎庫 1.9.90 起 cover-view 支持 overflow: scroll，但不支持動態更新 overflow
  5. tip: 基礎庫 1.9.90 起最外層 cover-view 支持 position: fixed
  6. tip: 基礎庫 1.9.0 起支持插在 view 等標籤下。在此以前只可嵌套在原生組件map、video、canvas、camera內，避免嵌套在其餘組件內。
  7. tip: 基礎庫 1.6.0 起支持css transition動畫，transition-property只支持transform (translateX, translateY)與opacity。
  8. tip: 基礎庫 1.6.0 起支持css opacity。
  9. tip: 事件模型遵循冒泡模型，但不會冒泡到原生組件。
  10. tip: 文本建議都套上cover-view標籤，避免排版錯誤。
  11. tip: 只支持基本的定位、佈局、文本樣式。不支持設置單邊的border、background-image、shadow、overflow: visible等。
  12. tip: 建議子節點不要溢出父節點
  13. tip: 支持使用 z-index 控制層級
  14. tip: 默認設置的樣式有：white-space: nowrap; line-height: 1.2; display: block;
  15. bug: 自定義組件嵌套 cover-view 時，自定義組件的 slot 及其父節點暫不支持經過 wx:if 控制顯隱，不然會致使 cover-view 不顯示

示例代碼

<video id="myVideo" src="http://wxsnsdy.tc.qq.com/105/20210/snsdyvideodownload?filekey=30280201010421301f0201690402534804102ca905ce620b1241b726bc41dcff44e00204012882540400&bizid=1023&hy=SH&fileparam=302c020101042530230204136ffd93020457e3c4ff02024ef202031e8d7f02030f42400204045a320a0201000400" controls="{{false}}" event-model="bubble">
  <cover-view class="controls">
    <cover-view class="play" bindtap="play">
      <cover-image class="img" src="/path/to/icon_play" />
    </cover-view>
    <cover-view class="pause" bindtap="pause">
      <cover-image class="img" src="/path/to/icon_pause" />
    </cover-view>
    <cover-view class="time">00:00</cover-view>
  </cover-view>
</video>
.controls {
  position: relative;
  top: 50%;
  height: 50px;
  margin-top: -25px;
  display: flex;
}
.play,.pause,.time {
  flex: 1;
  height: 100%;
}
.time {
  text-align: center;
  background-color: rgba(0, 0, 0, .5);
  color: white;
  line-height: 50px;
}
.img {
  width: 40px;
  height: 40px;
  margin: 5px auto;
}
Page({
  onReady() {
    this.videoCtx = wx.createVideoContext('myVideo')
  },
  play() {
    this.videoCtx.play()
  },
  pause() {
    this.videoCtx.pause()
  }
})

 

    ⑤scroll-view

可滾動視圖區域。使用豎向滾動時，須要給scroll-view一個固定高度，經過 WXSS 設置 height。組件屬性的長度單位默認爲px，2.4.0起支持傳入單位(rpx/px)。

屬性 類型 默認值 必填 說明 最低版本
scroll-x boolean false 否 容許橫向滾動 1.0.0
scroll-y boolean false 否 容許縱向滾動 1.0.0
upper-threshold number/string 50 否 距頂部/左邊多遠時，觸發 scrolltoupper 事件 1.0.0
lower-threshold number/string 50 否 距底部/右邊多遠時，觸發 scrolltolower 事件 1.0.0
scroll-top number/string   否 設置豎向滾動條位置 1.0.0
scroll-left number/string   否 設置橫向滾動條位置 1.0.0
scroll-into-view string   否 值應爲某子元素id（id不能以數字開頭）。設置哪一個方向可滾動，則在哪一個方向滾動到該元素 1.0.0
scroll-with-animation boolean false 否 在設置滾動條位置時使用動畫過渡 1.0.0
enable-back-to-top boolean false 否 iOS點擊頂部狀態欄、安卓雙擊標題欄時，滾動條返回頂部，只支持豎向 1.0.0
bindscrolltoupper eventhandle   否 滾動到頂部/左邊時觸發 1.0.0
bindscrolltolower eventhandle   否 滾動到底部/右邊時觸發 1.0.0
bindscroll eventhandle   否 滾動時觸發，event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY} 1.0.0

Bug & Tip

  1. tip: 基礎庫 2.4.0如下不支持嵌套textarea、map、canvas、video 組件
  2. tip: scroll-into-view 的優先級高於 scroll-top
  3. tip: 在滾動 scroll-view 時會阻止頁面回彈，因此在 scroll-view 中滾動，是沒法觸發 onPullDownRefresh
  4. tip: 若要使用下拉刷新，請使用頁面的滾動，而不是 scroll-view ，這樣也能經過點擊頂部狀態欄回到頁面頂部
<!--垂直滾動，這裏必須設置高度-->
<scroll-view scroll-y="true" style="height: 200px">
    <view style="background: red; width: 100px; height: 100px" ></view>
    <view style="background: green; width: 100px; height: 100px"></view>
    <view style="background: blue; width: 100px; height: 100px"></view>
    <view style="background: yellow; width: 100px; height: 100px"></view>
</scroll-view>

<!--  white-space
  normal: 正常無變化(默認處理方式.文本自動處理換行.假如抵達容器邊界內容會轉到下一行)
  pre: 保持HTML源代碼的空格與換行,等同與pre標籤
  nowrap: 強制文本在一行,除非遇到br換行標籤
  pre-wrap: 同pre屬性,可是遇到超出容器範圍的時候會自動換行
  pre-line: 同pre屬性,可是遇到連續空格會被看做一個空格
  inherit: 繼承
-->
<!--水平滾動-->
<scroll-view scroll-x="true" style=" white-space: nowrap; display: flex" >
<!--  display: inline-block-->
  <view style="background: red; width: 200px; height: 100px; display: inline-block" ></view>
  <view style="background: green; width: 200px; height: 100px; display: inline-block"></view>
  <view style="background: blue; width: 200px; height: 100px; display: inline-block"></view>
  <view style="background: yellow; width: 200px; height: 100px; display: inline-block"></view>
</scroll-view>

 

 

    ⑥swiper

滑塊視圖容器。其中只可放置swiper-item組件，不然會致使未定義的行爲。

屬性 類型 默認值 必填 說明 最低版本
indicator-dots boolean false 否 是否顯示面板指示點 1.0.0
indicator-color color rgba(0, 0, 0, .3) 否 指示點顏色 1.1.0
indicator-active-color color #000000 否 當前選中的指示點顏色 1.1.0
autoplay boolean false 否 是否自動切換 1.0.0
current number 0 否 當前所在滑塊的 index 1.0.0
interval number 5000 否 自動切換時間間隔 1.0.0
duration number 500 否 滑動動畫時長 1.0.0
circular boolean false 否 是否採用銜接滑動 1.0.0
vertical boolean false 否 滑動方向是否爲縱向 1.0.0
previous-margin string "0px" 否 前邊距，可用於露出前一項的一小部分，接受 px 和 rpx 值 1.9.0
next-margin string "0px" 否 後邊距，可用於露出後一項的一小部分，接受 px 和 rpx 值 1.9.0
display-multiple-items number 1 否 同時顯示的滑塊數量 1.9.0
skip-hidden-item-layout boolean false 否 是否跳過未顯示的滑塊佈局，設爲 true 可優化複雜狀況下的滑動性能，但會丟失隱藏狀態滑塊的佈局信息 1.9.0
easing-function string "default" 否 指定 swiper 切換緩動動畫類型 2.6.5
bindchange eventhandle   否 current 改變時會觸發 change 事件，event.detail = {current, source} 1.0.0
bindtransition eventhandle   否 swiper-item 的位置發生改變時會觸發 transition 事件，event.detail = {dx: dx, dy: dy} 2.4.3
bindanimationfinish eventhandle   否 動畫結束時會觸發 animationfinish 事件，event.detail 同上 1.9.0

easing-function 的合法值

值 說明 最低版本
default 默認緩動函數  
linear 線性動畫  
easeInCubic 緩入動畫  
easeOutCubic 緩出動畫  
easeInOutCubic 緩入緩出動畫  

change事件 source 返回值

從 1.4.0 開始，change事件增長 source字段，表示致使變動的緣由，可能值以下：

  1. autoplay 自動播放致使swiper變化；
  2. touch 用戶划動引發swiper變化；
  3. 其它緣由將用空字符串表示。

Bug & Tip

  1. tip: 若是在 bindchange 的事件回調函數中使用 setData 改變 current 值，則有可能致使 setData 被不停地調用，於是一般狀況下請在改變 current 值前檢測 source 字段來判斷是不是因爲用戶觸摸引發。

示例代碼

<swiper indicator-dots="{{indicatorDots}}"
  autoplay="{{autoplay}}" interval="{{interval}}" duration="{{duration}}">
  <block wx:for="{{imgUrls}}">
    <swiper-item>
      <image src="{{item}}" class="slide-image" width="355" height="150"/>
    </swiper-item>
  </block>
</swiper>
<button bindtap="changeIndicatorDots"> indicator-dots </button>
<button bindtap="changeAutoplay"> autoplay </button>
<slider bindchange="intervalChange" show-value min="500" max="2000"/>
<slider bindchange="durationChange" show-value min="1000" max="10000"/>
Page({
  data: {
    imgUrls: [
      'https://images.unsplash.com/photo-1551334787-21e6bd3ab135?w=640',
      'https://images.unsplash.com/photo-1551214012-84f95e060dee?w=640',
      'https://images.unsplash.com/photo-1551446591-142875a901a1?w=640'
    ],
    indicatorDots: false,
    autoplay: false,
    interval: 5000,
    duration: 1000
  },
  changeIndicatorDots: function(e) {
    this.setData({
      indicatorDots: !this.data.indicatorDots
    })
  },
  changeAutoplay: function(e) {
    this.setData({
      autoplay: !this.data.autoplay
    })
  },
  intervalChange: function(e) {
    this.setData({
      interval: e.detail.value
    })
  },
  durationChange: function(e) {
    this.setData({
      duration: e.detail.value
    })
  }
})

 

 

    ⑦swiper-item 僅可放置在swiper組件中，寬高自動設置爲100%

屬性 類型 默認值 必填 說明 最低版本
item-id string   否 該 swiper-item 的標識符 1.9.0

 

    ⑧view視圖容器

    

屬性 類型 默認值 必填 說明 最低版本
hover-class string none 否 指定按下去的樣式類。當 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 400 否 手指鬆開後點擊態保留時間，單位毫秒 1.0.0

Bug & Tip

  1. tip: 若是須要使用滾動視圖，請使用 scroll-view

示例代碼

<view class="section">
  <view class="section__title">flex-direction: row</view>
  <view class="flex-wrp" style="flex-direction:row;">
    <view class="flex-item bc_green">1</view>
    <view class="flex-item bc_red">2</view>
    <view class="flex-item bc_blue">3</view>
  </view>
</view>
<view class="section">
  <view class="section__title">flex-direction: column</view>
  <view class="flex-wrp" style="height: 300px;flex-direction:column;">
    <view class="flex-item bc_green">1</view>
    <view class="flex-item bc_red">2</view>
    <view class="flex-item bc_blue">3</view>
  </view>
</view>

 

（2）基礎內容

 

名稱 功能說明
icon 圖標
progress 進度條
rich-text 富文本
text 文本

    ①icon圖標

圖標。組件屬性的長度單位默認爲px，2.4.0起支持傳入單位(rpx/px)。

屬性 類型 默認值 必填 說明 最低版本
type string   是 icon的類型，有效值：success, success_no_circle, info, warn, waiting, cancel, download, search, clear 1.0.0
size number/string 23 否 icon的大小 1.0.0
color string   否 icon的顏色，同css的color 1.0.0 
<view class="group">
  <block wx:for="{{iconSize}}">
    <icon type="success" size="{{item}}"/>
  </block>
</view>

<view class="group">
  <block wx:for="{{iconType}}">
    <icon type="{{item}}" size="40"/>
  </block>
</view>

<view class="group">
  <block wx:for="{{iconColor}}">
    <icon type="success" size="40" color="{{item}}"/>
  </block>
</view>

Page({
  data: {
    iconSize: [20, 30, 40, 50, 60, 70],
    iconColor: [
      'red', 'orange', 'yellow', 'green', 'rgb(0,255,255)', 'blue', 'purple'
    ],
    iconType: [
      'success', 'success_no_circle', 'info', 'warn', 'waiting', 'cancel', 'download', 'search', 'clear'
    ]
  }
})

 

     ②progress進度條

 

屬性 類型 默認值 必填 說明 最低版本
percent number   否 百分比0~100 1.0.0
show-info boolean false 否 在進度條右側顯示百分比 1.0.0
border-radius number/string 0 否 圓角大小 2.3.1
font-size number/string 16 否 右側百分比字體大小 2.3.1
stroke-width number/string 6 否 進度條線的寬度 1.0.0
color string #09BB07 否 進度條顏色（請使用activeColor） 1.0.0
activeColor string #09BB07 否 已選擇的進度條的顏色 1.0.0
backgroundColor string #EBEBEB 否 未選擇的進度條的顏色 1.0.0
active boolean false 否 進度條從左往右的動畫 1.0.0
active-mode string backwards 否 backwards: 動畫從頭播；forwards：動畫從上次結束點接着播 1.7.0
bindactiveend eventhandle   否 動畫完成事件 2.4.1 
<progress percent="20" show-info />
<progress percent="40" stroke-width="12" />
<progress percent="60" color="pink" />
<progress percent="80" active show-info/>

 

    ③rich-text富文本

 

屬性 類型 默認值 必填 說明 最低版本
nodes array/string [] 否 節點列表/HTML String 1.4.0
space string   否 顯示連續空格 2.4.1

space 的合法值

值 說明 最低版本
ensp 中文字符空格一半大小  
emsp 中文字符空格大小  
nbsp 根據字體設置的空格大小  

nodes

現支持兩種節點，經過type來區分，分別是元素節點和文本節點，默認是元素節點，在富文本區域裏顯示的HTML節點 元素節點：type = node*

屬性 說明 類型 必填 備註
name 標籤名 string 是 支持部分受信任的 HTML 節點
attrs 屬性 object 否 支持部分受信任的屬性，遵循 Pascal 命名法
children 子節點列表 array 否 結構和 nodes 一致

文本節點：type = text*

屬性 說明 類型 必填 備註
text 文本 string 是 支持entities

受信任的HTML節點及屬性

全局支持class和style屬性，不支持id屬性。

節點 屬性
a  
abbr  
address  
article  
aside  
b  
bdi  
bdo dir
big  
blockquote  
br  
caption  
center  
cite  
code  
col span，width
colgroup span，width
dd  
del  
div  
dl  
dt  
em  
fieldset  
font  
footer  
h1  
h2  
h3  
h4  
h5  
h6  
header  
hr  
i  
img alt，src，height，width
ins  
label  
legend  
li  
mark  
nav  
ol start，type
p  
pre  
q  
rt  
ruby  
s  
section  
small  
span  
strong  
sub  
sup  
table width
tbody  
td colspan，height，rowspan，width
tfoot  
th colspan，height，rowspan，width
thead  
tr colspan，height，rowspan，width
tt  
u  
ul  

Bug & Tip

  1. tip: nodes 不推薦使用 String 類型，性能會有所降低。
  2. tip: rich-text 組件內屏蔽全部節點的事件。
  3. tip: attrs 屬性不支持 id ，支持 class 。
  4. tip: name 屬性大小寫不敏感。
  5. tip: 若是使用了不受信任的HTML節點，該節點及其全部子節點將會被移除。
  6. tip: img 標籤僅支持網絡圖片。
  7. tip: 若是在自定義組件中使用 rich-text 組件，那麼僅自定義組件的 wxss 樣式對 rich-text 中的 class 生效。

示例代碼

<rich-text nodes="{{nodes}}" bindtap="tap"></rich-text>
Page({
  data: {
    nodes: [{
      name: 'div',
      attrs: {
        class: 'div_class',
        style: 'line-height: 60px; color: red;'
      },
      children: [{
        type: 'text',
        text: 'Hello&nbsp;World!'
      }]
    }]
  },
  tap() {
    console.log('tap')
  }
})

 

    ④text文本

 

屬性 類型 默認值 必填 說明 最低版本
selectable boolean false 否 文本是否可選 1.1.0
space string   否 顯示連續空格 1.4.0
decode boolean false 否 是否解碼 1.4.0

space 的合法值

值 說明 最低版本
ensp 中文字符空格一半大小  
emsp 中文字符空格大小  
nbsp 根據字體設置的空格大小  

Bug & Tip

  1. tip: decode能夠解析的有 &nbsp; &lt; &gt; &amp; &apos; &ensp; &emsp;
  2. tip: 各個操做系統的空格標準並不一致。
  3. tip:text 組件內只支持 text 嵌套。
  4. tip: 除了文本節點之外的其餘節點都沒法長按選中。
  5. bug: 基礎庫版本低於 2.1.0 時， text 組件內嵌的 text style 設置可能不會生效。

示例代碼

<view class="btn-area">
  <view class="body-view">
    <text>{{text}}</text>
    <button bindtap="add">add line</button>
    <button bindtap="remove">remove line</button>
  </view>
</view>
var initData = 'this is first line\nthis is second line'
var extraLine = [];
Page({
  data: {
    text: initData
  },
  add: function(e) {
    extraLine.push('other line')
    this.setData({
      text: initData + '\n' + extraLine.join('\n')
    })
  },
  remove: function(e) {
    if (extraLine.length > 0) {
      extraLine.pop()
      this.setData({
        text: initData + '\n' + extraLine.join('\n')
      })
    }
  }
})

 

 

（3）表單組件

 

名稱 功能說明
button 按鈕
checkbox 多選項目
checkbox-group 多項選擇器，內部由多個checkbox組成
editor 富文本編輯器，能夠對圖片、文字進行編輯
form 表單
input 輸入框
label 用來改進表單組件的可用性
picker 從底部彈起的滾動選擇器
picker-view 嵌入頁面的滾動選擇器
picker-view-column 滾動選擇器子項
radio 單選項目
radio-group 單項選擇器，內部由多個 radio 組成
slider 滑動選擇器
switch 開關選擇器
textarea 多行輸入框

 

　　①按鈕

屬性 類型 默認值 必填 說明 最低版本
size string default 否 按鈕的大小 1.0.0
type string default 否 按鈕的樣式類型 1.0.0
plain boolean false 否 按鈕是否鏤空，背景色透明 1.0.0
disabled boolean false 否 是否禁用 1.0.0
loading boolean false 否 名稱前是否帶 loading 圖標 1.0.0
form-type string   否 用於 form 組件，點擊分別會觸發 form 組件的 submit/reset 事件 1.0.0
open-type string   否 微信開放能力 1.1.0
hover-class string button-hover 否 指定按鈕按下去的樣式類。當 hover-class="none"時，沒有點擊態效果 1.0.0
hover-stop-propagation boolean false 否 指定是否阻止本節點的祖先節點出現點擊態 1.5.0
hover-start-time number 20 否 按住後多久出現點擊態，單位毫秒 1.0.0
hover-stay-time number 70 否 手指鬆開後點擊態保留時間，單位毫秒 1.0.0
lang string en 否 指定返回用戶信息的語言，zh_CN 簡體中文，zh_TW 繁體中文，en 英文。 1.3.0
session-from string   否 會話來源，open-type="contact"時有效 1.4.0
send-message-title string 當前標題 否 會話內消息卡片標題，open-type="contact"時有效 1.5.0
send-message-path string 當前分享路徑 否 會話內消息卡片點擊跳轉小程序路徑，open-type="contact"時有效 1.5.0
send-message-img string 截圖 否 會話內消息卡片圖片，open-type="contact"時有效 1.5.0
app-parameter string   否 打開 APP 時，向 APP 傳遞的參數，open-type=launchApp時有效 1.9.5
show-message-card boolean false 否 是否顯示會話內消息卡片，設置此參數爲 true，用戶進入客服會話會在右下角顯示"可能要發送的小程序"提示，用戶點擊後能夠快速發送小程序消息，open-type="contact"時有效 1.5.0
bindgetuserinfo eventhandle   否 用戶點擊該按鈕時，會返回獲取到的用戶信息，回調的detail數據與wx.getUserInfo返回的一致，open-type="getUserInfo"時有效 1.3.0
bindcontact eventhandle   否 客服消息回調，open-type="contact"時有效 1.5.0
bindgetphonenumber eventhandle   否 獲取用戶手機號回調，open-type=getPhoneNumber時有效 1.2.0
binderror eventhandle   否 當使用開放能力時，發生錯誤的回調，open-type=launchApp時有效 1.9.5
bindopensetting eventhandle   否 在打開受權設置頁後回調，open-type=openSetting時有效 2.0.7
bindlaunchapp eventhandle   否 打開 APP 成功的回調，open-type=launchApp時有效

　　

size 的合法值

值 說明 最低版本
default 默認大小  
mini 小尺寸  

type 的合法值

值 說明 最低版本
primary 綠色  
default 白色  
warn 紅色  

form-type 的合法值

值 說明 最低版本
submit 提交表單  
reset 重置表單  

open-type 的合法值

值 說明 最低版本
contact 打開客服會話，若是用戶在會話中點擊消息卡片後返回小程序，能夠從 bindcontact 回調中得到具體信息，具體說明 1.1.0
share 觸發用戶轉發，使用前建議先閱讀使用指引 1.2.0
getPhoneNumber 獲取用戶手機號，能夠從bindgetphonenumber回調中獲取到用戶信息，具體說明 1.2.0
getUserInfo 獲取用戶信息，能夠從bindgetuserinfo回調中獲取到用戶信息 1.3.0
launchApp 打開APP，能夠經過app-parameter屬性設定向APP傳的參數具體說明 1.9.5
openSetting 打開受權設置頁 2.0.7
feedback 打開「意見反饋」頁面，用戶可提交反饋內容並上傳日誌，開發者能夠登陸小程序管理後臺後進入左側菜單「客服反饋」頁面獲取到反饋內容 2.1.0

lang 的合法值

值 說明 最低版本
en 英文  
zh_CN 簡體中文  
zh_TW 繁體中文  

Bug & Tip

  1. tip: button-hover 默認爲{background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}
  2. tip: bindgetphonenumber 從1.2.0 開始支持，可是在1.5.3如下版本中沒法使用wx.canIUse進行檢測，建議使用基礎庫版本進行判斷。
  3. tip: 在bindgetphonenumber 等返回加密信息的回調中調用 wx.login 登陸，可能會刷新登陸態。此時服務器使用 code 換取的 sessionKey 不是加密時使用的 sessionKey，致使解密失敗。建議開發者提早進行 login；或者在回調中先使用 checkSession 進行登陸態檢查，避免 login 刷新登陸態。
  4. tip: 從 2.1.0 起，button 可做爲原生組件的子節點嵌入，以便在原生組件上使用 open-type 的能力。
  5. tip: 目前設置了 form-type 的 button 只會對當前組件中的 form 有效。於是，將 button 封裝在自定義組件中，而 from 在自定義組件外，將會使這個 button 的 form-type 失效。

 

　　②checkbox多選按鈕

屬性 類型 默認值 必填 說明 最低版本
value string   否 checkbox標識，選中時觸發checkbox-group的 change 事件，並攜帶 checkbox 的 value 1.0.0
disabled boolean false 否 是否禁用 1.0.0
checked boolean false 否 當前是否選中，可用來設置默認選中 1.0.0
color string #09BB07 否 checkbox的顏色，同css的color 1.0.0

示例代碼

<checkbox-group bindchange="checkboxChange">
  <label class="checkbox" wx:for="{{items}}">
    <checkbox value="{{item.name}}" checked="{{item.checked}}"/>{{item.value}}
  </label>
</checkbox-group>
Page({
  data: {
    items: [
      {name: 'USA', value: '美國'},
      {name: 'CHN', value: '中國', checked: 'true'},
      {name: 'BRA', value: '巴西'},
      {name: 'JPN', value: '日本'},
      {name: 'ENG', value: '英國'},
      {name: 'TUR', value: '法國'},
    ]
  },
  checkboxChange: function(e) {
    console.log('checkbox發生change事件，攜帶value值爲：', e.detail.value)
  }
})

 

　　③checkbox-group 多項選擇器，內部由多個checkbox組成

 

　　④editor 富文本編輯器，能夠對圖片、文字進行編輯

　　富文本編輯器，能夠對圖片、文字進行編輯。

　　編輯器導出內容支持帶標籤的 html和純文本的 text，編輯器內部採用 delta 格式進行存儲。

　　經過setContents接口設置內容時，解析插入的 html 可能會因爲一些非法標籤致使解析錯誤，建議開發者在小程序內使用時經過 delta 進行插入。

　　富文本組件內部引入了一些基本的樣式使得內容能夠正確的展現，開發時能夠進行覆蓋。須要注意的是，在其它組件或環境中使用富文本組件導出的html時，須要額外引入這段樣式，並維護<ql-container><ql-editor></ql-editor></ql-container>的結構。

　　圖片控件僅初始化時設置有效。（待定）

 

　　⑤表單form

表單。將組件內的用戶輸入的switch input checkbox slider radio picker 提交。

當點擊 form 表單中 form-type 爲 submit 的 button 組件時，會將表單組件中的 value 值進行提交，須要在表單組件中加上 name 來做爲 key。

屬性 類型 默認值 必填 說明 最低版本
report-submit boolean false 否 是否返回 formId 用於發送模板消息 1.0.0
report-submit-timeout number 0 否 等待一段時間（毫秒數）以確認 formId 是否生效。若是未指定這個參數，formId 有很小的機率是無效的（如遇到網絡失敗的狀況）。指定這個參數將能夠檢測 formId 是否有效，以這個參數的時間做爲這項檢測的超時時間。若是失敗，將返回 requestFormId:fail 開頭的 formId 2.6.2
bindsubmit eventhandle   否 攜帶 form 中的數據觸發 submit 事件，event.detail = {value : {'name': 'value'} , formId: ''} 1.0.0
bindreset eventhandle   否 表單重置時會觸發 reset 事件 1.0.0

示例代碼

<form bindsubmit="formSubmit" bindreset="formReset">
  <view class="section section_gap">
    <view class="section__title">switch</view>
    <switch name="switch"/>
  </view>
  <view class="section section_gap">
    <view class="section__title">slider</view>
    <slider name="slider" show-value ></slider>
  </view>

  <view class="section">
    <view class="section__title">input</view>
    <input name="input" placeholder="please input here" />
  </view>
  <view class="section section_gap">
    <view class="section__title">radio</view>
    <radio-group name="radio-group">
      <label><radio value="radio1"/>radio1</label>
      <label><radio value="radio2"/>radio2</label>
    </radio-group>
  </view>
  <view class="section section_gap">
    <view class="section__title">checkbox</view>
    <checkbox-group name="checkbox">
      <label><checkbox value="checkbox1"/>checkbox1</label>
      <label><checkbox value="checkbox2"/>checkbox2</label>
    </checkbox-group>
  </view>
  <view class="btn-area">
    <button form-type="submit">Submit</button>
    <button form-type="reset">Reset</button>
  </view>
</form>
Page({
  formSubmit: function(e) {
    console.log('form發生了submit事件，攜帶數據爲：', e.detail.value)
  },
  formReset: function() {
    console.log('form發生了reset事件')
  }
})

 

 

　　⑥input輸入框

 

　　⑦label用來改進表單組件的可用性

 

　　⑧picker從底部彈起的滾動選擇器

從底部彈起的滾動選擇器。

屬性 類型 默認值 必填 說明 最低版本
mode string selector 否 選擇器類型 1.0.0
disabled boolean false 否 是否禁用 1.0.0
bindcancel eventhandle   否 取消選擇時觸發 1.9.90

mode 的合法值

值 說明 最低版本
selector 普通選擇器  
multiSelector 多列選擇器  
time 時間選擇器  
date 日期選擇器  
region 省市區選擇器  

除了上述通用的屬性，對於不一樣的mode，picker擁有不一樣的屬性。

 

　　⑨picker-view

　　嵌入頁面的滾動選擇器。其中只可放置 picker-view-column組件，其它節點不會顯示。

　　

 

 

　　十、picker-view-column 滾動選擇器子項

　　

　　十一、radio 單選項目

　　　　

屬性 類型 默認值 必填 說明 最低版本
value string   否 radio 標識。當該radio 選中時，radio-group 的 change 事件會攜帶radio的value 1.0.0
checked boolean false 否 當前是否選中 1.0.0
disabled boolean false 否 是否禁用 1.0.0
color string #09BB07 否 radio的顏色，同css的color 1.0.0

 

　　

　　十二、radio-group 單項選擇器，內部由多個 radio 組成

 

　　1三、slider 滑動選擇器

 

　　1四、switch 開關選擇器

Bug & Tip

  1. tip: switch類型切換時在iOS自帶振動反饋，可在系統設置 -> 聲音與觸感 -> 系統觸感反饋中關閉

示例代碼

<view class="body-view">
    <switch checked bindchange="switch1Change"/>
    <switch bindchange="switch2Change"/>
</view>
Page({
  switch1Change: function (e){
    console.log('switch1 發生 change 事件，攜帶值爲', e.detail.value)
  },
  switch2Change: function (e){
    console.log('switch2 發生 change 事件，攜帶值爲', e.detail.value)
  }
})

 

　　1五、textarea 多行輸入框

 

 

 

（4）導航

名稱 功能說明
functional-page-navigator 僅在插件中有效，用於跳轉到插件功能頁
navigator 頁面連接

 　　①functional-page-navigator 僅在插件中有效，用於跳轉到插件功能頁（待定）

 

        ②navigator 頁面連接

<view class="btn-area">
  <navigator url="/pages/navigator/navigator" hover-class="navigator-hover">跳轉到新頁面</navigator>
  <navigator url="/pages/redirect/redirect" open-type="redirect" hover-class="other-navigator-hover">在當前頁打開</navigator>
  <navigator url="/pages/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>

Page({
  onLoad: function(options) {
    this.setData({
      title: options.title
    })
  }
})

 

 

（5）媒體組件

　　①audio音頻

<!-- 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">設置當前播放時間爲14秒</button>
<button type="primary" bindtap="audioStart">回到開頭</button>

// audio.js
Page({
  onReady: function (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: function () {
    this.audioCtx.play()
  },
  audioPause: function () {
    this.audioCtx.pause()
  },
  audio14: function () {
    this.audioCtx.seek(14)
  },
  audioStart: function () {
    this.audioCtx.seek(0)
  }
})

 

 

　　②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)
  }
})

 

　　③image圖片

    圖片。支持JPG、PNG、SVG格式，2.3.0 起支持雲文件ID。

<view class="page">
  <view class="page__hd">
    <text class="page__title">image</text>
    <text class="page__desc">圖片</text>
  </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>
</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: '../resources/cat.jpg'
  },
  imageError: function(e) {
    console.log('image3發生error事件，攜帶值爲', e.detail.errMsg)
  }
})

 

　　④live-player 實時音視頻播放

 

　　⑤live-pusher 實時音視頻錄製

 

　　⑥video視頻

 

<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 () {
  let 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: function (res) {
    this.videoContext = wx.createVideoContext('myVideo')
  },
  inputValue: '',
  data: {
    src: '',
    danmuList: [
      {
        text: '第 1s 出現的彈幕',
        color: '#ff0000',
        time: 1
      },
      {
        text: '第 3s 出現的彈幕',
        color: '#ff00ff',
        time: 3
    }]
  },
  bindInputBlur: function(e) {
    this.inputValue = e.detail.value
  },
  bindButtonTap: function() {
    var that = this
    wx.chooseVideo({
      sourceType: ['album', 'camera'],
      maxDuration: 60,
      camera: ['front','back'],
      success: function(res) {
        that.setData({
          src: res.tempFilePath
        })
      }
    })
  },
  bindSendDanmu: function () {
    this.videoContext.sendDanmu({
      text: this.inputValue,
      color: getRandomColor()
    })
  }
})

 

 

（6）map地圖

     

（7）canvas畫布

 

（8） 開放能力（待定）

名稱 功能說明
web-view 承載網頁的容器
ad Banner 廣告
official-account 公衆號關注組件
open-data 用於展現微信開放的數據

　　

（9）原生組件

 native-component

小程序中的部分組件是由客戶端建立的原生組件，這些組件有：

原生組件的使用限制

因爲原生組件脫離在 WebView 渲染流程外，所以在使用時有如下限制：

  • 原生組件的層級是最高的，因此頁面中的其餘組件不管設置 z-index 爲多少，都沒法蓋在原生組件上。
    • 後插入的原生組件能夠覆蓋以前的原生組件。
  • 原生組件還沒法在 picker-view 中使用。
  • 部分CSS樣式沒法應用於原生組件，例如：
    • 沒法對原生組件設置 CSS 動畫
    • 沒法定義原生組件爲 position: fixed
    • 不能在父級節點使用 overflow: hidden 來裁剪原生組件的顯示區域
  • 原生組件的事件監聽不能使用 bind:eventname 的寫法，只支持 bindeventname。原生組件也不支持 catch 和 capture 的事件綁定方式。
  • 原生組件會遮擋 vConsole 彈出的調試面板。 在工具上，原生組件是用web組件模擬的，所以不少狀況並不能很好的還原真機的表現，建議開發者在使用到原生組件時儘可能在真機上進行調試。*

cover-view 與 cover-image

爲了解決原生組件層級最高的限制。小程序專門提供了 cover-view 和 cover-image 組件，能夠覆蓋在部分原生組件上面。這兩個組件也是原生組件，可是使用限制與其餘原生組件有所不一樣。

原生組件同層渲染

同層渲染是爲了解決原生組件的層級問題，在支持同層渲染後，原生組件與其它組件能夠隨意疊加，有關層級的限制將再也不存在。但須要注意的是，組件內部仍由原生渲染，樣式通常仍是對原生組件內部無效。小程序在 2.4.0 起已支持 video 組件的同層渲染。

原生組件相對層級

爲了能夠調整原生組件之間的相對層級位置，小程序在 v2.7.0 及以上版本支持在樣式中聲明 z-index 來指定原生組件的層級。該 z-index 僅調整原生組件之間的層級順序，其層級仍高於其餘非原生組件。

 原生組件的使用限制

因爲原生組件脫離在 WebView 渲染流程外，所以在使用時有如下限制：

  • 原生組件的層級是最高的，因此頁面中的其餘組件不管設置 z-index 爲多少，都沒法蓋在原生組件上 |

 

（10）無障礙訪問


名稱 功能說明
aria-component ## 無障礙訪問
爲了更好地知足視障人士對於小程序的訪問需求，基礎庫自2.7.1起，支持部分ARIA標籤

 

Tips

  1. 安卓和iOS讀屏模式下設置aria-role後朗讀的內容不一樣系統之間會有差別
  2. 可設置的aria-role可參看 Using Aria中的Widget Roles，部分role的設置在移動端可能無效。

.

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程