uni-app入门教程（4）组件的基本使用

以你之姓@ 2022-12-29 09:24 488阅读 0赞

### 文章目录 ###

*  前言
 *  一、基础组件
 *   *  1.scroll-view
     *  2.swiper
     *  3.text
     *  4.rich-text
     *  5.process
 *  二、表单组件
 *   *  1.button
     *  2.checkbox
     *  3.input
     *  4.label
     *  5.picker
     *  6.radio
     *  7.slider
     *  8.switch
     *  9.textarea
     *  10.form
 *  三、导航组件和页面传参
 *   *  1.navigator
     *  2.参数传递
 *  四、媒体组件
 *   *  1.audio
     *  2.image
     *  3.video
 *  总结

# 前言 #

本文主要介绍了uni-app中的组件，包括四大类：基础组件（scroll-view、swiper、text等）、表单组件（button、checkbox、input等）、导航组件navigator和页面传参、媒体组件（audio、image和video等），详细说明了这些组件的常用属性和方法，并进行使用举例和演示。

# 一、基础组件 #

组件是视图层的基本组成单元，一个组件通常包括开始标签和结束标签，**属性**用来修饰这个组件，内容在两个标签之内。  
所有组件与属性名都是小写，单词之间以连字符`-`连接，根节点为`<template>`，其下只能有一个根组件。

框架为开发者提供了一系列基础组件，开发者可以通过组合这些基础组件进行快速开发。  
常见的基础组件如下：

<table> 
 <thead> 
  <tr> 
   <th>组件名</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>view</td> 
   <td>视图容器，类似于HTML中的div</td> 
  </tr> 
  <tr> 
   <td>scroll-view</td> 
   <td>可滚动视图容器</td> 
  </tr> 
  <tr> 
   <td>swiper</td> 
   <td>滑块视图容器</td> 
  </tr> 
  <tr> 
   <td>icon</td> 
   <td>图标</td> 
  </tr> 
  <tr> 
   <td>text</td> 
   <td>文字</td> 
  </tr> 
  <tr> 
   <td>rich-text</td> 
   <td>富文本</td> 
  </tr> 
  <tr> 
   <td>progress</td> 
   <td>进度条</td> 
  </tr> 
 </tbody> 
</table>

view是最基础的视图容器，类似于传统html中的div，用于包裹各种元素内容。

## 1.scroll-view ##

可滚动视图区域，用于区域滚动。  
需注意在webview渲染的页面中，区域滚动的性能不及页面滚动。

常见的属性和含义如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>scroll-x</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>允许横向滚动</td> 
  </tr> 
  <tr> 
   <td>scroll-y</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>允许纵向滚动</td> 
  </tr> 
  <tr> 
   <td>upper-threshold</td> 
   <td>Number</td> 
   <td>50</td> 
   <td>距顶部/左边多远时（单位px），触发 scrolltoupper 事件</td> 
  </tr> 
  <tr> 
   <td>lower-threshold</td> 
   <td>Number</td> 
   <td>50</td> 
   <td>距底部/右边多远时（单位px），触发 scrolltolower 事件</td> 
  </tr> 
  <tr> 
   <td>scroll-top</td> 
   <td>Number</td> 
   <td>无</td> 
   <td>设置竖向滚动条位置</td> 
  </tr> 
  <tr> 
   <td>scroll-left</td> 
   <td>Number</td> 
   <td>无</td> 
   <td>设置横向滚动条位置</td> 
  </tr> 
  <tr> 
   <td>scroll-into-view</td> 
   <td>String</td> 
   <td>无</td> 
   <td>值应为某子元素id（id不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素</td> 
  </tr> 
  <tr> 
   <td>scroll-with-animation</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>在设置滚动条位置时使用动画过渡</td> 
  </tr> 
  <tr> 
   <td>enable-flex</td> 
   <td>boolean</td> 
   <td>false</td> 
   <td>启用 flexbox 布局。开启后，当前节点声明了 display: flex 就会成为 flex container，并作用于其孩子节点。</td> 
  </tr> 
 </tbody> 
</table>

常见的事件和含义如下：

<table> 
 <thead> 
  <tr> 
   <th>事件</th> 
   <th>含义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@scrolltoupper</td> 
   <td>滚动到顶部/左边，会触发 scrolltoupper 事件</td> 
  </tr> 
  <tr> 
   <td>@scrolltolower</td> 
   <td>滚动到底部/右边，会触发 scrolltolower 事件</td> 
  </tr> 
  <tr> 
   <td>@scroll</td> 
   <td>滚动时触发，event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}</td> 
  </tr> 
  <tr> 
   <td>@refresherpulling</td> 
   <td>自定义下拉刷新控件被下拉</td> 
  </tr> 
  <tr> 
   <td>@refresherrefresh</td> 
   <td>自定义下拉刷新被触发</td> 
  </tr> 
  <tr> 
   <td>@refresherrestore</td> 
   <td>自定义下拉刷新被复位</td> 
  </tr> 
  <tr> 
   <td>@refresherabort</td> 
   <td>自定义下拉刷新被中止</td> 
  </tr> 
 </tbody> 
</table>

hello uniapp项目中，index.vue如下：

<template>
    	<view>
    		<scroll-view class="scv" scroll-x="true">
    			<view>1</view>
    			<view>2</view>
    			<view>3</view>
    			<view>4</view>
    			<view>5</view>
    			<view>6</view>
    		</scroll-view>
    	</view>
    </template>
    <script> var _self; export default { data() { return { } }, onLoad() { _self = this }, onShow() { }, onHide() { }, methods: { } } </script>
    
    <style> scroll-view { display: flex; } .scv { width: 90%; margin: 0 auto; background: #F0AD4E; flex-wrap: nowrap; white-space: nowrap; } .scv view { width: 50%; height: 100px; background: #007AFF; display: inline-block; } </style>

显示：  
![uniapp component basic scrollview][]

显然，此时可以横向滚动。

## 2.swiper ##

滑块视图容器，一般用于左右滑动或上下滑动，比如banner轮播图。

说明：  
滑动切换和滚动之间是有区别的，滑动切换是一屏一屏的切换，swiper下的每个swiper-item是一个滑动切换区域，不能停留在2个滑动区域之间，而滚动是允许停留在2个滚动区域之间的。

常见属性和含义如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>indicator-dots</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否显示面板指示点</td> 
  </tr> 
  <tr> 
   <td>indicator-color</td> 
   <td>Color</td> 
   <td>rgba(0, 0, 0, .3)</td> 
   <td>指示点颜色</td> 
  </tr> 
  <tr> 
   <td>indicator-active-color</td> 
   <td>Color</td> 
   <td>#000000</td> 
   <td>当前选中的指示点颜色</td> 
  </tr> 
  <tr> 
   <td>active-class</td> 
   <td>String</td> 
   <td>无</td> 
   <td>swiper-item 可见时的 class</td> 
  </tr> 
  <tr> 
   <td>changing-class</td> 
   <td>String</td> 
   <td>无</td> 
   <td>acceleration 设置为 { {true}} 时且处于滑动过程中，中间若干屏处于可见时的class</td> 
  </tr> 
  <tr> 
   <td>autoplay</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否自动切换</td> 
  </tr> 
  <tr> 
   <td>current</td> 
   <td>Number</td> 
   <td>0</td> 
   <td>当前所在滑块的 index</td> 
  </tr> 
  <tr> 
   <td>interval</td> 
   <td>Number</td> 
   <td>5000</td> 
   <td>自动切换时间间隔</td> 
  </tr> 
  <tr> 
   <td>duration</td> 
   <td>Number</td> 
   <td>500</td> 
   <td>滑动动画时长</td> 
  </tr> 
  <tr> 
   <td>circular</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否采用衔接滑动，即播放到末尾后重新回到开头</td> 
  </tr> 
  <tr> 
   <td>vertical</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>滑动方向是否为纵向</td> 
  </tr> 
  <tr> 
   <td>previous-margin</td> 
   <td>String</td> 
   <td>0px</td> 
   <td>前边距，可用于露出前一项的一小部分，接受 px 和 rpx 值</td> 
  </tr> 
  <tr> 
   <td>next-margin</td> 
   <td>String</td> 
   <td>0px</td> 
   <td>后边距，可用于露出后一项的一小部分，接受 px 和 rpx 值</td> 
  </tr> 
 </tbody> 
</table>

常见事件如下：

<table> 
 <thead> 
  <tr> 
   <th>事件</th> 
   <th>含义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@change</td> 
   <td>current 改变时会触发 change 事件，event.detail = {current: current, source: source}</td> 
  </tr> 
  <tr> 
   <td>@transition</td> 
   <td>swiper-item 的位置发生改变时会触发 transition 事件，event.detail = {dx: dx, dy: dy}，支付宝小程序暂不支持dx, dy App、H5、微信小程序、支付宝小程序、字节跳动小程序、QQ小程序</td> 
  </tr> 
  <tr> 
   <td>@animationfinish</td> 
   <td>动画结束时会触发 animationfinish 事件，event.detail = {current: current, source: source}</td> 
  </tr> 
 </tbody> 
</table>

更多可参考[https://uniapp.dcloud.io/component/swiper][https_uniapp.dcloud.io_component_swiper]。

index.vue如下：

<template>
    	<view>
    		<swiper :indicator-dots="true" :autoplay="true" :interval="2000" :duration="1000" previous-margin="10px" next-margin="10px">
    			<swiper-item>
    				<view class="swiper-item uni-bg-red">A</view>
    			</swiper-item>
    			<swiper-item>
    				<view class="swiper-item uni-bg-green">B</view>
    			</swiper-item>
    			<swiper-item>
    				<view class="swiper-item uni-bg-blue">C</view>
    			</swiper-item>
    		</swiper>
    	</view>
    </template>
    <script> var _self; export default { data() { return { } }, onLoad() { _self = this }, onShow() { }, onHide() { }, methods: { } } </script>
    
    <style> swiper-item { background: #4CD964; height: 200px; width: 90%; } </style>

显示：  
![uniapp component basic swiper][]

可以看到，达到了轮播图动态播放的效果。

## 3.text ##

文本组件，用于包裹文本内容，提供**可被选择和复制**的文本，而其他组件的文本都不能被选中、复制。

常见属性如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>selectable</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>文本是否可选</td> 
  </tr> 
  <tr> 
   <td>space</td> 
   <td>String</td> 
   <td>无</td> 
   <td>显示连续空格</td> 
  </tr> 
  <tr> 
   <td>decode</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否解码</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>

## 4.rich-text ##

富文本。

常见属性如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>nodes</td> 
   <td>Array / String</td> 
   <td>[]</td> 
   <td>节点列表 / HTML String</td> 
  </tr> 
  <tr> 
   <td>space</td> 
   <td>string</td> 
   <td>无</td> 
   <td>显示连续空格</td> 
  </tr> 
  <tr> 
   <td>selectable</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>富文本是否可以长按选中，可用于复制，粘贴等场景</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下：

<template>
    	<view>
    		<rich-text :nodes="nodes" @tap="tap"></rich-text>
    	</view>
    </template>
    <script> var _self; export default { data() { return { nodes: [{ name: 'div', attrs: { class: 'div-class', style: 'line-height: 60px; color: red; text-align:center;' }, children: [{ type: 'text', text: 'Hello uni-app!' }] }], strings: '<div style="text-align:center;"><img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/images/uni@2x.png"/></div>' } }, onLoad() { _self = this }, onShow() { }, onHide() { }, methods: { } } </script>
    
    <style> </style>

显示：  
![uniapp component basic richtext][]

显然，渲染出了富文本。

## 5.process ##

进度条。

常见属性如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>percent</td> 
   <td>Float</td> 
   <td>无</td> 
   <td>百分比0~100</td> 
  </tr> 
  <tr> 
   <td>show-info</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>在进度条右侧显示百分比</td> 
  </tr> 
  <tr> 
   <td>stroke-width</td> 
   <td>Number</td> 
   <td>6</td> 
   <td>进度条线的宽度，单位px</td> 
  </tr> 
  <tr> 
   <td>activeColor</td> 
   <td>Color</td> 
   <td>#09BB07（百度为#E6E6E6）</td> 
   <td>已选择的进度条的颜色</td> 
  </tr> 
  <tr> 
   <td>backgroundColor</td> 
   <td>Color</td> 
   <td>#EBEBEB</td> 
   <td>未选择的进度条的颜色</td> 
  </tr> 
  <tr> 
   <td>active</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>进度条从左往右的动画</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下：

<template>
    	<view>
    		<view class="progress-box">
    			<progress percent="20" show-info stroke-width="3" />
    		</view>
    		<view class="progress-box">
    			<progress percent="40" active stroke-width="3" />
    		</view>
    		<view class="progress-box">
    			<progress percent="60" active stroke-width="3" backgroundColor="#999" />
    		</view>
    		<view class="progress-box">
    			<progress percent="80" activeColor="red" active stroke-width="8" />
    		</view>
    	</view>
    </template>
    <script> var _self; export default { data() { return { } }, onLoad() { _self = this }, onShow() { }, onHide() { }, methods: { } } </script>
    
    <style> </style>

显示：  
![uniapp component basic process][]

可以看到，显示出了进度的动态变化。

# 二、表单组件 #

表单组件很常用，主要用于**数据的收集和提交**。

## 1.button ##

按钮。

常见的属性和含义如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>size</td> 
   <td>String</td> 
   <td>default</td> 
   <td>按钮的大小</td> 
  </tr> 
  <tr> 
   <td>type</td> 
   <td>String</td> 
   <td>default</td> 
   <td>按钮的样式类型</td> 
  </tr> 
  <tr> 
   <td>plain</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>按钮是否镂空，背景色透明</td> 
  </tr> 
  <tr> 
   <td>disabled</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否禁用</td> 
  </tr> 
  <tr> 
   <td>loading</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>名称前是否带 loading 图标</td> 
  </tr> 
  <tr> 
   <td>form-type</td> 
   <td>String</td> 
   <td>无</td> 
   <td>用于 <code>&lt;form&gt;</code> 组件，点击分别会触发 <code>&lt;form&gt;</code> 组件的 submit/reset 事件</td> 
  </tr> 
  <tr> 
   <td>open-type</td> 
   <td>String</td> 
   <td>无</td> 
   <td>开放能力</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下：

<template>
    	<view>
    		<button type="default" size="defaultSize" :loading="loading" :plain="plain" :disabled="disabled" @tap="defaultHandler" hover-class="other-button-hover">default</button>
    		<button type="primary" size="primarySize" :loading="loading" :plain="plain" :disabled="disabled" @tap="primaryHandler">primary</button>
    		<button type="warn" size="warnSize" :loading="loading" :plain="plain" :disabled="disabled" @tap="warnHandler">warn</button>
    		<button @tap="setDisabled">点击设置以上按钮disabled属性</button>
    		<button @tap="setPlain">点击设置以上按钮plain属性</button>
    		<button @tap="setLoading">点击设置以上按钮loading属性</button>
    	</view>
    </template>
    <script> var types = ['default', 'primary', 'warn'] export default { data() { return { defaultSize: 'default', primarySize: 'default', warnSize: 'default', disabled: false, plain: false, loading: false } }, onLoad() { }, onShow() { }, onUnload() { }, methods: { setDisabled: function(e){ this.disabled = !this.disabled }, setPlain: function(e){ this.plain = !this.plain }, setLoading: function(e){ this.loading = !this.loading } } } </script>
    
    <style> </style>

显示：  
![uniapp component form button][]

可以看到，在点击button时，触发了相应的操作。

## 2.checkbox ##

checkbox-group是多项选择器，内部由多个 checkbox 组成。

属性如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@change</td> 
   <td>EventHandle</td> 
   <td><code>&lt;checkbox-group&gt;</code>中选中项发生改变是触发 change 事件，detail = {value:[选中的checkbox的value的数组]}</td> 
  </tr> 
 </tbody> 
</table>

checkbox是多选项目，即复选框。

常见属性如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>String</td> 
   <td>无</td> 
   <td><code>&lt;checkbox&gt;</code> 标识，选中时触发 <code>&lt;checkbox-group&gt;</code> 的 change 事件，并携带 <code>&lt;checkbox&gt;</code> 的 value</td> 
  </tr> 
  <tr> 
   <td>disabled</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否禁用</td> 
  </tr> 
  <tr> 
   <td>checked</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>当前是否选中，可用来设置默认选中</td> 
  </tr> 
  <tr> 
   <td>color</td> 
   <td>Color</td> 
   <td>无</td> 
   <td>checkbox的颜色，同css的color</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下：

<template>
    	<view class="content">
    		<checkbox-group name="" @change="checkboxChange">
    			<label class="checkbox" v-for="item in items" :key="item">
    				<checkbox :value="item" />{
       {item}}
    			</label>
    		</checkbox-group>
    	</view>
    </template>
    
    <script> var _self; export default { data() { return { items: ['Reading', 'Running'] } }, onLoad() { _self = this; setTimeout(function(){ _self.age = 20 }, 3000); }, onShow() { console.log('index onshow') }, onHide() { console.log('index onhide') }, methods: { checkboxChange: function(e) { console.log(e) } } } </script>
    
    <style> .content { display: flex; flex-direction: column; align-items: center; justify-content: center; } .logo { height: 200rpx; width: 200rpx; margin-top: 200rpx; margin-left: auto; margin-right: auto; margin-bottom: 50rpx; } .text-area { display: flex; justify-content: center; } .title { font-size: 36rpx; color: #8f8f94; } </style>

显示：  
![uniapp component form checkbox][]

可以看到，已经渲染出页面元素，同时支持点选。

## 3.input ##

输入框。

常见的属性如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>String</td> 
   <td>无</td> 
   <td>输入框的初始内容</td> 
  </tr> 
  <tr> 
   <td>type</td> 
   <td>String</td> 
   <td>text</td> 
   <td>input 的类型</td> 
  </tr> 
  <tr> 
   <td>password</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否是密码类型</td> 
  </tr> 
  <tr> 
   <td>placeholder</td> 
   <td>String</td> 
   <td>无</td> 
   <td>输入框为空时占位符</td> 
  </tr> 
  <tr> 
   <td>placeholder-style</td> 
   <td>String</td> 
   <td>无</td> 
   <td>指定 placeholder 的样式</td> 
  </tr> 
  <tr> 
   <td>placeholder-class</td> 
   <td>String</td> 
   <td>无</td> 
   <td>“input-placeholder” 指定 placeholder 的样式类，注意页面或组件的style中写了scoped时，需要在类名前写/deep/</td> 
  </tr> 
  <tr> 
   <td>disabled</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否禁用</td> 
  </tr> 
  <tr> 
   <td>maxlength</td> 
   <td>Number</td> 
   <td>140</td> 
   <td>最大输入长度，设置为 -1 的时候不限制最大长度</td> 
  </tr> 
  <tr> 
   <td>confirm-type</td> 
   <td>String</td> 
   <td>done</td> 
   <td>设置键盘右下角按钮的文字，仅在 type=“text” 时生效。</td> 
  </tr> 
 </tbody> 
</table>

常见的事件如下：

<table> 
 <thead> 
  <tr> 
   <th>事件</th> 
   <th>含义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@input</td> 
   <td>当键盘输入时，触发input事件，event.detail = {value}</td> 
  </tr> 
  <tr> 
   <td>@focus</td> 
   <td>输入框聚焦时触发，event.detail = { value, height }，height 为键盘高度</td> 
  </tr> 
  <tr> 
   <td>@blur</td> 
   <td>输入框失去焦点时触发，event.detail = {value: value}</td> 
  </tr> 
  <tr> 
   <td>@confirm</td> 
   <td>点击完成按钮时触发，event.detail = {value: value}</td> 
  </tr> 
  <tr> 
   <td>@keyboardheightchange</td> 
   <td>键盘高度发生变化的时候触发此事件，event.detail = {height: height, duration: duration}</td> 
  </tr> 
 </tbody> 
</table>

## 4.label ##

用来改进表单组件的可用性，使用for属性找到对应的id，或者将控件放在该标签下，当点击时，就会触发对应的控件。  
for优先级高于内部控件，内部有多个控件的时候默认触发第一个控件。  
目前可以绑定的控件有`<button>`、`<checkbox>`、`<radio>`、`<switch>`。

属性如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>for</td> 
   <td>String</td> 
   <td>绑定控件的 id</td> 
  </tr> 
 </tbody> 
</table>

## 5.picker ##

从底部弹起的滚动选择器。  
支持五种选择器，通过mode来区分，分别是普通选择器、多列选择器、时间选择器、日期选择器和省市区选择器，默认是普通选择器。

（1）普通选择器，参数为`mode = selector`，常见属性和事件如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>range</td> 
   <td>Array / Array&lt;Object&gt;</td> 
   <td>mode为 selector 或 multiSelector 时，range 有效</td> 
  </tr> 
  <tr> 
   <td>@change</td> 
   <td>EventHandle</td> 
   <td>value 改变时触发 change 事件，event.detail = {value: value}</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下：

<template>
    	<view>
    		<picker :range="years" @change="yearChange">
    			<view>
    				{
       {years[yearIndex]}}
    			</view>
    		</picker>
    	</view>
    </template>
    <script> export default { data() { return { years: ["请选择年份", 2019, 2020, 2021], yearIndex: 0 } }, onLoad() { }, onShow() { }, onUnload() { }, methods: { yearChange: function(e){ console.log(e) this.yearIndex = e.detail.value } } } </script>
    
    <style> </style>

显示：  
![uniapp component form picker normal][]

可以看到，在选择值后，显示也会同步变化，被选择的值的下标存储在`e.detail.value`中。

（2）多列选择器，参数为`mode = multiSelector`，常见属性和事件如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>range</td> 
   <td>二维 Array / 二维 Array&lt;Object&gt;</td> 
   <td>mode为 selector 或 multiSelector 时，range 有@change</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下：

<template>
    	<view>
    		<picker mode="multiSelector" :range="years" @change="yearChange">
    			<view>
    				{
       {years[0][yearIndex]}}-{
       {years[1][monthIndex]}}
    			</view>
    		</picker>
    	</view>
    </template>
    <script> export default { data() { return { years: [ ["请选择年份", 2019, 2020, 2021], ["请选择月份 ", 3, 4, 5] ], yearIndex: 0, monthIndex: 0 } }, onLoad() { }, onShow() { }, onUnload() { }, methods: { yearChange: function(e){ console.log(e) this.yearIndex = e.detail.value[0], this.monthIndex = e.detail.value[1] } } } </script>
    
    <style> </style>

显示：  
![uniapp component form picker multi][]

显然，可以进行多级选择，此时`e.detail.value`是一个数组，可以分别取值；  
还可以通过ajax等方式实现先选择一级、再动态显示二级。

（3）时间选择器，参数为`mode = time`，常见属性和事件如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>String</td> 
   <td>表示选中的时间，格式为"hh:mm"</td> 
  </tr> 
  <tr> 
   <td>start</td> 
   <td>String</td> 
   <td>表示有效时间范围的开始，字符串格式为"hh:mm" App 不支持</td> 
  </tr> 
  <tr> 
   <td>end</td> 
   <td>String</td> 
   <td>表示有效时间范围的结束，字符串格式为"hh:mm" App 不支持</td> 
  </tr> 
  <tr> 
   <td>@change</td> 
   <td>EventHandle</td> 
   <td>value 改变时触发 change 事件，event.detail = {value: value}</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下：

<template>
    	<view>
    		<picker mode="time" @change="yearChange">
    			<view>
    				{
       {timeText}}
    			</view>
    		</picker>
    	</view>
    </template>
    <script> export default { data() { return { timeText: "请选择时间" } }, onLoad() { }, onShow() { }, onUnload() { }, methods: { yearChange: function(e){ console.log(e); this.timeText = e.detail.value } } } </script>
    
    <style> </style>

显示：  
![uniapp component form picker time][]

（4）日期选择器，参数为`mode = date`，常见属性和事件如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>String</td> 
   <td>表示选中的日期，格式为"YYYY-MM-DD"</td> 
  </tr> 
  <tr> 
   <td>start</td> 
   <td>String</td> 
   <td>表示有效日期范围的开始，字符串格式为"YYYY-MM-DD"</td> 
  </tr> 
  <tr> 
   <td>end</td> 
   <td>String</td> 
   <td>表示有效日期范围的结束，字符串格式为"YYYY-MM-DD"</td> 
  </tr> 
  <tr> 
   <td>fields</td> 
   <td>String</td> 
   <td>有效值 year、month、day，表示选择器的粒度，默认为 day，App 端未配置此项时使用系统 UI</td> 
  </tr> 
  <tr> 
   <td>@change</td> 
   <td>EventHandle</td> 
   <td>value 改变时触发 change 事件，event.detail = {value: value}</td> 
  </tr> 
 </tbody> 
</table>

（5）省市区选择器，参数为`mode = region`，常见属性和事件如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>Array</td> 
   <td>表示选中的省市区，默认选中每一列的第一个值</td> 
  </tr> 
  <tr> 
   <td>custom-item</td> 
   <td>String</td> 
   <td>可为每一列的顶部添加一个自定义的项</td> 
  </tr> 
  <tr> 
   <td>@change</td> 
   <td>EventHandle</td> 
   <td>value 改变时触发 change 事件，event.detail = {value: value}</td> 
  </tr> 
  <tr> 
   <td>@cancel</td> 
   <td>EventHandle</td> 
   <td>取消选择时触发</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下：

<template>
    	<view>
    		<picker mode="region" @change="regionChange">
    			<view>
    				{
       {regionText}}
    			</view>
    		</picker>
    	</view>
    </template>
    <script> export default { data() { return { regionText: "请选择地区" } }, onLoad() { }, onShow() { }, onUnload() { }, methods: { regionChange: function(e){ console.log(e); this.regionText = e.detail.value } } } </script>
    
    <style> </style>

显示：  
![uniapp component form picker region][]

显然，控制台输出了对应省市区的编码和文本。

## 6.radio ##

radio-group是单项选择器，内部由多个 `<radio>` 组成，通过把多个radio包裹在一个radio-group下，实现这些radio的单选。

属性如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@change</td> 
   <td>EventHandle</td> 
   <td><code>&lt;radio-group&gt;</code> 中的选中项发生变化时触发 change 事件，event.detail = {value: 选中项radio的value}</td> 
  </tr> 
 </tbody> 
</table>

radio即单选项目，常见属性如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>String</td> 
   <td>无</td> 
   <td><code>&lt;radio&gt;</code> 标识。当该 <code>&lt;radio&gt;</code> 选中时，<code>&lt;radio-group&gt;</code> 的 change 事件会携带 <code>&lt;radio&gt;</code> 的 value</td> 
  </tr> 
  <tr> 
   <td>checked</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>当前是否选中</td> 
  </tr> 
  <tr> 
   <td>disabled</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否禁用</td> 
  </tr> 
  <tr> 
   <td>color</td> 
   <td>Color</td> 
   <td>无</td> 
   <td>radio的颜色，同css的color</td> 
  </tr> 
 </tbody> 
</table>

## 7.slider ##

滑动选择器，常见属性和含义如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>min</td> 
   <td>Number</td> 
   <td>0</td> 
   <td>最小值</td> 
  </tr> 
  <tr> 
   <td>max</td> 
   <td>Number</td> 
   <td>100</td> 
   <td>最大值</td> 
  </tr> 
  <tr> 
   <td>step</td> 
   <td>Number</td> 
   <td>1</td> 
   <td>步长，取值必须大于 0，并且可被(max - min)整除</td> 
  </tr> 
  <tr> 
   <td>disabled</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否禁用</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>Number</td> 
   <td>0</td> 
   <td>当前取值</td> 
  </tr> 
  <tr> 
   <td>activeColor</td> 
   <td>Color</td> 
   <td>微信是绿色(#1aad19)，头条是红色，其他平台是蓝色</td> 
   <td>滑块左侧已选择部分的线条颜色</td> 
  </tr> 
  <tr> 
   <td>backgroundColor</td> 
   <td>Color</td> 
   <td>#e9e9e9</td> 
   <td>滑块右侧背景条的颜色</td> 
  </tr> 
  <tr> 
   <td>block-size</td> 
   <td>Number</td> 
   <td>28</td> 
   <td>滑块的大小，取值范围为 12 - 28</td> 
  </tr> 
  <tr> 
   <td>block-color</td> 
   <td>Color</td> 
   <td>#ffffff</td> 
   <td>滑块的颜色</td> 
  </tr> 
  <tr> 
   <td>show-value</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否显示当前 value</td> 
  </tr> 
  <tr> 
   <td>@change</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>完成一次拖动后触发的事件，event.detail = {value: value}</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下：

<template>
    	<view>
    		<slider @change="sliderChange" step="5"></slider>
    	</view>
    </template>
    <script> export default { data() { return { } }, onLoad() { }, onShow() { }, onUnload() { }, methods: { sliderChange: function(e){ console.log(e); } } } </script>
    
    <style> </style>

显示：  
![uniapp component form slider][]

可以看到，获取到了滑动选择器的值。

## 8.switch ##

开关选择器。

常见属性和含义如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>checked</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否选中</td> 
  </tr> 
  <tr> 
   <td>disabled</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否禁用</td> 
  </tr> 
  <tr> 
   <td>type</td> 
   <td>String</td> 
   <td>switch</td> 
   <td>样式，有效值：switch, checkbox</td> 
  </tr> 
  <tr> 
   <td>color</td> 
   <td>Color</td> 
   <td>无</td> 
   <td>switch 的颜色，同 css 的 color</td> 
  </tr> 
  <tr> 
   <td>@change</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>checked 改变时触发 change 事件，event.detail={ value:checked}</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下：

<template>
    	<view>
    		<switch @change="switchChange"></switch>
    	</view>
    </template>
    <script> export default { data() { return { } }, onLoad() { }, onShow() { }, onUnload() { }, methods: { switchChange: function(e){ console.log(e); } } } </script>
    
    <style> </style>

显示：  
![uniapp component form switch][]

可以看到，在选择器处于打开状态时，value为true，处于关闭状态时，value为false。

## 9.textarea ##

多行输入框。

常见属性和事件如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>String</td> 
   <td>无</td> 
   <td>输入框的内容</td> 
  </tr> 
  <tr> 
   <td>placeholder</td> 
   <td>String</td> 
   <td>无</td> 
   <td>输入框为空时占位符</td> 
  </tr> 
  <tr> 
   <td>placeholder-style</td> 
   <td>String</td> 
   <td>无</td> 
   <td>指定 placeholder 的样式</td> 
  </tr> 
  <tr> 
   <td>placeholder-class</td> 
   <td>String</td> 
   <td>textarea-placeholder</td> 
   <td>指定 placeholder 的样式类</td> 
  </tr> 
  <tr> 
   <td>disabled</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否禁用</td> 
  </tr> 
  <tr> 
   <td>maxlength</td> 
   <td>Number</td> 
   <td>140</td> 
   <td>最大输入长度，设置为 -1 的时候不限制最大长度</td> 
  </tr> 
  <tr> 
   <td>focus</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>获取焦点</td> 
  </tr> 
  <tr> 
   <td>@focus</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>输入框聚焦时触发，event.detail = { value, height }，height 为键盘高度</td> 
  </tr> 
  <tr> 
   <td>@blur</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>输入框失去焦点时触发，event.detail = {value, cursor}</td> 
  </tr> 
  <tr> 
   <td>@linechange</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>输入框行数变化时调用，event.detail = {height: 0, heightRpx: 0, lineCount: 0}</td> 
  </tr> 
  <tr> 
   <td>@input</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>当键盘输入时，触发 input 事件，event.detail = {value, cursor}， @input 处理函数的返回值并不会反映到 textarea 上</td> 
  </tr> 
  <tr> 
   <td>@confirm</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>点击完成时， 触发 confirm 事件，event.detail = {value: value}</td> 
  </tr> 
 </tbody> 
</table>

## 10.form ##

表单，将组件内的用户输入的`<switch>`、`<input>`、`<checkbox>`、`<slider>`、`<radio>`和`<picker>`中的数据提交。  
当点击 `<form>` 表单中 formType 为 submit 的 `<button>` 组件时，会将表单组件中的 value 值进行提交，需要在表单组件中加上 name 来作为 key。

常见属性和含义如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>report-submit</td> 
   <td>Boolean</td> 
   <td>是否返回 formId 用于发送模板消息</td> 
  </tr> 
  <tr> 
   <td>@submit</td> 
   <td>EventHandle</td> 
   <td>携带 form 中的数据触发 submit 事件，event.detail = {value : {‘name’: ‘value’} , formId: ‘’}，report-submit 为 true 时才会返回 formId</td> 
  </tr> 
  <tr> 
   <td>@reset</td> 
   <td>EventHandle</td> 
   <td>表单重置时会触发 reset 事件</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下;

<template>
    	<view>
    		<form @submit="formSubmit" @reset="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="" />
    			</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" /><text>radio1</text>
    					</label>
    					<label>
    						<radio value="radio2" /><text>radio2</text>
    					</label>
    				</radio-group>
    			</view>
    			<view class="section section_gap">
    				<view class="section__title">checkbox</view>
    				<checkbox-group name="checkbox">
    					<label>
    						<checkbox value="checkbox1" /><text>checkbox1</text>
    					</label>
    					<label>
    						<checkbox value="checkbox2" /><text>checkbox2</text>
    					</label>
    				</checkbox-group>
    				<input name="input" placeholder="please input here" />
    			</view>
    			<view class="btn-area">
    				<button form-type="submit">Submit</button>
    				<button form-type="reset">Reset</button>
    			</view>
    		</form>
    	</view>
    </template>
    <script> export default { data() { return { } }, onLoad() { }, onShow() { }, onUnload() { }, methods: { formSubmit: function(e) { var formData = e.detail.value; console.log(formData); if (!formData.switch) { console.log('No Pass') } }, formReset: function(e) { console.log(e) } } } </script>
    
    <style> </style>

显示：  
![uniapp component form form][]

可以看到，在点击Submit按钮提交之后，会将数据全部提交，还可以对数据进行验证。

# 三、导航组件和页面传参 #

## 1.navigator ##

导航组件用于页面跳转，类似HTML中的`<a>`组件，但只能跳转本地页面，即目标页面必须在`pages.json`中注册。

常见的属性和含义如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>url</td> 
   <td>String</td> 
   <td>无</td> 
   <td>应用内的跳转链接，值为相对路径或绝对路径，如："…/first/first"，"/pages/first/first"，注意不能加 .vue 后缀</td> 
  </tr> 
  <tr> 
   <td>open-type</td> 
   <td>String</td> 
   <td>navigate</td> 
   <td>跳转方式，与api接口相对应</td> 
  </tr> 
  <tr> 
   <td>delta</td> 
   <td>Number</td> 
   <td>无</td> 
   <td>当 open-type 为 ‘navigateBack’ 时有效，表示回退的层数</td> 
  </tr> 
  <tr> 
   <td>target</td> 
   <td>String</td> 
   <td>self</td> 
   <td>在哪个小程序目标上发生跳转，默认当前小程序，值域self/miniProgram</td> 
  </tr> 
 </tbody> 
</table>

其中， open-type对应的API接口及其含义如下：

<table> 
 <thead> 
  <tr> 
   <th>接口</th> 
   <th>含义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>uni.navigateTo(OBJECT)</td> 
   <td>保留当前页面，跳转到应用内的某个页面，使用uni.navigateBack可以返回到原页面</td> 
  </tr> 
  <tr> 
   <td>uni.redirectTo(OBJECT)</td> 
   <td>关闭当前页面，跳转到应用内的某个页面</td> 
  </tr> 
  <tr> 
   <td>uni.reLaunch(OBJECT)</td> 
   <td>关闭所有页面，打开到应用内的某个页面</td> 
  </tr> 
  <tr> 
   <td>uni.switchTab(OBJECT)</td> 
   <td>跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面</td> 
  </tr> 
  <tr> 
   <td>uni.navigateBack(OBJECT)</td> 
   <td>关闭当前页面，返回上一页面或多级页面。可通过 getCurrentPages() 获取当前的页面栈，决定需要返回几层</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下：

<template>
    	<view>
    		<navigator url="../news" hover-class="navigator-hover">
    			<button type="default">跳转到news页面</button>
    		</navigator>
    		<navigator url="../about/about" open-type="switchTab" hover-class="navigator-hover">
    			<button type="default">跳转到about页面</button>
    		</navigator>
    	</view>
    </template>
    <script> export default { data() { return { } }, onLoad() { }, onShow() { }, onUnload() { }, methods: { } } </script>
    
    <style> </style>

显示：  
![uniapp component navigator basic][]

可以看到，实现了两种方式的跳转。

这是通过DOM进行页面跳转，还可以通过API进行跳转，如下：

<template>
    	<view>
    		<button type="default" @click="skip">跳转到新闻页面</button>
    	</view>
    </template>
    <script> export default { data() { return { } }, onLoad() { }, onShow() { setTimeout(function(){ uni.navigateBack({ delta: 1 }) }, 3000) }, onUnload() { }, methods: { skip: function() { uni.navigateTo({ url: '../news' }) } } } </script>
    
    <style> </style>

显示：  
![uniapp component navigator js][]

可以看到，也实现了页面跳转，并且可以定时跳转回原页面。

## 2.参数传递 ##

在进行页面跳转时，向其他页面传递参数一般在组件或接口的url参数指定的地址后追加，以`?`开始，`=`连接参数名和参数值，`&`拼接不同的参数。

index.vue传递参数如下：

<template>
    	<view>
    		<button type="default" @click="skip">跳转到新闻页面</button>
    	</view>
    </template>
    <script> export default { data() { return { } }, onLoad() { }, onShow() { setTimeout(function(){ uni.navigateBack({ delta: 1 }) }, 5000) }, onUnload() { }, methods: { skip: function() { uni.navigateTo({ url: '../news?size=20&page=1' }) } } } </script>
    
    <style> </style>

news.vue接收参数如下：

<template>
    	<view class="content">新闻页</view>
    </template>
    
    <script> export default { onLoad:function(options){ console.log(options) } } </script>
    
    <style> </style>

显示：  
![uniapp component navigator send param][]

可以看到，参数值保存在`options`中。

# 四、媒体组件 #

## 1.audio ##

音频组件。

常见属性和事件如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>id</td> 
   <td>String</td> 
   <td>无</td> 
   <td>audio 组件的唯一标识符</td> 
  </tr> 
  <tr> 
   <td>src</td> 
   <td>String</td> 
   <td>无</td> 
   <td>要播放音频的资源地址</td> 
  </tr> 
  <tr> 
   <td>loop</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否循环播放</td> 
  </tr> 
  <tr> 
   <td>controls</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否显示默认控件</td> 
  </tr> 
  <tr> 
   <td>poster</td> 
   <td>String</td> 
   <td>无</td> 
   <td>默认控件上的音频封面的图片资源地址，如果 controls 属性值为 false 则设置 poster 无效</td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td>String</td> 
   <td>无</td> 
   <td>未知音频</td> 
  </tr> 
  <tr> 
   <td>author</td> 
   <td>String</td> 
   <td>未知作者</td> 
   <td>默认控件上的作者名字，如果 controls 属性值为 false 则设置 author 无效</td> 
  </tr> 
  <tr> 
   <td>@error</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>当发生错误时触发 error 事件，detail = {errMsg: MediaError.code}</td> 
  </tr> 
  <tr> 
   <td>@play</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>当开始/继续播放时触发play事件</td> 
  </tr> 
  <tr> 
   <td>@pause</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>当暂停播放时触发 pause 事件</td> 
  </tr> 
  <tr> 
   <td>@timeupdate</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>当播放进度改变时触发 timeupdate 事件，detail = {currentTime, duration}</td> 
  </tr> 
  <tr> 
   <td>@ended</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>当播放到末尾时触发 ended 事件</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下：

<template>
    	<view>
    		<audio :src="audioSrc" :poster="posterSrc" :name="name" :author="author" controls style="text-align: center;"></audio>
    	</view>
    </template>
    <script> export default { data() { return { audioSrc: "https://m10.music.126.net/20201221165005/b4e7a310f6e3ffda9f12ab518201087c/yyaac/obj/wonDkMOGw6XDiTHCmMOi/2513074700/92fc/e94b/8333/c8592b8e05995aa1744976275eb09ab0.m4a", posterSrc: "https://y.gtimg.cn/music/photo_new/T002R300x300M000002npMQN1wN8nZ_1.jpg?max_age=2592000", name: "Blackheart", author: "Thomas Bergersen / Two Steps From Hell" } }, onLoad() { }, onShow() { }, onUnload() { }, methods: { } } </script>
    
    <style> audio { background: #007AFF; width: 100%; } </style>

显示：

uniapp component media audio

可以看到，实现了音乐播放功能。

## 2.image ##

图片组件。

常见的属性和事件如下：

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

index.vue如下：

<template>
    	<view>
    		<image src="../../static/imgs/saying.png" style="width: 55%;"></image>
    		<image src="../../static/imgs/saying.png" style="height: 200rpx;" mode="top right"></image>
    		<image src="../../static/imgs/saying.png" style="width: 55%;" mode="widthFix"></image>
    	</view>
    </template>
    <script> export default { data() { return { } }, onLoad() { }, onShow() { }, onUnload() { }, methods: { } } </script>
    
    <style> </style>

显示：  
![uniapp component media image][]  
可以看到，mode属性值不同，图片显示的形式也会有所区别。

## 3.video ##

视频组件。

常见属性和事件如下：

<table> 
 <thead> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>src</td> 
   <td>String</td> 
   <td>无</td> 
   <td>要播放视频的资源地址</td> 
  </tr> 
  <tr> 
   <td>autoplay</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否自动播放</td> 
  </tr> 
  <tr> 
   <td>loop</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否循环播放</td> 
  </tr> 
  <tr> 
   <td>muted</td> 
   <td>Boolean</td> 
   <td>false</td> 
   <td>是否静音播放</td> 
  </tr> 
  <tr> 
   <td>initial-time</td> 
   <td>Number</td> 
   <td>无</td> 
   <td>指定视频初始播放位置，单位为秒（s）</td> 
  </tr> 
  <tr> 
   <td>duration</td> 
   <td>Number</td> 
   <td>无</td> 
   <td>指定视频时长，单位为秒（s）</td> 
  </tr> 
  <tr> 
   <td>controls</td> 
   <td>Boolean</td> 
   <td>true</td> 
   <td>是否显示默认播放控件（播放/暂停按钮、播放进度、时间）</td> 
  </tr> 
  <tr> 
   <td>show-progress</td> 
   <td>Boolean</td> 
   <td>true</td> 
   <td>若不设置，宽度大于240时才会显示</td> 
  </tr> 
  <tr> 
   <td>poster</td> 
   <td>String</td> 
   <td>无</td> 
   <td>视频封面的图片网络资源地址，如果 controls 属性值为 false 则设置 poster 无效</td> 
  </tr> 
  <tr> 
   <td>@play</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>当开始/继续播放时触发play事件</td> 
  </tr> 
  <tr> 
   <td>@pause</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>当暂停播放时触发 pause 事件</td> 
  </tr> 
  <tr> 
   <td>@ended</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>当播放到末尾时触发 ended 事件</td> 
  </tr> 
  <tr> 
   <td>@timeupdate</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>播放进度变化时触发，event.detail = {currentTime, duration} 。触发频率 250ms 一次</td> 
  </tr> 
  <tr> 
   <td>@fullscreenchange</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>当视频进入和退出全屏时触发，event.detail = {fullScreen, direction}，direction取为 vertical 或 horizontal</td> 
  </tr> 
  <tr> 
   <td>@waiting</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>视频出现缓冲时触发</td> 
  </tr> 
  <tr> 
   <td>@error</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>视频播放出错时触发</td> 
  </tr> 
  <tr> 
   <td>@progress</td> 
   <td>EventHandle</td> 
   <td>无</td> 
   <td>加载进度变化时触发，只支持一段加载。event.detail = {buffered}，百分比</td> 
  </tr> 
  <tr> 
   <td>@controlstoggle</td> 
   <td>eventhandle</td> 
   <td>无</td> 
   <td>切换 controls 显示隐藏时触发。event.detail = {show}</td> 
  </tr> 
 </tbody> 
</table>

index.vue如下：

<template>
    	<view>
    		<video id="myVideo" src="https://vodkgeyttp9.vod.126.net/cloudmusic/N0qR6445_2249845426_hd.mp4?ts=1608546147&rid=C127086D22ABA8524D81BF20C706B22B&rl=3&rs=WPEhneQzZWbNSeETGHhAruzsoNATDuXC&sign=80864b2eb815f570c9ce0ca4e31a9b72&ext=XHOm0M2rNgl%252BOsuwtVhiXa7BA9%252FkbvJfK84GXv1FFd7SvvDty%252BQ0GH9eXueIlfcwNUnGHRzfhbEYqUYBZ7ygZIdke%252Bg2SpJHDq4lJBw1rnmQ3PMGLXkM3%252BzAlTLvRhAxrxz0O5mQJ%252BELGODgy6G%252Bp7lrZ1TUmeJpqovjqqiZ3g%252Bq8iLxQWFUOajn5NyiEBuv18Eb9Z%252FfrLVHVrjYvXEBAR6M3eYxHG13DGON2%252F0sniI%252FWdCjmuGWL6wk8NtEzV32kPjquU4yMUiMBX%252B3NYu70c9OUnBc4npLNLG2qBCjKxA8qv2Zyn7UjC3n4rvTjyQBnmMrh8ey%252FffGWXHOsrge088Wr7oVoVcCWbHlGaFyTJ9hgVfe%252F6%252BddmLZVuYT0mZ%252Ft4JPaSdoVAoujK54TRcwW9i5T4toFrUWjn1b13qquz3s%252FySUUnvfEF65s7Z1AjCdvoCG6LrShGdY%252Fu2yre8HDZVyHVjeAoYtbvG5VXQDVm1W74z%252BdRSLxp0Bml7L27EsVZlXaSqn32KJlR4fr4%252FvrgW5GrjiflWoOoyOZ1RK0sk%253D" enable-danmu danmu-btn controls></video>
    	</view>
    </template>
    <script> export default { data() { return { } }, onLoad() { }, onShow() { }, onUnload() { }, methods: { } } </script>
    
    <style> </style>

显示：

uniapp component media video

很明显，可以正常播放视频。

# 总结 #

uni-app为开发者提供的基础组件类似于HTML里的标签元素，并且更适合手机端使用，开发者可以通过组合这些组件、并在此基础上开发各种扩展组件来实现快速开发。

[uniapp component basic scrollview]: /images/20221120/484faad73f354778a1c1251b1c9a1c12.png
[https_uniapp.dcloud.io_component_swiper]: https://uniapp.dcloud.io/component/swiper
[uniapp component basic swiper]: /images/20221120/b35e9d538fc94cdcbf7f3c16cf0e1ece.png
[uniapp component basic richtext]: /images/20221120/a9bc37766e6744c7a59eb2517d4d35ec.png
[uniapp component basic process]: /images/20221120/b08150b69c87484c8829b602ef7296f2.png
[uniapp component form button]: /images/20221120/12cdd1c2b9a443e4a35a2f4c1291d21e.png
[uniapp component form checkbox]: /images/20221120/f30538ed3dda4e04bf3e93d2207a7fbd.png
[uniapp component form picker normal]: /images/20221120/1898f702e7a94de59cf335fd95f2d176.png
[uniapp component form picker multi]: /images/20221120/bc0371a5905f452fa080ea9baa21f320.png
[uniapp component form picker time]: /images/20221120/199c03cc7d094bcb8291f65a7f1e975b.png
[uniapp component form picker region]: /images/20221120/077ac4f5528f4ddfbbb7ccefec17afd4.png
[uniapp component form slider]: /images/20221120/2a84a4feb172447195b30a1ff8e1edd9.png
[uniapp component form switch]: /images/20221120/2b5633e085ba41b883af80c09dd4cf6e.png
[uniapp component form form]: /images/20221120/825a0985addc423c9bb2b5f61618b934.png
[uniapp component navigator basic]: /images/20221120/e9c6817655014766aaa4fa83932efc72.png
[uniapp component navigator js]: /images/20221120/b454c77c804f45259a6625d6193905db.png
[uniapp component navigator send param]: /images/20221120/c36336ba5ddc47f3ad0bbe1351058020.png
[uniapp component media image]: /images/20221120/f64d1bfc17ce4f9c9720da26964256ba.png