Uni-App

uni-app 是一个使用 Vue.js 开发所有前端应用的框架,开发者编写一套代码,可发布到 iOS、Android、Web(响应式)以及微信/支付宝/百度/头条/飞书/QQ/快手/钉钉/淘宝等小程序、快应用等多个平台。

其核心思想是**“一次开发,多端发布”**,让前端工程师用同一套 Vue 代码即可覆盖主流应用分发渠道,大幅降低跨端研发成本。

传统跨端方案往往需要为不同平台分别维护多套代码,而 uni-app 通过统一的 Vue 语法和编译器,解决了多端重复开发、维护困难的痛点。
DCloud UniApp 跨端框架 ## 1. 概述 uni-app 是一个使用 Vue.js 开发所有前端应用的框架。开发者编写一套代码,可发布到 iOS、Android、Web(响应式),以及各种小程序(微信/支付宝/百度/头条/飞书/QQ/快手/钉钉/淘宝)、快应用等多个平台。它将各端差异封装在编译器与运行时中,使业务代码保持统一。
**适用场景** 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),则需注意,包裹文字应该使用 `` 组件。 ### 3.2 scroll-view 可滚动视图区域 可滚动视图区域,用于区域滚动。
**性能提示** 在 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 表单 表单,将组件内的用户输入的 `` `` `` `` `` `` 提交。 当点击 `
` 表单中 formType 为 submit 的 `