uni-app随笔_API

小程序API

基础

日志打印

console

向控制台打印日志信息。

debug

向控制台打印 debug 日志

注：App 端 debug 方法等同于 log 方法。

定时器

setTimeout(callback, delay, rest)

设定一个定时器。在定时到期以后执行注册的回调函数

clearTimeout(timeoutID)

取消由 setTimeout 设置的定时器。

<script lang="ts">
	let timer: ReturnType<typeof setTimeout> | null = null;
	export default {
		data() {
			return {};
		},
		methods: {
			onSetTimeout() {
				timer = setTimeout(() => {
					console.log("setTimeout");
				}, 1000);
			},
			clearTimer() {
				// clearTime
				if (timer) {
					clearTimeout(timer);
					timer = null;
				}
			},
		},
		beforeUnmount() {
			// clearTime
			this.clearTimer();
		},
	};
</script>

uni.base64ToArrayBuffer(base64)

将 Base64 字符串转成 ArrayBuffer 对象

uni.arrayBufferToBase64(arrayBuffer)

将 ArrayBuffer 对象转成 Base64 字符串

获取启动时参数

uni.getLaunchOptionsSync()

获取启动时的参数。返回值与App.onLaunch的回调参数一致

uni.getEnterOptionsSync()

获取启动时的参数。

拦截器

uni.addInterceptor(STRING, OBJECT)

添加拦截器

网络

发起请求

uni.request(OBJECT)

发起网络请求。

在各个小程序平台运行时，网络相关的 API 在使用前需要配置域名白名单。

实例

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';
    }
});

OBJECT 参数说明

参数名	类型	必填	默认值	说明	平台差异说明
url	String	是		开发者服务器接口地址
data	Object/String/ArrayBuffer	否		请求的参数	App 3.3.7 以下不支持 ArrayBuffer 类型
header	Object	否		设置请求的 header，header 中不能设置 Referer	App、H5端会自动带上cookie，且H5端不可手动修改
method	String	否	GET	有效值详见下方说明
timeout	Number	否	60000	超时时间，单位 ms	H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+)、微信小程序（2.10.0）、支付宝小程序
dataType	String	否	json	如果设为 json，会对返回的数据进行一次 JSON.parse，非 json 不会进行 JSON.parse
responseType	String	否	text	设置响应的数据类型。合法值：text、arraybuffer	支付宝小程序不支持
sslVerify	Boolean	否	true	验证 ssl 证书	仅App安卓端支持（HBuilderX 2.3.3+），不支持离线打包
withCredentials	Boolean	否	false	跨域请求时是否携带凭证（cookies）	仅H5支持（HBuilderX 2.6.15+）
firstIpv4	Boolean	否	false	DNS解析时优先使用ipv4	仅 App-Android 支持 (HBuilderX 2.8.0+)
enableHttp2	Boolean	否	false	开启 http2	微信小程序
enableQuic	Boolean	否	false	开启 quic	微信小程序
enableCache	Boolean	否	false	开启 cache	微信小程序、抖音小程序 2.31.0+
enableHttpDNS	Boolean	否	false	是否开启 HttpDNS 服务。如开启，需要同时填入 httpDNSServiceId 。 HttpDNS 用法详见移动解析HttpDNS	微信小程序
httpDNSServiceId	String	否		HttpDNS 服务商 Id。 HttpDNS 用法详见移动解析HttpDNS	微信小程序
enableChunked	Boolean	否	false	开启 transfer-encoding chunked	微信小程序
forceCellularNetwork	Boolean	否	false	wifi下使用移动网络发送请求	微信小程序
enableCookie	Boolean	否	false	开启后可在headers中编辑cookie	支付宝小程序 10.2.33+
cloudCache	Object/Boolean	否	false	是否开启云加速（详见云加速服务）	百度小程序 3.310.11+
defer	Boolean	否	false	控制当前请求是否延时至首屏内容渲染后发送	百度小程序 3.310.11+
success	Function	否		收到开发者服务器成功返回的回调函数
fail	Function	否		接口调用失败的回调函数
complete	Function	否		接口调用结束的回调函数（调用成功、失败都会执行）

method 有效值

注意：method有效值必须大写，每个平台支持的method有效值不同，详细见下表。

method	App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	快手小程序	京东小程序
GET	√	√	√	√	√	√	√	√
POST	√	√	√	√	√	√	√	√
PUT	√	√	√	x	√	√	x	x
DELETE	√	√	√	x	√	x	x	x
CONNECT	x	√	√	x	x	x	x	x
HEAD	√	√	√	x	√	x	x	x
OPTIONS	√	√	√	x	√	x	x	x
TRACE	x	√	√	x	x	x	x	x

success 返回参数说明

参数	类型	说明
data	Object/String/ArrayBuffer	开发者服务器返回的数据
statusCode	Number	开发者服务器返回的 HTTP 状态码
header	Object	开发者服务器返回的 HTTP Response Header
cookies	`Array.<string>`	开发者服务器返回的 cookies，格式为字符串数组

data 数据说明

最终发送给服务器的数据是 String 类型，如果传入的 data 不是 String 类型，会被转换成 String。转换规则如下：

对于 GET 方法，会将数据转换为 query string。例如 { name: 'name', age: 18 } 转换后的结果是 name=name&age=18。
对于 POST 方法且 header['content-type'] 为 application/json 的数据，会进行 JSON 序列化。
对于 POST 方法且 header['content-type'] 为 application/x-www-form-urlencoded 的数据，会将数据转换为 query string。

上传下载

uni.uploadFile(OBJECT)

将本地资源上传到开发者服务器，客户端发起一个 POST 请求，其中 content-type 为 multipart/form-data。如页面通过 uni.chooseImage 等接口获取到一个本地资源的临时文件路径后，可通过此接口将本地资源上传到指定服务器。另外选择和上传非图像、视频文件参考：https://ask.dcloud.net.cn/article/35547。

在各个小程序平台运行时，网络相关的 API 在使用前需要配置域名白名单。

推荐开发者上传到uniCloud，uniCloud提供了免费CDN和更好的易用性，包括安全的cdn直传。

uniCloud的上传API：https://doc.dcloud.net.cn/uniCloud/storage/dev.html#uploadfile
封装的更完善的uni-file-picker组件，文件选择、上传到uniCloud，一站式集成。
推荐uni-cdn，帮你节省至少30%的 CDN 费用！详情。

实例

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);
			}
		});
	}
});

通过 uploadTask，可监听上传进度变化事件，以及取消上传任务。

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.navigateTo(OBJECT)

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

uni.redirectTo(OBJECT)

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

uni.reLaunch(OBJECT)

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

uni.switchTab(OBJECT)

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

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

uni.navigateBack(OBJECT)

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

//在起始页面跳转到test.vue页面并传递参数
uni.navigateTo({
	url: 'test?id=1&name=uniapp'
});

// 在test.vue页面接受参数
export default {
	onLoad: function (option) { //option为object类型，会序列化上个页面传递的参数
		console.log(option.id); //打印出上个页面传递的参数。
		console.log(option.name); //打印出上个页面传递的参数。
	}
}

// 在起始页面跳转到test.vue页面，并监听test.vue发送过来的事件数据
uni.navigateTo({
  url: '/pages/test?id=1',
  events: {
    // 为指定事件添加一个监听器，获取被打开页面传送到当前页面的数据
    acceptDataFromOpenedPage: function(data) {
      console.log(data)
    },
    someEvent: function(data) {
      console.log(data)
    }
    ...
  },
  success: function(res) {
    // 通过eventChannel向被打开页面传送数据
    res.eventChannel.emit('acceptDataFromOpenerPage', { data: 'data from starter page' })
  }
})

// 在test.vue页面，向起始页通过事件传递数据
onLoad: function(option) {
  const eventChannel = this.getOpenerEventChannel();
  eventChannel.emit('acceptDataFromOpenedPage', {data: 'data from test page'});
  eventChannel.emit('someEvent', {data: 'data from test page for someEvent'});
  // 监听acceptDataFromOpenerPage事件，获取上一页面通过eventChannel传送到当前页面的数据
  eventChannel.on('acceptDataFromOpenerPage', function(data) {
    console.log(data)
  })
}

窗口动画

本API仅App支持。小程序自身不支持自定义动画。H5的窗体动画可使用常规单页动画处理方案，见H5下单页动画示例

窗口的显示/关闭动画效果，支持在 API、组件、pages.json 中配置，优先级为：API = 组件 > pages.json。

#API

有效的路由 API

navigateTo
navigateBack

uni.navigateTo({
	url: '../test/test',
	animationType: 'pop-in',
	animationDuration: 200
});
uni.navigateBack({
	delta: 1,
	animationType: 'pop-out',
	animationDuration: 200
});

pages.json

pages.json 中配置的是窗口显示的动画

"style": {
	"app-plus": {
		"animationType": "fade-in",
		"animationDuration": 300
	}
}

显示动画与关闭动画，会有默认的对应规则。但是如果通过 API 或组件配置了窗口关闭的动画类型，则不会使用默认的类型。

显示动画	关闭动画	显示动画描述（关闭动画与之相反）
slide-in-right	slide-out-right	新窗体从右侧进入
slide-in-left	slide-out-left	新窗体从左侧进入
slide-in-top	slide-out-top	新窗体从顶部进入
slide-in-bottom	slide-out-bottom	新窗体从底部进入
pop-in	pop-out	新窗体从左侧进入，且老窗体被挤压而出
fade-in	fade-out	新窗体从透明到不透明逐渐显示
zoom-out	zoom-in	新窗体从小到大缩放显示
zoom-fade-out	zoom-fade-in	新窗体从小到大逐渐放大并且从透明到不透明逐渐显示
none	none	无动画

更多查看官方文档

页面通讯

uni.$emit(eventName,OBJECT)

触发全局的自定义事件，附加参数都会传给监听器回调函数。

属性	类型	描述
eventName	String	事件名
OBJECT	Object	触发事件携带的附加参数

代码示例

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

复制代码

#uni.$on(eventName,callback)

监听全局的自定义事件，事件由 uni.$emit 触发，回调函数会接收事件触发函数的传入参数。

属性	类型	描述
eventName	String	事件名
callback	Function	事件的回调函数

代码示例

1
2
3

uni.$on('update',function(data){
	console.log('监听到事件来自 update ，携带参数 msg 为：' + data.msg);
})

复制代码

#uni.$once(eventName,callback)

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

属性	类型	描述
eventName	String	事件名
callback	Function	事件的回调函数

代码示例

1
2
3

uni.$once('update',function(data){
	console.log('监听到事件来自 update ，携带参数 msg 为：' + data.msg);
})

复制代码

#uni.$off([eventName, callback])

移除全局自定义事件监听器。

属性	类型	描述
eventName	Array＜String＞	事件名
callback	Function	事件的回调函数

Tips

如果uni.$off没有传入参数，则移除App级别的所有事件监听器；
如果只提供了事件名（eventName），则移除该事件名对应的所有监听器；
如果同时提供了事件与回调，则只移除这个事件回调的监听器；
提供的回调必须跟$on的回调为同一个才能移除这个回调的监听器；

代码示例

$emit、$on、$off常用于跨页面、跨组件通讯，这里为了方便演示放在同一个页面

<template>
	<view class="content">
		<view class="data">
			<text>{{val}}</text>
		</view>
		<button type="primary" @click="comunicationOff">结束监听</button>
	</view>
</template>

<script>
	export default {
		data() {
			return {
				val: 0
			}
		},
		onLoad() {
			setInterval(()=>{
				uni.$emit('add', {
					data: 2
				})
			},1000)
			uni.$on('add', this.add)
		},
		methods: {
			comunicationOff() {
				uni.$off('add', this.add)
			},
			add(e) {
				this.val += e.data
			}
		}
	}
</script>

<style>
	.content {
		display: flex;
		flex-direction: column;
		align-items: center;
		justify-content: center;
	}

	.data {
		text-align: center;
		line-height: 40px;
		margin-top: 40px;
	}

	button {
		width: 200px;
		margin: 20px 0;
	}
</style>

复制代码

注意事项

uni.$emit、 uni.$on 、 uni.$once 、uni.$off 触发的事件都是 App 全局级别的，跨任意组件，页面，nvue，vue 等
使用时，注意及时销毁事件监听，比如，页面 onLoad 里边 uni.$on 注册监听，onUnload 里边 uni.$off 移除，或者一次性的事件，直接使用 uni.$once 监听
注意 uni.$on 定义完成后才能接收到 uni.$emit 传递的数据

数据缓存

uni.setStorage(OBJECT)

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

OBJECT 参数说明

参数名	类型	必填	说明
key	String	是	本地缓存中的指定的 key
data	Any	是	需要存储的内容，只支持原生类型、及能够通过 JSON.stringify 序列化的对象
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例

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

uni.setStorageSync(KEY,DATA)

将 data 存储在本地缓存中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个同步接口。

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

uni.getStorage(OBJECT)

从本地缓存中异步获取指定 key 对应的内容。

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

uni.getStorageSync(KEY)

从本地缓存中同步获取指定 key 对应的内容。

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

uni.getStorageInfo(OBJECT)

异步获取当前 storage 的相关信息。

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

uni.getStorageInfoSync()

同步获取当前 storage 的相关信息。

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

uni.removeStorage(OBJECT)

从本地缓存中异步移除指定 key。

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

uni.removeStorageSync(KEY)

从本地缓存中同步移除指定 key。

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

uni.clearStorage()

清理本地数据缓存。

示例

1	`uni.clearStorage();`

复制代码

#uni.clearStorageSync()

同步清理本地数据缓存。

示例

try {
	uni.clearStorageSync();
} catch (e) {
	// error
}

uni-app

#uni-app

uni-app随笔_API

http://www.dwyblog.cn/2023/01/12/uni-app随笔_API/

作者

幸福来敲门

发布于

2023年1月12日

许可协议

Lodash工具库上一篇

git使用ssh密钥下一篇