OpenHarmony上使用服務(wù)卡片

服務(wù)卡片是一種界面展示形式，將服務(wù)的重要信息以卡片的形式展示給用戶，用戶可通過輕量交互行為實(shí)現(xiàn)服務(wù)直達(dá)、減少層級(jí)跳轉(zhuǎn)的目的。

原子化服務(wù)卡片的核心理念在于提供用戶容易使用且一目了然的信息內(nèi)容，將智慧化能力融入到原子化服務(wù)卡片的體驗(yàn)中供用戶選擇使用，同時(shí)滿足在不同終端設(shè)備上的展示。

基本概念

卡片使用方：顯示卡片內(nèi)容的宿主應(yīng)用，控制卡片在宿主中展示的位置，如桌面、原子化服務(wù)中心等。

卡片管理服務(wù)：用于管理系統(tǒng)中所添加卡片的常駐代理服務(wù)，包括卡片對(duì)象的管理與使用，以及卡片周期性刷新等。

卡片提供方：提供卡片顯示內(nèi)容的 OpenHarmony 應(yīng)用或原子化服務(wù)，控制卡片的顯示內(nèi)容、控件布局以及控件點(diǎn)擊事件。

注：卡片使用方和提供方不要求常駐運(yùn)行，在需要添加/刪除/請(qǐng)求更新卡片時(shí)，卡片管理服務(wù)會(huì)拉起卡片提供方獲取卡片信息。

運(yùn)作機(jī)制

①卡片管理服務(wù)

包含以下模塊：

周期性刷新：在卡片添加后，根據(jù)卡片的刷新策略啟動(dòng)定時(shí)任務(wù)周期性觸發(fā)卡片的刷新。

卡片緩存管理：在卡片添加到卡片管理服務(wù)后，對(duì)卡片的視圖信息進(jìn)行緩存，以便下次獲取卡片時(shí)可以直接返回緩存數(shù)據(jù)，降低時(shí)延。

卡片生命周期管理：對(duì)于卡片切換到后臺(tái)或者被遮擋時(shí)，暫停卡片的刷新；以及卡片的升級(jí)/卸載場景下對(duì)卡片數(shù)據(jù)的更新和清理。

卡片使用方對(duì)象管理：對(duì)卡片使用方的 RPC 對(duì)象進(jìn)行管理，用于使用方請(qǐng)求進(jìn)行校驗(yàn)以及對(duì)卡片更新后的回調(diào)處理。

通信適配層：負(fù)責(zé)與卡片使用方和提供方進(jìn)行 RPC 通信。

②卡片提供方

包含以下模塊：

卡片服務(wù)：由卡片提供方開發(fā)者實(shí)現(xiàn)，開發(fā)者實(shí)現(xiàn) onCreateForm、onUpdateForm 和 onDeleteForm 處理創(chuàng)建卡片、更新卡片以及刪除卡片等請(qǐng)求，提供相應(yīng)的卡片服務(wù)。

卡片提供方實(shí)例管理模塊：由卡片提供方開發(fā)者實(shí)現(xiàn)，負(fù)責(zé)對(duì)卡片管理服務(wù)分配的卡片實(shí)例進(jìn)行持久化管理。

通信適配層：由 OpenHarmony SDK 提供，負(fù)責(zé)與卡片管理服務(wù)通信，用于將卡片的更新數(shù)據(jù)主動(dòng)推送到卡片管理服務(wù)。

卡片類別

①尺寸分類

每個(gè)原子化服務(wù)可以配置多個(gè)原子化服務(wù)卡片，原子化服務(wù)卡片有微（1×2）、小（ 2×2 ）、中（ 2×4 ）、大(4×4)4 種尺寸，圖示展示了不同尺寸的卡片。

②場景分類

服務(wù)卡片按照不同應(yīng)用場景使用的應(yīng)用模型分類，可分為 FA 卡片、Stage 卡片。

FA 卡片

FA 卡片開發(fā)，即基于 FA 模型的卡片提供方開發(fā)，主要涉及如下功能邏輯：

開發(fā)卡片生命周期回調(diào)函數(shù) LifecycleForm。

創(chuàng)建卡片數(shù)據(jù) FormBindingData 對(duì)象。

通過 FormProvider 更新卡片。

開發(fā)卡片頁面。

Stage 卡片

Stage 卡片開發(fā)，即基于 Stage 模型的卡片提供方開發(fā)，主要涉及如下功能邏輯：

卡片生命周期回調(diào)函數(shù) FormExtension 開發(fā)。

創(chuàng)建卡片數(shù)據(jù) FormBindingData 對(duì)象。

通過 FormProvider 更新卡片。

卡片頁面開發(fā)。

本文主要介紹如何拉起卡片服務(wù)，對(duì)于卡片的開發(fā)介紹可以參考社區(qū)已有文檔。 FA 卡片開發(fā)：

https://docs.openharmony.cn/pages/v3.1/zh-cn/application-dev/ability/fa-formability.md/

https://docs.openharmony.cn/pages/v3.1/zh-cn/application-dev/ability/stage-formextension.md/

實(shí)踐探索

原子化服務(wù)卡片分為獨(dú)立服務(wù)卡片和應(yīng)用內(nèi)服務(wù)卡片。其中，獨(dú)立服務(wù)卡片又分為本地卡片和云端卡片。

本地卡片可以直接安裝到設(shè)備上，而云端卡片需要下載并安裝到設(shè)備上。應(yīng)用內(nèi)服務(wù)卡片則是指嵌入到應(yīng)用程序中的服務(wù)卡片，可以提供更加定制化和個(gè)性化的服務(wù)。

卡片提供方可以提供單獨(dú)的服務(wù)卡片，也可以在應(yīng)用內(nèi)提供服務(wù)卡片，這取決于使用場景。

①拉起應(yīng)用內(nèi)卡片

卡片提供方在應(yīng)用內(nèi)提供卡片，應(yīng)用安裝到設(shè)備后，效果如下圖所示：

卡片提供方信息：在已有應(yīng)用中通過 File→New→Service Widget 新建應(yīng)用內(nèi)卡片。

卡片生成后，相關(guān)信息可以在 config.json 文件查看：

卡片使用方修改：調(diào)用 FormComponent 組件。

根據(jù)卡片提供方的卡片 name、bundle、ability、module、dimension 等信息調(diào)用 FormComponent 組件。

參考代碼如下：

FormComponent({
id:0,
name:"widget",
bundle:"com.example.test_card",
ability:"com.example.test_card.FormAbility",
module:"entry",
dimension:FormDimension.Dimension_2_2
})
.allowUpdate(true)
.size({width:360,height:360})
.visibility(Visibility.Visible)
.onAcquired((form)=>{
console.log(`forminfo:${JSON.stringify(form)}`);
this.formId=form.id;
})
.onError((err)=>{
console.log(`zjxappfailtoaddform,err:${JSON.stringify(err)}`);
})

https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-formcomponent.md

"abilities":[
{
"name":"EntryAbility",
"srcEntrance":"./ets/entryability/EntryAbility.ts",
"description":"$string:EntryAbility_desc",
"icon":"$media:icon",
"label":"$string:EntryAbility_label",
"startWindowIcon":"$media:icon",
"startWindowBackground":"$color:start_window_background",
"visible":true,
"skills":[
{
"entities":[
"entity.system.home"
],
"actions":[
"action.system.home"
]
}
]
}
],
"requestPermissions":[
{
"name":"ohos.permission.GET_BUNDLE_INFO"
},
{
"name":"ohos.permission.GET_BUNDLE_INFO_PRIVILEGED"
},
{
"name":"ohos.permission.REQUIRE_FORM"
}
]

②拉起獨(dú)立的卡片

單獨(dú)的服務(wù)卡片安裝到設(shè)備后，可以通過 hdc shell 命令查詢到對(duì)應(yīng)的卡片服務(wù)。

#ps-ef|grep"com.zjxtest.hmservice"

卡片提供方信息：工程模板通過選擇工程類型為"Atomic service"，可以新建獨(dú)立的服務(wù)卡片。

entrysrcmainmodule.json5 中可以查看卡片相關(guān)信息：

卡片使用方修改：調(diào)用 FormComponent 組件。

根據(jù)卡片提供方的卡片 name、bundle、ability、module、dimension 等信息調(diào)用 FormComponent 組件。

參考代碼如下：

FormComponent({
id:0,
name:"widget",
bundle:"com.example.test_card",
ability:"EntryFormAbility",
module:"entry",
dimension:FormDimension.Dimension_2_2
})
.allowUpdate(true)
.size({width:360,height:360})
.visibility(Visibility.Visible)
.onAcquired((form)=>{
console.log(`forminfo:${JSON.stringify(form)}`);
this.formId=form.id;
})
.onError((err)=>{
console.log(`zjxappfailtoaddform,err:${JSON.stringify(err)}`);
})

注：ability 與應(yīng)用內(nèi)的服務(wù)卡片有所區(qū)別。

增加權(quán)限：參考上面增加權(quán)限部分。

總結(jié)

本文介紹了兩種類型的卡片，獨(dú)立服務(wù)卡片、應(yīng)用內(nèi)服務(wù)卡片。 獨(dú)立服務(wù)卡片是指可以獨(dú)立安裝和運(yùn)行的服務(wù)卡片，可以提供各種功能和服務(wù)，如天氣、新聞、音樂等。 獨(dú)立服務(wù)卡片又分為本地卡片和云端卡片。本地卡片可以直接安裝到設(shè)備上，而云端卡片需要下載并安裝到設(shè)備上。 應(yīng)用內(nèi)服務(wù)卡片是指嵌入到應(yīng)用程序中的服務(wù)卡片，可以提供更加定制化和個(gè)性化的服務(wù)。 應(yīng)用內(nèi)服務(wù)卡片通常與應(yīng)用程序緊密集成，可以提供更加便捷和高效的服務(wù)。應(yīng)用內(nèi)服務(wù)卡片可以根據(jù)應(yīng)用程序的需求和用戶的偏好進(jìn)行定制和開發(fā)，可以提供更加豐富和多樣化的服務(wù)。 最后對(duì)如何兩種類型的拉起方式做了介紹，希望可以給初學(xué)開發(fā)者一些幫助。

作者：趙軍霞

審核編輯：湯梓紅