看本文章之前需要先熟悉一下原子化服務(wù)特征和流程 HarmonyOS-5分鐘教會(huì)你原子化服務(wù)。

服務(wù)卡片（以下簡(jiǎn)稱“卡片”）是 FA 的一種界面展示形式，將 FA 的重要信息或操作前置到卡片，以達(dá)到服務(wù)直達(dá)，減少體驗(yàn)層級(jí)的目的。

卡片常用于嵌入到其他應(yīng)用（當(dāng)前只支持系統(tǒng)應(yīng)用）中作為其界面的一部分顯示，并支持拉起頁(yè)面，發(fā)送消息等基礎(chǔ)的交互功能。卡片使用方負(fù)責(zé)顯示卡片。

卡片提供方：開(kāi)發(fā)者僅需作為卡片提供方進(jìn)行服務(wù)卡片內(nèi)容的開(kāi)發(fā)，控制卡片實(shí)際顯示的內(nèi)容、控件布局以及控件點(diǎn)擊事件。

卡片使用方：顯示卡片內(nèi)容的宿主應(yīng)用，控制卡片在宿主中展示的位置。

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

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

服務(wù)卡片的運(yùn)作機(jī)制

先上圖：

卡片管理服務(wù)包含以下模塊：

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

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

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

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

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

卡片提供方包含以下模塊：

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

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

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

服務(wù)卡片開(kāi)發(fā)簡(jiǎn)介

關(guān)于服務(wù)卡片的接口說(shuō)明，Java 卡片與 JS 卡片選型，約束與限制可以去官網(wǎng)上查看：

https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ability-service-widget-provider-intro-0000001150722105

Java 卡片開(kāi)發(fā)

這次先來(lái)講解 Java 卡片開(kāi)發(fā)，后期會(huì)專門(mén)用一篇來(lái)講解 JS 卡片開(kāi)發(fā)。

使用 DevEco Studio 創(chuàng)建卡片工程（前面文章已經(jīng)說(shuō)明，這里不再累述）。

我們先看看配置文件 config.json：

"forms":[
{
"landscapeLayouts":[
"$layout:form_weather_widget_2_2"
],
"isDefault":true,
"scheduledUpdateTime":"10:30",
"defaultDimension":"2*2",
"name":"widget",
"description":"Thisisaservicewidget",
"colorMode":"auto",
"type":"Java",
"supportDimensions":[
"2*2"
],
"portraitLayouts":[
"$layout:form_weather_widget_2_2"
],
"updateEnabled":true,
"updateDuration":1
}
],

①“type”：默認(rèn)值是 JS，我們需要更改為“Java”代表是一個(gè) Java 卡片。

②“scheduledUpdateTime”：表示卡片的定點(diǎn)刷新的時(shí)刻，采用 24 小時(shí)制，精確到分鐘。但是我在設(shè)置時(shí)間點(diǎn)的時(shí)候并沒(méi)有更新，具體原因待考察。

"scheduledUpdateTime":"10:30",

③“updateEnabled”：表示卡片是否支持周期性刷新，取值范圍：

• true：表示支持周期性刷。

• false：表示不支持周期性刷新。

④“updateDuration”：表示卡片定時(shí)刷新的更新周期，單位為 30 分鐘，取值為自然數(shù)。

• 當(dāng)取值為 0 時(shí)，表示該參數(shù)不生效。

• 當(dāng)取值為正整數(shù) N 時(shí)，表示刷新周期為 30*N 分鐘。

"updateEnabled":true,
"updateDuration":1

設(shè)置卡片定時(shí)刷新，每 30 分鐘更新一次。

⑤“supportDimensions”：表示卡片支持的外觀規(guī)格，取值范圍：

• 1*2：表示 1 行 2 列的二宮格。

• 2*2：表示 2 行 2 列的四宮格。

• 2*4：表示 2 行 4 列的八宮格。

• 4*4：表示 4 行 4 列的十六宮格。

⑥“portraitLayouts”：表示卡片外觀規(guī)格對(duì)應(yīng)的豎向布局文件，與 supportDimensions 中的規(guī)格一一對(duì)應(yīng)。僅當(dāng)卡片類型為 Java 卡片時(shí)，需要配置該標(biāo)簽。

⑦“l(fā)andscapeLayouts”：表示卡片外觀規(guī)格對(duì)應(yīng)的橫向布局文件，與 supportDimensions 中的規(guī)格一一對(duì)應(yīng)。僅當(dāng)卡片類型為 Java 卡片時(shí)，需要配置該標(biāo)簽。

MainAbility 中覆寫(xiě)卡片相關(guān)回調(diào)函數(shù)：

• onCreateForm(Intent intent)

• onUpdateForm(long formId)

• onDeleteForm(long formId)

• onCastTempForm(long formId)

• onEventNotify(Map formEvents)

• onAcquireFormState(Intent intent)

當(dāng)卡片使用方請(qǐng)求獲取卡片時(shí)，卡片提供方會(huì)被拉起并調(diào)用 onCreateForm(Intent intent) 回調(diào)，intent 中會(huì)帶有卡片 ID，卡片名稱，臨時(shí)卡片標(biāo)記和卡片外觀規(guī)格信息。

代碼如下：

protectedProviderFormInfoonCreateForm(Intentintent){
HiLog.info(TAG,"onCreateForm");
//卡片id
longformId=intent.getLongParam(AbilitySlice.PARAM_FORM_IDENTITY_KEY,INVALID_FORM_ID);
//卡片名稱
StringformName=intent.getStringParam(AbilitySlice.PARAM_FORM_NAME_KEY);
//卡片規(guī)格
intdimension=intent.getIntParam(AbilitySlice.PARAM_FORM_DIMENSION_KEY,DEFAULT_DIMENSION_2X2);
HiLog.info(TAG,"onCreateForm:formId="+formId+",formName="+formName+",dimension="+dimension);
//將卡片信息存入數(shù)據(jù)庫(kù)
saveFormInfo(formId,formName,dimension);

//開(kāi)發(fā)者需要根據(jù)卡片的名稱以及外觀規(guī)格獲取對(duì)應(yīng)的xml布局并構(gòu)造卡片對(duì)象，此處ResourceTable.Layout_form_weather_widget_2_2
ProviderFormInfoformInfo=newProviderFormInfo(ResourceTable.Layout_form_weather_widget_2_2,this);
//獲取此 ProviderFormInfo 對(duì)象中包含的ComponentProvider數(shù)據(jù)。
ComponentProvidercomponentProvider=formInfo.getComponentProvider();
//設(shè)置組件的文本內(nèi)容
componentProvider.setText(ResourceTable.Id_weather_text,"天氣:多云");
componentProvider.setText(ResourceTable.Id_weather_temperature,"溫度:29度");
componentProvider.setText(ResourceTable.Id_weather_ph,"PH值:2.9");
//將ComponentProvider中指定的操作合并到此ProviderFormInfo對(duì)象中包含的ComponentProvider對(duì)象中
formInfo.mergeActions(componentProvider);
returnformInfo;
}

布局：form_weather_widget_2_2.xml

<DependentLayout
xmlns:ohos="http://schemas.huawei.com/res/ohos"
ohos:height="match_parent"
ohos:width="match_parent"
ohos:background_element="#FFFFFFFF"
ohos:remote="true">

<Image
ohos:height="match_parent"
ohos:width="126vp"
ohos:horizontal_center="true"
ohos:image_src="$media:weather"
ohos:scale_mode="zoom_start"
ohos:top_margin="17vp"/>

<DirectionalLayout
ohos:height="match_content"
ohos:width="match_content"
ohos:align_parent_bottom="true"
ohos:bottom_margin="12vp"
ohos:horizontal_center="true"
ohos:orientation="vertical">

<Text
ohos:id="$+id:weather_text"
ohos:height="match_content"
ohos:width="match_parent"
ohos:text="天氣:晴"
ohos:text_color="#E5000000"
ohos:text_size="12fp"
ohos:text_weight="400"
ohos:top_margin="2vp"
ohos:truncation_mode="ellipsis_at_end"/>

<Text
ohos:id="$+id:weather_temperature"
ohos:height="match_content"
ohos:width="match_parent"
ohos:text="溫度:25度"
ohos:text_color="#99000000"
ohos:text_size="12fp"
ohos:text_weight="400"
ohos:top_margin="2vp"
ohos:truncation_mode="ellipsis_at_end"/>
<Text
ohos:id="$+id:weather_ph"
ohos:height="match_content"
ohos:width="match_parent"
ohos:text="PH值:2.5"
ohos:text_color="#99000000"
ohos:text_size="12fp"
ohos:text_weight="400"
ohos:top_margin="2vp"
ohos:truncation_mode="ellipsis_at_end"/>
DirectionalLayout>
DependentLayout>

當(dāng)需要卡片提供方更新數(shù)據(jù)時(shí)（如觸發(fā)了定時(shí)更新、定點(diǎn)更新或者卡片使用方主動(dòng)請(qǐng)求更新），卡片提供方獲取最新數(shù)據(jù)，并調(diào)用 updateForm 接口更新卡片。

示例如下：

protectedvoidonUpdateForm(longformId){
HiLog.info(TAG,"onUpdateForm");
super.onUpdateForm(formId);
refeshData();
}

/**
*updateforms
*/
privatevoidrefeshData(){
//獲取卡片集合
ListformList=DatabaseUtils.queryForms(this,null);

for(FormInfoformInfo:formList){
ProviderFormInforefesh=newProviderFormInfo(ResourceTable.Layout_form_weather_widget_2_2,this);

ComponentProvidercomponentProvider=refesh.getComponentProvider();
//這里更新的值，實(shí)際使用中可根據(jù)自己項(xiàng)目要求設(shè)置,比如:隨機(jī)獲取一個(gè)值
componentProvider.setText(ResourceTable.Id_weather_text,"天氣:多云轉(zhuǎn)晴");
componentProvider.setText(ResourceTable.Id_weather_temperature,"溫度:30度");
componentProvider.setText(ResourceTable.Id_weather_ph,"PH值:3.0");
try{
//卡片提供方主動(dòng)更新卡片
updateForm(formInfo.getFormId(),componentProvider);
}catch(FormExceptione){
HiLog.error(TAG,"FormException");
}
}
}

定時(shí)更新效果：

總結(jié)

實(shí)際項(xiàng)目中需要通過(guò)網(wǎng)絡(luò)獲取數(shù)據(jù)，這里只是簡(jiǎn)單的模擬數(shù)據(jù)。

只是簡(jiǎn)單說(shuō)明了服務(wù)卡片創(chuàng)建的回調(diào)方法實(shí)現(xiàn)，定點(diǎn)和定時(shí)數(shù)據(jù)更新的時(shí)機(jī)和回調(diào)方法的實(shí)現(xiàn)，下期會(huì)更新關(guān)于服務(wù)卡片信息持久化、卡片控制事件。

審核編輯 ：李倩