1.3.5.1 QN.on/off/emit
优质
小牛编辑
122浏览
2023-12-01
QAP-SDK 支持 3 种类型的事件机制: 页面级别事件
应用级别事件
全局级别事件
- 页面级别事件 —— 只能在当前页面被监听和触发。
- 事件名的前缀为
Page.
。如:Page.hello
。
- 事件名的前缀为
- 应用级别事件 —— 能在整个应用插件的任一页面被监听和触发。
- 事件名的前缀为
App.
。如:App.hello
。
- 事件名的前缀为
- 全局级别事件 —— 能在千牛内的任一页面被监听,但是应用插件不能触发此类型事件。
- 事件名的前缀为
Global.
。如:Global.hello
。
- 事件名的前缀为
注意: 如果事件不含上述的前缀,则默认为页面级别事件,前缀为 Page.
。即事件 hello
和 Page.hello
等同。
1.1. 内置事件
为了提升应用体验和开发效率,QAP-SDK 内置了以下事件:
事件名称 | 所属模块 | 含义 | 备注 |
---|---|---|---|
Page.back | 页面导航栏 | 返回按钮点击事件 | |
Page.close | 页面导航栏 | 关闭按钮点击事件 | |
Page.reload | 页面导航栏 | 刷新按钮点击事件 | |
Page.WillAppear | 页面 | 页面即将可见 | |
Page.DidAppear | 页面 | 页面已经可见 | |
Page.WillDisappear | 页面 | 页面即将不可见 | 可能的情况:被千牛的其他页面遮挡,如扫码;被其他应用遮挡,如拍照;用户按了Home千牛将被最小化。 |
Page.DidDisappear | 页面 | 页面已经不可见 | |
Global.LowMemory | 千牛应用 | 千牛进入低内存状态 | |
Global.DidBecomeActive | 千牛应用 | 千牛应用进入前台,处于活跃状态 | |
Global.DidEnterBackground | 千牛应用 | 千牛应用进入后台 | |
Global.KeyboardWillShow | 系统键盘 | 键盘将要显示 | |
Global.KeyboardDidShow | 系统键盘 | 键盘已经显示 | |
Global.KeyboardWillHide | 系统键盘 | 键盘将要隐藏 | |
Global.KeyboardDidHide | 系统键盘 | 键盘已经隐藏 | |
Global.KeyboardWillChangeFrame | 系统键盘 | 键盘外框架大小将要变化更新 | 键盘的显示和隐藏都会影响键盘外框架大小变化,因此会同时触发此事件 |
Global.KeyboardDidChageFrame | 系统键盘 | 键盘外框架大小已经变化更新 | 键盘的显示和隐藏都会影响键盘外框架大小变化,因此会同时触发此事件 |
1.2. API 调用
1.2.1. QN.on(event, callback)
注册事件
API 调用入参
参数名 | 类型 | 是否可选 | 默认值 | 含义 |
---|---|---|---|---|
event | String | 事件名称 | ||
callback | Function | 事件触发时的回调函数 |
API 响应结果
参数名 | 类型 | 是否必须返回 | 含义 |
---|---|---|---|
result | Object | 响应对象 | |
result.code | String | 错误码 | |
result.msg | String | 错误信息 |
事件回调入参
参数名 | 类型 | 是否必须 | 含义 |
---|---|---|---|
data | * | optional | 事件触发时传递的数据 |
调用示例
QN.on('Page.hello', (data) => {
console.log(data);
});
// 如果想知道事件注册是成功还是失败
QN.on('Page.hello', (data) => {
console.log(data);
})
.then(result => {
console.log('注册成功');
})
.catch(error => {
console.log('注册失败');
});
1.2.2. QN.off(event, callback)
注销事件
API 调用入参
参数名 | 类型 | 是否可选 | 默认值 | 含义 |
---|---|---|---|---|
event | String | 事件名称 | ||
callback | Function | optional | 事件触发的回调函数。如果传值,则会注销事件回调队列中为 callback 的回调。如果不传值,则会注销对应事件所有回调函数。 |
API 响应结果
参数名 | 类型 | 是否必须返回 | 含义 |
---|---|---|---|
result | Object | 响应对象 | |
result.code | String | 错误码 | |
result.msg | String | 错误信息 |
调用示例
// 注销事件时传递对应的回调函数。此时只会注销该回调函数,其他的事件回调函数不受影响。
QN.off('Page.hello', (data) => {
console.log(data);
});
// 注销事件时不传递事件回调函数,此时会注销所有该事件下的回到函数。
QN.off('Page.hello');
// 如果想知道注销事件是成功还是失败
QN.off('Page.hello', (data) => {
console.log(data);
})
.then(result => {
console.log('注销成功');
})
.catch(error => {
console.log('注销失败');
});
1.2.3. QN.emit(event, data, options)
触发事件
API 调用入参
参数名 | 类型 | 是否可选 | 默认值 | 含义 |
---|---|---|---|---|
event | String | 事件名称 | ||
data | * Object | optional | 触发事件时发送的数据,该参数会作为事件回调函数的第一个参数传入。 | |
options | Object | optional | 选项 | |
options.sticky | Boolean | optional | 是否以粘性事件进行触发。当以粘性事件进行触发时,如果事件未注册,客户端会等到事件注册后才触发 |
API 响应结果
参数名 | 类型 | 是否必须返回 | 含义 |
---|---|---|---|
result | Object | 响应对象 | |
result.code | String | 错误码 | |
result.msg | String | 错误信息 |
调用示例
let data = {msg: 'msg from Page.hello'};
// 仅触发事件
QN.emit('Page.hello');
// 触发事件,并发送数据
QN.emit('Page.hello', data);
// 触发粘性事件
QN.emit('Page.hello', {sticky: true});
// 触发粘性事件,并发送数据
QN.emit('Page.hello', data, {sticky: true});
// 触发事件,并希望得知触发是否成功
QN.emit('Page.hello')
.then(result => {
console.log('触发成功');
})
.catch(error => {
console.log('触发失败');
});