OpenHarmony上使用服務卡片

服務卡片是一種界面展示形式，將服務的重要信息以卡片的形式展示給用戶，用戶可通過輕量交互行為實現服務直達、減少層級跳轉的目的。

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

基本概念

卡片使用方：顯示卡片內容的宿主應用，控制卡片在宿主中展示的位置，如桌面、原子化服務中心等。

卡片管理服務：用于管理系統中所添加卡片的常駐代理服務，包括卡片對象的管理與使用，以及卡片周期性刷新等。

卡片提供方：提供卡片顯示內容的 OpenHarmony 應用或原子化服務，控制卡片的顯示內容、控件布局以及控件點擊事件。

注：卡片使用方和提供方不要求常駐運行，在需要添加/刪除/請求更新卡片時，卡片管理服務會拉起卡片提供方獲取卡片信息。

運作機制

①卡片管理服務

包含以下模塊：

周期性刷新：在卡片添加后，根據卡片的刷新策略啟動定時任務周期性觸發卡片的刷新。

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

卡片生命周期管理：對于卡片切換到后臺或者被遮擋時，暫?？ㄆ乃⑿?；以及卡片的升級/卸載場景下對卡片數據的更新和清理。

卡片使用方對象管理：對卡片使用方的 RPC 對象進行管理，用于使用方請求進行校驗以及對卡片更新后的回調處理。

通信適配層：負責與卡片使用方和提供方進行 RPC 通信。

②卡片提供方

包含以下模塊：

卡片服務：由卡片提供方開發者實現，開發者實現 onCreateForm、onUpdateForm 和 onDeleteForm 處理創建卡片、更新卡片以及刪除卡片等請求，提供相應的卡片服務。

卡片提供方實例管理模塊：由卡片提供方開發者實現，負責對卡片管理服務分配的卡片實例進行持久化管理。

通信適配層：由 OpenHarmony SDK 提供，負責與卡片管理服務通信，用于將卡片的更新數據主動推送到卡片管理服務。

卡片類別

①尺寸分類

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

②場景分類

服務卡片按照不同應用場景使用的應用模型分類，可分為 FA 卡片、Stage 卡片。

FA 卡片

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

開發卡片生命周期回調函數 LifecycleForm。

創建卡片數據 FormBindingData 對象。

通過 FormProvider 更新卡片。

開發卡片頁面。

Stage 卡片

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

卡片生命周期回調函數 FormExtension 開發。

創建卡片數據 FormBindingData 對象。

通過 FormProvider 更新卡片。

卡片頁面開發。

本文主要介紹如何拉起卡片服務，對于卡片的開發介紹可以參考社區已有文檔。 FA 卡片開發：

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/

實踐探索

原子化服務卡片分為獨立服務卡片和應用內服務卡片。其中，獨立服務卡片又分為本地卡片和云端卡片。

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

卡片提供方可以提供單獨的服務卡片，也可以在應用內提供服務卡片，這取決于使用場景。

①拉起應用內卡片

卡片提供方在應用內提供卡片，應用安裝到設備后，效果如下圖所示：

卡片提供方信息：在已有應用中通過 File→New→Service Widget 新建應用內卡片。

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

卡片使用方修改：調用 FormComponent 組件。

根據卡片提供方的卡片 name、bundle、ability、module、dimension 等信息調用 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"
}
]

②拉起獨立的卡片

單獨的服務卡片安裝到設備后，可以通過 hdc shell 命令查詢到對應的卡片服務。

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

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

entrysrcmainmodule.json5 中可以查看卡片相關信息：

卡片使用方修改：調用 FormComponent 組件。

根據卡片提供方的卡片 name、bundle、ability、module、dimension 等信息調用 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 與應用內的服務卡片有所區別。

增加權限：參考上面增加權限部分。

總結

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

作者：趙軍霞

審核編輯：湯梓紅