服務卡片概述

1.什么是服務卡片

HarmonyOS 2的到來，讓很多開發(fā)者眼前一亮。HarmonyOS 2推出的服務卡片，是FA（Feature Ability）的界面展現(xiàn)形式，將FA的重要信息或者操作前置到卡片上，以達到服務直達的目的。

卡片實際界面如下圖所示。

如圖所示，桌面上混合著服務卡片和應用圖標。如上面的天氣服務卡片，展示了多時段天氣；運動健康的服務卡片，展示了運動步數(shù)等重要信息。如果應用圖標下方有提示條，則表示該應用嵌有服務卡片，可以通過手指在該圖標上滑呼出服務卡片，如上圖的天氣、圖庫、運動健康、備忘錄等，均可以上滑圖標呼出服務卡片。

服務卡片有三個特征：易用可見、智能可選和多端可變。

易用可見：凸顯服務信息的內(nèi)容外露，減少層級跳轉(zhuǎn)。

智能可選：全天可變的數(shù)據(jù)信息，支持自定義類型的服務卡片設(shè)計。

多端可變：適配多端設(shè)備的自適應屬性。

2.服務卡片設(shè)計規(guī)范

數(shù)量選擇
?
【每個應用均能配置多個服務卡片，但是每個Page Ability配置的服務卡片總數(shù)不能超過16個】

例如：一個天氣的應用可以制作當?shù)靥鞖狻⒍鄷r段天氣、多天天氣、穿衣提醒等不同內(nèi)容的卡片信息，但如果將這些卡片配置在同一個Page Ability上，總數(shù)量不可以超過16個。

【每個服務卡片可以選擇4種服務卡片尺寸】

例如：系統(tǒng)為每個應用提供4種尺寸規(guī)格以供選擇，小尺寸的卡片尺寸為必選項。

【每個服務卡片被用戶使用時可以創(chuàng)建多個實例】

例如：用戶手動添加了當?shù)靥鞖獾姆湛ㄆ梢酝ㄟ^對單個服務卡片的重復添加來實現(xiàn)多個實例。
?
尺寸選擇
?
每個應用在選擇服務卡片時，按需選擇對應尺寸，保證內(nèi)容效益最大化。

服務卡片尺寸分為：微（1×2）、?。?2×2 ）、中（ 2×4 ）、大(4×4)4種尺寸，其中小尺寸為必選尺寸。

同一種尺寸還支持多個不同內(nèi)容布局的卡片，可以通過服務卡片管理界面進行選擇，應用方可以指定某一個服務卡片作為默認展示。

【微尺寸】

微尺寸卡片能提供簡單的數(shù)據(jù)信息，快捷指令和快捷入口。比如一個音樂應用可以提供一個微尺寸卡片，僅展示歌曲名字和歌手名字，以及歌曲縮略圖，運動健康展示步數(shù)數(shù)據(jù)，行程信息提供航班號和登機時間等。

【小尺寸】

小尺寸卡片能提供精簡的服務信息內(nèi)容、豐富的展示特性信息、即時信息或操作提示等。比如行程信息除了提供航班信息，還提供了查看詳情的操作。

【中尺寸和大尺寸】

中尺寸和大尺寸卡片能提供兩種以上緯度的服務信息展示和多個可交互的熱區(qū)展示，展示更加沉浸豐富的視覺圖片以及采用多個宮格和列表內(nèi)容展示。比如運動健康采用中尺寸卡片展示了步數(shù)和運動強度兩個緯度的信息。玩機技巧采用宮格方式推薦了多個應用入口。
?
內(nèi)容構(gòu)成
?
服務卡片由多種設(shè)計元素組合而成，以下7種常見信息元素可以作為內(nèi)容選擇：
?
圖標、數(shù)據(jù)、文本、按鈕、圖片、宮格、列表
?
在組織服務卡片內(nèi)容的時候可以按照尺寸的大小來判斷應當選擇哪種元素，包括元素組合的數(shù)量。

如上圖所示，對于微尺寸卡片，建議卡片上內(nèi)容元素不超過2種，可以在“圖標、數(shù)據(jù)、文本、圖片”中選擇最多兩種元素進行組合，以達內(nèi)容收益盡可能多且不顯得繁雜。對于小尺寸卡片，建議卡片上的內(nèi)容不超過3種，可以在“圖標、數(shù)據(jù)、文本、按鈕、圖片”中選擇最多3種元素進行組合。中/大尺寸卡片可根據(jù)業(yè)務需要自由選擇。

服務卡片運行機制

1.服務卡片整體框架

服務卡片整體框架主要包含三部分：卡片使用方、卡片管理服務和卡片提供方。

● 卡片使用方

顯示卡片內(nèi)容的宿主應用，控制卡片在宿主中展示的位置，如桌面、服務中心、搜索等。

● 卡片管理服務

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

● 卡片提供方

提供卡片顯示內(nèi)容的HarmonyOS應用或原子化服務，控制卡片的顯示內(nèi)容、控件布局以及控件點擊事件。

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

當卡片主動刷新時候，具體流程如下：

1. 當卡片使用方如“桌面”，呼出服務卡片時，通過Java kit中的SDK客戶端向卡片管理服務請求卡片對象。

2. 卡片管理服務會檢查其緩存管理模塊是否存在該卡片對象實例，如果存在，則會立即返回該卡片對象給卡片使用方；

3. 如果不存在，則會通過卡片提供方kit，向卡片提供方索取該卡片數(shù)據(jù)，并生成卡片對象；

4. 卡片管理服務會拉起服務卡片F(xiàn)A，回調(diào)刷新函數(shù)更新卡片數(shù)據(jù)，并將刷新數(shù)據(jù)返回給卡片管理服務；

5. 卡片管理服務會檢查是否存在卡片使用方宿主，存在則會將卡片提供方數(shù)據(jù)刷新到卡片使用方宿主實例緩存中，不存在則可能是系統(tǒng)異常無法刷新；

6. 卡片管理服務通過服務接口將卡片數(shù)據(jù)傳到卡片使用方（如“桌面”），宿主應用界面顯示數(shù)據(jù)。

當卡片定時/定點刷新時候，具體流程如下：

1. 當一個服務卡片在config.json中配置了定時或者定點刷新時，timer事件會通知卡片管理服務；

2. 卡片管理服務會去卡片提供方對象管理模塊中找到對應的卡片提供方；通過卡片提供方kit，回調(diào)卡片提供方的刷新函數(shù)，卡片提供方刷新數(shù)據(jù)返回給卡片管理服務。

3. 卡片管理服務根據(jù)卡片名稱查找卡片使用方宿主，并刷新卡片使用方宿主對象緩存數(shù)據(jù)。

4. 接著通過服務接口將卡片數(shù)據(jù)傳到卡片使用方中，宿主應用界面顯示數(shù)據(jù)。

服務卡片根據(jù)開發(fā)方式可以分為Java服務卡片和JS服務卡片，Java服務卡片返回的實例采用ComponentProvider方式顯示在服務卡片使用方上，JS服務卡片是通過ACE引擎加載和解析hap包的卡片資源，如hml、css和config.json文件，解析引擎解析完hml和css后進行渲染，結(jié)合數(shù)據(jù)生成InstantView顯示在服務卡片使用方指定的位置上。

2.服務卡片生命周期回調(diào)函數(shù)

卡片提供方控制卡片實際顯示的內(nèi)容、控件布局以及控件點擊事件。應用或原子化服務想要成為一個卡片提供方，需要實現(xiàn)卡片相關(guān)的回調(diào)函數(shù)：

服務卡片關(guān)鍵回調(diào)函數(shù)如下：

服務卡片生命周期回調(diào)函數(shù)時序如下：

卡片管理服務不負責卡片應用進程?；?，卡片管理服務在相應的時機拉起卡片提供方進程，調(diào)用創(chuàng)建、更新、刪除卡片等回調(diào)。

服務卡片開發(fā)過程

下面以JS服務卡片開發(fā)為例，介紹服務卡片的開發(fā)過程。

1.服務卡片開發(fā)環(huán)境

華為近期發(fā)布了最新的HarmonyOS IDE版本：DevEco Studio 2.1 Release，該版本已經(jīng)支持了服務卡片的開發(fā)。DevEco Studio 開發(fā)卡片環(huán)境如下圖所示：

【創(chuàng)建服務卡片項目步驟】

1.新建一個Project，根據(jù)項目需要選擇JS或者Java的項目模板，建議選擇JS項目工程。

2.在“Configure your project”中，打開“Show In Service Center”，表示在服務中心中展示。

3.Finish之后就能創(chuàng)建一個帶有服務卡片的項目。

說明
如果在步驟1中采用Java項目，則默認創(chuàng)建Java服務卡片，如果采用JS項目，則默認創(chuàng)建JS服務卡片。

詳細創(chuàng)建項目過程可以參考官網(wǎng)資料【開發(fā)服務卡片】。

● 開發(fā)服務卡片

 https://developer./cn/docs/documentation/doc-guides/ide_service_widget-0000001078566997

2.JS服務卡片開發(fā)過程

JS服務卡片開發(fā)主要分為四步：

1. 配置config.json

2. 實現(xiàn)生命周期回調(diào)方法

3. 開發(fā)卡片界面元素

4. 實現(xiàn)卡片界面交互

1.配置config.json

config.json整體結(jié)構(gòu)

采用DevEco Studio創(chuàng)建帶有服務卡片的Project之后，會生成下面的config.json的配置文件。

如上圖所示，config.json文件是項目創(chuàng)建之后生成的配置文件，其中”js”配置了兩個json對象，第一個name屬性值為”default”是JS UI的界面配置。name屬性值為“service_widget”的是服務卡片的配置，type的屬性值是form表示該JS配置是一個服務卡片。

JS服務卡片的工程目錄如下：

● common目錄主要存放公共資源；

● i18n目錄是存放國際化資源；

● pages.index目錄（實際是pages/index）存放服務卡片界面開發(fā)主要文件，里面采用hml+css+json文件組合，構(gòu)成JS服務卡片界面。

config.json中abilities配置forms細節(jié)

在abilities的json配置中，配置了forms屬性值，如下圖所示：

forms配置在哪個Ability上，服務卡片聲明周期回調(diào)方法就會在哪個Ability上回調(diào)執(zhí)行。

● formsEnable的值若設(shè)置為true，則表示該Ability支持服務卡片顯示。

● forms的值是一個json 數(shù)組，表示可配置多張服務卡片。

● jsComponentName是JS服務卡片名字，僅JS服務卡片上需要配置（Java卡片不需要配置），其名字需要和js配置的name一致，表示js組件實例。

● isDefault為true表示該卡片是一個默認卡片。Ability可以配置多張服務卡片，其中僅有一張是默認卡片，即在圖標上滑呼出的卡片。

● scheduledUpdateTime表示卡片定時/定點觸發(fā)更新的時間。

● defaultDimension表示默認卡片的尺寸是22，其他的可選12，24，44尺寸。對于需要在服務中心露出的卡片，默認規(guī)格必須設(shè)置成2*2。

● type表示服務卡片類型，有JS和Java兩種，本次配置選擇為JS。

● updateDuration表示服務卡片刷新的時間間隔，以30min作為單位，1表示30min，2表示1個小時，以此類推。

forms的其他屬性參考官網(wǎng)資料【服務卡片-JS卡片開發(fā)】。

● 服務卡片-JS卡片開發(fā)

 https://developer./cn/docs/documentation/doc-guides/ability-service-widget-provider-js-0000001150602175

配置卡片編輯功能（可選功能）

有些服務卡片需要具備可編輯能力，如天氣App需要編輯所在城市。具體實現(xiàn)方法如下：

在config.json中，對某一個form的配置增加formConfigAbility的屬性配置，可實現(xiàn)編輯功能。formConfigAbility的值是一個url格式的Ability名稱。若不配置formConfigAbility，則不顯示編輯菜單。示例代碼如下：

實現(xiàn)效果如下圖所示：

長按服務卡片，會彈出編輯菜單選項：

2.實現(xiàn)生命周期回調(diào)方法

創(chuàng)建一個Form Ability，并覆寫Ability在服務卡片上相應的回調(diào)函數(shù)：

● onCreateForm(Intent intent)

● onUpdateForm(long formId)

● onDeleteForm(long formId)

● onCastTempForm(long formId)

● onEventNotify(Map<Long,Integer>formEvents)

● onTriggerFormEvent(long formId, String message)

下面重點給大家介紹onCreatForm和onUpdateForm的使用方法，其他回調(diào)函數(shù)以此類推。
?
onCreateForm方法
?
當卡片使用方請求獲取卡片時，卡片提供方會被拉起并調(diào)用onCreateForm(Intent intent)回調(diào)，intent中會帶有卡片ID，卡片名稱和卡片外觀規(guī)格信息，可按需獲取使用。onCreateForm方法代碼示例如下：

可以通過intent變量獲取到卡片相關(guān)的信息，intent中攜帶的信息如下表：

首先，可以通過卡片名字區(qū)分不同的卡片，根據(jù)不同的卡片執(zhí)行不同的業(yè)務邏輯。其次可以根據(jù)卡片的尺寸設(shè)置不同的卡片內(nèi)容。最終需要刷新卡片數(shù)據(jù)時，需要創(chuàng)建一個ZSONObject對象，將key-value設(shè)置進去，其中key需要和index.json中的data數(shù)據(jù)中的key保持一致。然后創(chuàng)建一個ProviderFormInfo對象，將ZSONObject對象設(shè)置進去，返回ProviderFormInfo對象給onCreateForm方法。

onUpdateForm方法

當config.json中配置了定點更新或者定時更新，卡片服務會拉起卡片執(zhí)行界面更新。系統(tǒng)會回調(diào)onUpdateForm方法，應用則調(diào)用updateForm去更新卡片內(nèi)容。onUpdateForm方法代碼示例如下：

將需要更新的數(shù)據(jù)設(shè)置到ZSONObject對象中，然后通過FormBindingData對象攜帶ZSONObject對象，調(diào)用updateForm()方法去更新界面。

當定時/定點觸發(fā)之后，以上代碼生效的效果界面如下：

同時日志輸出：

3.開發(fā)卡片界面元素

JS卡片頁面需要開發(fā)三個文件：hml、css、json，json文件主要配置數(shù)據(jù)和點擊事件。詳情請參考官網(wǎng)資料【JSON語法參考】。

● JSON語法參考

 https://developer./cn/docs/documentation/doc-references/js-service-widget-syntax-json-0000001106228840

hml、css和json文件示例內(nèi)容如下：

index.hml文件

index.css文件：

其中hml文件中聲明了服務卡片布局：

● 如果json文件中mini屬性為true，則顯示class=”mini_container”的text控件。

否則不顯示該控件，從而顯示class="items_container"的div布局，該布局從上到下顯示了一張圖片，兩個文本。所以if語句可以作為多張卡片時的判斷條件，用于顯示不同的布局。

● css文件則定義hml布局中的樣式，如寬高度、顏色等。

● json文件中定義卡片支持的數(shù)據(jù)和點擊事件。

實例代碼運行效果如下（運行在模擬器上的顯示效果）：

4.實現(xiàn)卡片界面交互

服務卡片json文件提供數(shù)據(jù)綁定和界面交互。

卡片僅支持click觸發(fā)的事件，事件的定義只能是直接命令式，事件定義必須包含action字段，用以說明事件類型?？ㄆС謨煞N事件類型：跳轉(zhuǎn)事件(router)和消息事件(message)。跳轉(zhuǎn)事件可以跳轉(zhuǎn)到卡片提供方的組件；消息事件可以將開發(fā)者自定義信息傳遞給卡片提供方。

跳轉(zhuǎn)事件格式如下：

消息事件的格式如下：

json的樣例代碼如下：

其中定義了一個routerEvent事件和imageEvent事件，這兩個事件在hml文件中應用代碼如下：

routerEvent事件表示點擊卡片后跳轉(zhuǎn)到其他界面過去，而imageEvent是給圖片賦予了點擊事件，該點擊事件會通過onTriggerFormEvent方法，回調(diào)到Ability中過去。

在跳轉(zhuǎn)事件中，params參數(shù)在onStart()中的intent中可以提取，如下所示：

json文件中params中定義的json對象字符串是通過intent.getStringParam(“params”)獲得，是一個json格式的字符串，可以通過構(gòu)建ZSONObject對象，獲取對應的value值。

在消息事件中，params參數(shù)可以在onTriggerFormEvent的message中提取，如下所示：

json文件中params定義的json對象字符串通過message變量傳遞到Java側(cè)的Ability中，在onTriggerFormEvent方法中可以根據(jù)該json字符串，去做對應的業(yè)務邏輯。

如上面實例代碼所示，運行出來的卡片界面效果如下：

若點擊了服務卡片上的圖片，則圖片下面的文字會變成“點擊后的標題”和“這是通過json文件傳遞的內(nèi)容”，該字符串是在index.json的params中定義的。

3.服務卡片模板

為了方便開發(fā)者快速開發(fā)服務卡片，DevEco Studio中推出了服務卡片模板，分為“Basic”和“Advance”兩類，開發(fā)者可以根據(jù)業(yè)務需要選擇不同的模板。

Grid Pattern（宮格卡片模板）

宮格卡片模板在大尺寸的卡片上特征較為明顯，能夠有規(guī)律進行布局排列。例如展示多排應用圖標，每個熱區(qū)獨立可點擊，或展示影視海報等信息，以凸顯圖片為主，描述文本為輔。

Image With Info（圖文卡片模板）

圖文卡片模板主要在于展現(xiàn)圖片和一定數(shù)量文本的搭配，在這種布局下，圖片和文本屬于同等重要的信息。在不同尺寸下，圖片大小和文本數(shù)量會發(fā)生一定變化，用于凸顯關(guān)鍵信息。

Immersive Pattern（沉浸布局卡片模板）

圖片內(nèi)容是更能夠吸引用戶的展現(xiàn)形式，因此，沉浸式的布局能夠擁有更好的代入感和展現(xiàn)形式。相比較圖文和宮格類，這種布局在造型上的制約會更小，設(shè)計形式上的發(fā)揮空間更大，但在不同設(shè)備下的適配需要注意展示效果。

List Pattern（列表卡片模板）

列表卡片模板是展示信息時的常用界面組件，通常會在列表的左側(cè)或右側(cè)帶有圖片或點綴元素。這類布局的優(yōu)勢在于可以集中的展示較多信息量，并遵循有序的排列。常用于新聞類、搜索類應用，方便用戶獲取關(guān)鍵的文本信息。

Call（通話卡片模板）

通話卡片模板主要用于在桌面顯示自定義的聯(lián)系人圖片和通話按鈕，在這種場景下，可以直接點擊卡片上的通話按鈕進行快速呼叫。

Contact（聯(lián)系人卡片模板）

聯(lián)系人卡片模板主要用于在桌面顯示聯(lián)系人快捷按鈕，點擊某個聯(lián)系人快捷按鈕可快速進入聯(lián)系人詳情頁，實現(xiàn)通過卡片快速跳轉(zhuǎn)聯(lián)系人詳情頁的功能。

DataPattern（數(shù)據(jù)內(nèi)容卡片模板）

數(shù)據(jù)內(nèi)容卡片模板主要用于在桌面展示自定義內(nèi)容的百分占比，這種卡片主體是一個環(huán)形百分比圖，用于凸顯關(guān)鍵的百分比信息。

Functions（功能卡片模板）

功能卡片模板主要用于在桌面上聚合不同功能的快捷入口，通過點擊卡片的某個功能，能夠?qū)崿F(xiàn)快速跳轉(zhuǎn)至對應功能頁面。

MusicPlayer（音樂播放器卡片模板）

音樂播放器卡片模板主要用于在桌面展示一個音樂播放的控制界面，通過點擊卡片上的對應功能按鈕，能夠?qū)崿F(xiàn)對音樂播放的控制。

Schedule（行程卡片模板）

行程卡片模板布局主要用于在卡片上展示行程關(guān)鍵信息，并帶有功能圖標，可通過點擊功能圖標查看詳細行程信息。

Shortcuts（捷徑卡片模板）

捷徑卡片模板布局主要用于在桌面展示多個快捷功能圖標，在這種布局下，每個熱區(qū)獨立可點擊，可快速進入相關(guān)功能。

更多卡片模板詳情和卡片模板使用方法可以參考官網(wǎng)資料【開發(fā)服務卡片】。

● 開發(fā)服務卡片

 https://developer./cn/docs/documentation/doc-guides/ide_service_widget-0000001078566997

4.服務卡片部署

上述的服務卡片代碼和資源，可與App一起打包成一個entry hap進行部署。同時，服務卡片還可以獨立成一個Module，作為HarmonyOS應用的feature進行獨立編譯和部署。無論是打包部署還是獨立部署，兩種方式構(gòu)建的服務卡片都可在 AGC和HAG市場上架和更新。

卡片代碼部署工程界面如下圖所示：

小Tips：調(diào)試安裝時，需要和Entry一起安裝，參考以下命令行：

總結(jié)
服務卡片作為HarmonyOS應用和原子化服務的一部分對外呈現(xiàn)重要的信息，具有易用、智能、多端部署特性，能給用戶帶來嶄新的交互體驗。
本文整體介紹了HarmonyOS服務卡片的運行原理和開發(fā)方法，服務卡片運行過程中主要是卡片管理服務作為中間樞紐，連接著卡片使用方和卡片提供方。服務卡片開發(fā)過程主要分為配置config.json、實現(xiàn)生命周期回調(diào)方法、開發(fā)卡片界面元素和界面交互，基于HarmonyOS提供的回調(diào)函數(shù)方法，簡單的幾步就能開發(fā)出業(yè)務所需的服務卡片。