uniapp简结 #

• 参考链接

  uniapp官网

  白话uni-app 【也是html、vue、小程序的区别】

  微信小程序开发文档

  Some selectors are not allowed in component wxss

  使用了scss，微信小程序编译.wxss文件错误，已正确安装scss模块

  uni-app自定义底部tabbar

  uni-app如何获取当前页面路由（整个页面对象）？如何获取前一个甚至已经打开的页面路由？

• 概述

  • 架构
  • 目录结构

• 组件/标签的变化

  • html标签和uni-app内置组件的映射表
  • 新增了一批手机端常用的新组件
  • js的变化
  • css的变化
  • 标签详解
  • API

• 原生组件说明

  • 混合渲染模式下原生组件的使用限制
  • 其他原生界面元素
  • vue页面层级覆盖解决方案
  • App的nvue页面层级问题
  • Android系统主题字体对原生组件渲染的影响

• 生命周期

  • 应用生命周期
  • 页面生命周期
  • 组件生命周期

• 路由跳转

• 页面样式与布局

  • 尺寸单位
  • 内置CSS变量
  • 自定义组件

• 配置

  • pages.json
  • manifest.json
  • package.json
  • vue.config.js
  • uni.scss
  • App.vue
  • main.js

• 页面通讯

• 测试

• 使用问题

  • uni-app启动微信开发者工具
  • sass/scss插件安装失败
  • 微信小程序分享
  • h5请求跨域解决方案
  • 微信小程序转uniapp

• 项目性能优化

• 原生nvue相关

• 手机模拟器调试

• 关于ssr

• 支付

概述 #

uni-app 是一个使用 Vue.js 开发所有前端应用的框架，开发者编写一套代码，可发布到iOS、Android、H5、以及各种小程序（微信/支付宝/百度/头条/QQ/钉钉/淘宝）、快应用等多个平台。

开发者使用HBuilderX工具开发。

每个可显示的页面，都必须在 pages.json 中注册。如果你开发过小程序，那么pages.json类似app.json。如果你熟悉vue，这里没有vue的路由，都是在pages.json里管理。

uni-app的首页，是在pages.json里配的，page节点下第一个页面就是首页。一般在/pages/xx的目录下。

app和小程序中，为了提升体验，页面提供了原生的导航栏和底部tabbar，注意这些配置是在pages.json中做，而不是在vue页面里创建，但点击事件的监听在显示的vue页面中做。

在vue中，以前的js事件监听概念改为了生命周期概念。

如果你熟悉小程序开发的话，对比变化如下：

• 原来app.json被一拆为二。页面管理，被挪入了uni-app的pages.json；非页面管理，挪入了manifest.json
• 原来的app.js和app.wxss被合并到了app.vue中

架构 #

目录结构 #

┌─components            uni-app组件目录
│  └─comp-a.vue         可复用的a组件
├─hybrid                存放本地网页的目录
├─platforms             存放各平台专用页面的目录
├─wxcomponents          微信小程序自定义组件存放目录
│   └──custom           微信小程序自定义组件
│        ├─index.js
│        ├─index.wxml
│        ├─index.json
│        └─index.wxss
├─mycomponents          支付宝小程序自定义组件存放目录
│   └──custom           支付宝小程序自定义组件
│        ├─index.js
│        ├─index.axml
│        ├─index.json
│        └─index.wxss
├─swancomponents        百度小程序自定义组件存放目录
│   └──custom           百度小程序自定义组件
│        ├─index.js
│        ├─index.swan
│        ├─index.json
│        └
├─pages                 业务页面文件存放的目录
│  ├─index
│  │  └─index.vue       index页面
│  └─list
│     └─list.vue        list页面
├─static                存放应用引用静态资源（如图片、视频等）的目录，注意：静态资源只能存放于此
├─wxcomponents          存放小程序组件的目录
├─main.js               Vue初始化入口文件
├─App.vue               应用配置，用来配置App全局样式以及监听 应用生命周期
├─manifest.json         配置应用名称、appid、logo、版本等打包信息
└─pages.json            配置页面路由、导航条、选项卡等页面类信息

组件/标签的变化 #

html标签和uni-app内置组件的映射表 #

• div 改成 view
• span、font 改成 text
• a 改成 navigator
• img 改成 image
• input 还在，但type属性改成了confirmtype
• form、button、checkbox、radio、label、textarea、canvas、video 这些还在。
• select 改成 picker
• iframe 改成 web-view
• ul、li没有了，都用view替代
• audio 不再推荐使用，改成api方式，背景音频api文档

其实老的HTML标签也可以在uni-app里使用，uni-app编译器会在编译时把老标签转为新标签，比如把div编译成view。但不推荐这种用法，调试H5端时容易混乱。

建议使用v-if代替v-show，因为小程序上display:block会与display:flex冲突

向组件传值时，传入正则表达式，会被转化为空对象，因此可传入对象{regExp: '^1[3456789]\d{9}$'}，在组件里new RegExp

新增了一批手机端常用的新组件 #

• scroll-view 可区域滚动视图容器
• swiper 可滑动区域视图容器
• icon 图标
• rich-text 富文本（不可执行js，但可渲染各种文字格式和图片）
• progress 进度条
• slider 滑块指示器
• switch 开关选择器
• camera 相机
• live-player 直播
• map 地图
• cover-view 可覆盖原生组件的视图容器 cover-view需要多强调几句，uni-app的非h5端的video、map、canvas、textarea是原生组件，层级高于其他组件。如需覆盖原生组件，则需要使用cover-view组件。详见原生组件说明

更多封装好的插件可到插件市场下载

js的变化 #

h5端使用js，非h5端使用nodejs，因此window、document、navigator、location可能无法使用，其工具库如jquery也无法使用。

app和小程序支持web-view组件，里面可以加载标准HTML，这种页面仍然支持浏览器专用对象window、document、navigator、location。

以前的dom操作，改成vue的MVVM模式

因为uni-app的api是参考小程序的，所以和浏览器的js api有很多不同，如：

• alert,confirm 改成 uni.showmodel
• ajax 改成 uni.request
• cookie、session 没有了，local.storage 改成 uni.storage
• 更多的基本就是小程序的api，把wx.xxx改为uni.xxx即可，可查看api

跨端兼容:每个平台有自己的一些特性，因此会存在一些无法跨平台的情况，可使用条件编译

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

// #ifdef APP-PLUS
需条件编译的代码
// #endif

注意

• Android 和 iOS 平台不支持通过条件编译来区分，如果需要区分 Android、iOS 平台，请通过调用 uni.getSystemInfo 来获取平台信息。支持ifios、ifAndroid代码块，可方便编写判断。
• 有些跨端工具可以提供js的条件编译或多态，但这对于实际开发远远不够。uni-app不止是处理js，任何代码都可以多端条件编译，才能真正解决实际项目的跨端问题。另外所谓多态在实际开发中会造成大量冗余代码，很不利于复用和维护。举例，微信小程序主题色是绿色，而百度支付宝小程序是蓝色，你的应用想分平台适配颜色，只有条件编译是代码量最低、最容易维护的。
• 有些公司的产品运营总是给不同平台提不同需求，但这不是拒绝uni-app的理由。关键在于项目里，复用的代码多还是个性的代码多，正常都是复用的代码多，所以仍然应该多端。而个性的代码放到不同平台的目录下，差异化维护。

运行环境判断

if(process.env.NODE_ENV === 'development'){
    console.log('开发环境')
}else{
    console.log('生产环境')
}

运行期判断

switch(uni.getSystemInfoSync().platform){
    case 'android':
       console.log('运行Android上')
       break;
    case 'ios':
       console.log('运行iOS上')
       break;
    default:
       console.log('运行在开发者工具上')
       break;
}

css的变化 #

标准的css基本都是支持的。

选择器有2个变化：*选择器不支持；元素选择器里没有body，改为了page。

单位方面，px无法动态适应不同宽度的屏幕，rem无法用于nvue/weex。如果想使用根据屏幕宽度自适应的单位，推荐使用rpx，全端支持。详见页面样式与布局中的尺寸单位

标签详解 #

• 视图容器

  • view:类似div，可设置hover相关属性：hover-class，hover-stop-propagation(是否阻止本节点的祖先节点出现点击态)，hover-start-time，hover-stay-time

  • scroll-view:可滚动视图区域。在webview渲染的页面中，区域滚动的性能不及页面滚动。可设置滚动方向、位置、上下拉等属性和事件。

    html

    <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>
    

  • swiper:轮播图。可设置导航点、动画时长、交互事件

    注意：

    使用竖向滚动时，需要给 scroll-view 一个固定高度，通过 css 设置 height

    其中只可放置 swiper-item 组件，否则会导致未定义的行为

    竖向的swiper内嵌视频可实现抖音、映客等视频垂直拖动切换效果

    同时监听 change transition，开始滑动时触发transition, 放开手后，在ios平台触发顺序为 transition... change，Android/微信小程序/支付宝为 transition... change transition...

    html

    <swiper class="swiper" :indicator-dots="indicatorDots" :autoplay="autoplay" :interval="interval" :duration="duration">
        <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>
    

  • movable-area:可拖动区域组件。内嵌movable-view组件用于指示可拖动的滑块(默认宽高为10px)。scale-area属性为true时支持双指缩放。还可设置其他移动和缩放的属性和事件。

    html

    <movable-area>
        <movable-view :x="x" :y="y" direction="all" @change="onChange">text</movable-view>
    </movable-area>
    

  • cover-view:覆盖在原生组件上的文本视图。仅可覆盖video、map

  • cover-image:覆盖在原生组件上的图片视图。支持click，不支持position: fixed、opacity、overflow、padding、linebreak、white-space

    html

    <view class="page">
        <video class="video" id="demoVideo" :controls="false" :enable-progress-gesture="false" :show-center-play-btn="disable" src="https://img.cdn.aliyun.dcloud.net.cn/guide/uniapp/%E7%AC%AC1%E8%AE%B2%EF%BC%88uni-app%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D%EF%BC%89-%20DCloud%E5%AE%98%E6%96%B9%E8%A7%86%E9%A2%91%E6%95%99%E7%A8%[email protected]">
            <cover-view class="controls-title">简单的自定义 controls</cover-view>
            <cover-image class="controls-play img" @click="play" src="/static/play.png"></cover-image>
            <cover-image class="controls-pause img" @click="pause" src="/static/pause.png"></cover-image>
        </video>
    </view>
    

• 基础内容

  • icon:图标。可设置类型、大小、颜色。

    类型：

    • App、H5、微信小程序、QQ小程序：success, success_no_circle, info, warn, waiting, cancel, download, search, clear
    • 支付宝小程序：info, warn, waiting, cancel, download, search, clear, success, success_no_circle,loading
    • 百度小程序：success, info, warn, waiting, success_no_circle, clear, search, personal, setting, top, close, cancel, download, checkboxSelected, radioSelected, radioUnselect

  • text:文本组件。可设置是否可选、空格类型(ensp中文字符空格一半大小/emsp中文字符空格大小/nbsp根据字体设置的空格大小)、是否解码。

  • rich-text:富文本。在富文本区域里显示的 HTML/文本 节点。

  • progress:进度条。可设置百分比、样式、动画

• 表单组件

  • button:按钮。可设置样式、loading、是否触发submit、按钮事件

    • size 有效值：default默认大小、mini小尺寸
    • type 有效值：primary微信小程序、360小程序为绿色，App、H5、百度小程序、支付宝小程序、快应用为蓝色，字节跳动小程序为红色，QQ小程序为浅蓝色。如想在多端统一颜色，请改用default，然后自行写样式；default 白色；warn红色
    • form-type 有效值：submit提交表单、reset重置表单

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

    html

    <checkbox-group>
        <label>
            <checkbox value="cb" checked="true" />选中
        </label>
        <label>
            <checkbox value="cb" />未选中
        </label>
    </checkbox-group>
    

  • editor:富文本编辑器，可以对图片、文字格式进行编辑和混排。只有H5、App的vue页面和微信支持，其他端平台自身为提供editor组件，只能使用webview加载web页面，或查看插件市场。

    • 不满足的标签会被忽略，div会被转行为p储存。
    • 行内元素:span/strong/b/ins/em/i/u/a/del/s/sub/sup/img
    • 块级元素:p/h1/h2/h3/h4/h5/h6/hr/ol/ul/li
    • 块级样式:text-align direction margin margin-top margin-left margin-right margin-bottom padding padding-top padding-left padding-right padding-bottom line-height text-indent
    • 行内样式:font font-size font-style font-variant font-weight font-family letter-spacing text-decoration color background-color
    html

    <editor id="editor" class="ql-container" :placeholder="placeholder" @ready="onEditorReady"></editor>
    

  • form:表单，与html相同

  • input:输入框。多了confirm-type用于设置键盘右下角按钮的文字(send发送/search搜索/next下一个/go前往/done完成)，仅在 type="text" 时生效。APP平台兼容可查文档

  • label:用来改进表单组件的可用性，使用for属性找到对应的id，或者将控件放在该标签下，当点击时，就会触发对应的控件。目前可以绑定的控件有：button, checkbox, radio, switch。

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

    mode为 selector 或 multiSelector(多列选择器) 时，range 有效

    当 range 是一个 Array＜Object＞ 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容

    value 的值表示选择了 range 中的第几个（下标从 0 开始）

    可监听change和cancel事件，可禁用

    mode = time时间选择器，可设置起止时间

    mode = region省市区选择器，不支持app和h5，需用picker-view自行填充

  • picker-view:嵌入页面的滚动选择器。

    html

    <picker-view v-if="visible" :indicator-style="indicatorStyle" :value="value" @change="bindChange">
        <picker-view-column>
            <view class="item" v-for="(item,index) in years" :key="index">{{item}}年</view>
        </picker-view-column>
        <picker-view-column>
            <view class="item" v-for="(item,index) in months" :key="index">{{item}}月</view>
        </picker-view-column>
        <picker-view-column>
            <view class="item" v-for="(item,index) in days" :key="index">{{item}}日</view>
        </picker-view-column>
    </picker-view>
    

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

    html

    <radio-group @change="radioChange">
        <label class="uni-list-cell uni-list-cell-pd" v-for="(item, index) in items" :key="item.value">
            <view>
                <radio :value="item.value" :checked="index === current" />
            </view>
            <view>{{item.name}}</view>
        </label>
    </radio-group>
    

  • slider:滑动选择器。可设置范围值、步长、样式、改变事件。

    html

    <slider value="60" @change="sliderChange" step="5" />
    

  • switch:开关选择器。

  • textarea:多行输入框。

    textarea 的 blur 事件会晚于页面上的 tap 事件，如果需要在 button 的点击事件获取 textarea，可以使用 form 的 @submit。

    微信小程序、百度小程序、字节跳动小程序中，textarea是原生组件，层级高于前端组件，请勿在 scroll-view、swiper、picker-view、movable-view 中使用 textarea 组件。覆盖textarea需要使用cover-view。

    小程序端 css 动画对 textarea 组件无效。

    如需禁止点击其他位置收起键盘的默认行为，可以监听touch事件并使用prevent修饰符

• 导航navigator见路由跳转

• 媒体组件

  • audio:音频。
  • camera:页面内嵌的区域相机组件。注意这不是点击后全屏打开的相机。
  • image:图片。比h5多了图片裁剪缩放、懒加载设置、动画。
  • video:视频播放组件。能设置弹幕、手势、缓冲。
  • live-player:实时音视频播放，也称直播拉流。
  • live-pusher:实时音视频录制，也称直播推流。

• 地图map

• 画布canvas

• webview:web-view 是一个 web 浏览器组件(类似iframe)，可以用来承载网页的容器，会自动铺满整个页面

• 广告ad:应用内展示的广告组件，可用于banner或信息流。

• 开放能力组件

  • official-account:微信公众号关注组件。当用户扫小程序码打开小程序时，开发者可在小程序内配置公众号关注组件，方便用户快捷关注公众号，可嵌套在原生组件内。

  • open-data:用于展示平台开放的数据。

    html

    <open-data type="userNickName"></open-data>
    

• app nvue专用组件

  • Barcode:app端nvue专用的扫码组件。
  • list:app端nvue专用组件。在app-nvue下，如果是长列表，使用list组件的性能高于使用view或scroll-view的滚动。原因在于list在不可见部分的渲染资源回收有特殊的优化处理。
  • cell:app端nvue专用组件。它的重要价值在于告诉原生引擎，哪些部分是可重用的。Cell 支持添加任意类型的组件作为自己的子组件，但是请不要再内部添加滚动容器了。
  • recycle-list:一个新的列表容器，具有回收和复用的能力，可以大幅优化内存占用和渲染性能。它的性能比list组件更高，但写法受限制。它除了会释放不可见区域的渲染资源，在非渲染的数据结构上也有更多优化。
  • waterfall:瀑布流布局的核心组件。
  • refresh:为容器提供下拉刷新功能

• 拓展组件

  • uni-ui:DCloud提供的一个跨端ui库，它是基于vue组件的、flex布局的、无dom的跨全端ui框架。
  • Badge:数字角标
  • Calendar:日历
  • Card:卡片
  • Collapse:折叠面板
  • Combox:组合框
  • CountDown:倒计时
  • Drawer:抽屉
  • Fab:悬浮按钮
  • Fav:收藏按钮
  • GoodsNav:商品导航
  • Grid:宫格
  • Icons:图标
  • IndexedList:索引列表
  • List:列表
  • LoadMore:加载更多
  • NavBar:自定义导航栏
  • NoticeBar:通告栏
  • NumberBox:数字输入框
  • Pagination:分页器
  • PopUp:弹出层
  • Rate:评分
  • SearchBar:搜索栏
  • SegmentedControl:分段器
  • Steps:步骤条
  • SwipeAction:滑动操作
  • SwiperDot:轮播图指示点
  • Tag:标签

• 导航栏navigation-bar:页面导航条配置节点，用于指定导航栏的一些属性。只能是 page-meta 组件内的第一个节点，需要配合它一同使用。

• 页面属性配置:page-meta

API #

• 基础

  • console日志打印:与h5相同

  • 定时器:与h5相同

  • base64与arrayBuffer互转:uni.arrayBufferToBase64(arrayBuffer)/uni.base64ToArrayBuffer(base64) 仅支持app和微信小程序

  • 应用级事件:

    • uni.onPageNotFound(funciton callback):监听应用要打开的页面不存在事件。该事件与 App.onPageNotFound 的回调时机一致
    • uni.onError(funciton callback):监听小程序错误事件
    • uni.onAppShow(function callback):监听应用切前台事件
    • uni.onAppHide(function callback):监听应用切后台事件
    • uni.offPageNotFound(function callback):取消监听应用要打开的页面不存在事件
    • uni.offError(funciton callback):取消监听应用错误事件
    • uni.offAppShow(function callback):取消监听小程序切前台事件
    • uni.offAppHide(function callback):取消监听小程序切后台事件

• 网络

  • uni.request(OBJECT):发起网络请求。

    javascript

    uni.request({
        url: 'https://www.example.com/request', //仅为示例，并非真实接口地址。
        data: {
            text: 'uni.request'
        },
        header: {
            'custom-header': 'hello' //自定义请求头信息
        },
        success: (res) => {
            console.log(res.data);
            this.text = 'request success';
        }
    });
    

  • uni.uploadFile(OBJECT):上传

    javascript

    uni.chooseImage({
        success: (chooseImageRes) => {
            const tempFilePaths = chooseImageRes.tempFilePaths;
            uni.uploadFile({
                url: 'https://www.example.com/upload', //仅为示例，非真实的接口地址
                filePath: tempFilePaths[0],
                name: 'file',
                formData: {
                    'user': 'test'
                },
                success: (uploadFileRes) => {
                    console.log(uploadFileRes.data);
                }
            });
        }
    });
    

    上传进度

    javascript

    uni.chooseImage({
        success: (chooseImageRes) => {
            const tempFilePaths = chooseImageRes.tempFilePaths;
            const uploadTask = uni.uploadFile({
                url: 'https://www.example.com/upload', //仅为示例，非真实的接口地址
                filePath: tempFilePaths[0],
                name: 'file',
                formData: {
                    'user': 'test'
                },
                success: (uploadFileRes) => {
                    console.log(uploadFileRes.data);
                }
            });
    
            uploadTask.onProgressUpdate((res) => {
                console.log('上传进度' + res.progress);
                console.log('已经上传的数据长度' + res.totalBytesSent);
                console.log('预期需要上传的数据总长度' + res.totalBytesExpectedToSend);
    
                // 测试条件，取消上传任务。
                if (res.progress > 50) {
                    uploadTask.abort();
                }
            });
        }
    });
    

  • uni.downloadFile(OBJECT):下载文件资源到本地，客户端直接发起一个 HTTP GET 请求，返回文件的本地临时路径。

    javascript

    uni.downloadFile({
        url: 'https://www.example.com/file/test', //仅为示例，并非真实的资源
        success: (res) => {
            if (res.statusCode === 200) {
                console.log('下载成功');
            }
        }
    });
    

    下载进度

    javascript

    const downloadTask = uni.downloadFile({
        url: 'http://www.example.com/file/test', //仅为示例，并非真实的资源
        success: (res) => {
            if (res.statusCode === 200) {
                console.log('下载成功');
            }
        }
    });
    
    downloadTask.onProgressUpdate((res) => {
        console.log('下载进度' + res.progress);
        console.log('已经下载的数据长度' + res.totalBytesWritten);
        console.log('预期需要下载的数据总长度' + res.totalBytesExpectedToWrite);
    
        // 测试条件，取消下载任务。
        if (res.progress > 50) {
            downloadTask.abort();
        }
    });
    

  • websocket

    • uni.connectSocket(OBJECT):创建一个 WebSocket 连接。

      javascript

      uni.connectSocket({
          url: 'wss://www.example.com/socket',
          data() {
              return {
                  x: '',
                  y: ''
              };
          },
          header: {
              'content-type': 'application/json'
          },
          protocols: [[protocol1'],
          method: 'GET',
          success: ()=> {}
      });
      

    • uni.onSocketOpen(CALLBACK):监听WebSocket连接打开事件。

    • uni.onSocketError(CALLBACK):监听WebSocket错误。

    • uni.sendSocketMessage(OBJECT):通过 WebSocket 连接发送数据

      需要先 uni.connectSocket，并在 uni.onSocketOpen 回调之后才能发送。

      javascript

      var socketOpen = false;
      var socketMsgQueue = [];
      
      uni.connectSocket({
          url: 'wss://www.example.com/socket'
      });
      
      uni.onSocketOpen(function (res) {
          socketOpen = true;
          for (var i = 0; i < socketMsgQueue.length; i++) {
              sendSocketMessage(socketMsgQueue[i]);
          }
          socketMsgQueue = [];
      });
      
      function sendSocketMessage(msg) {
          if (socketOpen) {
              uni.sendSocketMessage({
              data: msg
              });
          } else {
              socketMsgQueue.push(msg);
          }
      }
      

    • uni.onSocketMessage(CALLBACK):监听WebSocket接受到服务器的消息事件。

    • uni.closeSocket(OBJECT):监听WebSocket关闭。

    • SocketTask.onMessage(CALLBACK):监听 WebSocket 接受到服务器的消息事件

    • SocketTask.send(OBJECT):通过 WebSocket 连接发送数据

    • SocketTask.close(OBJECT):关闭 WebSocket 连接

    • SocketTask.onOpen(CALLBACK):监听 WebSocket 连接打开事件

    • SocketTask.onClose(CALLBACK):监听 WebSocket 连接关闭事件

    • SocketTask.onError(CALLBACK):监听 WebSocket 错误事件

• 数据缓存

  • uni.setStorage(OBJECT):将数据存储在本地缓存中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个异步接口。

    javascript

    uni.setStorage({
        key: 'storage_key',
        data: 'hello',
        success: function () {
            console.log('success');
        }
    });
    

  • uni.setStorageSync(KEY,DATA):将 data 存储在本地缓存中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个同步接口。

    javascript

    try {
        uni.setStorageSync('storage_key', 'hello');
    } catch (e) {
        // error
    }
    

  • uni.getStorage(OBJECT):从本地缓存中异步获取指定 key 对应的内容。

    javascript

    uni.getStorage({
        key: 'storage_key',
        success: function (res) {
            console.log(res.data);
        }
    });
    

  • uni.getStorageSync(KEY):从本地缓存中同步获取指定 key 对应的内容。

    javascript

    try {
        const value = uni.getStorageSync('storage_key');
        if (value) {
            console.log(value);
        }
    } catch (e) {
        // error
    }
    

  • uni.getStorageInfo(OBJECT):异步获取当前 storage 的相关信息。

    javascript

    uni.getStorageInfo({
        success: function (res) {
            console.log(res.keys);
            console.log(res.currentSize);
            console.log(res.limitSize);
        }
    });
    

  • uni.getStorageInfoSync():同步获取当前 storage 的相关信息。

    javascript

    try {
        const res = uni.getStorageInfoSync();
        console.log(res.keys);
        console.log(res.currentSize);
        console.log(res.limitSize);
    } catch (e) {
        // error
    }
    

  • uni.removeStorage(OBJECT):从本地缓存中异步移除指定 key。

    javascript

    uni.removeStorage({
        key: 'storage_key',
        success: function (res) {
            console.log('success');
        }
    });
    

  • uni.removeStorageSync(KEY):从本地缓存中同步移除指定 key。

    javascript

    try {
        uni.removeStorageSync('storage_key');
    } catch (e) {
        // error
    }
    

  • uni.clearStorage():清理本地数据缓存。

  • uni.clearStorageSync():同步清理本地数据缓存。

  • 注意：

    • H5端为localStorage，浏览器限制5M大小，是缓存概念，可能会被清理

    • 微信小程序单个 key 允许存储的最大数据长度为 1MB，所有数据存储上限为 10MB。

• 位置

  • uni.getLocation(OBJECT):获取当前的地理位置、速度。

    javascript

    uni.getLocation({
        type: 'wgs84',
        success: function (res) {
            console.log('当前位置的经度：' + res.longitude);
            console.log('当前位置的纬度：' + res.latitude);
        }
    });
    

  • uni.chooseLocation(OBJECT):打开地图选择位置。

    javascript

    uni.chooseLocation({
        success: function (res) {
            console.log('位置名称：' + res.name);
            console.log('详细地址：' + res.address);
            console.log('纬度：' + res.latitude);
            console.log('经度：' + res.longitude);
        }
    });
    

  • uni.openLocation(OBJECT):使用应用内置地图查看位置。

    javascript

    uni.getLocation({
        type: 'gcj02', //返回可以用于uni.openLocation的经纬度
        success: function (res) {
            const latitude = res.latitude;
            const longitude = res.longitude;
            uni.openLocation({
                latitude: latitude,
                longitude: longitude,
                success: function () {
                    console.log('success');
                }
            });
        }
    });
    

  • uni.createMapContext(mapId,this):创建并返回 map 上下文 mapContext 对象。在自定义组件下，第二个参数传入组件实例this，以操作组件内 <map> 组件。

• 媒体

  • 图片

    • uni.chooseImage(OBJECT):从本地相册选择图片或使用相机拍照。

      javascript

      uni.chooseImage({
          count: 6, //默认9
          sizeType: [[original', 'compressed'], //可以指定是原图还是压缩图，默认二者都有
          sourceType: [[album'], //从相册选择
          success: function (res) {
              console.log(JSON.stringify(res.tempFilePaths));
          }
      });
      

    • uni.previewImage(OBJECT):预览图片。

      javascript

      uni.chooseImage({
          count: 6,
          sizeType: [[original', 'compressed'],
          sourceType: [[album'],
          success: function(res) {
              // 预览图片
              uni.previewImage({
                  urls: res.tempFilePaths,
                  longPressActions: {
                      itemList: [[发送给朋友', '保存图片', '收藏'],
                      success: function(data) {
                          console.log('选中了第' + (data.tapIndex + 1) + '个按钮,第' + (data.index + 1) + '张图片');
                      },
                      fail: function(err) {
                          console.log(err.errMsg);
                      }
                  }
              });
          }
      });
      

    • uni.getImageInfo(OBJECT):获取图片信息。

      javascript

      uni.chooseImage({
          count: 1,
          sourceType: [[album'],
          success: function (res) {
              uni.getImageInfo({
                  src: res.tempFilePaths[0],
                  success: function (image) {
                      console.log(image.width);
                      console.log(image.height);
                  }
              });
          }
      });
      

    • uni.saveImageToPhotosAlbum(OBJECT):保存图片到系统相册。

      javascript

      uni.chooseImage({
          count: 1,
          sourceType: [[camera'],
          success: function (res) {
              uni.saveImageToPhotosAlbum({
                  filePath: res.tempFilePaths[0],
                  success: function () {
                      console.log('save success');
                  }
              });
          }
      });
      

    • uni.compressImage(OBJECT):压缩图片接口，可选压缩质量

      javascript

      uni.compressImage({
          src: '/static/logo.jpg',
          quality: 80,
          success: res => {
              console.log(res.tempFilePath)
          }
      })
      

    • wx.chooseMessageFile(OBJECT):从微信聊天会话中选择文件。

  • 录音

    • uni.getRecorderManager():获取全局唯一的录音管理器 recorderManager

      javascript

      const recorderManager = uni.getRecorderManager();
      const innerAudioContext = uni.createInnerAudioContext();
      
      innerAudioContext.autoplay = true;
      
      export default {
          data: {
              text: 'uni-app',
              voicePath: ''
          },
          onLoad() {
              let self = this;
              recorderManager.onStop(function (res) {
                  console.log('recorder stop' + JSON.stringify(res));
                  self.voicePath = res.tempFilePath;
              });
          },
          methods: {
              startRecord() {
                  console.log('开始录音');
      
                  recorderManager.start();
              },
              endRecord() {
                  console.log('录音结束');
                  recorderManager.stop();
              },
              playVoice() {
                  console.log('播放录音');
      
                  if (this.voicePath) {
                      innerAudioContext.src = this.voicePath;
                      innerAudioContext.play();
                  }
              }
          }
      }
      

  • 音频

    • uni.getBackgroundAudioManager():获取全局唯一的背景音频管理器 backgroundAudioManager

      javascript

      const bgAudioMannager = uni.getBackgroundAudioManager();
      bgAudioMannager.title = '致爱丽丝';
      bgAudioMannager.singer = '暂无';
      bgAudioMannager.coverImgUrl = 'https://img-cdn-qiniu.dcloud.net.cn/uniapp/audio/music.jpg';
      bgAudioMannager.src = 'https://img-cdn-qiniu.dcloud.net.cn/uniapp/audio/music.mp3';
      

    • uni.createInnerAudioContext():创建并返回内部 audio 上下文 innerAudioContext 对象

      javascript

      const innerAudioContext = uni.createInnerAudioContext();
      innerAudioContext.autoplay = true;
      innerAudioContext.src = 'https://img-cdn-qiniu.dcloud.net.cn/uniapp/audio/music.mp3';
      innerAudioContext.onPlay(() => {
          console.log('开始播放');
      });
      innerAudioContext.onError((res) => {
          console.log(res.errMsg);
          console.log(res.errCode);
      });
      

  • 视频

    • uni.chooseVideo(OBJECT):拍摄视频或从手机相册中选视频，返回视频的临时文件路径。

      javascript

      uni.chooseVideo({
          count: 1,
          sourceType: [[camera', 'album'],
          success: function (res) {
              self.src = res.tempFilePath;
          }
      });
      

    • uni.chooseMedia(OBJECT):拍摄或从手机相册中选择图片或视频。

      javascript

      uni.chooseMedia({
          count: 9,
          mediaType: [[image','video'],
          sourceType: [[album', 'camera'],
          maxDuration: 30,
          camera: 'back',
          success(res) {
              console.log(res.tempFilest)
          }
      })
      

    • uni.saveVideoToPhotosAlbum(OBJECT):保存视频到系统相册

      javascript

      uni.chooseVideo({
          count: 1,
          sourceType: [[camera'],
          success: function (res) {
              self.src = res.tempFilePath;
      
              uni.saveVideoToPhotosAlbum({
                  filePath: res.tempFilePath,
                  success: function () {
                      console.log('save success');
                  }
              });
          }
      });
      

    • uni.getVideoInfo(OBJECT):获取视频详细信息

    • uni.compressVideo(OBJECT):压缩视频接口。

    • uni.openVideoEditor(OBJECT):打开视频编辑器

    • uni.createVideoContext(videoId, this):创建并返回 video 上下文 videoContext 对象。在自定义组件下，第二个参数传入组件实例this，以操作组件内 <video> 组件。

  • 相机

    • uni.createCameraContext():创建并返回 camera 组件的上下文 cameraContext 对象

  • 直播

    • uni.createLivePlayerContext(livePlayerId, this):创建 live-player 上下文 livePlayerContext 对象。注意是直播的播放而不是推流。

    • uni.createLivePusherContext(livePusherId, this):创建 live-pusher 上下文 livePusherContext 对象

  • 富文本

    • editorContext:editor 组件对应的 editorContext 实例，可通过 uni.createSelectorQuery 获取。

    • editorContext.format(name, value):修改样式

    • editorContext.insertDivider(OBJECT):插入分割线

    • editorContext.insertImage(OBJECT):插入图片

    • editorContext.insertText(OBJECT):覆盖当前选区，设置一段文本

    • editorContext.setContents(OBJECT):初始化编辑器内容

    • editorContext.getContents(OBJECT):获取编辑器内容

    • editorContext.clear(OBJECT):清空编辑器内容

    • editorContext.removeFormat(OBJECT):清除当前选区的样式

    • editorContext.undo(OBJECT):撤销

    • editorContext.redo(OBJECT):恢复

  • 音视频合成

    • uni.createMediaContainer():创建音视频处理容器，最终可将容器中的轨道合成一个视频 ，返回 MediaContainer 对象

    • MediaContainer.addTrack(track):将音频或视频轨道添加到容器

    • MediaContainer.destroy():将容器销毁，释放资源

    • MediaContainer.export():将容器内的轨道合并并导出视频文件

    • MediaContainer.extractDataSource(object):将容器内的轨道合并并导出视频文件 ,返回 MediaTrack 对象

    • MediaContainer.removeTrack(track):将音频或视频轨道添加到容器

    • MediaTrack:音频或视频轨道，可以对轨道进行一些操作，可通过 MediaContainer.extractDataSource 返回

• 设备信息

  • uni.getSystemInfo(OBJECT):获取系统信息(手机品牌、屏幕宽高、导航、电量、wifi、蓝牙等)

    javascript

    uni.getSystemInfo({
        success: function (res) {
            console.log(res.model);
            console.log(res.pixelRatio);
            console.log(res.windowWidth);
            console.log(res.windowHeight);
            console.log(res.language);
            console.log(res.version);
            console.log(res.platform);
        }
    });
    

  • uni.getSystemInfoSync():获取系统信息同步接口

    javascript

    try {
        const res = uni.getSystemInfoSync();
        console.log(res.model);
        console.log(res.pixelRatio);
        console.log(res.windowWidth);
        console.log(res.windowHeight);
        console.log(res.language);
        console.log(res.version);
        console.log(res.platform);
    } catch (e) {
        // error
    }
    

  • uni.canIUse(String):判断应用的 API，回调，参数，组件等是否在当前版本可用

    javascript

    uni.canIUse('getSystemInfoSync.return.screenWidth');
    uni.canIUse('getSystemInfo.success.screenWidth');
    uni.canIUse('showToast.object.image');
    uni.canIUse('request.object.method.GET');
    uni.canIUse('live-player');
    uni.canIUse('text.selectable');
    uni.canIUse('button.open-type.contact');
    

  • uni.onMemoryWarning(CALLBACK):监听内存不足告警事件

  • uni.getNetworkType(OBJECT):获取网络类型

    javascript

    uni.getNetworkType({
        success: function (res) {
            console.log(res.networkType);
        }
    });
    

  • uni.onNetworkStatusChange(CALLBACK):监听网络状态变化。

    javascript

    uni.onNetworkStatusChange(function (res) {
        console.log(res.isConnected);
        console.log(res.networkType);
    });
    

  • uni.onUIStyleChange(CALLBACK):监听系统主题状态变化。

    javascript

    uni.onUIStyleChange(function (res) {
        console.log(res.style);
    });
    

  • uni.onAccelerometerChange(CALLBACK):监听加速度数据，频率：5次/秒，接口调用后会自动开始监听，可使用 uni.stopAccelerometer 停止监听。

    javascript

    uni.onAccelerometerChange(function (res) {
        console.log(res.x);
        console.log(res.y);
        console.log(res.z);
    });
    

  • uni.startAccelerometer(OBJECT):开始监听加速度数据,包含回调函数

  • uni.stopAccelerometer(OBJECT):停止监听加速度数据,包含回调函数

  • uni.onCompassChange(CALLBACK):监听罗盘数据，频率：5次/秒，接口调用后会自动开始监听，可使用 uni.stopCompass 停止监听。

  • uni.startCompass(OBJECT):开始监听罗盘数据,包含回调函数

  • uni.stopCompass(OBJECT):停止监听罗盘数据,包含回调函数

  • uni.onGyroscopeChange(CALLBACK):监听陀螺仪数据变化事件。

  • uni.startGyroscope(OBJECT):开始监听陀螺仪数据,包含回调函数

  • uni.stopGyroscope(OBJECT):停止监听陀螺仪数据,包含回调函数

  • uni.makePhoneCall(OBJECT):拨打电话

    javascript

    uni.makePhoneCall({
        phoneNumber: '114' //仅为示例
    });
    

  • uni.scanCode(OBJECT):调起客户端扫码界面，扫码成功后返回对应的结果。

    javascript

    // 允许从相机和相册扫码
    uni.scanCode({
        success: function (res) {
            console.log('条码类型：' + res.scanType);
            console.log('条码内容：' + res.result);
        }
    });
    
    // 只允许通过相机扫码
    uni.scanCode({
        onlyFromCamera: true,
        success: function (res) {
            console.log('条码类型：' + res.scanType);
            console.log('条码内容：' + res.result);
        }
    });
    
    // 调起条码扫描
    uni.scanCode({
        scanType: [[barCode'],
        success: function (res) {
            console.log('条码类型：' + res.scanType);
            console.log('条码内容：' + res.result);
        }
    });
    

  • uni.setClipboardData(OBJECT):设置系统剪贴板的内容。

    javascript

    uni.setClipboardData({
        data: 'hello',
        success: function () {
            console.log('success');
        }
    });
    

  • uni.getClipboardData(OBJECT):获取系统剪贴板内容

    javascript

    uni.getClipboardData({
        success: function (res) {
            console.log(res.data);
        }
    });
    

  • uni.setScreenBrightness(OBJECT):设置屏幕亮度

    javascript

    uni.setScreenBrightness({
        value: 0.5,
        success: function () {
            console.log('success');
        }
    });
    

  • uni.getScreenBrightness(OBJECT):获取屏幕亮度

    javascript

    uni.getScreenBrightness({
        success: function (res) {
            console.log('屏幕亮度值：' + res.value);
        }
    });
    

  • uni.setKeepScreenOn(OBJECT):设置是否保持常亮状态。仅在当前应用生效，离开应用后设置失效。

    javascript

    uni.setKeepScreenOn({
        keepScreenOn: true
    });
    

  • uni.onUserCaptureScreen(CALLBACK):监听用户主动截屏事件，用户使用系统截屏按键截屏时触发此事件。

  • uni.vibrate(OBJECT):使手机发生振动。

    javascript

    uni.vibrate({
        success: function () {
            console.log('success');
        }
    });
    

  • uni.vibrateLong(OBJECT):使手机发生较长时间的振动（400ms）。

    javascript

    uni.vibrateLong({
        success: function () {
            console.log('success');
        }
    });
    

  • uni.vibrateShort(OBJECT):使手机发生较短时间的振动（15ms）。

    javascript

    uni.vibrateShort({
        success: function () {
            console.log('success');
        }
    });
    

  • uni.addPhoneContact(OBJECT):调用后，用户可以选择将该表单以“新增联系人”或“添加到已有联系人”的方式（APP端目前没有选择步骤，将直接写入），写入手机系统通讯录，完成手机通讯录联系人和联系方式的增加。

    javascript

    uni.addPhoneContact({
        nickName: '昵称',
        lastName: '姓',
        firstName: '名',
        remark: '备注',
        mobilePhoneNumber: '114',
        weChatNumber: 'wx123',
        success: function () {
            console.log('success');
        },
        fail: function () {
            console.log('fail');
        }
    });
    

  • uni.openBluetoothAdapter(OBJECT):初始化蓝牙模块

    其他蓝牙相关 API 必须在 uni.openBluetoothAdapter 调用之后使用。否则 API 会返回错误（errCode=10000）。

    在用户蓝牙开关未开启或者手机不支持蓝牙功能的情况下，调用 uni.openBluetoothAdapter 会返回错误（errCode=10001），表示手机蓝牙功能不可用。此时APP蓝牙模块已经初始化完成，可通过 uni.onBluetoothAdapterStateChange 监听手机蓝牙状态的改变，也可以调用蓝牙模块的所有API。

    javascript

    uni.openBluetoothAdapter({
        success(res) {
            console.log(res)
        }
    })
    

  • uni.startBluetoothDevicesDiscovery(OBJECT):开始搜寻附近的蓝牙外围设备。此操作比较耗费系统资源，请在搜索并连接到设备后调用 uni.stopBluetoothDevicesDiscovery 方法停止搜索。

    javascript

    uni.startBluetoothDevicesDiscovery({
        services: [[FEE7'],
        success(res) {
            console.log(res)
        }
    })
    

  • uni.onBluetoothDeviceFound(CALLBACK):监听寻找到新设备的事件

  • uni.stopBluetoothDevicesDiscovery(OBJECT):停止搜寻附近的蓝牙外围设备。若已经找到需要的蓝牙设备并不需要继续搜索时，建议调用该接口停止蓝牙搜索。

    javascript

    uni.stopBluetoothDevicesDiscovery({
        success(res) {
            console.log(res)
        }
    })
    

  • uni.onBluetoothAdapterStateChange(CALLBACK):监听蓝牙适配器状态变化事件

  • uni.getConnectedBluetoothDevices(OBJECT):根据 uuid 获取处于已连接状态的设备。

    javascript

    uni.getConnectedBluetoothDevices({
        success(res) {
            console.log(res)
        }
    })
    

  • uni.getBluetoothDevices(OBJECT):获取在蓝牙模块生效期间所有已发现的蓝牙设备。包括已经和本机处于连接状态的设备。

    javascript

    uni.getBluetoothDevices({
        success(res) {
            console.log(res)
        }
    })
    

  • uni.getBluetoothAdapterState(OBJECT):获取本机蓝牙适配器状态。

    javascript

    uni.getBluetoothAdapterState({
        success(res) {
            console.log(res)
        }
    })
    

  • uni.closeBluetoothAdapter(OBJECT):关闭蓝牙模块。调用该方法将断开所有已建立的连接并释放系统资源。建议在使用蓝牙流程后，与 uni.openBluetoothAdapter 成对调用。

    javascript

    uni.closeBluetoothAdapter({
        success(res) {
            console.log(res)
        }
    })
    

  • uni.setBLEMTU(OBJECT):设置蓝牙最大传输单元。需在 uni.createBLEConnection调用成功后调用，mtu 设置范围 (22,512)。安卓5.1以上有效。

  • uni.writeBLECharacteristicValue(OBJECT):向低功耗蓝牙设备特征值中写入二进制数据。注意：必须设备的特征值支持 write 才可以成功调用。

    javascript

    // 向蓝牙设备发送一个0x00的16进制数据
    const buffer = new ArrayBuffer(1)
    const dataView = new DataView(buffer)
    dataView.setUint8(0, 0)
    uni.writeBLECharacteristicValue({
        // 这里的 deviceId 需要在 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取
        deviceId,
        // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
        serviceId,
        // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
        characteristicId,
        // 这里的value是ArrayBuffer类型
        value: buffer,
        success(res) {
            console.log('writeBLECharacteristicValue success', res.errMsg)
        }
    })
    

  • uni.readBLECharacteristicValue(OBJECT):读取低功耗蓝牙设备的特征值的二进制数据值。注意：必须设备的特征值支持 read 才可以成功调用。

    javascript

    // 必须在这里的回调才能获取
    uni.onBLECharacteristicValueChange(function (characteristic) {
    console.log('characteristic value comed:', characteristic)
    })
    uni.readBLECharacteristicValue({
        // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
        deviceId,
        // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
        serviceId,
        // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
        characteristicId,
        success(res) {
            console.log('readBLECharacteristicValue:', res.errCode)
        }
    })
    

  • uni.onBLEConnectionStateChange(CALLBACK):监听低功耗蓝牙连接状态的改变事件。包括开发者主动连接或断开连接，设备丢失，连接异常断开等等

  • uni.onBLECharacteristicValueChange(CALLBACK):监听低功耗蓝牙设备的特征值变化事件。必须先启用 notifyBLECharacteristicValueChange 接口才能接收到设备推送的 notification。

  • uni.notifyBLECharacteristicValueChange(OBJECT):启用低功耗蓝牙设备特征值变化时的 notify 功能，订阅特征值。注意：必须设备的特征值支持 notify 或者 indicate 才可以成功调用。 另外，必须先启用 notifyBLECharacteristicValueChange 才能监听到设备 characteristicValueChange 事件

    javascript

    uni.notifyBLECharacteristicValueChange({
        state: true, // 启用 notify 功能
        // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
        deviceId,
        // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
        serviceId,
        // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
        characteristicId,
        success(res) {
            console.log('notifyBLECharacteristicValueChange success', res.errMsg)
        }
    })
    

  • uni.getBLEDeviceServices(OBJECT):获取蓝牙设备所有服务(service)。

    javascript

    uni.getBLEDeviceServices({
        // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
        deviceId,
        success(res) {
            console.log('device services:', res.services)
        }
    })
    

  • uni.getBLEDeviceRSSI(OBJECT):获取蓝牙设备的信号强度。

  • uni.getBLEDeviceCharacteristics(OBJECT):获取蓝牙设备某个服务中所有特征值(characteristic)。

  • uni.createBLEConnection(OBJECT):连接低功耗蓝牙设备。

    若APP在之前已有搜索过某个蓝牙设备，并成功建立连接，可直接传入之前搜索获取的 deviceId 直接尝试连接该设备，无需进行搜索操作。

    javascript

    uni.createBLEConnection({
        // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
        deviceId,
        success(res) {
            console.log(res)
        }
    })
    

  • uni.closeBLEConnection(OBJECT):断开与低功耗蓝牙设备的连接。

    javascript

    uni.closeBLEConnection({
        deviceId,
        success(res) {
            console.log(res)
        }
    })
    

  • 还可以获取iBeacon、wifi、电量、NFC、设备方向、生物认证(人脸、指纹)等信息

• 键盘

  • uni.hideKeyboard():隐藏已经显示的软键盘

  • uni.onKeyboardHeightChange(CALLBACK):监听键盘高度变化

• 交互框

  • uni.showToast(OBJECT):显示消息提示框。

    javascript

    uni.showToast({
        title: '标题',
        duration: 2000
    });
    

  • uni.hideToast():隐藏消息提示框。

  • uni.showLoading(OBJECT):显示 loading 提示框, 需主动调用 uni.hideLoading 才能关闭提示框。

    javascript

    uni.showLoading({
        title: '加载中'
    });
    

  • uni.hideLoading():隐藏 loading 提示框。

  • uni.showModal(OBJECT):显示模态弹窗，类似于标准 html 的消息框：alert、confirm。

    javascript

    uni.showModal({
        title: '提示',
        content: '这是一个模态弹窗',
        success: function (res) {
            if (res.confirm) {
                console.log('用户点击确定');
            } else if (res.cancel) {
                console.log('用户点击取消');
            }
        }
    });
    

  • uni.showActionSheet(OBJECT):​显示操作菜单

    javascript

    uni.showActionSheet({
        itemList: [[A', 'B', 'C'],
        success: function (res) {
            console.log('选中了第' + (res.tapIndex + 1) + '个按钮');
        },
        fail: function (res) {
            console.log(res.errMsg);
        }
    });
    

• 导航条

  • uni.setNavigationBarTitle(OBJECT):动态设置当前页面的标题

    javascript

    uni.setNavigationBarTitle({
        title: '新的标题'
    });
    

  • uni.setNavigationBarColor(OBJECT):设置页面导航条颜色。如果需要进入页面就设置颜色，请延迟执行，防止被框架内设置颜色逻辑覆盖

    javascript

    uni.setNavigationBarColor({
        frontColor: '#ffffff',
        backgroundColor: '#ff0000',
        animation: {
            duration: 400,
            timingFunc: 'easeIn'
        }
    })
    

  • uni.showNavigationBarLoading(OBJECT):在当前页面显示导航条加载动画

  • uni.hideNavigationBarLoading(OBJECT):在当前页面隐藏导航条加载动画

  • uni.hideHomeButton(OBJECT):隐藏返回首页按钮

• tabbar

  • uni.setTabBarItem(OBJECT):动态设置 tabBar 某一项的内容

    javascript

    uni.setTabBarItem({
        index: 0,
        text: 'text',
        iconPath: '/path/to/iconPath',
        selectedIconPath: '/path/to/selectedIconPath'
    })
    

  • uni.setTabBarStyle(OBJECT):动态设置 tabBar 的整体样式

    javascript

    uni.setTabBarStyle({
        color: '#FF0000',
        selectedColor: '#00FF00',
        backgroundColor: '#0000FF',
        borderStyle: 'white'
    })
    

  • uni.hideTabBar(OBJECT)/uni.showTabBar(OBJECT):隐藏和显示tabbar

  • uni.setTabBarBadge(OBJECT):为 tabBar 某一项的右上角添加文本

    javascript

    uni.setTabBarBadge({
        index: 0,
        text: '1'
    })
    

  • uni.removeTabBarBadge(OBJECT):移除 tabBar 某一项右上角的文本

  • uni.showTabBarRedDot(OBJECT)/uni.hideTabBarRedDot(OBJECT):显示/隐藏 tabBar 某一项的右上角的红点

  • uni.onTabBarMidButtonTap(CALLBACK):监听中间按钮的点击事件

• 窗口背景

  • uni.setBackgroundColor(OBJECT):动态设置窗口的背景色

    javascript

    uni.setBackgroundColor({
        backgroundColor: '#ffffff',
        backgroundColorTop: '#222222',
        backgroundColorBottom: '#333333'
    });
    

  • uni.setBackgroundTextStyle(OBJECT):动态设置下拉背景字体、loading 图的样式

    javascript

    uni.setBackgroundTextStyle({
        textStyle: 'dark' // 下拉背景字体、loading 图的样式为dark
    })
    

• 动画:uni.createAnimation(OBJECT)

  html

  <view :animation="animationData" style="background:red;height:100rpx;width:100rpx"></view>
  <script>
  export default{
      data: {
          animationData: {}
      },
      onShow: function(){
          var animation = uni.createAnimation({
          duration: 1000,
              timingFunction: 'ease',
          })
  
          this.animation = animation
  
          animation.scale(2,2).rotate(45).step()
  
          this.animationData = animation.export()
  
          setTimeout(function() {
          animation.translate(30).step()
          this.animationData = animation.export()
          }.bind(this), 1000)
      },
      methods:{
          rotateAndScale: function () {
          // 旋转同时放大
          this.animation.rotate(45).scale(2, 2).step()
          this.animationData = this.animation.export()
          },
          rotateThenScale: function () {
          // 先旋转后放大
          this.animation.rotate(45).step()
          this.animation.scale(2, 2).step()
          this.animationData = this.animation.export()
          },
          rotateAndScaleThenTranslate: function () {
          // 先旋转同时放大，然后平移
          this.animation.rotate(45).scale(2, 2).step()
          this.animation.translate(100, 100).step({ duration: 1000 })
          this.animationData = this.animation.export()
          }
      }
  }
  </script>
  

• 滚动:uni.pageScrollTo(OBJECT)

  javascript

  uni.pageScrollTo({
      scrollTop: 0,
      duration: 300
  });
  

• 窗口

  • uni.onWindowResize(CALLBACK):监听窗口尺寸变化事件

  • uni.offWindowResize(CALLBACK):取消监听窗口尺寸变化事件

• 字体:uni.loadFontFace(Object object):动态加载网络字体，文件地址需为下载类型

  javascript

  uni.loadFontFace({
      family: 'Bitstream Vera Serif Bold',
      source: 'url("https://sungd.github.io/Pacifico.ttf")',
      success() {
          console.log('success')
      }
  })
  

• 下拉刷新

  • uni.startPullDownRefresh(OBJECT):开始下拉刷新，调用后触发下拉刷新动画，效果与用户手动下拉刷新一致。

  • uni.stopPullDownRefresh():停止当前页面下拉刷新

• 节点信息

  • uni.createSelectorQuery():返回一个 SelectorQuery 对象实例。可以在这个实例上使用 select 等方法选择节点，并使用 boundingClientRect 等方法选择需要查询的信息。

  • selectorQuery.in(component):将选择器的选取范围更改为自定义组件 component 内，返回一个 SelectorQuery 对象实例。

  • selectorQuery.select(selector):在当前页面下选择第一个匹配选择器 selector 的节点，返回一个 NodesRef 对象实例，可以用于获取节点信息。

    javascript

    const query = uni.createSelectorQuery().in(this);
    query.select('#id').boundingClientRect(data => {
        console.log("得到布局位置信息" + JSON.stringify(data));
        console.log("节点离页面顶部的距离为" + data.top);
    }).exec();
    

  • selectorQuery.selectAll(selector):在当前页面下选择匹配选择器 selector 的所有节点，返回一个 NodesRef 对象实例，可以用于获取节点信息

  • selectorQuery.selectViewport():选择显示区域，可用于获取显示区域的尺寸、滚动位置等信息，返回一个 NodesRef 对象实例

  • selectorQuery.exec(callback):执行所有的请求。请求结果按请求次序构成数组，在callback的第一个参数中返回。

  • nodesRef.fields(object,callback):获取节点的相关信息。第一个参数是节点相关信息配置（必选）；第二参数是方法的回调函数，参数是指定的相关节点信息。

  • nodesRef.boundingClientRect(callback):添加节点的布局位置的查询请求。相对于显示区域，以像素为单位。其功能类似于 DOM 的 getBoundingClientRect。返回 NodesRef 对应的 SelectorQuery。

  • nodesRef.scrollOffset(callback):添加节点的滚动位置查询请求。以像素为单位。节点必须是 scroll-view 或者 viewport。返回 NodesRef 对应的 SelectorQuery。

  • nodesRef.context(callback):添加节点的 Context 对象查询请求。支持 VideoContext、CanvasContext、和 MapContext 等的获取。

  • nodesRef.node(callback):获取 Node 节点实例。目前支持 Canvas 的获取。

    javascript

    uni.createSelectorQuery().selectViewport().scrollOffset(res => {
        console.log("竖直滚动位置" + res.scrollTop);
    }).exec();
    
    let view = uni.createSelectorQuery().in(this).select(".test");
    
    view.fields({
        size: true,
        scrollOffset: true
    }, data => {
        console.log("得到节点信息" + JSON.stringify(data));
        console.log("节点的宽为" + data.width);
    }).exec();
    
    view.boundingClientRect(data => {
        console.log("得到布局位置信息" + JSON.stringify(data));
        console.log("节点离页面顶部的距离为" + data.top);
    }).exec();
    

  • uni.createIntersectionObserver([this], [options]):创建并返回一个 IntersectionObserver 对象实例

• 延时执行:nextTick(function callback)

• 菜单:getMenuButtonBoundingClientRect():在小程序平台，如果原生导航栏被隐藏，仍然在右上角会有一个悬浮按钮，微信下也被称为胶囊按钮。本API用于获取小程序下该菜单按钮的布局位置信息，方便开发者布局顶部内容时避开该按钮。

• 页面

  • getCurrentPages():获取当前页面栈的实例，以数组形式按栈的顺序给出，第一个元素为首页，最后一个元素为当前页面

  • $getAppWebview():获取webview实例，仅app可用

  • 页面通信见页面通讯

• 文件

  • uni.saveFile(OBJECT):保存文件到本地

    javascript

    uni.chooseImage({
        success: function (res) {
            var tempFilePaths = res.tempFilePaths;
            uni.saveFile({
            tempFilePath: tempFilePaths[0],
                success: function (res) {
                    var savedFilePath = res.savedFilePath;
                }
            });
        }
    });
    

  • uni.getSavedFileList(OBJECT):获取本地已保存的文件列表

    javascript

    uni.getSavedFileList({
        success: function (res) {
            console.log(res.fileList);
        }
    });
    

  • uni.getSavedFileInfo(OBJECT):获取本地文件的文件信息。此接口只能用于获取已保存到本地的文件。

    javascript

    uni.getSavedFileInfo({
        filePath: 'unifile://somefile', //仅做示例用，非真正的文件路径
        success: function (res) {
            console.log(res.size);
            console.log(res.createTime);
        }
    });
    

  • uni.removeSavedFile(OBJECT):删除本地存储的文件

    javascript

    uni.getSavedFileList({
        success: function (res) {
            if (res.fileList.length > 0) {
                uni.removeSavedFile({
                    filePath: res.fileList[0].filePath,
                    complete: function (res) {
                        console.log(res);
                    }
                });
            }
        }
    });
    

  • uni.getFileInfo(OBJECT):获取文件信息

  • uni.openDocument(OBJECT):新开页面打开文档，支持格式：doc, xls, ppt, pdf, docx, xlsx, pptx。

    javascript

    uni.downloadFile({
        url: 'https://example.com/somefile.pdf',
        success: function (res) {
            var filePath = res.tempFilePath;
            uni.openDocument({
                filePath: filePath,
                success: function (res) {
                    console.log('打开文档成功');
                }
            });
        }
    });
    

• 绘画

  • uni.createOffscreenCanvas():创建离屏 canvas 实例

  • uni.createCanvasContext(canvasId, this):创建 canvas 绘图上下文（指定 canvasId）。在自定义组件下，第二个参数传入组件实例this，以操作组件内 <canvas/> 组件

  • uni.canvasToTempFilePath(object, component):把当前画布指定区域的内容导出生成指定大小的图片，并返回文件路径。在自定义组件下，第二个参数传入自定义组件实例，以操作组件内 <canvas> 组件。

    javascript

    uni.canvasToTempFilePath({
        x: 100,
        y: 200,
        width: 50,
        height: 50,
        destWidth: 100,
        destHeight: 100,
        canvasId: 'myCanvas',
        success: function(res) {
            // 在H5平台下，tempFilePath 为 base64
            console.log(res.tempFilePath)
        } 
    })
    

  • uni.canvasPutImageData(OBJECT,this):将像素数据绘制到画布的方法

    javascript

    const data = new Uint8ClampedArray([255, 0, 0, 255])
    uni.canvasPutImageData({
        canvasId: 'myCanvas',
        x: 0,
        y: 0,
        width: 1,
        data: data,
        success(res) {}
    })
    

  • uni.canvasGetImageData(OBJECT,this):返回一个数组，用来描述 canvas 区域隐含的像素数据

    javascript

    uni.canvasGetImageData({
        canvasId: 'myCanvas',
        x: 0,
        y: 0,
        width: 100,
        height: 100,
        success(res) {
            console.log(res.width) // 100
            console.log(res.height) // 100
            console.log(res.data instanceof Uint8ClampedArray) // true
            console.log(res.data.length) // 100 * 100 * 4
        }
    })
    

  • CanvasGradient.addColorStop(stop,color):创建一个颜色的渐变点

  • CanvasContext等canvas api与html类似，可参考文档

• 获取供应商:uni.getProvider(OBJECT)

  javascript

  uni.getProvider({
      service: 'oauth',
      success: function (res) {
          console.log(res.provider)
          if (~res.provider.indexOf('qq')) {
              uni.login({
                  provider: 'qq',
                  success: function (loginRes) {
                      console.log(JSON.stringify(loginRes));
                  }
              });
          }
      }
  });
  

• 登录

  • uni.login(OBJECT):登录

  • uni.checkSession(OBJECT):检查登录状态是否过期

  • uni.getUserInfo(OBJECT):获取用户信息

    javascript

    uni.login({
        provider: 'weixin',
        success: function (loginRes) {
            console.log(loginRes.authResult);
            // 获取用户信息
            uni.getUserInfo({
                provider: 'weixin',
                success: function (infoRes) {
                    console.log('用户昵称为：' + infoRes.userInfo.nickName);
                }
            });
        }
    });
    

• 分享

  • uni.share(OBJECT):分享

    分享到微信聊天界面

    分享文字

    javascript

    uni.share({
        provider: "weixin",
        scene: "WXSceneSession",
        type: 1,
        summary: "我正在使用HBuilderX开发uni-app，赶紧跟我一起来体验！",
        success: function (res) {
            console.log("success:" + JSON.stringify(res));
        },
        fail: function (err) {
            console.log("fail:" + JSON.stringify(err));
        }
    });
    

    分享图片

    javascript

    uni.share({
        provider: "weixin",
        scene: "WXSceneSession",
        type: 2,
        imageUrl: "https://img-cdn-qiniu.dcloud.net.cn/uniapp/images/[email protected]",
        success: function (res) {
            console.log("success:" + JSON.stringify(res));
        },
        fail: function (err) {
            console.log("fail:" + JSON.stringify(err));
        }
    });
    

    分享图文

    javascript

    uni.share({
        provider: "weixin",
        scene: "WXSceneSession",
        type: 0,
        href: "http://uniapp.dcloud.io/",
        title: "uni-app分享",
        summary: "我正在使用HBuilderX开发uni-app，赶紧跟我一起来体验！",
        imageUrl: "https://img-cdn-qiniu.dcloud.net.cn/uniapp/images/[email protected]",
        success: function (res) {
            console.log("success:" + JSON.stringify(res));
        },
        fail: function (err) {
            console.log("fail:" + JSON.stringify(err));
        }
    });
    

    分享到微信朋友圈

    分享文字

    javascript

    uni.share({
        provider: "weixin",
        scene: "WXSenceTimeline",
        type: 1,
        summary: "我正在使用HBuilderX开发uni-app，赶紧跟我一起来体验！",
        success: function (res) {
            console.log("success:" + JSON.stringify(res));
        },
        fail: function (err) {
            console.log("fail:" + JSON.stringify(err));
        }
    });
    

    分享图片

    javascript

    uni.share({
        provider: "weixin",
        scene: "WXSenceTimeline",
        type: 2,
        imageUrl: "https://img-cdn-qiniu.dcloud.net.cn/uniapp/images/[email protected]",
        success: function (res) {
            console.log("success:" + JSON.stringify(res));
        },
        fail: function (err) {
            console.log("fail:" + JSON.stringify(err));
        }
    });
    

    分享图文

    javascript

    uni.share({
        provider: "weixin",
        scene: "WXSenceTimeline",
        type: 0,
        href: "http://uniapp.dcloud.io/",
        title: "uni-app分享",
        summary: "我正在使用HBuilderX开发uni-app，赶紧跟我一起来体验！",
        imageUrl: "https://img-cdn-qiniu.dcloud.net.cn/uniapp/images/[email protected]",
        success: function (res) {
            console.log("success:" + JSON.stringify(res));
        },
        fail: function (err) {
            console.log("fail:" + JSON.stringify(err));
        }
    });
    

    App分享为微信小程序

    javascript

    uni.share({
        provider: 'weixin',
        scene: "WXSceneSession",
        type: 5,
        imageUrl: 'https://img-cdn-qiniu.dcloud.net.cn/uniapp/app/[email protected]',
        title: '欢迎体验uniapp',
        miniProgram: {
            id: 'gh_abcdefg',
            path: 'pages/index/index',
            type: 0,
            webUrl: 'http://uniapp.dcloud.io'
        },
        success: ret => {
            console.log(JSON.stringify(ret));
        }
    });
    

  • plus.share.sendWithSystem(msg, successCB, errorCB):App端可调用手机的系统分享，实现所有注册分享的应用的呼起，比如短信、邮件、蓝牙(仅Android)、隔空投送(仅iOS)，或其他注册系统分享的应用，比如钉钉。仅app可用

    javascript

    plus.share.sendWithSystem({content:'分享内容',href:'https://www.dcloud.io/'}, function(){
        console.log('分享成功');
    }, function(e){
        console.log('分享失败：'+JSON.stringify(e));
    });
    

  • onShareAppMessage(OBJECT):小程序中用户点击分享后，在 js 中定义 onShareAppMessage 处理函数（和 onLoad 等生命周期函数同级），设置该页面的分享信息。

    javascript

    onShareAppMessage(res) {
        if (res.from === 'button') {// 来自页面内分享按钮
            console.log(res.target)
        }
        return {
            title: '自定义分享标题',
            path: '/pages/test/test?id=123'
        }
    }
    

  • uni.showShareMenu(OBJECT)/hideShareMenu(OBJECT):小程序的原生菜单中显示/隐藏分享按钮

• 支付:uni.requestPayment(OBJECT)

  统一各平台的客户端支付API，不管是在某家小程序还是在App中，客户端均使用本API调用支付

  App 支付

  javascript

  uni.requestPayment({
      provider: 'alipay',
      orderInfo: 'orderInfo', //微信、支付宝订单数据
      success: function (res) {
          console.log('success:' + JSON.stringify(res));
      },
      fail: function (err) {
          console.log('fail:' + JSON.stringify(err));
      }
  });
  

  微信小程序支付

  javascript

  uni.requestPayment({
      provider: 'wxpay',
      timeStamp: String(Date.now()),
      nonceStr: 'A1B2C3D4E5',
      package: 'prepay_id=wx20180101abcdefg',
      signType: 'MD5',
      paySign: '',
      success: function (res) {
          console.log('success:' + JSON.stringify(res));
      },
      fail: function (err) {
          console.log('fail:' + JSON.stringify(err));
      }
  });
  

  苹果应用内支付

  javascript

  uni.requestPayment({
      provider: 'appleiap',
      orderInfo: {
          productid: productId
      },
      success: (e) => {
          uni.showModal({
              content: "感谢您的赞助",
              showCancel: false
          })
      },
      fail: (e) => {
          uni.showModal({
              content: "支付失败,原因为: " + e.errMsg,
              showCancel: false
          })
      },
      complete: () => {
          console.log("payment结束")
          this.loading = false;
      }
  })
  

• 授权:uni.authorize(OBJECT)

  提前向用户发起授权请求。调用后会立刻弹窗询问用户是否同意授权小程序使用某项功能或获取用户的某些数据，但不会实际调用对应接口。如果用户之前已经同意授权，则不会出现弹窗，直接返回成功。如果用户之前拒绝了授权，此接口会直接进入失败回调，一般搭配uni.getSetting和uni.openSetting使用

  请求授权:用户信息、地理位置、通信录、录音等

  • uni.openSetting(OBJECT):调起客户端小程序设置界面，返回用户设置的操作结果。

    javascript

    uni.openSetting({
        success(res) {
            console.log(res.authSetting)
        }
    });
    

  • uni.getSetting(OBJECT):获取用户的当前设置

    javascript

    uni.getSetting({
        success(res) {
            console.log(res.authSetting)
        }
    })
    

• 收货地址:uni.chooseAddress(OBJECT):获取用户收货地址。调起用户编辑收货地址原生界面，并在编辑完成后返回用户选择的地址，需要用户授权 scope.address。

  javascript

  uni.chooseAddress({
      success(res) {
          console.log(res.userName)
          console.log(res.postalCode)
          console.log(res.provinceName)
          console.log(res.cityName)
          console.log(res.countyName)
          console.log(res.detailInfo)
          console.log(res.nationalCode)
          console.log(res.telNumber)
      }
  })
  

• 发票抬头:uni.chooseInvoiceTitle(OBJECT):选择用户的发票抬头，需要用户授权 scope.invoiceTitle。

  javascript

  uni.chooseInvoiceTitle({
      success(res) {
          console.log(res.type);
          console.log(res.title);
          console.log(res.taxNumber);
          console.log(res.companyAddress);
          console.log(res.telephone);
          console.log(res.bankName);
          console.log(res.bankAccount);
      }
  })
  

• 小程序跳转

  • uni.navigateToMiniProgram(OBJECT):打开另一个小程序

    javascript

    uni.navigateToMiniProgram({
        appId: '',
        path: 'pages/index/index?id=123',
        extraData: {
            'data1': 'test'
        },
        success(res) {
            // 打开成功
        }
    })
    

  • uni.navigateBackMiniProgram(OBJECT):跳转回上一个小程序，只有当另一个小程序跳转到当前小程序时才会能调用成功。

    javascript

    uni.navigateBackMiniProgram({
        extraData: {
            'data1': 'test'
        },
        success(res) {
            // 返回成功
        }
    })
    

• 账号信息:uni.getAccountInfoSync()

  javascript

  const accountInfo = uni.getAccountInfoSync();
  console.log(accountInfo.miniProgram.appId); // 小程序 appId
  console.log(accountInfo.plugin.appId); // 插件 appId
  console.log(accountInfo.plugin.version); // 插件版本号， 'a.b.c' 这样的形式