Uni-App
uni-app 是一个使用 Vue.js 开发所有前端应用的框架,开发者编写一套代码,可发布到 iOS、Android、Web(响应式)以及微信/支付宝/百度/头条/飞书/QQ/快手/钉钉/淘宝等小程序、快应用等多个平台。
其核心思想是**“一次开发,多端发布”**,让前端工程师用同一套 Vue 代码即可覆盖主流应用分发渠道,大幅降低跨端研发成本。
传统跨端方案往往需要为不同平台分别维护多套代码,而 uni-app 通过统一的 Vue 语法和编译器,解决了多端重复开发、维护困难的痛点。
**适用场景** uni-app 适合需要同时覆盖 App、H5 与多端小程序的团队,用一套 Vue 技术栈完成跨端交付。
## 2. 环境准备与官方资源
### 2.1 下载 HBuilderX
HBuilderX 是 DCloud 官方推荐的开发工具,内置 uni-app 编译与运行环境。
[HBuilderX-高效极客技巧 (dcloud.io)](https://dcloud.io/hbuilderx.html)
### 2.2 uni-app 官方文档
官方文档覆盖了组件、API、配置与多端差异说明,是日常开发的权威参考。
[uni-app官网 (dcloud.net.cn)](https://uniapp.dcloud.net.cn/resource.html)
### 2.3 unplugin-auto-import 自动导入插件
使用 `unplugin-auto-import` 可以在项目中自动导入 `vue` 与 `uni-app` 的 API,免去手动 `import`。
安装依赖:
npm i unplugin-auto-import
创建 `vite.config.js` 文件:
import uni from '@dcloudio/vite-plugin-uni';
import {defineConfig} from 'vite'
import AutoImport from 'unplugin-auto-import/vite'
export default defineConfig({
plugins:[
uni(),
AutoImport({
imports:[
'vue',
'uni-app'
]
})
]
})
## 3. 内置组件
### 3.1 view 视图容器
视图容器,类似于传统 HTML 中的 `div`,用于包裹各种元素内容。
如果使用 [nvue](https://uniapp.dcloud.io/tutorial/nvue-outline),则需注意,包裹文字应该使用 ` **性能提示** 在 webview 渲染的页面中,区域滚动的性能不及页面滚动,长列表场景需谨慎使用。
属性说明:
| 属性名 | 类型 | 默认值 | 说明 | 平台差异说明 |
| :---------------------- | :------------ | :------ | :----------------------------------------------------------- | :------------------------------------------ |
| scroll-x | Boolean | false | 允许横向滚动 | |
| scroll-y | Boolean | false | 允许纵向滚动 | |
| upper-threshold | Number/String | 50 | 距顶部/左边多远时(单位px),触发 scrolltoupper 事件 | |
| lower-threshold | Number/String | 50 | 距底部/右边多远时(单位px),触发 scrolltolower 事件 | |
| scroll-top | Number/String | | 设置竖向滚动条位置 | |
| scroll-left | Number/String | | 设置横向滚动条位置 | |
| scroll-into-view | String | | 值应为某子元素id(id不能以数字开头)。设置哪个方向可滚动,则在哪个方向滚动到该元素 | |
| scroll-with-animation | Boolean | false | 在设置滚动条位置时使用动画过渡 | |
| enable-back-to-top | Boolean | false | iOS点击顶部状态栏、安卓双击标题栏时,滚动条返回顶部,只支持竖向 | app-nvue,微信小程序 |
| show-scrollbar | Boolean | false | 控制是否出现滚动条 | App-nvue 2.1.5+ |
| refresher-enabled | Boolean | false | 开启自定义下拉刷新 | H5、app-vue 2.5.12+,微信小程序基础库2.10.1+ |
| refresher-threshold | Number | 45 | 设置自定义下拉刷新阈值 | H5、app-vue 2.5.12+,微信小程序基础库2.10.1+ |
| refresher-default-style | String | "black" | 设置自定义下拉刷新默认样式,支持设置 black,white,none,none 表示不使用默认样式 | H5、app-vue 2.5.12+,微信小程序基础库2.10.1+ |
| refresher-background | String | "#FFF" | 设置自定义下拉刷新区域背景颜色 | H5、app-vue 2.5.12+,微信小程序基础库2.10.1+ |
| refresher-triggered | Boolean | false | 设置当前下拉刷新状态,true 表示下拉刷新已经被触发,false 表示下拉刷新未被触发 | H5、app-vue 2.5.12+,微信小程序基础库2.10.1+ |
| enable-flex | Boolean | false | 启用 flexbox 布局。开启后,当前节点声明了 display: flex 就会成为 flex container,并作用于其孩子节点。 | 微信小程序 2.7.3 |
| scroll-anchoring | Boolean | false | 开启 scroll anchoring 特性,即控制滚动位置不随内容变化而抖动,仅在 iOS 下生效,安卓下可参考 CSS overflow-anchor 属性。 | 微信小程序 2.8.2 |
| @scrolltoupper | EventHandle | | 滚动到顶部/左边,会触发 scrolltoupper 事件 | |
| @scrolltolower | EventHandle | | 滚动到底部/右边,会触发 scrolltolower 事件 | |
| @scroll | EventHandle | | 滚动时触发,event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY} | |
| @refresherpulling | EventHandle | | 自定义下拉刷新控件被下拉 | H5、app-vue 2.5.12+,微信小程序基础库2.10.1+ |
| @refresherrefresh | EventHandle | | 自定义下拉刷新被触发 | H5、app-vue 2.5.12+,微信小程序基础库2.10.1+ |
| @refresherrestore | EventHandle | | 自定义下拉刷新被复位 | H5、app-vue 2.5.12+,微信小程序基础库2.10.1+ |
| @refresherabort | EventHandle | | 自定义下拉刷新被中止 | H5、app-vue 2.5.12+,微信小程序基础库2.10.1+ |
示例代码:
<!-- 本示例未包含完整css,获取外链css请参考上文,在hello uni-app项目中查看 -->
<template>
<view>
<view class="uni-padding-wrap uni-common-mt">
<view class="uni-title uni-common-mt">
Vertical Scroll
<text>\n纵向滚动</text>
</view>
<view>
<scroll-view :scroll-top="scrollTop" scroll-y="true" class="scroll-Y" @scrolltoupper="upper"
@scrolltolower="lower" @scroll="scroll">
<view id="demo1" class="scroll-view-item uni-bg-red">A</view>
<view id="demo2" class="scroll-view-item uni-bg-green">B</view>
<view id="demo3" class="scroll-view-item uni-bg-blue">C</view>
</scroll-view>
</view>
<view @tap="goTop" class="uni-link uni-center uni-common-mt">
点击这里返回顶部
</view>
<view class="uni-title uni-common-mt">
Horizontal Scroll
<text>\n横向滚动</text>
</view>
<view>
<scroll-view class="scroll-view_H" scroll-x="true" @scroll="scroll" scroll-left="120">
<view id="demo1" class="scroll-view-item_H uni-bg-red">A</view>
<view id="demo2" class="scroll-view-item_H uni-bg-green">B</view>
<view id="demo3" class="scroll-view-item_H uni-bg-blue">C</view>
</scroll-view>
</view>
<view class="uni-common-pb"></view>
</view>
</view>
</template>
<script>
export default {
data() {
return {
scrollTop: 0,
old: {
scrollTop: 0
}
}
},
methods: {
upper: function(e) {
console.log(e)
},
lower: function(e) {
console.log(e)
},
scroll: function(e) {
console.log(e)
this.old.scrollTop = e.detail.scrollTop
},
goTop: function(e) {
// 解决view层不同步的问题
this.scrollTop = this.old.scrollTop
this.$nextTick(function() {
this.scrollTop = 0
});
uni.showToast({
icon: "none",
title: "纵向滚动 scrollTop 值已被修改为 0"
})
}
}
}
</script>
### 3.3 swiper 滑块视图容器
滑块视图容器,一般用于左右滑动或上下滑动,比如 banner 轮播图。
注意滑动切换和滚动的区别,滑动切换是一屏一屏的切换。swiper 下的每个 swiper-item 是一个滑动切换区域,不能停留在 2 个滑动区域之间。
**属性说明**
| 属性名 | 类型 | 默认值 | 说明 | 平台差异说明 |
| :----------------------------- | :---------- | :---------------- | :----------------------------------------------------------- | :----------------------------------------------------------- |
| indicator-dots | Boolean | false | 是否显示面板指示点 | |
| indicator-color | Color | rgba(0, 0, 0, .3) | 指示点颜色 | |
| indicator-active-color | Color | #000000 | 当前选中的指示点颜色 | |
| active-class | String | | swiper-item 可见时的 class | 支付宝小程序 |
| changing-class | String | | acceleration 设置为 true 时且处于滑动过程中,中间若干屏处于可见时的class | 支付宝小程序 |
| autoplay | Boolean | false | 是否自动切换 | |
| current | Number | 0 | 当前所在滑块的 index | |
| current-item-id | String | | 当前所在滑块的 item-id ,不能与 current 被同时指定 | 支付宝小程序不支持 |
| interval | Number | 5000 | 自动切换时间间隔 | |
| duration | Number | 500 | 滑动动画时长 | app-nvue不支持 |
| circular | Boolean | false | 是否采用衔接滑动,即播放到末尾后重新回到开头 | |
| vertical | Boolean | false | 滑动方向是否为纵向 | |
| previous-margin | String | 0px | 前边距,可用于露出前一项的一小部分,接受 px 和 rpx 值 | app-nvue、抖音小程序、飞书小程序不支持 |
| next-margin | String | 0px | 后边距,可用于露出后一项的一小部分,接受 px 和 rpx 值 | app-nvue、抖音小程序、飞书小程序不支持 |
| acceleration | Boolean | false | 当开启时,会根据滑动速度,连续滑动多屏 | 支付宝小程序 |
| disable-programmatic-animation | Boolean | false | 是否禁用代码变动触发 swiper 切换时使用动画。 | 支付宝小程序 |
| display-multiple-items | Number | 1 | 同时显示的滑块数量 | app-nvue、支付宝小程序不支持 |
| skip-hidden-item-layout | Boolean | false | 是否跳过未显示的滑块布局,设为 true 可优化复杂情况下的滑动性能,但会丢失隐藏状态滑块的布局信息 | App、微信小程序、京东小程序 |
| disable-touch | Boolean | false | 是否禁止用户 touch 操作 | App 2.5.5+、H5 2.5.5+、支付宝小程序、抖音小程序与飞书小程序(只在初始化时有效,不能动态变更) |
| touchable | Boolean | true | 是否监听用户的触摸事件,只在初始化时有效,不能动态变更 | 抖音小程序与飞书小程序(uni-app 2.5.5+ 推荐统一使用 disable-touch) |
| easing-function | String | default | 指定 swiper 切换缓动动画类型,有效值:default、linear、easeInCubic、easeOutCubic、easeInOutCubic | 微信小程序、快手小程序、京东小程序 |
| @change | EventHandle | | current 改变时会触发 change 事件,event.detail = {current: current, source: source} | |
| @transition | EventHandle | | swiper-item 的位置发生改变时会触发 transition 事件,event.detail = {dx: dx, dy: dy},支付宝小程序暂不支持dx, dy | App、H5、微信小程序、支付宝小程序、抖音小程序、飞书小程序、QQ小程序、快手小程序 |
| @animationfinish | EventHandle | | 动画结束时会触发 animationfinish 事件,event.detail = {current: current, source: source} | 抖音小程序与飞书小程序不支持 |
### 3.4 icon 图标
示例代码:
<view class="item" v-for="(value,index) in iconType" :key="index">
<icon :type="value" size="26"/>
<text>{{value}}</text>
</view>
### 3.5 form 表单
表单,将组件内的用户输入的 `