1

2026-03-15 10:15:02 +08:00
parent 2dd217522c
commit 72bb11b34f
916 changed files with 65306 additions and 16102803 deletions
--- a/_DEL/wechat-miniprogram/steering/builtin-components.md
+++ b/_DEL/wechat-miniprogram/steering/builtin-components.md
@@ -0,0 +1,364 @@
+# 内置组件
+
+> 官方文档：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 &nbsp; World
+</text>
+```
+- `selectable`：文本是否可选
+- `space`：显示连续空格（ensp/emsp/nbsp）
+- `decode`：是否解码（`&nbsp;` `&lt;` 等）
+- **注意**：`<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