璎耜

外观

速记 ​

注意：
若内容和实际不符，有可能是文档过时了
注意：
若内容和实际不符，有可能是文档过时了
最新内容还是得看官方文档

开发时，若预期效果和展现效果不一致，应该查看开发文档，毕竟uniapp语法有时和正常vue语法不一致。

对于需要实现的功能，优先插件市场搜索

基础速记 ​

  • uniapp中使用js在不同版本、不同平台可能展示的效果不一样，有可能无法生效，遇到此种情况时应该查看官方文档或者搜索引擎
  • 组件上的属性规范：
    • :disabled="false"：这里引号包裹的是js表达式
    • hover-start-time=20：这里20未被引号包裹，属于number
  • 不推荐使用html标签，而是使用特定的基础组件+扩展组件（需导入）
  • easycom规范：组件位于/components|uni_modules/com-name/com-name.vue时，就可直接在tempalte中使用

环境 ​

注意事项 ​

  • 使用vue3/vite开发时，node版本需要使用^14.18.0 || >=16.0.0
  • cli创建的项目是传统node项目结构，代码在src目录，编译器在项目目录下（非常占据磁盘内存，升级麻烦，兼容问题多），编译结果在dist目录；
  • hbuilderx创建的项目，代码在项目目录下，编译器在hbuilderx目录下，编译结果在项目的unpackage目录下。
  • cli创建的项目：
    • 内置了d.ts，在支持该语法的开发工具中有语法提示
    • 需手动升级编译器版本，拖入到hbuilderx开发时，不会跟随hbuilderx升级
    • 拖入到hbuilderx开发时，整个项目拖入则使用项目下编译器，src目录拖入使用hbuilderx安装目录下plugin目录下的编译器
    • 可使用npm
    • 开发app时，仍然需要在hbuilderx运行，然后在其他编译器中修改
  • hbuilderx创建的项目的好处：
    • 能够让ide版本、编译器版本、uniapp运行时版本保持一致；
    • 自动安装less、scss、ts；
    • 不带d.ts，因为hbuilderx内置了uniapp语法提示库，若想将其在其他编译器中打开，需要先执行npm init，然后npm i @dcloudio/types -D补充d.ts
    • 可使用npm
  • 在hbuilderx(❤️.6.7)运行vue3/vite创建的cli工程项目时，需要在hbuilder设置中设置上述版本的node路径
  • 使用@dcloudio/uvm自动更新uniapp编译器的主要依赖，使用npx @dcloudio/uvm@latest更新到最新正式版，npx @dcloudio/uvm@latest 3.2.0更新到指定版本
  • 打包时，使用npm run build:xx会在/dist/build/xx下生成对应的打包资源
  • dev和build的区别：dev模式有sourcemap可进行断点调试，process.env.NODE_ENV值为development；build会将代码进行压缩体积更小，同时NODE_ENV值为production
  • 跨端注意事项：https://uniapp.dcloud.net.cn/matter.html

can i use ​

定义：判断应用的api、回调、参数、组件等是否在当前版本可用

语法：

javascript
// 名字.调用方式.参数/返回值.参选可选值，在app、web端不支持
uni.canIUse(${API}.${method}.${param}.${options})
// app、web端只支持
uni.canIUse(${API})

// 组件名.组件属性.组件属性可选值
uni.canIUse(${component}.${attribute}.${option})

编译及条件编译 ​

条件编译：

  • 注释内容基本都是#ifdef %platform%，#ifndef %platform%（除该平台之外）开始，尾部注释是#endif结束。不同语言对应的注释写法不一样，比如js/json/uts使用//，css使用/* */，vue/nvue/uvue组件使用<!-- -->
  • platform：VUE3、UNI-APP-X、uniVersion、APP、APP-PLUS、APP-PLUS-NVUE、APP-NVUE、APP-ANDROID、APP-IOS、H5、WEB、MP（小程序）、MP-WEIXIN、MP-QQ、MP-TOUTIAO等
  • 使用||支持多平台编译，比如#ifdef plat1 || plat2
bash
<!-- #ifdef %PLATFORM% -->
此处写内容
<!-- #endif -->

注意：

  • 保证条件编译前和编译后文件都应当能够通过语法校验
  • ios和Android不支持通过条件编译来区分，需要调用uni.getSystemInfo获取平台信息

全局文件 ​

pages.json ​

作用：应用的全局配置文件，用于配置页面文件路径pages、窗口样式globalStyle、导航栏globalStyle、tabbar等。类似微信小程序app.json的页面管理

注意：

  • topWindow、leftWindow、rightWindow属性用于适配宽屏的（上、左、右栏）

manifest.json ​

作用：应用的配置文件，用于指定应用的名称、图标、权限

App.vue/App.uvue ​

作用：

  • 作为应用的入口文件，所有页面都是在该组件下进行切换的；
  • 本身不是页面，不能编写视图元素，没有<template>标签，有<script>标签
  • 是监听应用的生命周期的唯一方式（不能在页面中监听）、配置全局样式、配置全局的存储globalData

main.js/uts ​

作用：

  • 作为应用的入口文件，用于初始化vue示例
  • 定义全局组件（一般情况下，easycom更常用且节省资源）
  • 使用插件，例如vuex、i18n

注意：

  • 谨慎在main.js、组件/页面的export default外部、onLaunch中编写代码，会影响启动速度；执行太早以至于很多功能和api无法使用；在应用存活时一直占据内存，不会随着页面关闭而回收

uni.scss ​

作用：

  • 全局可用，无需导入即可在scss代码中使用该文件中的样式变量
  • 为了整体控制应用的风格，比如按钮颜色、边框等

宽屏适配方案 ​

方案：

  • 页面窗体级：使用pages.json下的direction-Window属性，适用于独立的页面
  • 组件级：match-media组件，媒体查询组件，用于动态屏幕适配，在屏幕宽度满足查询条件时，显示对应组件

资源引入 ​

js文件引入 ​

  • 不支持使用/开头的方式引入
typescript
import add from '@/common/add.js';
import add from '../../common/add.js';

静态资源引入 ​

  • 默认情况下根目录下的static为静态资源文件夹，存放此处的资源，可在任意文件中直接引入
  • 非static目录的静态资源，需要使用import引入后使用
  • @开头的路径会经过base64校验
  • web平台，小于4kb的会转为base64
  • 支付宝小程序组件image不能使用相对路径
vue
<template>
  <view>
    <!-- /static或@/static：根目录下的static目录，cli项目为src下的static -->
    <image class="logo" src="/static/logo.png"></image>
    <image class="logo" src="@/static/logo.png"></image>
    <image class="logo" src="../../static/logo.png"></image>

    <!-- 引入非static下文件：需要使用import导入来引入 -->
    <image :src="src"/>
  </view>
</template>

<script>
// 引入非static下文件：需要使用import导入来引入
import icon_src from './icon.png'
export default {
  data () {
    return {
      src: icon_src
    }
  }
}
</script>

<style>
/* 注意有些小程序css不允许引用本地文件 */
/* v2.6.6+开始支持绝对路径引入 */
/* 样式导入，使用;分号结束 */
@import url('/common/uni.css');
@import url('@/common/uni.css');
@import url('../../common/uni.css');

/* 背景图片 */
.test {
  /* 本地背景图片推荐使用~@开头的绝对路径 */
  background-image: url('~@/static/logo.png');
}
</style>

js语法 ​

uni-app js API = 标准ecmascript + uni扩展API

android不支持的js语法：

  • array.values
  • Proxy(android <= 5)

css语法 ​

尺寸单位 ​

  • px：屏幕像素
  • rpx：响应式的px，以750宽的屏幕为基准，即750rpx等于屏幕宽度，rpx效果随宽度等比缩放。当app和h5端屏幕大于960px，将按照375px的屏幕宽度进行计算，可在pages.json的rpxCalcBaseDeviceWidth进行修改
  • rem、vh/vw、%：在nvue中不支持
  • 设计稿 1px / 设计稿基准宽度 = 框架样式 1rpx / 750rpx，故元素的rpx值 = 750 * 元素在设计稿的宽度 / 设计稿基准宽度
  • 若在字体大小和元素高度中也使用了rpx，需要注意会随着宽度等比缩放，故而想固定高度应使用px
  • rpx不支持动态横竖屏切换计算，故使用时应锁定屏幕方向
  • 若设计稿宽度非750px，可在setting.json中的【编辑器设置】-启用【px转upx提示】，则在代码编写时，会给出相关的提示

选择器 ​

支持的选择器有：

  • .class
  • #id
  • element
  • element, element
  • ::after，仅vue页面生效
  • ::before，仅vue页面生效

注意：

  • 微信小程序自定义组件仅支持class选择器
  • 设置body节点样式时，应该使用page {}的语法
  • App.vue中通过@import导入的样式，可作用于全部页面
  • nvue不支持全局样式，但可使用uni.css中样式

固定值 ​

NavigationBar（44px）、TabBar组件（50px）的高度是固定的，不可修改

字体图标 ​

注意：

  • 图标格式支持base64、网络路径（仅https）
  • 小程序不支持在css中使用本地文件（背景图、字体），需以base64形式使用
  • 字体文件引入路径推荐使用~@开头的绝对路径
  • nvue引入字体文件，需通过addRule进行引入，详见nvue开发文档

vue语法 ​

注意：

  • data数据在methods中的某些方法中引入时，可能该方法的this指向到其他内容了，故而需要将this赋值给另一个变量（const that = this），再去调用data的数据（that.xxx）
  • 组件的key发生变化，会导致组件重渲染
  • 事件使用@绑定（非bind和catch），不能在js中使用preventDefault和stopPropagation方法（使用修饰符.prevent、.stop代替）

v-for ​

vue
<template>
  <!-- 使用数组 -->
  <view v-for="(item, index) in items">
    {{ index }} - {{ item.message }}
  </view>

  <!-- 使用对象 -->
  <view v-for="(value, name, index) in object">
    {{ index }}. {{ name }}: {{ value }}
  </view>
</template>

组件 ​

注意：

  • 通过uniapp的easycom（自动开启的，可在pages.json中设置），只需要组件符合components/组件名/组件名.vue的形式，就可以不需引入注册，直接在页面中使用
  • uniapp内置了Vuex，使用方法如vue
  • 小程序不支持：
    • 作用域插槽
    • 动态组件
    • 异步组件
    • inline-template
    • X-Templates
    • keep-alive（app也未支持）
    • transition(使用animation或css动画代替)

API ​

不支持的全局API：

  • 小程序：Vue.extend、Vue.nextTick（this.$nextTick还是支持的）、Vue.directive
  • app：Vue.nextTick（this.$nextTick还是支持的）

不支持的选项：

  • 小程序：el、template、render、renderError、directives、delimiters、functional、model、inheritAttrs、comments
  • app：el、template、render、renderError、delimiters、functional、comments

不支持的声明周期：

  • 小程序：activated、deactivated

不支持的组件实例属性和方法：

  • 小程序：$el、$isServer、$attrs、$listeners、$mount()、is（用于动态组件的）
  • app：$el、$mount()

不支持的模板指令：

  • 小程序：v-html、v-pre、v-cloak、v-once
  • app：v-cloak

不支持的内置组件：

  • 小程序：component、transition、transition-group、keep-alive
  • app：transition、transition-group、keep-alive

路由 ​

  • 页面跳转有层级限制，不能无限制跳转
  • 跳转到tabBar只能使用uni.switchTab
  • 跳转目标必须是注册到pages.json的页面，网络路径可使用plus.runtime.openURL（app端）、window.open（h5）
  • eventChannel支持页面间事件通信
js
// pages/current.vue
// 1️⃣保留当前页面，跳到指定页面，可使用navigateBack返回
uni.navigateTo({
  url: '/pages/next',
  // app窗口显示的动画效果
  animationType: 'pop-in',
  // 页面间通信接口，用于监听被打开页面发送到当前页面的数据
  events: {
    // 获取url页面传送到当前页面的数据
    sendToPre: function (data) {
      console.log(data)
    }
  },
  success: function (res) {
    // 通过eventChannel发送数据给url页面
    res.eventChannel.emit('sendToNext', { data: 'aaa' })
  }
})

// pages/next.
onLoad: function (option) {
  // vue2
  const eventChannel = this.getOpenerEventChannel()

  // vue3
  import { getCurrentInstance } from 'vue'
  const instance = getCurrentInstance().proxy
  const eventChannel = instance.getOpenerEventChannel()

  // 发送数据到current.vue
  eventChannel.emit('sendToPre', { data: 'bbb' })

  // 获取current.vue传过来的数据
  eventChannel.on('sendToNext', function (data) {
    console.log(data)
  })
}

// 2️⃣：关闭当前页面，返回前面的页面
uni.navigateBack({
  // 返回的页面数
  delta: 1,
  animationType: 'pop-out',
  success_fail_complete(){}
)}
  

// 3️⃣：关闭当前页面，跳到新页面
uni.redirectTo({
  url: '',
  success_fail_complete() {}
})

// 4️⃣：关闭所有打开的页面，跳到新页面，如果调用了uni.preloadPage则不会关闭，仅仅是触发onHide
uni.reLaunch({
  url: '',
  success_fail_complete(){}
})

// 5️⃣：关闭所有非tabBar页面，跳转到tabBar页面，如果调用了uni.preloadPage则不会关闭，仅仅是触发onHide
uni.switchTab({
  url: '',
  success_fail_complete() {}
})

组件注意事项 ​

uni-ui ​

  • 非uni-ui模板项目，需要去插件市场手动将uni ui组件下载到工程中，才能使用相关的ui组件
  • uni-ui组件常用代码封装成了以u开头的user snippets，在hbuilder中在template标签内，直接输入例如ulist就会快速生成对应的ui组件模板；同时在js代码块中直接输入例如uRequest也会生成相应的uni api代码块，提升开发效率

内置组件 ​

  • 视图
  • view
  • scroll-view：
    • 避免使用map、video等原生组件
    • 长列表、下拉刷新性能原因使用其他组件
  • swiper、swiper-item：滑块（轮播图）
  • match-media：类似媒体查询，在满足条件时展示内部内容
  • movable-area、movable-view：可拖拽区块
  • cover-view：主要用于展示覆盖在原生组件（如map、video、canvas等，层级高于内置组件）上的文本内容
  • cover-image：主要用于覆盖在原生组件上的图片内容
  • 文本
    • icon
    • text
    • rich-text：富文本（主要是dom树、html字符串）展示组件
    • progress：进度条
  • 表单
  • button
  • checkbox
  • radio
  • input
  • textarea
  • editor：富文本编辑器
  • label
  • picker：选择器
  • picker-view、picker-view-column：更灵活的选择器，嵌入页面的滚动选择器
  • slider：滑块
  • switch：开关
  • form：表单容器
  • 路由、页面跳转
  • navigator
  • 媒体
  • animation-view：动画组件
  • audio
  • video
  • camera
  • image
  • live-player：实时音视频播放（直播拉流）
  • live-pusher：实时音视频录制（直播推流）
  • 地图：
  • map
  • 画布：
  • canvas
  • webview：
  • web-view：web浏览器组件，用于装载网页
  • 广告
  • unicloud-db云数据库
  • 页面配置节点组件
  • page-meta：页面属性配置组件
  • navigation-bar：页面导航条配置组件
  • custom-tab-bar：自定义tabbar组件

vue组件 ​

  • 全平台支持：template、slot
  • h5支持：component、transition、transition-group、keep-alive

nvue专有组件 ​

  • barcode：扫码
  • list：高性能的列表组件
  • recycle-list：具备回收复用的列表容器
  • waterfall：提供瀑布流布局的核心组件
  • cell：作为list、recycler、waterfall的子组件
  • refresh：为容器提供下拉刷新功能，作为list、scroll-view、waterfall的子组件

小程序组件 ​

  • official-account：微信公众号关注组件
  • open-data：展示平台提供的开放数据

扩展组件库 ​

  • 全端组件：uni-ui、color ui、thorui、graceui、uviewui
  • only web：element、iview
  • 小程序自定义组件：vant weapp、iview weapp

小程序自定义组件 ​

定义：

  • 小程序组件不是vue组件
  • 每家小程序都有自己的组件规范
  • 小程序组件不是全端可用的
  • 代码存放目录在各自的目录中，比如App/微信在wxcomponents，其他的类同

使用：在pages.json中需要使用小程序自定义组件的页面的style->usingComponents中引入组件（可使用条件选择环境），然后就能在该页面使用了

注意：

  • 小程序组件的性能不如vue组件，需要手动setData
  • 使用数据和事件绑定时，应遵循vue的语法规范，即属性前添加:，方法使用@

uniapp内的wxs语法规范 ​

使用：

vue
<!-- 其他家小程序，lang可改为filter、sjs等 -->
<script module="utils" lang="wxs" src="./utils.wxs">

// 内联语法，即将src删除，代码写在这里
</script>

注意：

  • module指定的模块名，不可和data、methods、computed内的属性重名
  • 在vue3中不支持setup script
  • nvue不支持wxs等语法

datacom数据驱动组件 ​

datacom：data components，属于vue组件，是二次封装组件

特点：给它绑定一个data，即可渲染出预定的结果

缺陷：

  • 不够灵活，即不能个性化定制，覆盖场景不够广泛

规范：

  • 以组件库名称-data-组件功能表达命名
  • 通过属性赋值，绑定一个data，data是json格式数据（数组、树）
  • 符合uni-forms组件的表单校验规范

常用api ​

web api 和JavaScript api的区别 ​

定义：JavaScript = ECMAScript(js语言规范) + Web APIs

常见的web api：

  • 操作文档的api：DOM（document）、BOM（window）
  • 从服务器获取数据的api：XMLHttpRequest、Fetch
  • 绘制和操作图形的api：canvas、webgl
  • 音视频api：webrtc
  • 设备api：地理定位api、系统通知api、震动硬件api
  • 存储api：storage、indexeddb

uni.canIUse判定api/回调/组件/参数是否可用 ​

js
// app、web仅支持${API}的方式
uni.canIUse('${API}.${method}.${param}.${options}')
uni.canIUse('${component}.${attribute}.${option}')

uni.request发起网络请求 ​

js
// 小程序需要配置域名白名单
uni.request({
  url: '',
  // 请求参数：object、string、arrayBuffer
  data: {},
  header: {},
  method: 'GET',
  timeout: 60000,
  // 响应数据类型：text、arraybuffer
  responseType: 'arraybuffer',
  // ssl证书验证
  sslVerify: true,
  // 跨域请求是否携带凭证
  withCredentials: true,
  // 请求成功、失败、结束时调用
  success_fail_complete() {},
  // others...
})

文件上传下载 ​

  • 微信小程序仅仅支持单文件上传，故而传递多文件，需要循环调用该api
  • 其他上传，可使用插件市场的插件
  • 超时时间可在manifest.json中的networkTimeout配置
js
// 可通过task对象监听上传进度变化事件，及取消上传，此时至少需要传入success/fail/complete属性
const uploadTask = uni.uploadFile({
  url: '',
  // files和filePath二选一，需要上传的文件列表，使用files时，filePath和name不生效
  // 仅app、h5
  files: [],
  // 仅支付宝支持
  fileType: 'image/video/audio',
  // 文件对象，仅h5支持
  file: File,
  // 文件资源路径
  filePath: '',
  // 文件的key，服务器通过该key获取文件二进制内容
  name: '',
  header: {},
  timeout: 60000,
  // 其他数据
  formData: {},
  success_fail_complete() {}
})

// 中止上传
uploadTask.abort()
// 监听上传进度
uploadTask.onProgressUpdate(callback)

// task可监听下载进度变化、取消下载
const downloadTask = uni.downloadFile({
  url: '',
  header: {},
  timeout: 10000,
  // 下载后存储的临时路径，持久保存使用uni.saveFile（下次启动能访问的）
  filePath: '',
  success_fail_complete(){}
})

// 中止下载
downloadTask.abort()
// 监听下载进度
downloadTask.onProgressUpdate(callback)

系统相关 ​

获取系统信息 ​

js
// 该接口可获取device、os、rom、host、uni、app、屏幕窗口等的信息
uni.getSystemInfo({
  //成功获取的回调函数，返回值为系统信息
  success: (sysinfo) => {
    height = sysinfo.windowHeight;
  },
  complete: () => {}
});

const sysInfo = uni.getSystemInfoSync()

// 获取设备信息：仅app、h5、微信支持
uni.getDeviceInfo({})

// 获取窗口信息：仅app、h5、微信支持
uni.getWindowInfo({})

// 获取app基础信息：仅app、h5、微信支持
uni.getAppBaseInfo({})

// 获取设备的设置信息，比如蓝牙开关、地理位置开关、wifi开关、设备方向：仅app、微信
uni.getSystemSetting({})

// 跳转系统对应用的授权管理页面：仅app、微信
uni.openAppAuthorizeSetting({})

// 创建一个监听权限申请的对象
let permissionListener = uni.createRequestPermissionListener()
permissionListener.onConfirm(e => {
  // 权限申请确认做的操作
})
permissionListener.onComplete(e => {
  // 权限申请完成做的操作
})

function startRequestAuth () {
  // 申请读取日历的权限
  plus.android.requestPermissions(["android.permission.READ_CALENDAR"]， e => {

  }, e => {

  })
}

内存 ​

js
// 监听内存不足告警事件：不支持h5、抖音飞书，该api需下载插件
uni.onMemoryWarning(function (res) {})

// 取消监听：不支持app、h5、抖音飞书、qq
uni.offMemoryWarning(function (res) {})

网络状态 ​

js
// 获取网络类型
uni.getNetworkType({})

// 监听网络状态变化
uni.onNetworkStatusChange(function (res) {})

// 取消监听网络状态变化：仅支持app、h5、微信、快手
uni.offNetworkStatusChange(function (res) {})

系统主题 ​

js
// 监听系统主题状态变化：dark，light
uni.onThemeChange(function (res) {})

// 取消监听系统主题状态变化：app、h5、微信、飞书支持
uni.onThemeChange(function (res) {})

拨打电话 ​

js
// 拨打电话：app需要在manifest中添加权限
uni.makePhoneCall({
  phoneNumber； '',
  s_f_c(){}
})

扫码 ​

js
// 调起客户端扫码界面
uni.scanCode({
  // 扫码源：相机、相册
  onlyFromCamera: false,
  scanType: [''],
  // ......
})

剪切板 ​

js
// 设置系统剪切板内容
uni.setClipboardData({
  data: '',
  // 是否弹窗提示
  showToast: true,
  s_f_c(){}
})

// 获取剪切板内容
uni.getClipboardData({})

屏幕亮度 ​

js
// 设置屏幕亮度：不支持h5
// 避免在onShow使用，不然会一直触发
uni.setScreenBrightness({
  value: 0.5,
  s_f_c(){}
})

// 获取屏幕亮度：不支持h5
uni.getScreenBrightness({})

// 设置屏幕保持常亮，仅在当前应用生效，离开应用失效，不支持h5
uni.setKeepScreenOn({
  keepScreenOn: true
})

截屏 ​

js
// 监听用户主动截屏事件，使用系统截屏按键截屏时触发，不支持h5
uni.onUserCaptureScreen(function (path) {
  // 截屏文件路径
})

// 取消监听用户主动截屏事件，使用系统截屏按键截屏时触发，不支持h5、qq
uni.offUserCaptureScreen(function (res) {})

// 开启关闭防截屏，仅支持app
// 安卓某些页面（图片选择、图片预览、一键登录、原生插件内部等页面）不支持
uni.setUserCaptureScreen({
  // 是否允许截屏
  enable: true
})

振动 ​

js
// 使手机发生振动
uni.vibrate({})

// 使手机长时间发生振动（400ms）
uni.vibrateLong({})

// 使手机短时间振动（15ms）
uni.vibrateShort({})

手机联系人 ​

js
// 添加联系人：h5、抖音飞书、qq、京东不支持
uni.addPhoneContact({
  firstName: '',
  remark: '',
  mobilePhoneNumber: '',
  // ...
})

蓝牙 ​

js
// 初始化蓝牙模块，其他api必须在这之后调用，未开启蓝牙会报错
uni.openBluetoothAdapter({})

// 开始搜寻附近的蓝牙设备，比较耗费系统资源
// 应该在搜索并连接到设备后，调用停止搜寻方法停止搜索
// app仅支持ble蓝牙，其他设置参考插件市场
uni.startBluetoothDevicesDiscovery({
  // ...
})

// 停止搜索
uni.stopBluetoothDevicesDiscovery({
  // ...
})

// 监听寻找到的新设备事件
uni.onBluetoothDeviceFound(function (devices) {})

// 监听蓝牙适配器状态变化事件
uni.onBluetoothAdapterStateChange(function(res) {})

// 根据uuid获取处于已连接状态的设备
uni.getConnectedBluetoothDevices({
  services: ['uuid1']
})

// 获取在蓝牙模块生效期间所有发现的蓝牙设备，包括已连接的
uni.getBluetoothDevices({})

// 获取本机蓝牙适配器状态
uni.getBluetoothAdapterState({})

// 关闭蓝牙模块，断开连接释放系统资源，在使用蓝牙流程后和uni.openBluetoothAdapter成对调用
uni.closeBluetoothAdapter({})

Wi-Fi ​

https://ext.dcloud.net.cn/plugin?id=10337

js
uni.startWifi({})
uni.stopWifi({})
uni.getWifiList({})
uni.getConnectedWifi({
  // 是否返回部分wifi信息
  partialInfo: true
})
uni.connectWifi({
  // wifi设备ssid，
  SSID: '',
  password: '',
})
// 监听连接上wifi事件
uni.onWifiConnected(function(wifi){})
uni.onWifiConnectedWithPartialInfo(CALLBACK)
// 监听获取到wifi列表数据事件
uni.onGetWifiList(function(res) {})

电量 ​

js
// 获取设备电量：不支持快手、京东、抖音、飞书
uni.getBatteryInfo({})

生物认证（指纹、人脸） ​

https://zh.uniapp.dcloud.io/api/system/authentication.html

键盘 ​

js
// 隐藏软键盘
uni.hideKeyboard()

// 监听键盘高度变化
uni.onKeyboardHeightChange(callback)
uni.offKeyboardHeightChange(callback)

界面 ​

消息提示 ​

js
// 显示消息提示框
uni.showToast({
  title: '',
})

// 隐藏消息提示框
uni.hideToast()

// 显示loading提示框
uni.showLoading({
  title: ''
})

// 隐藏loading提示框
uni.hideLoading()

// 显示模态弹窗
uni.showModal({})

// 从底部向上弹出操作菜单
uni.showActionSheet({
  // 按钮文字的数组
  itemList: ['']
})

设置导航条 ​

js
// 动态设置当前页面的标题
uni.setNavigationBarTitle({
  title: ''
})

// 设置导航条颜色
uni.setNavigationBarColor({
  frontColor: '',
  backgroundColor: ''
})

// 显示导航条加载动画：不支持app、抖音飞书
uni.showNavigationBarLoading({})

// 隐藏导航条加载动画：不支持app、抖音飞书
uni.hideNavigationBarLoading({})

// 隐藏返回首页按钮：仅支持微信、京东、抖音飞书、qq
uni.hideHomeButton({})

设置TabBar ​

js
// 动态设置tabBar某项内容
uni.setTabBarItem({
  index: 0
})

uni.setTabBarStyle({})

uni.hideTabBar()

uni.showTabBar()

// 为tabBar添加右上角角标文本
uni.setTabBarBadge({
  index: '',
  text: ''
})

// 为tabBar移除右上角角标文本
uni.removeTabBarBadge({
  index: ''
})

// 显示tabBar右上角红点
uni.showTabBarRedDot({
  index: ''
})

// 隐藏tabBar右上角红点
uni.hideTabBarRedDot({
  index: ''
})

// 监听中间按钮的点击事件：仅支持app、h5
uni.onTabBarMidButtonTap(cb)

背景 ​

js
// 动态设置窗口背景：仅微信、支付宝、百度、qq、快手、京东支持
uni.setBackgroundColor({})

// 动态设置下拉背景字体、loading图样式：仅微信、支付宝、百度、qq、快手、京东支持
uni.setBackgroundTextStyle({
  textStyle: 'dark | light'
})

动画 ​

https://zh.uniapp.dcloud.io/api/ui/animation.html

滚动 ​

js
// 将页面滚动到目标位置
uni.pageScrollTo({})

下拉刷新 ​

js
// 监听下拉刷新事件，需要在pages.json对应的页面节点style开启enablePullDownRefresh
// 该事件，和onLoad同级别
onPullDownRefresh()

// 开始下拉刷新
uni.startPullDownRefresh({})

// 停止下拉刷新
uni.stopPullDownRefresh()

宽屏适配 ​

https://zh.uniapp.dcloud.io/api/ui/adapt.html

js
// 设置、获取窗口样式，传入、返回css属性值对象
uni.getTopWindowStyle()
uni.getLeftWindowStyle()
uni.getRightWindowStyle()

uni.setTopWindowStyle()
uni.setLeftWindowStyle()
uni.setRightWindowStyle()

窗口尺寸变化 ​

js
uni.onWindowResize(cb)
uni.offWindowResize(cb)

uni.createSelectorQuery获取节点信息 ​

js
let selectorQuery = uni.createSelectorQuery()

// select(selector)、selectAll(selector)、selectViewport()（获取显示区域的尺寸信息）：返回nodesRef（节点信息对象）
// boundingClientRect：返回selectorQuery，故而可链式调用
selectorQuery.select('.uni-status-bar').boundingClientRect().select('.uni-nav-bar')
  .boundingClientRect().select('.sba-apps-nav-lv2')
  .boundingClientRect()
  
// exec执行selectorQuery所有的请求，将请求结果依次放在数组data中
selectorQuery.exec(data => {
  that.wrapperHeight = res.windowHeight - (data[0].height || 0) - (data[1].height || 0)
  that.appsHeight = that.wrapperHeight - (data[2].height || 0)
})

节点布局相交状态 ​

用于监听多个组件节点在布局位置上的相交状态。常用于推断节点是否被用户看见，以及看见的区域范围

媒体查询 ​

MediaQueryObserver对象，用于监听页面media query状态的变化，比如页面的宽高是否在某个指定范围

小程序右上角菜单按钮位置信息 ​

js
let menuButtonInfo = uni.getMenuButtonBoundingClientRect()

当前设置的语言 ​

https://zh.uniapp.dcloud.io/api/ui/locale.html

ArrayBuffer对象和base64字符串互转 ​

js
// 不支持支付宝和百度
const base64 = 'test'
const arrayBuffer = uni.base64ToArrayBuffer(base64)
// 不支持支付宝、百度、抖音
const arrayBuffer = new Unit8Array([55, 55, 55])
const base64 = uni.arrayBufferToBase64(arrayBuffer)

获取应用启动时的参数 ​

js
// 不支持百度、京东
const launchOptions = uni.getLaunchOptionsSync()
// 不支持qq、百度、京东、钉钉、飞书
const launchOptions = uni.getEnterOptionsSync()

getCurrentPages获取当前页面栈实例 ​

js
// 返回数组，第一个为首页，最后一个为当前页面
// 该方法仅用于展示页面栈情况，切勿修改
const curPages = getCurrentPages()

// 获取当前页面路由
const currentRoute = curPages[0].route

// 获取当前页面的vue实例
const currentInstance = curPages[0].$vm
// 监听生命周期，小程序端部分其他生命周期需在页面选项中配置过才可生效
currentInstance.$on('hook:onHide', () => {
  console.log('onHide')
})
// 获取数据
console.log(currentInstance.$data.title)

// 获取当前的webview对象实例
const currentWebview = curPages[0].$getAppWebView()
// #ifdef APP-PLUS
const currentWebview = this.$scope.$getAppWebview()
currentWebview.setBounce({ position: { top: '100px' }, changeoffset: { top: '0px' }})
// #endif

页面通信 ​

  • $emit、$on、$once、$off触发的事件都是全局的，跨任意组件、页面、nvue、vue（即他们都能够触发和监听）
js
// 触发
uni.$emit(eventName, data)

// 监听
uni.$on(eventName, function (data) {
  console.log(data)
})

// 监听一次
uni.$once(eventName, function (data) {
  console.log(data)
})

// 移除
// 若不传任何参数，则移除所有app级别的事件监听器
// 若只传eventName，则移除该事件名的所有监听器
// 提供的回调函数必须跟$on同一个，才能移除这个回调的监听器
uni.$off([eventName, function (e) {
  console.log(e)
}])

存储 ​

  • storage在不同端的实现不同：
    • app：原生plus.storage，持久化无限制存储
    • h5：localstorage
    • 小程序：各个小程序自带的storage api，存储生命周期和小程序本身一致，存储大小（微信10mb，支付宝10mb）
  • 其他存储方案：
    • h5：websql、indexedDB、sessionStorage
    • app：SQLite、IO文件等本地存储
js
// 未带sync的为异步接口
uni.setStorage({
  // 避开使用系统保留前缀`uni-`, `uni_`, `dcloud-`, `dcloud_`的key
  key: '本地缓存中指定的key',
  data: '需要存储的内容，仅支持能够序列化的对象',
  success_fail_complete(){}
})

uni.getStorage({
  key: '',
  success_fail_complete(){}
})

uni.removeStorage({
  key: '',
  success_fail_complete(){}
})

// 清理本地数据缓存
uni.clearStorage()

// 获取当前storage的相关信息
uni.getStorageInfo({
  success(keys, currentSize, limitSize) {
    console.log(keys, currentSize, limitSize)
  }
})

try {
  uni.setStorageSync(key, data)
  const data = uni.getStorageSync(key)
  uni.removeStorageSync(key)
  uni.clearStorageSync()
  const storage = uni.getStorageInfoSync()
} catch (e) {
  console.log(e)
}

媒体 ​

图片 ​

js
// 从本地相册选择，或相机拍照（前置摄像参考plus.camera）
// 微信小程序2.21+，使用uni.chooseMedia
uni.chooseImage({
  count: 9,
  sizeType: ['original', 'compressed'],
  // 根据文件扩展过滤，不能为空字符串，默认不过滤
  // 非媒体文件，应去插件市场搜索文件选择
  extension: ['png'],
  // 从哪里打开，默认相册和相机都有
  sourceType: ['album', 'camera'],
  // 图像裁剪参数，设置后sizeType失效
  crop: {
    // 图片质量
    quality: 100,
    // 裁剪宽高
    width: 100,
    height: 100,
    // 是否将宽高作为裁剪保存图片真实的像素值
    resize: true
  },
  // 持久存储应使用uni.saveFile
  success_fail_complete(tempFilePaths, tempFiles) {}
})

// 预览
uni.previewImage({
  // 当前图片的链接或在urls中的索引值，默认为urls的第一张
  current: '',
  // 是否显示长按菜单
  showmenu: true,
  // 需要预览的图片链接列表
  urls: [''],
  // 图片指示器样式: default, number, none
  indicator: 'default',
  // 循环预览
  loop: true,
  // 长按图片显示操作菜单，默认为保存相册
  longPressActions: {
    // 按钮的文字数组
    itemList: [''],
    // 选中按钮文字引发的回调
    success_fail_complete (){}
  },
  success_fail_complete(){}
})

// 仅支持app、h5
uni.closePreviewImage({
  success_fail_complete(){}
})

// 获取图片信息，小程序需配置download白名单
uni.getImageInfo({
  // 可以是相对路径、临时文件路径、存储文件路径、网络路径
  src: '',
  success_fail_complete(){}
})

// 保存图片到相册：不支持h5
// 可以通过用户授权api判断是否有相册访问权限https://uniapp.dcloud.io/api/other/authorize
uni.saveImageToPhotosAlbum({
  // 临时路径、永久路径，不支持网络路径
  filePath: '',
  success_fail_complete(){}
})

// 图片压缩：不支持h5
uni.compressImage({
  // 相对路径、临时路径、永久路径，不支持网络
  src: '',
  quality：100,
  // 缩放的宽高，支持px、%、auto
  width: 'auto',
  height: 'auto',
  // 压缩后的宽高，单位px
  compressedWidth: 100,
  compressedHeight: 100,
  // 图片旋转
  rotate: 360,
  success_fail_complete(){}
})

文件 ​

js
// 从本地选择文件（非媒体文件），仅支持h5(v2.9.9+)
uni.chooseFile({
  count: 100,
  type: 'all',
  extension: ['exe'],
  sourceType: ['album', 'camera'],
  success_fail_complete(){}
})

// 从微信聊天会话中选择文件，仅支持微信、qq
wx.chooseMessageFile({

})

录音管理 ​

js
/**
 * 获取全局唯一的录音管理器recorderManager，该对象的方法如下：
 * start（全支持）、pause（app不支持）、resume（app不支持）、stop（全支持）：开始、暂停、继续、停止录音
 * onStart、onPause、onResume、onStop：监听对应事件，将on改为off则为取消监听
 * 
 */
const recorderManager = uni.getRecorderManager()
// 播放录音
const innerAudioContext = uni.createInnerAudioContext()

recorderManager.onStop(function (res) {
  // 停止录音之后，将其存储
  this.voicePath = res.tempFilePath
})

function startRecord (){
  recorderManager.start()
}

function stopRecord (){
  recorderManager.stop()
}

function playVoice () {
  if (this.voicePath) {
    innerAudioContext.src = this.voicePath
    innerAudioContext.play()
  }
}

音频组件控制 ​

js
// 创建并返回内部audio上下文对象
const innerAudioContext = uni.createInnerAudioContext()
innerAudioContext.autoplay = true
innerAudioContext.src = 'https://xxx.mp3'
// 多次调用会播放新的文件时，应该提前销毁实例：即调用pause()、destroy()、将innerAudioContext设为null
// 倍数播放应使用video替代（可到插件市场搜索）
innerAudioContext.onPlay(() => {
  console.log('开始播放')
})

视频 ​

js
// 拍摄或从相册中选择，返回临时路径
uni.chooseVideo({
  sourceType: ['album', 'camera'],
  extension: ['mp4'],
  compressed: true,
  // 最长拍摄时间
  maxDuration: 60,
  camera: 'front | back',
  // 安卓app选择的最大大小为180MB，突破限制可到插件市场查找
  // 选择视频可使用uni-file-picker
  success_fail_complete(){}
})

// 拍摄或从相册选择图片或视频，仅支持微信、抖音、京东
uni.chooseMedia({
  count: 9,
  mediaType: ['image', 'video', 'mix'],
  sourceType: ['album', 'camera'],
  // 最长拍摄时间
  maxDuration: 10,
  sizeType: ['original', 'compressed'],
  // 前置、后置
  camera: 'back | front',
  success_fail_complete(){}
})

// 保存视频到系统相册，需要有相册写入权限
uni.saveVideoToPhotosAlbum({
  // 视频的临时、永久路径
  filePath: '',
  success_fail_complete(){}
})

// 获取视频详细信息，仅支持app、h5
uni.getVideoInfo({
  src: '',
  success_fail_complete(){}
})

// 压缩视频，仅支持app、微信
uni.compressVideo({
  src: '',
  quality: 'low | medium | high',
  success_fail_complete(){}
})

// 打开视频编辑器,仅支持微信
uni.openVideoEditor({
  filePath: '',
  // 视频裁剪的最长度
  minDuration: '',
  maxDuration: '',
  success_fail_complete(){}
})

视频、相机、直播组件控制、富文本、音视频合成 ​

见文档https://zh.uniapp.dcloud.io/api/media/video-context.html

文件 ​

js
// 对于app的io操作，可使用更强大的plus.io api
// app打开文件，可见插件市场

// 保存文件到本地：不支持h5、快手
// 微信建议使用uni.getFileSystemManager()
uni.saveFile({
  // 需要保存文件的临时路径
  tempFilePath: ''
})

// 获取本地已保存的文件列表：不支持h5、快手
uni.getSavedFileList({})

// 获取本地文件的文件信息，仅用于已保存到本地的文件：不支持h5、快手
uni.getSavedFileInfo({
  filePath: ''
})

// 获取文件信息，仅用于已保存到本地的文件：不支持快手
// 微信建议使用uni.getFileSystemManager()
uni.getFileInfo({
  filePath: ''
})

// 删除本地存储的文件：不支持h5、快手
uni.removeSavedFile({
  filePath: ''
})

// 新开页面打开文档格式文件
uni.openDocument({
  filePath: '',
  fileType: '',
})

绘画 ​

应用级事件 ​

js
// 监听应用要打开的页面不存在事件
uni.onPageNotFound(function (path, query, isEntryPage) {})

// 取消监听应用要打开的页面不存在事件
uni.offPageNotFound(function (path, query, isEntryPage) {})

// 监听小程序错误事件
uni.onError(function (err) {})

// 取消监听小程序错误事件
uni.offError(function (err) {})

// 监听应用切前台事件
uni.onAppShow(function (path, scene, query, ...others) {})

// 取消监听应用切前台事件
uni.offAppShow(function (path, scene, query, ...others) {})

// 监听应用切后台事件
uni.onAppHide(function (...others) {})

// 取消监听应用切后台事件
uni.offAppHide(function (...others) {})

拦截器 ​

使用场景：路由拦截、权限引导

js
// 添加拦截器
uni.addInterceptor(
  // 需要拦截的api名称，仅支持异步接口，
  // 这里将拦截uni.request
  'request', 
  {
    // 拦截前触发
    invoke () {},
    // 方法调用后触发
    returnValue () {},
    success_fail_complte(){ }
  }
)

// 删除拦截器
uni.removeInterceptor('request')

性能优化 ​

  • 非h5端运行时，架构上分为逻辑层（业务逻辑，运行在独立的jscore中，不依赖本机webview）和视图层（页面渲染），编译时会将两者进行拆分
  • 逻辑层和视图层分离：
    • 好处：js运算不卡页面渲染
    • 坏处：互相通信有损耗（比如绘制canvas、视图层滚动、跟手操作）
  • 解决逻辑层视图层通信损耗的方法：
    • 对于webview渲染的视图层：在app-vue和微信小程序中，提供一种运行于视图层的专属js（renderjs、wxs）
    • 对于原生渲染的视图层：在app-nvue中，提供一套bingdingx机制，可进行手势监听、动画等
  • app-vue中使用系统webview时会有手机浏览器的css兼容问题，故而不应该使用太新的css语法，或者集成腾讯x5引擎
  • 对于复杂页面，更新某区域的数据时，应该将这个区域做成组件，然后更新数据仅更新这个组件，避免更新整个页面（造成点击延迟卡顿），此问题在app-nvue和h5不存在

优化建议：

  • 避免使用大图，包括图片和base64形式
  • 优化数据更新，data数据的每次变化都会引发视图层的重渲染，故而对于非视图需要的变量，不应该放在data中（放在外部、或者全局vue实例上）
  • 长列表：性能优化参考上述复杂页面
  • 减少一次性渲染的节点数量，可进行分批次加载渲染
  • 减少组件数量和节点嵌套层级
  • 避免视图层和逻辑层频繁通信
  • 优化页面切换动画
  • 使用nvue代替vue，nvue实现页面原生渲染能力、提高页面流畅性
  • 优化启动速度：控制资源的体积、splash关闭白屏检测、首页为nvue时设置为fast启动模式

文件历史 ​

内容整理权归解璎所有 Copyright © 2022-present