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.。即事件 helloPage.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 调用入参

参数名类型是否可选默认值含义
eventString事件名称
callbackFunction事件触发时的回调函数

API 响应结果

参数名类型是否必须返回含义
resultObject响应对象
result.codeString错误码
result.msgString错误信息

事件回调入参

参数名类型是否必须含义
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 调用入参

参数名类型是否可选默认值含义
eventString事件名称
callbackFunctionoptional事件触发的回调函数。如果传值,则会注销事件回调队列中为 callback 的回调。如果不传值,则会注销对应事件所有回调函数。

API 响应结果

参数名类型是否必须返回含义
resultObject响应对象
result.codeString错误码
result.msgString错误信息

调用示例

// 注销事件时传递对应的回调函数。此时只会注销该回调函数,其他的事件回调函数不受影响。
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 调用入参

参数名类型是否可选默认值含义
eventString事件名称
data* Objectoptional触发事件时发送的数据,该参数会作为事件回调函数的第一个参数传入。
optionsObjectoptional选项
options.stickyBooleanoptional是否以粘性事件进行触发。当以粘性事件进行触发时,如果事件未注册,客户端会等到事件注册后才触发

API 响应结果

参数名类型是否必须返回含义
resultObject响应对象
result.codeString错误码
result.msgString错误信息

调用示例

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('触发失败');
});