diff --git a/zh-cn/application-dev/application-models/Readme-CN.md b/zh-cn/application-dev/application-models/Readme-CN.md index a6f69b38c8af66d2b966485977fb4296a6314b4b..e4b25b7da6aec2c222df691f6380e6052059a909 100644 --- a/zh-cn/application-dev/application-models/Readme-CN.md +++ b/zh-cn/application-dev/application-models/Readme-CN.md @@ -37,9 +37,10 @@ - [å¡ç‰‡ä½¿ç”¨è‡ªå®šä¹‰ç»˜åˆ¶èƒ½åŠ›](arkts-ui-widget-page-custom-drawing.md) - å¼€å‘å¡ç‰‡äº‹ä»¶ - [å¡ç‰‡äº‹ä»¶èƒ½åŠ›è¯´æ˜Ž](arkts-ui-widget-event-overview.md) - - [通过FormExtensionAbility刷新å¡ç‰‡å†…容](arkts-ui-widget-event-formextensionability.md) - - [通过UIAbility刷新å¡ç‰‡å†…容](arkts-ui-widget-event-uiability.md) - - [使用router事件跳转到指定页é¢](arkts-ui-widget-event-router.md) + - [使用router事件跳转到指定UIAbility](arkts-ui-widget-event-router.md) + - [使用call事件拉起指定UIAbility到åŽå°](arkts-ui-widget-event-call.md) + - [通过message事件刷新å¡ç‰‡å†…容](arkts-ui-widget-event-formextensionability.md) + - [通过router或call事件刷新å¡ç‰‡å†…容](arkts-ui-widget-event-uiability.md) - å¡ç‰‡æ•°æ®äº¤äº’ - [å¡ç‰‡æ•°æ®äº¤äº’说明](arkts-ui-widget-interaction-overview.md) - [定时刷新和定点刷新](arkts-ui-widget-update-by-time.md) diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-event-call.md b/zh-cn/application-dev/application-models/arkts-ui-widget-event-call.md new file mode 100644 index 0000000000000000000000000000000000000000..50e43ab959093891ccb81408864faf66ce4957fd --- /dev/null +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-event-call.md @@ -0,0 +1,89 @@ +# 使用call事件拉起指定UIAbility到åŽå° + + +许多应用希望借助å¡ç‰‡çš„能力,实现和应用在å‰å°æ—¶ç›¸åŒçš„功能。例如音ä¹å¡ç‰‡ï¼Œå¡ç‰‡ä¸Šæä¾›æ’放ã€æš‚åœç‰æŒ‰é’®ï¼Œç‚¹å‡»ä¸åŒæŒ‰é’®å°†è§¦å‘音ä¹åº”用的ä¸åŒåŠŸèƒ½ï¼Œè¿›è€Œæ高用户的体验。在å¡ç‰‡ä¸ä½¿ç”¨**postCardAction**接å£çš„call能力,能够将å¡ç‰‡æ供方应用的指定的UIAbility拉到åŽå°ã€‚åŒæ—¶ï¼Œcall能力æ供了调用应用指定方法ã€ä¼ 递数æ®çš„功能,使应用在åŽå°è¿è¡Œæ—¶å¯ä»¥é€šè¿‡å¡ç‰‡ä¸Šçš„按钮执行ä¸åŒçš„功能。 + + +通常使用按钮控件æ¥è§¦å‘call事件,示例代ç 如下: + + +- 在å¡ç‰‡é¡µé¢ä¸å¸ƒå±€ä¸¤ä¸ªæŒ‰é’®ï¼Œç‚¹å‡»å…¶ä¸ä¸€ä¸ªæŒ‰é’®æ—¶è°ƒç”¨postCardActionå‘指定UIAbilityå‘é€call事件,并在事件内定义需è¦è°ƒç”¨çš„æ–¹æ³•å’Œä¼ é€’çš„æ•°æ®ã€‚需è¦æ³¨æ„的是,methodå‚数为必选å‚数,且类型需è¦ä¸ºstring类型,用于触å‘UIAbilityä¸å¯¹åº”的方法。 + + ```ts + @Entry + @Component + struct WidgetCard { + build() { + Column() { + Button('功能A') + .margin('20%') + .onClick(() => { + console.info('call EntryAbility funA'); + postCardAction(this, { + 'action': 'call', + 'abilityName': 'EntryAbility', // åªèƒ½è·³è½¬åˆ°å½“å‰åº”用下的UIAbility + 'params': { + 'method': 'funA' // 在EntryAbilityä¸è°ƒç”¨çš„方法å + } + }); + }) + + Button('功能B') + .margin('20%') + .onClick(() => { + console.info('call EntryAbility funB'); + postCardAction(this, { + 'action': 'call', + 'abilityName': 'EntryAbility', // åªèƒ½è·³è½¬åˆ°å½“å‰åº”用下的UIAbility + 'params': { + 'method': 'funB', // 在EntryAbilityä¸è°ƒç”¨çš„方法å + 'num': 1 // 需è¦ä¼ 递的其他å‚æ•° + } + }); + }) + } + .width('100%') + .height('100%') + } + } + ``` + +- 在UIAbilityä¸æŽ¥æ”¶call事件并获å–å‚æ•°ï¼Œæ ¹æ®ä¼ 递的methodä¸åŒï¼Œæ‰§è¡Œä¸åŒçš„方法。其余数æ®å¯ä»¥é€šè¿‡readStringçš„æ–¹å¼èŽ·å–。需è¦æ³¨æ„的是,UIAbility需è¦onCreate生命周期ä¸ç›‘å¬æ‰€éœ€çš„方法。 + + ```ts + import UIAbility from '@ohos.app.ability.UIAbility'; + + function FunACall(data) { + // 获å–call事件ä¸ä¼ 递的所有å‚æ•° + console.log('FunACall param:' + JSON.stringify(data.readString())); + return null; + } + + function FunBCall(data) { + console.log('FunACall param:' + JSON.stringify(data.readString())); + return null; + } + + export default class CameraAbility extends UIAbility { + // 如果UIAbility第一次å¯åŠ¨ï¼Œåœ¨æ”¶åˆ°call事件åŽä¼šè§¦å‘onCreate生命周期回调 + onCreate(want, launchParam) { + try { + // 监å¬call事件所需的方法 + this.callee.on('funA', FunACall); + this.callee.on('funB', FunBCall); + } catch (error) { + console.log('register failed with error. Cause: ' + JSON.stringify(error)); + } + } + + // è¿›ç¨‹é€€å‡ºæ—¶ï¼Œè§£é™¤ç›‘å¬ + onDestroy() { + try { + this.callee.off('funA'); + this.callee.off('funB'); + } catch (error) { + console.log('register failed with error. Cause: ' + JSON.stringify(error)); + } + } + }; + ``` diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-event-formextensionability.md b/zh-cn/application-dev/application-models/arkts-ui-widget-event-formextensionability.md index ab376c0ea9312e34c52632c17c88339b2e8f06fa..295e6773e56f4bc2fcddaf8d14867db35f75b07b 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-event-formextensionability.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-event-formextensionability.md @@ -1,7 +1,7 @@ -# 通过FormExtensionAbility刷新å¡ç‰‡å†…容 +# 通过message事件刷新å¡ç‰‡å†…容 -在å¡ç‰‡é¡µé¢ä¸å¯ä»¥é€šè¿‡**postCardAction**接å£è§¦å‘message事件至FormExtensionAbility,然åŽç”±FormExtensionAbility刷新å¡ç‰‡å†…容,下é¢æ˜¯è¿™ç§åˆ·æ–°æ–¹å¼çš„简å•ç¤ºä¾‹ã€‚ +在å¡ç‰‡é¡µé¢ä¸å¯ä»¥é€šè¿‡**postCardAction**接å£è§¦å‘message事件拉起FormExtensionAbility,然åŽç”±FormExtensionAbility刷新å¡ç‰‡å†…容,下é¢æ˜¯è¿™ç§åˆ·æ–°æ–¹å¼çš„简å•ç¤ºä¾‹ã€‚ - 在å¡ç‰‡é¡µé¢é€šè¿‡æ³¨å†ŒButtonçš„onClick点击事件回调,并在回调ä¸è°ƒç”¨**postCardAction**接å£è§¦å‘事件至FormExtensionAbility diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md b/zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md index 783dc774f4db8dc76a20935f9772a00e6c8fb4a5..1852056075be181e437f773204f29267de89c249 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md @@ -24,7 +24,7 @@ actionå‚数说明: | **Key** | **Value** | **æ ·ä¾‹æè¿°** | | -------- | -------- | -------- | -| "action" | string | action的类型,支æŒä¸‰ç§é¢„定义的类型:<br/>- "router":应用跳转,触å‘åŽä¼šè·³è½¬åˆ°å¯¹åº”UIAbility,仅å…许跳转到当å‰åº”用的UIAbility。<br/>- "message":自定义消æ¯ï¼Œè§¦å‘åŽä¼šè°ƒç”¨æ供方FormExtensionAbilityçš„[onFormEvent()](../reference/apis/js-apis-app-form-formExtensionAbility.md#onformevent)生命周期回调。<br/>- "call":应用éžå‰å°å¯åŠ¨ï¼Œè§¦å‘åŽä¼šå¯åŠ¨å¯¹åº”çš„UIAbility,但ä¸ä¼šè°ƒåº¦åˆ°å‰å°ï¼Œcallçš„ç›®æ ‡åº”ç”¨éœ€è¦å…·å¤‡åŽå°è¿è¡Œæƒé™([ohos.permission.KEEP_BACKGROUND_RUNNING](../security/permission-list.md#ohospermissionkeep_background_running))。 | +| "action" | string | action的类型,支æŒä¸‰ç§é¢„定义的类型:<br/>- "router":跳转到æ供方应用的指定UIAbility。<br/>- "message":自定义消æ¯ï¼Œè§¦å‘åŽä¼šè°ƒç”¨æ供方FormExtensionAbilityçš„[onFormEvent()](../reference/apis/js-apis-app-form-formExtensionAbility.md#onformevent)生命周期回调。<br/>- "call":åŽå°å¯åŠ¨æ供方应用。触å‘åŽä¼šæ‹‰èµ·æ供方应用的指定UIAbility,但ä¸ä¼šè°ƒåº¦åˆ°å‰å°ã€‚æ供方应用需è¦å…·å¤‡åŽå°è¿è¡Œæƒé™([ohos.permission.KEEP_BACKGROUND_RUNNING](../security/permission-list.md#ohospermissionkeep_background_running))。 | | "bundleName" | string | "router" / "call" 类型时跳转的包å,å¯é€‰ã€‚ | | "moduleName" | string | "router" / "call" 类型时跳转的模å—å,å¯é€‰ã€‚ | | "abilityName" | string | "router" / "call" 类型时跳转的UIAbilityå,必填。 | @@ -55,8 +55,3 @@ Button('跳转') 以下是å¡ç‰‡å¼€å‘过程ä¸å¯ä»¥é€šè¿‡å¡ç‰‡äº‹ä»¶å®žçŽ°çš„典型开å‘场景: -- [通过FormExtensionAbility刷新å¡ç‰‡å†…容](arkts-ui-widget-event-formextensionability.md) - -- [通过UIAbility刷新å¡ç‰‡å†…容](arkts-ui-widget-event-uiability.md) - -- [使用router事件跳转到指定页é¢](arkts-ui-widget-event-router.md) diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-event-router.md b/zh-cn/application-dev/application-models/arkts-ui-widget-event-router.md index 82588a66874482e44a46e2ed669b99d5ba2fb9a7..3f3531d6ea75c2bdc8be75fdb45d58b6a70247c3 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-event-router.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-event-router.md @@ -1,7 +1,7 @@ -# 使用routeräº‹ä»¶è·³è½¬åˆ°æŒ‡å®šé¡µé¢ +# 使用router事件跳转到指定UIAbility -在å¡ç‰‡ä¸ä½¿ç”¨**postCardAction**接å£çš„router能力,能够快速拉起å¡ç‰‡æä¾›æ–¹åº”ç”¨ï¼Œå› æ¤é¡µé¢è¾ƒå¤šçš„应用往往会通过å¡ç‰‡æä¾›ä¸åŒçš„跳转按钮,实现一键直达的效果。例如相机å¡ç‰‡ï¼Œå¡ç‰‡ä¸Šæä¾›æ‹ç…§ã€å½•åƒç‰æŒ‰é’®ï¼Œç‚¹å‡»ä¸åŒæŒ‰é’®å°†æ‹‰èµ·ç›¸æœºåº”用的ä¸åŒé¡µé¢ï¼Œä»Žè€Œæ高用户的体验。 +在å¡ç‰‡ä¸ä½¿ç”¨**postCardAction**接å£çš„router能力,能够快速拉起å¡ç‰‡æ供方应用的指定UIAbilityï¼Œå› æ¤UIAbility较多的应用往往会通过å¡ç‰‡æä¾›ä¸åŒçš„跳转按钮,实现一键直达的效果。例如相机å¡ç‰‡ï¼Œå¡ç‰‡ä¸Šæä¾›æ‹ç…§ã€å½•åƒç‰æŒ‰é’®ï¼Œç‚¹å‡»ä¸åŒæŒ‰é’®å°†æ‹‰èµ·ç›¸æœºåº”用的ä¸åŒUIAbility,从而æ高用户的体验。 ![WidgerCameraCard](figures/WidgerCameraCard.png) diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-event-uiability.md b/zh-cn/application-dev/application-models/arkts-ui-widget-event-uiability.md index 141d66506508cd60d12b76c8d98da70e918612d6..502085500187180e1a8e9286c93df3c71a1b1c48 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-event-uiability.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-event-uiability.md @@ -1,9 +1,11 @@ -# 通过UIAbility刷新å¡ç‰‡å†…容 +# 通过router或call事件刷新å¡ç‰‡å†…容 在å¡ç‰‡é¡µé¢ä¸å¯ä»¥é€šè¿‡**postCardAction**接å£è§¦å‘router事件或者call事件拉起UIAbility,然åŽç”±UIAbility刷新å¡ç‰‡å†…容,下é¢æ˜¯è¿™ç§åˆ·æ–°æ–¹å¼çš„简å•ç¤ºä¾‹ã€‚ +## 通过router事件刷新å¡ç‰‡å†…容 + - 在å¡ç‰‡é¡µé¢é€šè¿‡æ³¨å†ŒButtonçš„onClick点击事件回调,并在回调ä¸è°ƒç”¨**postCardAction**接å£è§¦å‘事件至FormExtensionAbility。 ```ts @@ -84,3 +86,104 @@ ... } ``` + +## 通过call事件刷新å¡ç‰‡å†…容 + +- 在使用**postCardAction**接å£çš„call事件时,需è¦åœ¨FormExtensionAbilityä¸çš„onAddForm生命周期回调ä¸æ›´æ–°formId。 + + ```ts + import formBindingData from '@ohos.app.form.formBindingData'; + import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; + + export default class EntryFormAbility extends FormExtensionAbility { + onAddForm(want) { + let formId = want.parameters["ohos.extra.param.key.form_identity"]; + let dataObj1 = { + "formId": formId + }; + let obj1 = formBindingData.createFormBindingData(dataObj1); + return obj1; + } + + ... + }; + ``` + +- 在å¡ç‰‡é¡µé¢é€šè¿‡æ³¨å†ŒButtonçš„onClick点击事件回调,并在回调ä¸è°ƒç”¨**postCardAction**接å£è§¦å‘call事件至UIAbility。 + + ```ts + let storage = new LocalStorage(); + @Entry(storage) + @Component + struct WidgetCard { + @LocalStorageProp('detail') detail: string = 'init'; + @LocalStorageProp('formId') formId: string = '0'; + + build() { + Column() { + Button('拉至åŽå°') + .margin('20%') + .onClick(() => { + console.info('postCardAction to EntryAbility'); + postCardAction(this, { + 'action': 'call', + 'abilityName': 'EntryAbility', // åªèƒ½æ‹‰èµ·å½“å‰åº”用下的UIAbility + 'params': { + 'method': 'funA', + 'formId': this.formId, + 'detail': 'CallFromCard' + } + }); + }) + Text(`${this.detail}`).margin('20%') + } + .width('100%') + .height('100%') + } + } + ``` + +- 在UIAbilityçš„onCreate生命周期ä¸ç›‘å¬call事件所需的方法,然åŽåœ¨å¯¹åº”方法ä¸è°ƒç”¨[updateForm](../reference/apis/js-apis-app-form-formProvider.md#updateform)接å£åˆ·æ–°å¡ç‰‡ã€‚ + + ```ts + import UIAbility from '@ohos.app.ability.UIAbility'; + import formBindingData from '@ohos.app.form.formBindingData'; + import formProvider from '@ohos.app.form.formProvider'; + import formInfo from '@ohos.app.form.formInfo'; + + const MSG_SEND_METHOD: string = 'funA' + + // 在收到call事件åŽä¼šè§¦å‘callee监å¬çš„方法 + function FunACall(data) { + // 获å–call事件ä¸ä¼ 递的所有å‚æ•° + let params = JSON.parse(data.readString()) + if (params.formId !== undefined) { + let curFormId = params.formId; + let message = params.detail; + console.info(`UpdateForm formId: ${curFormId}, message: ${message}`); + let formData = { + "detail": message + }; + let formMsg = formBindingData.createFormBindingData(formData) + formProvider.updateForm(curFormId, formMsg).then((data) => { + console.info('updateForm success.' + JSON.stringify(data)); + }).catch((error) => { + console.error('updateForm failed:' + JSON.stringify(error)); + }) + } + return null; + } + export default class EntryAbility extends UIAbility { + // 如果UIAbility第一次å¯åŠ¨ï¼Œcall事件åŽä¼šè§¦å‘onCreate生命周期回调 + onCreate(want, launchParam) { + console.info('Want:' + JSON.stringify(want)); + try { + // 监å¬call事件所需的方法 + this.callee.on(MSG_SEND_METHOD, FunACall); + } catch (error) { + console.log(`${MSG_SEND_METHOD} register failed with error ${JSON.stringify(error)}`) + } + } + ... + } + ```