uniapp快速回顾

uniapp快速回顾官方文档

uniapp从入门到精通

uni-app 跨平台应用开发教程

uniapp实战总结

uniapp重头到尾

uview使用

vue 标签语法

vue基本使用

在线文档

条件编译

下拉刷新

页面跳转

预加载页面

数据显示

Class Style

条件渲染

列表渲染

事件处理器

应用声明周期

页面生命周期

组件生命周期

页面通讯

API

分包

easycom

H5发布注意

uniapp 微信小程序保存图片到系统相册（包括获取手机相册权限）即拿即用

uni-app 引用 微信小程序原生自定义组件

组件slot的使用

uniapp总结

uview使用

Native.js入门指南

Native API经典实用例子

uniapp 布局及插件使用

uniapp编译相关

uniapp中slot插槽用法

uniapp小程序开发中的两个主要注意点

条件编译

**写法：**以 #ifdef 或 #ifndef 加 %PLATFORM% 开头，以 #endif 结尾。

#ifdef：if defined 仅在某平台存在

#ifndef：if not defined 除了某平台均存在

%PLATFORM%：平台名称

条件编译写法 说明

#ifdef APP-PLUS

需条件编译的代码

#endif

仅出现在 App 平台下的代码

#ifndef H5

需条件编译的代码

#endif

除了 H5 平台，其它平台均存在的代码

#ifdef H5 || MP-WEIXIN

需条件编译的代码

#endif

在 H5 平台或微信小程序平台存在的代码（这里只有||，不可能出现&&，因为没有交集）

%PLATFORM% 可取值如下：

值 生效条件

VUE3 HBuilderX 3.2.0+ 详情(opens new window)

APP-PLUS App

APP-PLUS-NVUE或APP-NVUE App nvue

H5 H5

MP-WEIXIN 微信小程序

MP-ALIPAY 支付宝小程序

MP-BAIDU 百度小程序

MP-TOUTIAO 字节跳动小程序

MP-LARK 飞书小程序

MP-QQ QQ小程序

MP-KUAISHOU 快手小程序

MP-JD 京东小程序

MP-360 360小程序

MP 微信小程序/支付宝小程序/百度小程序/字节跳动小程序/飞书小程序/QQ小程序/360小程序

QUICKAPP-WEBVIEW 快应用通用(包含联盟、华为)

QUICKAPP-WEBVIEW-UNION 快应用联盟

QUICKAPP-WEBVIEW-HUAWEI 快应用华为

下拉刷新

onPullDownRefresh

在 js 中定义 onPullDownRefresh 处理函数（和onLoad等生命周期函数同级），监听该页面用户下拉刷新事件。

需要在 pages.json 里，找到的当前页面的pages节点，并在 style 选项中开启 enablePullDownRefresh。

当处理完数据刷新后，uni.stopPullDownRefresh 可以停止当前页面的下拉刷新。

uni.startPullDownRefresh(OBJECT)

开始下拉刷新，调用后触发下拉刷新动画，效果与用户手动下拉刷新一致。

OBJECT 参数说明

参数名 类型 必填 说明

success Function 否 接口调用成功的回调

fail Function 否 接口调用失败的回调函数

complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数 类型 说明

errMsg String 接口调用结果

uni.stopPullDownRefresh()

停止当前页面下拉刷新。

示例

pages.json

{

    "pages": [

        {

            "path": "pages/index/index",

            "style": {

                "navigationBarTitleText": "uni-app",

                "enablePullDownRefresh": true

            }

        }

    ],

    "globalStyle": {

        "navigationBarTextStyle": "white",

        "navigationBarBackgroundColor": "#0faeff",

        "backgroundColor": "#fbf9fe"

    }

}

index.vue

// 仅做示例，实际开发中延时根据需求来使用。

export default {

    data() {

        return {

            text: 'uni-app'

        }

    },

    onLoad: function (options) {

        setTimeout(function () {

            console.log('start pulldown');

        }, 1000);

        uni.startPullDownRefresh();

    },

    onPullDownRefresh() {

        console.log('refresh');

        setTimeout(function () {

            uni.stopPullDownRefresh();

        }, 1000);

    }

}

页面跳转

uni.navigateTo(OBJECT)

保留当前页面，跳转到应用内的某个页面，使用uni.navigateBack可以返回到原页面。

参数 类型 必填 默认值 说明 平台差异说明

url String 是 需要跳转的应用内非 tabBar 的页面的路径 , 路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'，path为下一个页面的路径，下一个页面的onLoad函数可得到传递的参数

animationType String 否 pop-in 窗口显示的动画效果，详见：窗口动画 App

animationDuration Number 否 300 窗口动画持续时间，单位为 ms App

events Object 否 页面间通信接口，用于监听被打开页面发送到当前页面的数据。2.8.9+ 开始支持。

success Function 否 接口调用成功的回调函数

fail Function 否 接口调用失败的回调函数

complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

uni.navigateTo({

    url: 'test?id=1&name=uniapp'

});

 

uni.redirectTo(OBJECT)

关闭当前页面，跳转到应用内的某个页面。

OBJECT参数说明

参数 类型 必填 说明

url String 是 需要跳转的应用内非 tabBar 的页面的路径，路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'

success Function 否 接口调用成功的回调函数

fail Function 否 接口调用失败的回调函数

complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

示例

uni.redirectTo({

    url: 'test?id=1'

});

uni.reLaunch(OBJECT)

关闭所有页面，打开到应用内的某个页面。

注意： 如果调用了 uni.preloadPage(OBJECT) 不会关闭，仅触发生命周期 onHide

OBJECT参数说明

参数 类型 必填 说明

url String 是 需要跳转的应用内页面路径 , 路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'，如果跳转的页面路径是 tabBar 页面则不能带参数

success Function 否 接口调用成功的回调函数

fail Function 否 接口调用失败的回调函数

complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

示例

uni.reLaunch({

    url: 'test?id=1'

});

uni.switchTab(OBJECT)

跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面。

注意： 如果调用了 uni.preloadPage(OBJECT) 不会关闭，仅触发生命周期 onHide

OBJECT参数说明

参数 类型 必填 说明

url String 是 需要跳转的 tabBar 页面的路径（需在 pages.json 的 tabBar 字段定义的页面），路径后不能带参数

success Function 否 接口调用成功的回调函数

fail Function 否 接口调用失败的回调函数

complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

示例

pages.json

{

  "tabBar": {

    "list": [{

      "pagePath": "pages/index/index",

      "text": "首页"

    },{

      "pagePath": "pages/other/other",

      "text": "其他"

    }]

  }

}

other.vue

uni.switchTab({

    url: '/pages/index/index'

});

uni.navigateBack(OBJECT)

关闭当前页面，返回上一页面或多级页面。可通过 getCurrentPages() 获取当前的页面栈，决定需要返回几层。

OBJECT参数说明

参数 类型 必填 默认值 说明 平台差异说明

delta Number 否 1 返回的页面数，如果 delta 大于现有页面数，则返回到首页。

animationType String 否 pop-out 窗口关闭的动画效果，详见：窗口动画 App

animationDuration Number 否 300 窗口关闭动画的持续时间，单位为 ms App

success Function 否 接口调用成功的回调函数

fail Function 否 接口调用失败的回调函数

complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

示例

// 注意：调用 navigateTo 跳转时，调用该方法的页面会被加入堆栈，而 redirectTo 方法则不会。见下方示例代码

// 此处是A页面

uni.navigateTo({

    url: 'B?id=1'

});

// 此处是B页面

uni.navigateTo({

    url: 'C?id=1'

});

// 在C页面内 navigateBack，将返回A页面

uni.navigateBack({

    delta: 2

});

预加载页面

uni.preloadPage(OBJECT)

预加载页面，是一种性能优化技术。被预载的页面，在打开时速度更快。

平台差异说明

App-nvue H5 微信小程序 支付宝小程序 百度小程序 字节跳动小程序、飞书小程序 QQ小程序

√(2.7.12+) √(2.7.12+) x x x x x

属性 类型 必填 说明

url string 是 预加载页面url

complete Function 否 预加载成功完成回调

fail Function 否 预加载失败回调

H5 平台

预加载 /pages/test/test 对应的js文件，不执行页面预渲染逻辑

uni.preloadPage({url: "/pages/test/test"});

App-nvue 平台

预加载nvue页面 /pages/test/test

uni.preloadPage({url: "/pages/test/test"});

注意事项

App平台仅支持预加载 nvue 页面，执行页面预渲染，预载时触发生命周期 onLoad，onReady，不触发 onShow

打开新页面时，url 完全相同（包含参数）时，优先使用预加载页面，触发生命周期 onShow

tabbar页面，仅支持预加载尚未显示过的页面，否则返回 fail，提示 already exists

同一时间，相同 url 仅 preloadPage 一次

当同一个预载页面已被打开(在路由栈)，再次打开相同url时，不再使用该预加载页面，而是打开新的非预载页面

uni.reLanuch, uni.switchTab, uni.navigateBack(含Android返回键) 切换页面时，预加载页面不会被销毁，仅触发生命周期 onHide

在预载页面使用 uni.redirectTo 时，预加载页面会被销毁，触发生命周期 onUnload

示例

uni.preloadPage({url: "/pages/test/test"}); // 预加载 /pages/test/test 页面（仅触发onLoad，onReady)

uni.navigateTo({url: "/pages/test/test"}); // url匹配，跳转预加载页面（仅触发onShow)

uni.navigateTo({url: "/pages/test/test?a=b"}); // url不匹配，正常打开新页面

uni.unPreloadPage(OBJECT)

取消预载页面。

仅App-nvue支持

当预载页面未被打开时，使用 unPreloadPage时会销毁该页面，触发生命周期 onUnload

当预载页面已被打开时，使用 unPreloadPage时不销毁该页面，但该预加载页面不再继续存在，会随着路由变化而销毁

main.js

import Vue from 'vue'

import App from './App'

import VueI18n from 'vue-i18n'

import appdata from './appdata/appdata'

Vue.use(VueI18n)

Vue.config.productionTip = false;

let Chinese = require('./static/locales/zh-CN.js')

let English = require('./static/locales/en-US.js')

let Tradition = require('./static/locales/zh-HK.js')

const i18n = new VueI18n({

// 默认语言

locale: language,

// 引入语言文件

messages: {

'zh-CN': Chinese,

'en-US': English,

        'zh-HK': Tradition

}

})

Vue.prototype._i18n = i18n;

appdata.language=language;

Vue.prototype.appdata = appdata;

在页面使用

var _self;

onLoad: function(option) {

_self = this;

     ...

}

_self.appdata.SetUserInfo(m_UserInfo);

_self.appdata.SetLGKey(data.m_ReturnOBJ.lgkey,m_Data.username);

数据显示

<template>

    <view>

        <view>Message: {{ msg }}</view>

    </view>

</template>

<script>

    export default {

        data() {

            return {

                msg: 'Hello Vue!'

            }

        }

    }

</script>

对于所有的数据绑定，Vue.js 都提供了完全的 JavaScript 表达式支持

<view>{{ number + 1 }}</view>

      <view>{{ ok ? 'YES' : 'NO' }}</view>

      <!-- 把一个字符串分割成字符串数组,颠倒其元素的顺序,把数组中的所有元素放入一个字符串 -->

      <view>{{ message.split('').reverse().join('') }}</view>

<script>

  export default {

    data() {

      return {

        number:1,

        ok:true,

        message: 'Hello Vue!'

      }

    }

  }

</script>

 <image :src="imgUrl"></image>  索性绑定

 <view @click="doSomething">点击</view> 事件绑定

Class 与 Style 绑定

 <view class="static" :class="{ active: isActive, 'text-danger': hasError }">222</view>

 <view v-bind:style="{ color: activeColor, fontSize: fontSize + 'px' }">333</view>

<script>

        export default {

            data() {

                return {

                    isActive: true,

                    hasError: false,

                    activeColor:"green",

                    fontSize:50

                }

            }

        }

    </script>

    <style>

    .static{

        color: #2C405A;

    }

    .active{

        background-color: #007AFF;

    }

    .text-danger{

        color: #DD524D;

    }

    </style>

当 isActive 或者 hasError 变化时，class 列表将相应地更新。例如，如果 hasError 的值为 true ，class 列表将变为 static active text-danger。

可以把一个数组传给 v-bind:class，以应用一个 class 列表

<template>

    <view>

        <!-- class -->

        <view class="static" :class="[activeClass,errorClass]">111</view>

        <view class="static" v-bind:class="[isActive ? activeClass : '', errorClass]">222</view><!-- 三元表达式 -->

        <view class="static" v-bind:class="[{ active: isActive }, errorClass]">333</view>

        <!-- style -->

        <view v-bind:style="[{ color: activeColor, fontSize: fontSize + 'px' }]">444</view>

    </view>

</template>

<script>

    export default {

        data() {

            return {

                isActive: true,

                activeClass: 'active',

                errorClass: 'text-danger',

                activeColor:"green",

                fontSize:50

            }

        }

    }

</script>

<style>

    .static{

        font-size:30rpx;

    }

    .active{

        background-color: #007AFF;

    }

    .text-danger{

        font-size:60rpx;

        color:#DD524D;

    }

</style>

可以用 computed 方法生成 class 或者 style 字符串，插入到页面中，举例说明

<template>

      <!-- 支持 -->

      <view class="container" :class="computedClassStr"></view>

      <view class="container" :class="{active: isActive}"></view>

      <!-- 不支持 -->

      <view class="container" :class="computedClassObject"></view>

  </template>

  <script>

      export default {

          data () {

              return {

                  isActive: true

              }

          },

          computed: {

              computedClassStr () {

                  return this.isActive ? 'active' : ''

              },

              computedClassObject () {

                  return { active: this.isActive }

              }

          }

      }

  </script>

条件渲染

v-if和v-else

v-if 指令用于条件性地渲染一块内容。这块内容只会在指令的表达式返回 truthy 值的时候被渲染。 使用 v-else 指令来表示 v-if 的“else 块”。

<template>

        <view>

            <view v-if="seen">现在你看到我了</view>

            <view v-else>你看不到我了</view>

        </view>

    </template>

    <script>

        export default {

            data() {

                return {

                    seen: true

                }

            }

        }

    </script>

v-show

v-show 是一个根据条件展示元素选项的指令 。用法大致和 v-if 一样：

    <view v-show="ok">Hello!</view>

不同的是带有 v-show 的元素始终会被渲染并保留在 DOM 中。v-show 只是简单地切换元素的 CSS 属性的 display 

v-if 和 v-show 区别

v-if 是“真正”的条件渲染，因为它会确保在切换过程中条件块内的事件监听器和子组件适当地被销毁和重建。

v-if 也是惰性的：如果在初始渲染时条件为假，则什么也不做，直到条件第一次变为真时，才会开始渲染条件块。

相比之下，v-show 就简单得多，不管初始条件是什么，元素总是会被渲染，并且只是简单地基于 CSS 进行切换，来控制元素的显示和隐藏。

根据应用场景选择

v-if 有更高的切换开销，如果在运行时条件很少改变，则使用 v-if 较好。

v-show 有更高的初始渲染开销。如果需要非常频繁地切换，则使用 v-show 较好。

注意

不推荐同时使用 v-if 和 v-for。

当 v-if 与 v-for 一起使用时，v-for 具有比 v-if 更高的优先级。

列表渲染

在 v-for 里使用数组

v-for 指令可以实现基于一个数组来渲染一个列表。

v-for 指令需要使用 item in items 形式的特殊语法，其中 items 是源数据数组，而 item 则是被迭代的数组元素的别名。

第一个参数 item 则是被迭代的数组元素的别名。

第二个参数，即当前项的索引 index ，是可选的。

    <template>

        <view>

            <view v-for="(item, index) in items">

                {{ index }} - {{ item.message }}

            </view>

        </view>

    </template>

    <script>

        export default {

            data() {

                return {

                    items: [

                        { message: 'Foo' },

                        { message: 'Bar' }

                    ]

                }

            }

        }

    </script>

data() {

            return {

                stuArray:[

                    {name:"张三",age:12,skills:["Java","C#","Python"]},

                    {name:"李四",age:13,skills:["Sing","Dance","Rap","Basketball"]},

                    {name:"王五",age:14,skills:["Piano","Guitar","Trumpet"]}

                ]

            }

        },

<view>

        <view v-for="(stu,index) in stuArray" :key="stu.name"> <!--key唯一标志-->

            <view>{{"姓名:"+stu.name+",年龄:"+stu.age+",序号:"+index}}</view>

            <view>

                擅长技能:

                <block v-for="(sk,index) in stu.skills" :key="sk+index">

                    {{sk}},

                </block>

            </view>

        </view>

    </view>

在 v-for 里使用对象

你也可以用 v-for 来遍历一个对象的 property。

第一个参数 value 是被迭代的对象元素的属性值。

第二个参数为 property 名称 (也就是键名)。

第三个参数作为索引。

    <template>

        <view>

            <view v-for="(value, name, index) in object">

                 {{ index }}. {{ name }}: {{ value }}

            </view>

        </view>

    </template>

    <script>

        export default {

            data() {

                return {

                    object: {

                        title: 'How to do lists in Vue',

                        author: 'Jane Doe',

                        publishedAt: '2020-04-10'

                    }

                }

            }

        }

    </script>

列表渲染分组

类似于 v-if，你也可以利用带有 v-for 的 template 来循环渲染一段包含多个元素的内容。比如：

    <template v-for="item in items">

        <view>{{ item.message }}</view>

        <view class="divider" role="presentation"></view>

    </template>

key

当 Vue 正在更新使用 v-for 渲染的元素列表时，它默认使用“就地更新”的策略。如果数据项的顺序被改变，Vue 将不会移动 DOM 元素来匹配数据项的顺序，而是就地更新每个元素，并且确保它们在每个索引位置正确渲染。

如果列表中项目的位置会动态改变或者有新的项目添加到列表中，并且希望列表中的项目保持自己的特征和状态（如 input 中的输入内容，switch 的选中状态），需要使用 :key 来指定列表中项目的唯一的标识符。

:key 的值以两种形式提供

使用 v-for 循环 array 中 item 的某个 property，该 property 的值需要是列表中唯一的字符串或数字，且不能动态改变。

使用 v-for 循环中 item 本身，这时需要 item 本身是一个唯一的字符串或者数字

当数据改变触发渲染层重新渲染的时候，会校正带有 key 的组件，框架会确保他们被重新排序，而不是重新创建，以确保使组件保持自身的状态，并且提高列表渲染时的效率。

如不提供 :key，会报一个 warning， 如果明确知道该列表是静态，或者不必关注其顺序，可以选择忽略。

示例：

    <template>

        <view>

            <!-- array 中 item 的某个 property -->

            <view v-for="(item,index) in objectArray" :key="item.id">

                {{index +':'+ item.name}}

            </view>

            <!-- item 本身是一个唯一的字符串或者数字时，可以使用 item 本身 -->

            <view v-for="(item,index) in stringArray" :key="item">

                {{index +':'+ item}}

            </view>

        </view>

    </template>

    <script>

    export default {

        data () {

            return {

                objectArray:[{

                    id:0,

                    name:'li ming'

                },{

                    id:1,

                    name:'wang peng'

                }],

                stringArray:['a','b','c']

            }

        }

    }

    </script>

在组件上使用 v-for

在自定义组件上，你可以像在任何普通元素上一样使用 v-for 。

    <my-component v-for="item in items" :key="item.id"></my-component>

当在组件上使用 v-for 时，key是必须的。

事件处理器

可以用@事件监听 DOM 事件，并在触发时运行一些 JavaScript 代码。

有时也需要在内联语句处理器中访问原始的 DOM 事件。可以用特殊变量 $event 把它传入方法

<template>

        <view>

            <button @click="warn('Form cannot be submitted yet.', $event)">

              Submit

            </button>

        </view>

    </template>

    <script>

        export default {

            methods: {

                warn(message, event) {

                    // 现在我们可以访问原生事件对象

                    if (event) {

                        //可访问 event.target等原生事件对象

                    }

                    uni.showToast({

                        title: message

                    });

                }

            }

        }

    </script>

事件修饰符

修饰符 (modifier) 是以半角句号 . 指明的特殊后缀，用于指出一个指令应该以特殊方式绑定。例如，.prevent 修饰符告诉 @事件对于触发的事件调用 event.preventDefault()：

@事件（v-on）提供了事件修饰符:

.stop: 各平台均支持， 使用时会阻止事件冒泡，在非 H5 端同时也会阻止事件的默认行为

.native: 监听原生事件，各平台均支持

.prevent: 仅在 H5 平台支持

.capture: 仅在 H5 平台支持

.self: 仅在 H5 平台支持

.once: 仅在 H5 平台支持

.passive: 仅在 H5 平台支持

    <!-- 阻止单击事件继续传播 -->

    <view @click.stop="doThis"></view>

使用修饰符时，顺序很重要；相应的代码会以同样的顺序产生。因此，用 @click.prevent.self 会阻止所有的点击，而 @click.self.prevent 只会阻止对元素自身的点击。

注意

为兼容各端，事件需使用 @ 的方式绑定，请勿使用小程序端的 bind 和 catch 进行事件绑定；也不能在 JS 中使用event.preventDefault()和event.stopPropagation()方法；

若需要禁止蒙版下的页面滚动，可使用 @touchmove.stop.prevent="moveHandle"，moveHandle 可以用来处理 touchmove 的事件，也可以是一个空函数。

<view class="mask" @touchmove.stop.prevent="moveHandle"></view>

按键修饰符：uni-app 运行在手机端，没有键盘事件，所以不支持按键修饰符。

事件映射表

// 事件映射表，左侧为 WEB 事件，右侧为 ``uni-app`` 对应事件

    {

        click: 'tap',

        touchstart: 'touchstart',

        touchmove: 'touchmove',

        touchcancel: 'touchcancel',

        touchend: 'touchend',

        tap: 'tap',

        longtap: 'longtap', //推荐使用longpress代替

        input: 'input',

        change: 'change',

        submit: 'submit',

        blur: 'blur',

        focus: 'focus',

        reset: 'reset',

        confirm: 'confirm',

        columnchange: 'columnchange',

        linechange: 'linechange',

        error: 'error',

        scrolltoupper: 'scrolltoupper',

        scrolltolower: 'scrolltolower',

        scroll: 'scroll'

    }

应用生命周期

uni-app 支持如下应用生命周期函数：

函数名 说明

onLaunch 当uni-app 初始化完成时触发（全局只触发一次）

onShow 当 uni-app 启动，或从后台进入前台显示

onHide 当 uni-app 从前台进入后台

onError 当 uni-app 报错时触发

onUniNViewMessage 对 nvue 页面发送的数据进行监听，可参考 nvue 向 vue 通讯

onUnhandledRejection 对未处理的 Promise 拒绝事件监听函数（2.8.1+）

onPageNotFound 页面不存在监听函数

onThemeChange 监听系统主题变化

页面生命周期

uni-app 支持如下页面生命周期函数：

函数名 说明 平台差异说明 最低版本

onInit 监听页面初始化，其参数同 onLoad 参数，为上个页面传递的数据，参数类型为 Object（用于页面传参），触发时机早于 onLoad 百度小程序 3.1.0+

onLoad 监听页面加载，其参数为上个页面传递的数据，参数类型为 Object（用于页面传参），参考示例

onShow 监听页面显示。页面每次出现在屏幕上都触发，包括从下级页面点返回露出当前页面

onReady 监听页面初次渲染完成。注意如果渲染速度快，会在页面进入动画完成前触发

onHide 监听页面隐藏

onUnload 监听页面卸载

onResize 监听窗口尺寸变化 App、微信小程序

onPullDownRefresh 监听用户下拉动作，一般用于下拉刷新，参考示例

onReachBottom 页面滚动到底部的事件（不是scroll-view滚到底），常用于下拉下一页数据。具体见下方注意事项

onTabItemTap 点击 tab 时触发，参数为Object，具体见下方注意事项 微信小程序、QQ小程序、支付宝小程序、百度小程序、H5、App

onShareAppMessage 用户点击右上角分享 微信小程序、QQ小程序、支付宝小程序、字节小程序、飞书小程序、快手小程序

onPageScroll 监听页面滚动，参数为Object nvue暂不支持

onNavigationBarButtonTap 监听原生标题栏按钮点击事件，参数为Object App、H5

onBackPress 监听页面返回，返回 event = {from:backbutton、 navigateBack} ，backbutton 表示来源是左上角返回按钮或 android 返回键；navigateBack表示来源是 uni.navigateBack ；详细说明及使用：onBackPress 详解。支付宝小程序只有真机能触发，只能监听非navigateBack引起的返回，不可阻止默认行为。 app、H5、支付宝小程序

onNavigationBarSearchInputChanged 监听原生标题栏搜索输入框输入内容变化事件 App、H5 1.6.0

onNavigationBarSearchInputConfirmed 监听原生标题栏搜索输入框搜索事件，用户点击软键盘上的“搜索”按钮时触发。 App、H5 1.6.0

onNavigationBarSearchInputClicked 监听原生标题栏搜索输入框点击事件（pages.json 中的 searchInput 配置 disabled 为 true 时才会触发） App、H5 1.6.0

onShareTimeline 监听用户点击右上角转发到朋友圈 微信小程序 2.8.1+

onAddToFavorites 监听用户点击右上角收藏 微信小程序 2.8.1+

组件生命周期

uni-app 组件支持的生命周期，与vue标准组件的生命周期相同。这里没有页面级的onLoad等生命周期：

函数名 说明 平台差异说明 最低版本

beforeCreate 在实例初始化之后被调用。详见

created 在实例创建完成后被立即调用。详见

beforeMount 在挂载开始之前被调用。详见

mounted 挂载到实例上去之后调用。详见 注意：此处并不能确定子组件被全部挂载，如果需要子组件完全挂载之后在执行操作可以使用$nextTickVue官方文档

beforeUpdate 数据更新时调用，发生在虚拟 DOM 打补丁之前。详见 仅H5平台支持

updated 由于数据更改导致的虚拟 DOM 重新渲染和打补丁，在这之后会调用该钩子。详见 仅H5平台支持

beforeDestroy 实例销毁之前调用。在这一步，实例仍然完全可用。详见

destroyed Vue 实例销毁后调用。调用后，Vue 实例指示的所有东西都会解绑定，所有的事件监听器会被移除，所有的子实例也会被销毁。详见

页面通讯

uni.$emit('update',{msg:'页面更新'})

uni.$on('update',function(data){

        console.log('监听到事件来自 update ，携带参数 msg 为：' + data.msg);

    })

uni.$once(eventName,callback)

监听全局的自定义事件。事件可以由 uni.$emit 触发，但是只触发一次，在第一次触发之后移除监听器。

uni.$off([eventName, callback])

uni.$emit、 uni.$on 、 uni.$once 、uni.$off 触发的事件都是 App 全局级别的，跨任意组件，页面，nvue，vue 等

使用时，注意及时销毁事件监听，比如，页面 onLoad 里边 uni.$on 注册监听，onUnload 里边 uni.$off 移除，或者一次性的事件，直接使用 uni.$once 监听

API

Page 模块提供了控制页面的方法

属性

page.path

页面路径。

page.path: string

page.query

页面参数。 page.query: Object

方法

page.$

获取页面元素。

示例代码：

  const page = await program.currentPage()

  const element = await page.$('.index-desc')

  console.log(element.tagName) // 'view'

page.$$

示例代码：

  const page = await program.currentPage()

  const elements = await page.$$('.list-text')

  console.log(elements.length)

page.waitFor

等待直到指定条件成立。

page.waitFor(condition: string | number | Function): Promise<void>

参数说明

字段 类型 必填 默认值 说明

condition string number Function 是 - 等待条件

如果条件是 string 类型，那么该参数会被当成选择器，当该选择器选中元素个数不为零时，结束等待。

如果条件是 number 类型，那么该参数会被当成超时时长，当经过指定时间后，结束等待。

如果条件是 Function 类型，那么该参数会被当成断言函数，当该函数返回真值时，结束等待。

示例代码：

  const page = await program.currentPage()

  await page.waitFor(5000) // 等待 5 秒

  await page.waitFor('picker') // 等待页面中出现 picker 元素

  await page.waitFor(async () => {

    return (await page.$$('picker')).length > 5

  }) // 等待页面中 picker 元素数量大于 5

page.data

获取页面渲染数据。

page.data(path?: string): Promise<Object>

参数说明

字段 类型 必填 默认值 说明

path string 否 - 数据路径

示例代码：

  const page = await program.currentPage()

  console.log(await page.data('list'))

page.setData

设置页面渲染数据。

page.setData(data: Object): Promise<void>

参数说明

字段 类型 必填 默认值 说明

data Object 是 - 要改变的数据

示例代码：

  const page = await program.currentPage()

  await page.setData({

    text: 'changed data'

  })

page.size

获取页面大小。

page.size(): Promise<Object>

返回值说明

字段 类型 说明

width number 页面可滚动宽度

height number 页面可滚动高度

示例代码：

  const page = await program.currentPage()

  const { width, height } = await page.size()

  console.log(width, height)

page.scrollTop

获取页面滚动位置。

page.scrollTop(): Promise<number>

示例代码：

  const page = await program.currentPage()

  await program.pageScrollTo(20)

  console.log(await page.scrollTop())

page.callMethod

调用页面指定方法。

page.callMethod(method: string, ...args: any[]): Promise<any>

参数说明

字段 类型 必填 默认值 说明

method string 是 - 需要调用的方法名

...args array 否 - 方法参数

示例代码：

  const page = await program.currentPage()

  await page.callMethod('onShareAppMessage')

Element

Element 模块提供了控制页面元素的方法。

属性

element.tagName

标签名，小写。

element.tagName: string

方法

element.$

在元素范围内获取元素。

element.$(selector: string): Promise<Element>

参数说明

字段 类型 必填 默认值 说明

selector string 是 - 选择器

示例代码：

  const page = await program.currentPage()

  let element = await page.$('.index-hd')

  element = await element.$('.index-desc')

  console.log(await element.text())

element.$$

在元素范围内获取元素数组。

element.$$(selector: string): Promise<Element[]>

参数说明

字段 类型 必填 默认值 说明

selector string 是 - 选择器

示例代码：

  const page = await program.currentPage()

  const element = await page.$('.index-bd')

  const elements = await element.$$('.list-text')

  console.log(await elements[0].text())

element.size

获取元素大小。

element.size(): Promise<Object>

返回值说明

字段 类型 说明

width number 元素宽度

height number 元素高度

示例代码：

  const page = await program.currentPage()

  const element = await page.$('.index-bd')

  const { width, height } = await element.size()

  console.log(width, height)

element.offset

获取元素绝对位置。

element.offset(): Promise<Object>

返回值说明

字段 类型 说明

left number 左上角x坐标，单位：px

top number 左上角y坐标，单位：px

坐标信息以页面左上角为原点。

示例代码：

  const page = await program.currentPage()

  const element = await page.$('.index-bd')

  const { left top } = await element.offset()

  console.log(left, top)

element.text

获取元素文本。

element.text(): Promise<string>

示例代码：

  const page = await program.currentPage()

  const element = await page.$('.index-desc')

  console.log(await element.text())

element.attribute

获取元素特性。

element.attribute(name: string): Promise<string>

参数说明

字段 类型 必填 默认值 说明

name string 是 - 特性名

示例代码：

  const page = await program.currentPage()

  const element = await page.$('.logo')

  console.log(await element.attribute('src')) // -> 'static/logo.png'

element.property

获取元素属性。

element.property(name: string): Promise<any>

参数说明

字段 类型 必填 默认值 说明

name string 是 - 属性名

element.property 与 element.attribute 主要区别如下：

element.attribute 获取的是标签上的值，因此它的返回类型一定是字符串，element.property 则不一定。

element.attribute 可以获取到 class 和 id 之类的值，element.property 不行。

element.property 可以获取到文档里对应组件列举的大部分属性值，比如表单 input 等组件的 value 值。

示例代码：

  const page = await program.currentPage()

  const element = await page.$('input')

  console.log(await element.property('value'))

element.html

获取元素 HTML。

element.html(): Promise<string>

element.outerHtml

同 html，只是会获取到元素本身。

element.outerHtml(): Promise<string>

示例代码：

  const page = await program.currentPage()

  const element = await page.$('.index-desc')

  console.log(await element.html())

  console.log(await element.outerHtml())

element.value

获取元素值。

element.value(): Promise<string>

示例代码：

  const page = await program.currentPage()

  const element = await page.$('.input')

  console.log(await element.value())

element.style

获取元素样式值。

element.style(name: string): Promise<string>

参数说明

字段 类型 必填 默认值 说明

name string 是 - 样式名

示例代码：

  const page = await program.currentPage()

  const element = await page.$('.index-desc')

  console.log(await element.style('color')) // -> 'rgb(128, 128, 128)'

element.tap

点击元素。

element.tap(): Promise<void>

示例代码：

  const page = await program.currentPage()

  const element = await page.$('.list-item-hd')

  await element.tap()

element.longpress

长按元素。

element.longpress(): Promise<void>

element.touchstart

手指开始触摸元素。

element.touchstart(options: Object): Promise<void>

options 字段定义如下：

字段 类型 必填 默认值 说明

touches array 是 - 触摸事件，当前停留在屏幕中的触摸点信息的数组

changedTouches array 是 - 触摸事件，当前变化的触摸点信息的数组

element.touchmove

手指触摸元素后移动。

element.touchmove(options: Object): Promise<void>

options 字段同 touchstart。

element.touchend

手指结束触摸元素。

element.touchend(options: Object): Promise<void>

options 字段同 touchstart。

  const page = await program.currentPage()

  const element = await page.$('.touch')

  await element.touchstart({

    touches: [

      {

        identifier: 1,

        pageX: 500,

        pageY: 500

      }

    ],

    changedTouches: [

      {

        identifier: 1,

        pageX: 500,

        pageY: 500

      }

    ]

  })

  await element.touchend({

    touches: [],

    changedTouches: [

      {

        identifier: 1,

        pageX: 500,

        pageY: 500

      }

    ]

  })

element.trigger

触发元素事件。

element.trigger(type: string, detail?: Object): Promise<void>

参数说明

字段 类型 必填 默认值 说明

type string 是 - 触发事件类型

detail Object 否 - 触发事件时传递的 detail 值

示例代码：

  const page = await program.currentPage()

  const element = await page.$('picker')

  await element.trigger('change', { value: 1 })

该方法无法改变组件状态，仅触发响应方法，也无法触发用户操作事件，即 tap，longpress 等事件，请使用对应的其它方法调用。

element.input

输入文本，仅 input、textarea 组件可以使用。

element.input(value: string): Promise<void>

参数说明

字段 类型 必填 默认值 说明

value string 是 - 需要输入的文本

示例代码：

  const page = await program.currentPage()

  const element = await page.$('input')

  await element.input('test')

element.callMethod

调用组件实例指定方法，仅自定义组件可以使用。

element.callMethod(method: string, ...args: any[]): Promise<any>

参数说明

字段 类型 必填 默认值 说明

method string 是 - 需要调用的方法名

...args array 否 - 方法参数

示例代码：

  const page = await program.currentPage()

  const element = await page.$('set-tab-bar')

  await element.callMethod('navigateBack')

element.data

获取组件实例渲染数据，仅自定义组件可以使用。

element.data(path?: string): Promise<Object>

参数说明

字段 类型 必填 默认值 说明

path string 否 - 数据路径

示例代码：

  const page = await program.currentPage()

  const element = await page.$('set-tab-bar')

  console.log(await element.data('hasSetTabBarBadge'))

element.setData

设置组件实例渲染数据，仅自定义组件可以使用。

element.setData(data: Object): Promise<void>

参数说明

字段 类型 必填 默认值 说明

data Object 是 - 要改变的数据

示例代码：

  const page = await program.currentPage()

  const element = await page.$('set-tab-bar')

  await page.setData({

    hasSetTabBarBadge: true

  })

element.callContextMethod

调用上下文 Context 对象方法，仅 video 组件可以使用。

element.callContextMethod(method: string, ...args: any[]): Promise<any>

参数说明

字段 类型 必填 默认值 说明

method string 是 - 需要调用的方法名

...args array 否 - 方法参数

video 组件必须设置了 id 才能使用。

  const page = await program.currentPage()

  const element = await page.$('video')

  await element.callContextMethod('play')

element.scrollWidth

获取滚动宽度，仅 scroll-view 组件可以使用。

element.scrollWidth(): Promise<number>

element.scrollHeight

获取滚动高度，仅 scroll-view 组件可以使用。

element.scrollHeight(): Promise<number>

element.scrollTo

滚动到指定位置，仅 scroll-view 组件可以使用。

element.scrollTo(x: number, y: number): Promise<void>

参数说明

字段 类型 必填 默认值 说明

x number 是 - 横向滚动位置

y number 是 - 纵向滚动位置

示例代码：

  const page = await program.currentPage()

  const element = await page.$('scroll-view')

  const y = (await element.scrollHeight()) - 50

  await element.scrollTo(0, y)

element.swipeTo

滑动到指定滑块，仅 swiper 组件可以使用。

element.swipeTo(index: number): Promise<void>

参数说明

字段 类型 必填 默认值 说明

index number 是 - 目标滑块的 index

示例代码：

  const page = await program.currentPage()

  const element = await page.$('swiper')

  await element.swipeTo(2)

element.moveTo

移动视图容器，仅 movable-view 组件可以使用。

element.moveTo(x: number, y: number): Promise<void>

参数说明

字段 类型 必填 默认值 说明

x number 是 - x 轴方向的偏移

y number 是 - y 轴方向的偏移

示例代码：

  const page = await program.currentPage()

  const element = await page.$('movable-view')

  await element.moveTo(40, 40)

element.slideTo

滑动到指定数值，仅 slider 组件可以使用。

element.slideTo(value: number): Promise<void>

参数说明

字段 类型 必填 默认值 说明

value number 是 - 要设置的值

示例代码：

  const page = await program.currentPage()

  const element = await page.$('slider')

  await element.slideTo(10)

平台差异

program(全局对象)

方法 APP-NVUE APP-VUE H5 微信小程序 百度小程序 说明

pageStack √ √ √ √ √ 获取小程序页面堆栈

navigateTo √ √ √ √ √ 保留当前页面，跳转到应用内的某个页面，同uni.navigateTo

redirectTo √ √ √ √ √ 关闭当前页面，跳转到应用内的某个页面，同uni.redirectTo

navigateBack √ √ √ √ √ 关闭当前页面，返回上一页面，同uni.navigateBack

reLaunch √ √ √ √ √ 关闭所有页面，打开到应用内的某个页面，同uni.reLaunch

switchTab √ √ √ √ √ 跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面，同uni.switchTab

currentPage √ √ √ √ √ 获取当前页面

systemInfo √ √ √ √ √ 获取系统信息，同uni.getSystemInfo

pageScrollTo x √ √ √ √ 将页面滚动到目标位置，同uni.pageScrollTo

callUniMethod √ √ √ √ √ 调用 uni 对象上的指定方法

screenshot √ √ √ √ x 对当前页面截图，目前只有开发者工具模拟器支持，客户端无法使用

mockUniMethod √ √ √ √ √ 覆盖 uni 对象上指定方法的调用结果

restoreUniMethod √ √ √ √ √ 重置 uni 指定方法，消除 mockUniMethod 调用的影响

testAccounts x x x √ x 获取多账号调试中已添加的用户列表

evaluate x x x √ x 注入代码片段并返回执行结果

exposeFunction x x x √ x 在全局暴露方法，供小程序侧调用测试脚本中的方法

Page

属性 APP-NVUE APP-VUE H5 微信小程序 百度小程序 说明

path √ √ √ √ √ 页面路径

query √ √ √ √ √ 页面参数

方法 APP-NVUE APP-VUE H5 微信小程序 百度小程序 说明

$ √ √ √ √ √ 获取页面元素

$$ √ √ √ √ √ 获取页面元素数组

waitFor √ √ √ √ √ 等待直到指定条件成立

data √ √ √ √ √ 获取页面渲染数据

setData √ √ √ √ √ 设置页面渲染数据

size √ √ √ √ √ 获取页面大小(width,height)

scrollTop √ √ √ √ √ 获取页面滚动位置

callMethod √ √ √ √ √ 调用页面指定方法

Element

属性 APP-NVUE APP-VUE H5 微信小程序 百度小程序 说明

tagName √ √ √ √ √ 标签名，小写

方法 APP-NVUE APP-VUE H5 微信小程序 百度小程序 说明

$ √ √ √ √ √ 在元素范围内获取元素

$$ √ √ √ √ √ 在元素范围内获取元素数组

size √ √ √ √ √ 获取元素大小(width,height)

offset √ √ √ √ √ 获取元素绝对位置(left,top)

text √ √ √ √ √ 获取元素文本

attribute √ √ √ √ √ 获取元素特性

style √ √ √ √ √ 获取元素样式值

tap √ √ √ √ √ 点击元素

value √ √ √ √ √ 获取元素值

callMethod √ √ √ √ √ 调用组件实例指定方法，仅自定义组件可以使用

html √ √ √ √ √ 获取元素 HTML

outerHtml √ √ √ √ √ 同 html，只是会获取到元素本身

data √ √ √ √ √ 获取组件实例渲染数据，仅自定义组件可以使用

setData √ √ √ √ √ 设置组件实例渲染数据，仅自定义组件可以使用

property √ √ √ √ x 获取元素属性

touchstart √ √ √ √ x 手指开始触摸元素

touchmove √ √ √ √ x 手指触摸元素后移动

touchend √ √ √ √ x 手指结束触摸元素

longpress √ √ √ √ x 获取元素文本

trigger √ √ √ √ x 触发元素事件

input √ √ √ √ x 输入文本，仅 input、textarea 组件可以使用

callContextMethod x x x √ x 调用上下文 Context 对象方法，仅 video 组件可以使用

scrollWidth x √ √ √ x 获取滚动宽度，仅 scroll-view 组件可以使用

scrollHeight x √ √ √ x 获取滚动高度，仅 scroll-view 组件可以使用

scrollTo x √ √ √ x 滚动到指定位置，仅 scroll-view 组件可以使用

swipeTo √ √ √ √ x 滑动到指定滑块，仅 swiper 组件可以使用

moveTo √ √ √ √ x 移动视图容器，仅 movable-view 组件可以使用

slideTo √ √ √ √ x 滑动到指定数值，仅 slider 组件可以使用

分包

全局文件配置manifest.json

"app-plus": {

  "optimization": {

    "subPackages": true

  },

  "runmode" : "liberate" // 开启分包优化后，必须配置资源释放模式

}

pages.json文件

 "subPackages": [{

        "root": "pagesDome",

        "pages": [

            {

                "path": "http/http",

                "style": {

                "navigationBarTitleText": "http接口示例"

                }

            },

            ...

         ],

         {

          root": "pagesPackageA",

        "pages": [

            {

                "path": "address/address",

                "style": {

                    "navigationBarTitleText": "地址管理"

                }

            },

            ...

           ]

         }

         ...

         ]

easycom

传统vue组件，需要安装、引用、注册，三个步骤后才能使用组件。easycom将其精简为一步。 只要组件安装在项目的components目录下，并符合components/组件名称/组件名称.vue目录结构。就可以不用引用、注册，直接在页面中使用。 如下：

<template>

<view class="container">

<uni-list>

<uni-list-item title="第一行"></uni-list-item>

<uni-list-item title="第二行"></uni-list-item>

</uni-list>

</view>

</template>

<script>

// 这里不用import引入，也不需要在components内注册uni-list组件。template里就可以直接用

export default {

data() {

return {

}

}

}

</script>

不管components目录下安装了多少组件，easycom打包后会自动剔除没有使用的组件，对组件库的使用尤为友好。

组件库批量安装，随意使用，自动按需打包。以官方的uni-ui为例，在HBuilderX新建项目界面选择uni-ui项目模板，只需在页面中敲u，拉出大量组件代码块，直接选择，即可使用。大幅提升开发效率，降低使用门槛。

在uni-app插件市场 (opens new window)下载符合components/组件名称/组件名称.vue目录结构的组件，均可直接使用。

H5发布注意

uview  u-icon字体修改

u-icon.vue :

<script>

// #ifdef APP-NVUE

// nvue通过weex的dom模块引入字体，相关文档地址如下：

// https://weex.apache.org/zh/docs/modules/dom.html#addrule

//const fontUrl = 'https://at.alicdn.com/t/font_2225171_8kdcwk4po24.ttf'

const fontUrl = '

http://at.alicdn.com/t/font_2225171_8kdcwk4po24.ttf'