uni-app 中组件的基本使用

绝地灬酷狼 2023-03-04 08:18 7阅读 0赞

# 组件的基本使用： #

uni-app 提供了丰富的基础组件给开发者，开发者可以像搭积木一样，组合各种组件拼接成自己的应用。

uni-app 中的组件，就像 HTML 中的 div、span、p 等等标签一样，用于搭建页面的基础结构。

更多介绍参见：[uni-app 官网][uni-app]

## text 文本组件的用法： ##

text 组件就是用来显示一个文本的，它就类似于 HTML 中的 span 标签。

text 组件的属性如下：

**属性说明**

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
   <th>平台差异说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>selectable</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>文本是否可选</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>space</td> 
   <td>String</td> 
   <td>&nbsp;</td> 
   <td>显示连续空格</td> 
   <td>App、H5、微信小程序</td> 
  </tr> 
  <tr> 
   <td>decode</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否解码</td> 
   <td>App、H5、微信小程序</td> 
  </tr> 
 </tbody> 
</table>

**space 值说明**

<table> 
 <thead> 
  <tr> 
   <th>值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>ensp</td> 
   <td>中文字符空格一半大小</td> 
  </tr> 
  <tr> 
   <td>emsp</td> 
   <td>中文字符空格大小</td> 
  </tr> 
  <tr> 
   <td>nbsp</td> 
   <td>根据字体设置的空格大小</td> 
  </tr> 
 </tbody> 
</table>

** 注意：**

*  `<text>` 组件内只支持嵌套 `<text>`，不支持其它组件或自定义组件，否则会引发在不同平台的渲染差异。
 *  在app-nvue下，只有`<text>`才能包裹文本内容。无法在`<view>`组件包裹文本。
 *  decode 可以解析的有 ` ` `<` `>` `&` `'` ` ` ` `。
 *  各个操作系统的空格标准并不一致。
 *  除了文本节点以外的其他节点都无法长按选中。
 *  支持 `\n` 方式换行。
 *  如果使用 `<span>` 组件编译时会被转换为 `<text>`。

示例代码如下：

<view class="container">
    		首页
    		<view>
    			<text>text组件的学习</text>
    		</view>
    		<view>
    			<text selectable="true">text组件中的selectable的属性的学习</text>
    		</view>
    		<view>
    			<text space="nbsp" style="font-size: 20px;">组件中的    space属性的学习</text>
    		</view>
    	</view>

效果图：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM1MzY2MjY5_size_16_color_FFFFFF_t_70][]

## view 视图容器组件的用法： ##

view 视图容器组件，类似于 HTML 中的 div ，是一个盒子，一个容器组件。

如果使用[nvue][]，则需注意，包裹文字应该使用组件。

**属性说明**

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>hover-class</td> 
   <td>String</td> 
   <td>none</td> 
   <td>指定按下去的样式类。当 hover-class="none" 时，没有点击态效果</td> 
  </tr> 
  <tr> 
   <td>hover-stop-propagation</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>指定是否阻止本节点的祖先节点出现点击态，也就是阻止事件冒泡</td> 
  </tr> 
  <tr> 
   <td>hover-start-time</td> 
   <td>Number</td> 
   <td>50</td> 
   <td>按住后多久出现点击态，单位毫秒</td> 
  </tr> 
  <tr> 
   <td>hover-stay-time</td> 
   <td>Number</td> 
   <td>400</td> 
   <td>手指松开后点击态保留时间，单位毫秒</td> 
  </tr> 
 </tbody> 
</table>

hover-stop-propagation 属性介绍：

在实际开开发过程中，当子父组件都有点击事件时，触发子组件的点击事件会一并触发触发父组件的点击事件，如果想阻止事件穿透，那么就需要给子组件设置hover-stop-propagation 属性

事件冒泡代码：

<template>
    	<view class="container">
    		
    		
    		<view class="box2" hover-class="box2-active">
    			<view class="box3" hover-class="box3-active">view 组件中 hover-stop-propagation 属性的使用</view>
    		</view>
    	</view>
    </template>
    
    <script>
    	export default {
    		data() {
    			return {
    			}
    		},
    		methods: {
    			getData() {
    				//#ifdef APP-PLUS
    				
    				//#endif
    			}
    
    		}
    	}
    </script>
    
    <style lang="scss">
    	.container {
    		padding: 20px;
    		font-size: 14px;
    		line-height: 24px;
    		
    		.box2 {
    			width: 300px;
    			height: 300px;
    			background: yellow;
    		}
    		.box2-active {
    			background-color: red;
    		}
    		.box3 {
    			width: 100px;
    			height: 100px;
    			background: blue;
    		}
    		.box3-active {
    			background-color: black;
    		}
    	}
    </style>

事件冒泡效果图：

![20200802173201124.gif][]

出现上述情况以后，可以通过子组件设置 hover-stop-propagation 属性 来阻止事件冒泡，如下代码：

<template>
    	<view class="container">
    		
    		
    		<view class="box2" hover-class="box2-active">
    			<view class="box3" hover-class="box3-active" hover-stop-propagation="true">view 组件中 hover-stop-propagation 属性的使用</view>
    		</view>
    	</view>
    </template>
    
    <script>
    	export default {
    		data() {
    			return {
    			}
    		},
    		methods: {
    			getData() {
    				//#ifdef APP-PLUS
    				
    				//#endif
    			}
    
    		}
    	}
    </script>
    
    <style lang="scss">
    	.container {
    		padding: 20px;
    		font-size: 14px;
    		line-height: 24px;
    		
    		.box2 {
    			width: 300px;
    			height: 300px;
    			background: yellow;
    		}
    		.box2-active {
    			background-color: red;
    		}
    		.box3 {
    			width: 100px;
    			height: 100px;
    			background: blue;
    		}
    		.box3-active {
    			background-color: black;
    		}
    	}
    </style>

效果图：

![2020080217365322.gif][]

## button 按钮组件的用法： ##

button 按钮组件

**属性说明**

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
   <th>生效时机</th> 
   <th>平台差异说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>size</td> 
   <td>String</td> 
   <td>default</td> 
   <td>按钮的大小</td> 
   <td>&nbsp;</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>type</td> 
   <td>String</td> 
   <td>default</td> 
   <td>按钮的样式类型</td> 
   <td>&nbsp;</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>plain</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>按钮是否镂空，背景色透明</td> 
   <td>&nbsp;</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>disabled</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否禁用</td> 
   <td>&nbsp;</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>loading</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>名称前是否带 loading 图标</td> 
   <td>&nbsp;</td> 
   <td>App-nvue 平台，在 ios 上为雪花，Android上为圆圈</td> 
  </tr> 
  <tr> 
   <td>form-type</td> 
   <td>String</td> 
   <td>&nbsp;</td> 
   <td>用于&nbsp;<code>&lt;form&gt;</code>&nbsp;组件，点击分别会触发&nbsp;<code>&lt;form&gt;</code>&nbsp;组件的 submit/reset 事件</td> 
   <td>&nbsp;</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>open-type</td> 
   <td>String</td> 
   <td>&nbsp;</td> 
   <td>开放能力</td> 
   <td>&nbsp;</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>hover-class</td> 
   <td>String</td> 
   <td>button-hover</td> 
   <td>指定按钮按下去的样式类。当 hover-class="none" 时，没有点击态效果</td> 
   <td>&nbsp;</td> 
   <td>App-nvue 平台暂不支持</td> 
  </tr> 
  <tr> 
   <td>hover-start-time</td> 
   <td>Number</td> 
   <td>20</td> 
   <td>按住后多久出现点击态，单位毫秒</td> 
   <td>&nbsp;</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>hover-stay-time</td> 
   <td>Number</td> 
   <td>70</td> 
   <td>手指松开后点击态保留时间，单位毫秒</td> 
   <td>&nbsp;</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>app-parameter</td> 
   <td>String</td> 
   <td>&nbsp;</td> 
   <td>打开 APP 时，向 APP 传递的参数，open-type=launchApp时有效</td> 
   <td>&nbsp;</td> 
   <td>微信小程序、QQ小程序</td> 
  </tr> 
  <tr> 
   <td>hover-stop-propagation</td> 
   <td>boolean</td> 
   <td>false</td> 
   <td>指定是否阻止本节点的祖先节点出现点击态</td> 
   <td>&nbsp;</td> 
   <td>微信小程序</td> 
  </tr> 
  <tr> 
   <td>lang</td> 
   <td>string</td> 
   <td>'en'</td> 
   <td>指定返回用户信息的语言，zh_CN 简体中文，zh_TW 繁体中文，en 英文。</td> 
   <td>&nbsp;</td> 
   <td>微信小程序</td> 
  </tr> 
  <tr> 
   <td>session-from</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>会话来源，open-type="contact"时有效</td> 
   <td>&nbsp;</td> 
   <td>微信小程序</td> 
  </tr> 
  <tr> 
   <td>send-message-title</td> 
   <td>string</td> 
   <td>当前标题</td> 
   <td>会话内消息卡片标题，open-type="contact"时有效</td> 
   <td>&nbsp;</td> 
   <td>微信小程序</td> 
  </tr> 
  <tr> 
   <td>send-message-path</td> 
   <td>string</td> 
   <td>当前分享路径</td> 
   <td>会话内消息卡片点击跳转小程序路径，open-type="contact"时有效</td> 
   <td>&nbsp;</td> 
   <td>微信小程序</td> 
  </tr> 
  <tr> 
   <td>send-message-img</td> 
   <td>string</td> 
   <td>截图</td> 
   <td>会话内消息卡片图片，open-type="contact"时有效</td> 
   <td>&nbsp;</td> 
   <td>微信小程序</td> 
  </tr> 
  <tr> 
   <td>show-message-card</td> 
   <td>boolean</td> 
   <td>false</td> 
   <td>是否显示会话内消息卡片，设置此参数为 true，用户进入客服会话会在右下角显示"可能要发送的小程序"提示，用户点击后可以快速发送小程序消息，open-type="contact"时有效</td> 
   <td>&nbsp;</td> 
   <td>微信小程序</td> 
  </tr> 
  <tr> 
   <td>@getphonenumber</td> 
   <td>Handler</td> 
   <td>&nbsp;</td> 
   <td>获取用户手机号回调</td> 
   <td>open-type="getPhoneNumber"</td> 
   <td>微信小程序</td> 
  </tr> 
  <tr> 
   <td>@getuserinfo</td> 
   <td>Handler</td> 
   <td>&nbsp;</td> 
   <td>用户点击该按钮时，会返回获取到的用户信息，从返回参数的detail中获取到的值同uni.getUserInfo</td> 
   <td>open-type="getUserInfo"</td> 
   <td>微信小程序</td> 
  </tr> 
  <tr> 
   <td>@error</td> 
   <td>Handler</td> 
   <td>&nbsp;</td> 
   <td>当使用开放能力时，发生错误的回调</td> 
   <td>open-type="launchApp"</td> 
   <td>微信小程序</td> 
  </tr> 
  <tr> 
   <td>@opensetting</td> 
   <td>Handler</td> 
   <td>&nbsp;</td> 
   <td>在打开授权设置页并关闭后回调</td> 
   <td>open-type="openSetting"</td> 
   <td>微信小程序</td> 
  </tr> 
  <tr> 
   <td>@launchapp</td> 
   <td>Handler</td> 
   <td>&nbsp;</td> 
   <td>打开 APP 成功的回调</td> 
   <td>open-type="launchApp"</td> 
   <td>微信小程序</td> 
  </tr> 
 </tbody> 
</table>

*  **注1：`button-hover` 默认为 `{background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}`**
 *  `open-type="launchApp"`时需要调起的APP接入微信OpenSDK[详见][Link 1]

**size 有效值**

<table> 
 <thead> 
  <tr> 
   <th>值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>default</td> 
   <td>默认大小</td> 
  </tr> 
  <tr> 
   <td>mini</td> 
   <td>小尺寸</td> 
  </tr> 
 </tbody> 
</table>

**type 有效值**

<table> 
 <thead> 
  <tr> 
   <th>值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>primary</td> 
   <td>微信小程序、360小程序为绿色，App、H5、百度小程序、支付宝小程序、快应用为蓝色，字节跳动小程序为红色，QQ小程序为浅蓝色。如想在多端统一颜色，请改用default，然后自行写样式</td> 
  </tr> 
  <tr> 
   <td>default</td> 
   <td>白色</td> 
  </tr> 
  <tr> 
   <td>warn</td> 
   <td>红色</td> 
  </tr> 
 </tbody> 
</table>

**form-type 有效值**

<table> 
 <thead> 
  <tr> 
   <th>值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>submit</td> 
   <td>提交表单</td> 
  </tr> 
  <tr> 
   <td>reset</td> 
   <td>重置表单</td> 
  </tr> 
 </tbody> 
</table>

**open-type 有效值**

<table> 
 <thead> 
  <tr> 
   <th>值</th> 
   <th>说明</th> 
   <th>平台差异说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>feedback</td> 
   <td>打开“意见反馈”页面，用户可提交反馈内容并上传日志</td> 
   <td>App、微信小程序、QQ小程序</td> 
  </tr> 
  <tr> 
   <td>share</td> 
   <td>触发用户转发</td> 
   <td>微信小程序、百度小程序、支付宝小程序、字节跳动小程序、QQ小程序</td> 
  </tr> 
  <tr> 
   <td>getUserInfo</td> 
   <td>获取用户信息，可以从@getuserinfo回调中获取到用户信息，包括头像、昵称等信息</td> 
   <td>微信小程序、百度小程序、QQ小程序</td> 
  </tr> 
  <tr> 
   <td>contact</td> 
   <td>打开客服会话，如果用户在会话中点击消息卡片后返回应用，可以从 @contact 回调中获得具体信息</td> 
   <td>微信小程序、百度小程序</td> 
  </tr> 
  <tr> 
   <td>getPhoneNumber</td> 
   <td>获取用户手机号，可以从@getphonenumber回调中获取到用户信息</td> 
   <td>微信小程序、百度小程序、字节跳动小程序、支付宝小程序</td> 
  </tr> 
  <tr> 
   <td>launchApp</td> 
   <td>打开APP，可以通过app-parameter属性设定向APP传的参数</td> 
   <td><a href="https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/launchApp.html" rel="nofollow">微信小程序</a>、<a href="https://q.qq.com/wiki/develop/miniprogram/frame/open_ability/open_app.html" rel="nofollow">QQ小程序</a></td> 
  </tr> 
  <tr> 
   <td>openSetting</td> 
   <td>打开授权设置页</td> 
   <td>微信小程序、百度小程序</td> 
  </tr> 
  <tr> 
   <td>getAuthorize</td> 
   <td>支持小程序授权</td> 
   <td>支付宝小程序</td> 
  </tr> 
  <tr> 
   <td>contactShare</td> 
   <td>分享到通讯录好友</td> 
   <td>支付宝小程序</td> 
  </tr> 
  <tr> 
   <td>lifestyle</td> 
   <td>关注生活号</td> 
   <td>支付宝小程序</td> 
  </tr> 
  <tr> 
   <td>openGroupProfile</td> 
   <td>呼起QQ群资料卡页面，可以通过group-id属性设定需要打开的群资料卡的群号，同时manifest中必须配置groupIdList</td> 
   <td>QQ小程序基础库1.4.7版本+</td> 
  </tr> 
 </tbody> 
</table>

**注意**

*  在小程序中，开发者可以登录 [微信小程序管理后台][Link 2] 、[QQ小程序后台][QQ]后，进入菜单“客服反馈”页面获取反馈内容。
 *  在 App 中，开发者登录 [DCloud开发者中心][DCloud] 后点击应用名称，进入左侧菜单“用户反馈”页面获取反馈内容。
 *  点击 share 分享按钮时会触发 [onShareAppMessage][]
 *  支付宝小程序平台，获取用户手机号时，建议先通过条件编译的方式，调用支付宝原生API，[参考][Link 3]

<button type="primary">登录</button>
    		<button size="mini" plain>注册</button>

## image 组件的使用： ##

image 就是用来显示图片的组件

**属性：**

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
   <th>平台差异说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>src</td> 
   <td>String</td> 
   <td>&nbsp;</td> 
   <td>图片资源地址</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>mode</td> 
   <td>String</td> 
   <td>'scaleToFill'</td> 
   <td>图片裁剪、缩放的模式</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>lazy-load</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>图片懒加载。只针对page与scroll-view下的image有效</td> 
   <td>微信小程序、App、百度小程序、字节跳动小程序</td> 
  </tr> 
  <tr> 
   <td>fade-show</td> 
   <td>Boolean</td> 
   <td>true</td> 
   <td>图片显示动画效果</td> 
   <td>仅App-nvue 2.3.4+ Android有效</td> 
  </tr> 
  <tr> 
   <td>webp</td> 
   <td>boolean</td> 
   <td>false</td> 
   <td>默认不解析 webP 格式，只支持网络资源</td> 
   <td>微信小程序2.9.0</td> 
  </tr> 
  <tr> 
   <td>show-menu-by-longpress</td> 
   <td>boolean</td> 
   <td>false</td> 
   <td>开启长按图片显示识别小程序码菜单</td> 
   <td>微信小程序2.7.0</td> 
  </tr> 
  <tr> 
   <td>@error</td> 
   <td>HandleEvent</td> 
   <td>&nbsp;</td> 
   <td>当错误发生时，发布到 AppService 的事件名，事件对象event.detail = {errMsg: 'something wrong'}</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>@load</td> 
   <td>HandleEvent</td> 
   <td>&nbsp;</td> 
   <td>当图片载入完毕时，发布到 AppService 的事件名，事件对象event.detail = {height:'图片高度px', width:'图片宽度px'}</td> 
   <td>&nbsp;</td> 
  </tr> 
 </tbody> 
</table>

**Tips**

*  `<image>` 组件默认宽度 300px、高度 225px；`app-nvue平台，暂时默认为屏幕宽度`
 *  `src` 仅支持相对路径、绝对路径，支持 base64 码；
 *  页面结构复杂，css样式太多的情况，使用 image 可能导致样式生效较慢，出现 “闪一下” 的情况，此时设置 `image{will-change: transform}` ,可优化此问题。
 *  自定义组件里面使用 `<image>`时，若 `src` 使用相对路径可能出现路径查找失败的情况，故建议使用绝对路径。
 *  webp格式的图片在Android上是内置支持的。iOS上不同平台不一样，具体如下：app-vue下，iOS不支持；app-nvue下，iOS支持；微信小程序2.9.0起，iOS支持。
 *  svg 格式的图片在不同的平台支持情况不同。具体为：app-nvue 不支持 svg 格式的图片，小程序上只支持网络地址。

**mode 有效值：**

mode 有 13 种模式，其中 4 种是缩放模式，9 种是裁剪模式。

<table> 
 <thead> 
  <tr> 
   <th style="width:66px;">模式</th> 
   <th style="width:57px;">值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td style="width:66px;">缩放</td> 
   <td style="width:57px;">scaleToFill</td> 
   <td>不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素</td> 
  </tr> 
  <tr> 
   <td style="width:66px;">缩放</td> 
   <td style="width:57px;">aspectFit</td> 
   <td>保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。</td> 
  </tr> 
  <tr> 
   <td style="width:66px;">缩放</td> 
   <td style="width:57px;">aspectFill</td> 
   <td>保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。</td> 
  </tr> 
  <tr> 
   <td style="width:66px;">缩放</td> 
   <td style="width:57px;">widthFix</td> 
   <td>宽度不变，高度自动变化，保持原图宽高比不变</td> 
  </tr> 
  <tr> 
   <td style="width:66px;">缩放</td> 
   <td style="width:57px;">heightFix</td> 
   <td>高度不变，宽度自动变化，保持原图宽高比不变&nbsp;<strong>微信小程序 2.10.3 支持</strong></td> 
  </tr> 
  <tr> 
   <td style="width:66px;">裁剪</td> 
   <td style="width:57px;">top</td> 
   <td>不缩放图片，只显示图片的顶部区域</td> 
  </tr> 
  <tr> 
   <td style="width:66px;">裁剪</td> 
   <td style="width:57px;">bottom</td> 
   <td>不缩放图片，只显示图片的底部区域</td> 
  </tr> 
  <tr> 
   <td style="width:66px;">裁剪</td> 
   <td style="width:57px;">center</td> 
   <td>不缩放图片，只显示图片的中间区域</td> 
  </tr> 
  <tr> 
   <td style="width:66px;">裁剪</td> 
   <td style="width:57px;">left</td> 
   <td>不缩放图片，只显示图片的左边区域</td> 
  </tr> 
  <tr> 
   <td style="width:66px;">裁剪</td> 
   <td style="width:57px;">right</td> 
   <td>不缩放图片，只显示图片的右边区域</td> 
  </tr> 
  <tr> 
   <td style="width:66px;">裁剪</td> 
   <td style="width:57px;">top left</td> 
   <td>不缩放图片，只显示图片的左上边区域</td> 
  </tr> 
  <tr> 
   <td style="width:66px;">裁剪</td> 
   <td style="width:57px;">top right</td> 
   <td>不缩放图片，只显示图片的右上边区域</td> 
  </tr> 
  <tr> 
   <td style="width:66px;">裁剪</td> 
   <td style="width:57px;">bottom left</td> 
   <td>不缩放图片，只显示图片的左下边区域</td> 
  </tr> 
  <tr> 
   <td style="width:66px;">裁剪</td> 
   <td style="width:57px;">bottom right</td> 
   <td>不缩放图片，只显示图片的右下边区域</td> 
  </tr> 
 </tbody> 
</table>

示例代码：

<image src="../../static/image/home_default.png" mode="aspectFit"></image>

## swipter 按钮组件的用法： ##

swipter 组件通常用于实现轮播图，可以实现上下滑动、也可以左右滑动。

注意滑动切换和滚动的区别，滑动切换是一屏一屏的切换。swiper下的每个swiper-item是一个滑动切换区域，不能停留在2个滑动区域之间。

**属性说明**

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
   <th>平台差异说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>indicator-dots</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否显示面板指示点</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>indicator-color</td> 
   <td>Color</td> 
   <td>rgba(0, 0, 0, .3)</td> 
   <td>指示点颜色</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>indicator-active-color</td> 
   <td>Color</td> 
   <td>#000000</td> 
   <td>当前选中的指示点颜色</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>active-class</td> 
   <td>String</td> 
   <td>&nbsp;</td> 
   <td>swiper-item 可见时的 class</td> 
   <td>支付宝小程序</td> 
  </tr> 
  <tr> 
   <td>changing-class</td> 
   <td>String</td> 
   <td>&nbsp;</td> 
   <td>acceleration 设置为 { {true}} 时且处于滑动过程中，中间若干屏处于可见时的class</td> 
   <td>支付宝小程序</td> 
  </tr> 
  <tr> 
   <td>autoplay</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否自动切换</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>current</td> 
   <td>Number</td> 
   <td>0</td> 
   <td>当前所在滑块的 index</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>current-item-id</td> 
   <td>String</td> 
   <td>&nbsp;</td> 
   <td>当前所在滑块的 item-id ，不能与 current 被同时指定</td> 
   <td>支付宝小程序不支持</td> 
  </tr> 
  <tr> 
   <td>interval</td> 
   <td>Number</td> 
   <td>5000</td> 
   <td>自动切换时间间隔</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>duration</td> 
   <td>Number</td> 
   <td>500</td> 
   <td>滑动动画时长</td> 
   <td>app-nvue不支持</td> 
  </tr> 
  <tr> 
   <td>circular</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否采用衔接滑动，即播放到末尾后重新回到开头</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>vertical</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>滑动方向是否为纵向</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>previous-margin</td> 
   <td>String</td> 
   <td>0px</td> 
   <td>前边距，可用于露出前一项的一小部分，接受 px 和 rpx 值</td> 
   <td>app-nvue、字节跳动小程序不支持</td> 
  </tr> 
  <tr> 
   <td>next-margin</td> 
   <td>String</td> 
   <td>0px</td> 
   <td>后边距，可用于露出后一项的一小部分，接受 px 和 rpx 值</td> 
   <td>app-nvue、字节跳动小程序不支持</td> 
  </tr> 
  <tr> 
   <td>acceleration</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>当开启时，会根据滑动速度，连续滑动多屏</td> 
   <td>支付宝小程序</td> 
  </tr> 
  <tr> 
   <td>disable-programmatic-animation</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否禁用代码变动触发 swiper 切换时使用动画。</td> 
   <td>支付宝小程序</td> 
  </tr> 
  <tr> 
   <td>display-multiple-items</td> 
   <td>Number</td> 
   <td>1</td> 
   <td>同时显示的滑块数量</td> 
   <td>app-nvue、支付宝小程序不支持</td> 
  </tr> 
  <tr> 
   <td>skip-hidden-item-layout</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否跳过未显示的滑块布局，设为 true 可优化复杂情况下的滑动性能，但会丢失隐藏状态滑块的布局信息</td> 
   <td>App、微信小程序</td> 
  </tr> 
  <tr> 
   <td>disable-touch</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否禁止用户 touch 操作</td> 
   <td>App 2.5.5+、H5 2.5.5+、支付宝小程序、字节跳动小程序（只在初始化时有效，不能动态变更）</td> 
  </tr> 
  <tr> 
   <td>touchable</td> 
   <td>Boolean</td> 
   <td>true</td> 
   <td>是否监听用户的触摸事件，只在初始化时有效，不能动态变更</td> 
   <td>字节跳动小程序（uni-app 2.5.5+ 推荐统一使用 disable-touch）</td> 
  </tr> 
  <tr> 
   <td>easing-function</td> 
   <td>String</td> 
   <td>default</td> 
   <td>指定 swiper 切换缓动动画类型，有效值：default、linear、easeInCubic、easeOutCubic、easeInOutCubic</td> 
   <td>微信小程序</td> 
  </tr> 
  <tr> 
   <td>@change</td> 
   <td>EventHandle</td> 
   <td>&nbsp;</td> 
   <td>current 改变时会触发 change 事件，event.detail = {current: current, source: source}</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>@transition</td> 
   <td>EventHandle</td> 
   <td>&nbsp;</td> 
   <td>swiper-item 的位置发生改变时会触发 transition 事件，event.detail = {dx: dx, dy: dy}，支付宝小程序暂不支持dx, dy</td> 
   <td>App、H5、微信小程序、支付宝小程序、字节跳动小程序、QQ小程序</td> 
  </tr> 
  <tr> 
   <td>@animationfinish</td> 
   <td>EventHandle</td> 
   <td>&nbsp;</td> 
   <td>动画结束时会触发 animationfinish 事件，event.detail = {current: current, source: source}</td> 
   <td>字节跳动小程序不支持</td> 
  </tr> 
 </tbody> 
</table>

change 事件返回 detail 中包含一个 source 字段，表示导致变更的原因，可能值如下：

*  autoplay 自动播放导致swiper变化。
 *  touch 用户划动引起swiper变化。
 *  其他原因将用空字符串表示。

**swiper做左右拖动的长列表的专项问题**

*  swiper是单页组件，适合做banner图轮播和简单列表左右滑动。
 *  因为性能问题，用swiper做复杂长列表，需要较高的优化技巧以及接受一些限制。
 *  这是一个范例，[插件市场新闻模板示例][Link 4]，它在App端使用了nvue的原生渲染，实现高性能的左右拖动长列表；并支持可自定义的任何形式的下拉刷新。它在非App端使用的模式是只缓存左右一共3列的数据，dom中的数据过多时，它会自动释放。就是说App上，只要看过这一页，再进去时内容是还在的。而在非App上，只能做到缓存3页数据，其他页即便看过，再进去也会重新加载。并且非App的这种情况下，不再提供下拉刷新。虽然插件市场也有其他前端模拟的下拉刷新，但性能不佳。一般小程序的大厂案例里，提供左右拖长列表的，都是这种做法。

**Tips**

*  使用竖向滚动时，需要给 `<scroll-view>` 一个固定高度，通过 css 设置 height。
 *  注意：其中只可放置 `<swiper-item>` 组件，否则会导致未定义的行为。
 *  如果遇到current、current-item-id属性设置不生效的问题参考：[组件属性设置不生效解决办法][Link 5]
 *  banner图的切换效果和指示器的样式，有多种风格可自定义，可在[uni-app插件市场][uni-app 1]搜索
 *  swiper在App的vue中、百度支付宝头条QQ小程序中，不支持内嵌video、map等原生组件。在微信基础库2.4.4起和App nvue2.1.5起支持内嵌原生组件。竖向的swiper内嵌视频可实现抖音、映客等视频垂直拖动切换效果。
 *  同时监听 change transition，开始滑动时触发transition, 放开手后，在ios平台触发顺序为 transition... change，Android/微信小程序/支付宝为 transition... change transition...

[swiper-item][]

仅可放置在 `<swiper>` 组件中，宽高自动设置为100%。注意：宽高100%是相对于其父组件，不是相对于子组件，不能被子组件自动撑开。

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>item-id</td> 
   <td>String</td> 
   <td>&nbsp;</td> 
   <td>该 swiper-item 的标识符</td> 
  </tr> 
 </tbody> 
</table>

示例：

样式

.swipter-container {
    			width: 100%;
    		}

效果图：

![20200813142130567.gif][]

[uni-app]: https://uniapp.dcloud.io/component/README
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM1MzY2MjY5_size_16_color_FFFFFF_t_70]: /images/20230208/39e3b75223f64037831ac3657886e55b.png
[nvue]: https://uniapp.dcloud.io/use-weex
[20200802173201124.gif]: /images/20230208/1ec9869758a94feea65ce216233409e6.png
[2020080217365322.gif]: /images/20230208/d3efc448e9a94d67973370b9d891354b.png
[Link 1]: https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/launchApp.html
[Link 2]: https://mp.weixin.qq.com/
[QQ]: https://q.qq.com/#/
[DCloud]: https://dev.dcloud.net.cn/
[onShareAppMessage]: https://uniapp.dcloud.io/api/plugins/share
[Link 3]: https://docs.alipay.com/mini/api/getphonenumber
[Link 4]: https://ext.dcloud.net.cn/plugin?id=103
[Link 5]: https://uniapp.dcloud.io/use?id=%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98
[uni-app 1]: https://ext.dcloud.net.cn/search?q=%E8%BD%AE%E6%92%AD
[swiper-item]: https://uniapp.dcloud.io/component/swiper?id=swiper-item
[20200813142130567.gif]: /images/20230208/4bee8ed67a4e4f1e94bc27d4e00c0913.png