365 lines
8.9 KiB
Markdown
365 lines
8.9 KiB
Markdown
# 内置组件
|
||
|
||
> 官方文档：https://developers.weixin.qq.com/miniprogram/dev/component/
|
||
|
||
## 视图容器
|
||
|
||
### view
|
||
基础视图容器，类似 HTML 的 `<div>`。
|
||
```xml
|
||
<view class="container" hover-class="hover" hover-stay-time="400">
|
||
内容
|
||
</view>
|
||
```
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| hover-class | string | 按下去的样式类，none 为不设置 |
|
||
| hover-stop-propagation | boolean | 阻止祖先节点出现点击态 |
|
||
| hover-start-time | number | 按住后多久出现点击态(ms)，默认 50 |
|
||
| hover-stay-time | number | 松开后点击态保留时间(ms)，默认 400 |
|
||
|
||
### scroll-view
|
||
可滚动视图区域。
|
||
```xml
|
||
<!-- 纵向滚动需设置固定高度 -->
|
||
<scroll-view
|
||
scroll-y
|
||
style="height: 300px;"
|
||
bindscrolltolower="loadMore"
|
||
bindscroll="onScroll"
|
||
scroll-into-view="{{toView}}"
|
||
scroll-top="{{scrollTop}}"
|
||
refresher-enabled="{{true}}"
|
||
bindrefresherrefresh="onRefresh"
|
||
>
|
||
<view id="item1">A</view>
|
||
<view id="item2">B</view>
|
||
<view id="item3">C</view>
|
||
</scroll-view>
|
||
```
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| scroll-x | boolean | 允许横向滚动 |
|
||
| scroll-y | boolean | 允许纵向滚动 |
|
||
| upper-threshold | number | 距顶部/左边多远时触发 scrolltoupper(px)，默认 50 |
|
||
| lower-threshold | number | 距底部/右边多远时触发 scrolltolower(px)，默认 50 |
|
||
| scroll-top | number | 设置竖向滚动条位置 |
|
||
| scroll-into-view | string | 滚动到某子元素（id） |
|
||
| scroll-with-animation | boolean | 滚动动画过渡 |
|
||
| enable-back-to-top | boolean | iOS 点击状态栏回到顶部 |
|
||
| refresher-enabled | boolean | 开启自定义下拉刷新（2.10.1+） |
|
||
| refresher-triggered | boolean | 设置刷新状态 |
|
||
| enhanced | boolean | 增强模式（2.12.0+，支持 scroll-into-view 动画等） |
|
||
|
||
### swiper / swiper-item
|
||
滑块视图容器（轮播图）。
|
||
```xml
|
||
<swiper
|
||
indicator-dots="{{true}}"
|
||
autoplay="{{true}}"
|
||
interval="{{3000}}"
|
||
duration="{{500}}"
|
||
circular="{{true}}"
|
||
bindchange="swiperChange"
|
||
>
|
||
<swiper-item wx:for="{{imgUrls}}" wx:key="*this">
|
||
<image src="{{item}}" mode="aspectFill"/>
|
||
</swiper-item>
|
||
</swiper>
|
||
```
|
||
|
||
### movable-area / movable-view
|
||
可拖拽区域。
|
||
```xml
|
||
<movable-area style="height: 200px; width: 200px; background: red;">
|
||
<movable-view direction="all" style="height: 50px; width: 50px; background: blue;">
|
||
text
|
||
</movable-view>
|
||
</movable-area>
|
||
```
|
||
|
||
### cover-view / cover-image
|
||
覆盖在原生组件（map、video、canvas、camera、live-player、live-pusher）之上的视图。
|
||
|
||
## 基础内容
|
||
|
||
### text
|
||
```xml
|
||
<text selectable="{{true}}" space="ensp" decode="{{true}}">
|
||
Hello World
|
||
</text>
|
||
```
|
||
- `selectable`：文本是否可选
|
||
- `space`：显示连续空格（ensp/emsp/nbsp）
|
||
- `decode`：是否解码（` ` `<` 等）
|
||
- **注意**：`<text>` 组件内只支持嵌套 `<text>`
|
||
|
||
### rich-text
|
||
```xml
|
||
<rich-text nodes="{{htmlNodes}}"></rich-text>
|
||
```
|
||
```javascript
|
||
data: {
|
||
htmlNodes: '<div class="div_class"><h5>标题</h5><p>段落</p></div>'
|
||
// 也支持 nodes 数组格式
|
||
}
|
||
```
|
||
|
||
### icon
|
||
```xml
|
||
<icon type="success" size="23" color="green"/>
|
||
```
|
||
type 可选：success, success_no_circle, info, warn, waiting, cancel, download, search, clear
|
||
|
||
### progress
|
||
```xml
|
||
<progress percent="80" show-info stroke-width="3" activeColor="#00CC00"/>
|
||
```
|
||
|
||
## 表单组件
|
||
|
||
### button
|
||
```xml
|
||
<button
|
||
type="primary"
|
||
size="default"
|
||
loading="{{isLoading}}"
|
||
disabled="{{isDisabled}}"
|
||
open-type="getPhoneNumber"
|
||
bindgetphonenumber="getPhoneNumber"
|
||
>
|
||
获取手机号
|
||
</button>
|
||
```
|
||
| open-type | 说明 |
|
||
|-----------|------|
|
||
| contact | 打开客服会话 |
|
||
| share | 触发转发 |
|
||
| getPhoneNumber | 获取手机号（需配合 bindgetphonenumber） |
|
||
| getUserInfo | 已废弃（2.27.1+） |
|
||
| launchApp | 打开 APP |
|
||
| openSetting | 打开授权设置页 |
|
||
| chooseAvatar | 获取用户头像（基础库 2.21.2+） |
|
||
| agreePrivacyAuthorization | 同意隐私协议（2.33.2+） |
|
||
|
||
### input
|
||
```xml
|
||
<input
|
||
type="text"
|
||
placeholder="请输入"
|
||
value="{{inputValue}}"
|
||
bindinput="onInput"
|
||
bindfocus="onFocus"
|
||
bindblur="onBlur"
|
||
bindconfirm="onConfirm"
|
||
maxlength="140"
|
||
confirm-type="send"
|
||
adjust-position="{{true}}"
|
||
/>
|
||
```
|
||
| type | 说明 |
|
||
|------|------|
|
||
| text | 文本 |
|
||
| number | 数字 |
|
||
| idcard | 身份证 |
|
||
| digit | 带小数点数字 |
|
||
| nickname | 昵称输入（基础库 2.21.2+） |
|
||
| safe-password | 密码安全输入 |
|
||
|
||
### textarea
|
||
```xml
|
||
<textarea
|
||
value="{{content}}"
|
||
placeholder="请输入内容"
|
||
maxlength="-1"
|
||
auto-height
|
||
bindinput="onInput"
|
||
bindblur="onBlur"
|
||
show-confirm-bar="{{false}}"
|
||
/>
|
||
```
|
||
|
||
### picker
|
||
```xml
|
||
<!-- 普通选择器 -->
|
||
<picker mode="selector" range="{{array}}" bindchange="pickerChange">
|
||
<view>当前选择：{{array[index]}}</view>
|
||
</picker>
|
||
|
||
<!-- 多列选择器 -->
|
||
<picker mode="multiSelector" range="{{multiArray}}" bindchange="multiChange" bindcolumnchange="columnChange">
|
||
<view>{{multiArray[0][multiIndex[0]]}} - {{multiArray[1][multiIndex[1]]}}</view>
|
||
</picker>
|
||
|
||
<!-- 时间选择器 -->
|
||
<picker mode="time" value="{{time}}" start="09:00" end="21:00" bindchange="timeChange">
|
||
<view>{{time}}</view>
|
||
</picker>
|
||
|
||
<!-- 日期选择器 -->
|
||
<picker mode="date" value="{{date}}" start="2020-01-01" end="2030-12-31" bindchange="dateChange">
|
||
<view>{{date}}</view>
|
||
</picker>
|
||
|
||
<!-- 省市区选择器 -->
|
||
<picker mode="region" value="{{region}}" bindchange="regionChange">
|
||
<view>{{region[0]}} - {{region[1]}} - {{region[2]}}</view>
|
||
</picker>
|
||
```
|
||
|
||
### form
|
||
```xml
|
||
<form bindsubmit="formSubmit" bindreset="formReset">
|
||
<input name="username" placeholder="用户名"/>
|
||
<switch name="agree" checked/>
|
||
<slider name="age" show-value/>
|
||
<button form-type="submit">提交</button>
|
||
<button form-type="reset">重置</button>
|
||
</form>
|
||
```
|
||
```javascript
|
||
formSubmit(e) {
|
||
e.detail.value // { username: '...', agree: true, age: 50 }
|
||
}
|
||
```
|
||
|
||
### 其他表单组件
|
||
- `checkbox-group` + `checkbox`
|
||
- `radio-group` + `radio`
|
||
- `slider`
|
||
- `switch`
|
||
- `label`（绑定表单控件）
|
||
|
||
## 导航
|
||
|
||
### navigator
|
||
```xml
|
||
<navigator url="/pages/detail/detail?id=1" open-type="navigate">
|
||
跳转到详情
|
||
</navigator>
|
||
|
||
<navigator url="/pages/index/index" open-type="switchTab">
|
||
切换到首页 Tab
|
||
</navigator>
|
||
|
||
<navigator open-type="navigateBack" delta="1">
|
||
返回上一页
|
||
</navigator>
|
||
```
|
||
|
||
## 媒体组件
|
||
|
||
### image
|
||
```xml
|
||
<image
|
||
src="{{imgUrl}}"
|
||
mode="aspectFill"
|
||
lazy-load
|
||
show-menu-by-longpress
|
||
binderror="imgError"
|
||
bindload="imgLoad"
|
||
/>
|
||
```
|
||
| mode | 说明 |
|
||
|------|------|
|
||
| scaleToFill | 不保持比例缩放，填满 |
|
||
| aspectFit | 保持比例，完整显示（可能留白） |
|
||
| aspectFill | 保持比例，填满（可能裁剪） |
|
||
| widthFix | 宽度不变，高度自适应 |
|
||
| heightFix | 高度不变，宽度自适应（2.10.3+） |
|
||
| top/bottom/center/left/right | 不缩放，显示对应区域 |
|
||
|
||
**注意**：image 默认宽 320px、高 240px。
|
||
|
||
### video
|
||
```xml
|
||
<video
|
||
src="{{videoUrl}}"
|
||
controls
|
||
autoplay="{{false}}"
|
||
loop="{{false}}"
|
||
muted="{{false}}"
|
||
initial-time="0"
|
||
show-fullscreen-btn
|
||
show-play-btn
|
||
enable-progress-gesture
|
||
bindplay="onPlay"
|
||
bindpause="onPause"
|
||
bindended="onEnded"
|
||
binderror="onError"
|
||
/>
|
||
```
|
||
|
||
### camera
|
||
```xml
|
||
<camera
|
||
device-position="back"
|
||
flash="auto"
|
||
bindscancode="onScanCode"
|
||
style="width: 100%; height: 300px;"
|
||
/>
|
||
```
|
||
|
||
## 地图
|
||
|
||
### map
|
||
```xml
|
||
<map
|
||
longitude="{{longitude}}"
|
||
latitude="{{latitude}}"
|
||
scale="16"
|
||
markers="{{markers}}"
|
||
polyline="{{polyline}}"
|
||
show-location
|
||
style="width: 100%; height: 300px;"
|
||
bindmarkertap="onMarkerTap"
|
||
bindregionchange="onRegionChange"
|
||
/>
|
||
```
|
||
|
||
## 画布
|
||
|
||
### canvas
|
||
```xml
|
||
<!-- 新版 Canvas 2D（推荐，基础库 2.9.0+） -->
|
||
<canvas type="2d" id="myCanvas" style="width: 300px; height: 200px;"/>
|
||
```
|
||
```javascript
|
||
const query = wx.createSelectorQuery()
|
||
query.select('#myCanvas')
|
||
.fields({ node: true, size: true })
|
||
.exec((res) => {
|
||
const canvas = res[0].node
|
||
const ctx = canvas.getContext('2d')
|
||
const dpr = wx.getWindowInfo().pixelRatio
|
||
canvas.width = res[0].width * dpr
|
||
canvas.height = res[0].height * dpr
|
||
ctx.scale(dpr, dpr)
|
||
ctx.fillRect(0, 0, 100, 100)
|
||
})
|
||
```
|
||
|
||
## 开放能力组件
|
||
|
||
### web-view
|
||
```xml
|
||
<!-- 承载网页的容器，会自动铺满整个小程序页面 -->
|
||
<web-view src="https://mp.weixin.qq.com/"></web-view>
|
||
```
|
||
- 需要在小程序管理后台配置业务域名
|
||
- 个人类型小程序暂不支持
|
||
|
||
### open-data（已限制）
|
||
```xml
|
||
<!-- 基础库 2.0.1+ 起，大部分 type 已不再返回真实数据 -->
|
||
<open-data type="userAvatarUrl"></open-data>
|
||
<open-data type="userNickName"></open-data>
|
||
```
|
||
|
||
## 在线查询
|
||
|
||
组件文档非常详细，如需查看某个具体组件的完整属性和事件，可抓取：
|
||
- 组件总览：https://developers.weixin.qq.com/miniprogram/dev/component/
|
||
- 具体组件：`https://developers.weixin.qq.com/miniprogram/dev/component/{组件名}.html`
|
||
例如：https://developers.weixin.qq.com/miniprogram/dev/component/scroll-view.html
|