一文看懂HarmonyOS服務卡片運行原理和開發方法
服務卡片概述
1、什么是服務卡片
HarmonyOS 2的到來，讓很多開發者眼前一亮。HarmonyOS 2推出的服務卡片，是FA(Feature Ability)的界面展現形式，將FA的重要信息或者操作前置到卡片上，以達到服務直達的目的。
卡片實際界面如下圖所示。
圖1 具有服務卡片的桌面
如圖所示，桌面上混合著服務卡片和應用圖標。如上面的天氣服務卡片，展示了多時段天氣;運動健康的服務卡片，展示了運動步數等重要信息。如果應用圖標下方有提示條，則表示該應用嵌有服務卡片，可以通過手指在該圖標上滑呼出服務卡片，如上圖的天氣、圖庫、運動健康、備忘錄等，均可以上滑圖標呼出服務卡片。
服務卡片有三個特征：易用可見、智能可選和多端可變。
易用可見：凸顯服務信息的內容外露，減少層級跳轉。
智能可選：全天可變的數據信息，支持自定義類型的服務卡片設計。
多端可變：適配多端設備的自適應屬性。
2、服務卡片設計規范
數量選擇
【每個應用均能配置多個服務卡片，但是每個Page Ability配置的服務卡片總數不能超過16個】
例如：一個天氣的應用可以制作當地天氣、多時段天氣、多天天氣、穿衣提醒等不同內容的卡片信息，但如果將這些卡片配置在同一個Page Ability上，總數量不可以超過16個。
【每個服務卡片可以選擇4種服務卡片尺寸】
例如：系統為每個應用提供4種尺寸規格以供選擇，小尺寸的卡片尺寸為必選項。
【每個服務卡片被用戶使用時可以創建多個實例】
例如：用戶手動添加了當地天氣的服務卡片，可以通過對單個服務卡片的重復添加來實現多個實例。
尺寸選擇
每個應用在選擇服務卡片時，按需選擇對應尺寸，保證內容效益最大化。
服務卡片尺寸分為：微(1×2)、小( 2×2 )、中( 2×4 )、大(4×4)4種尺寸，其中小尺寸為必選尺寸。
同一種尺寸還支持多個不同內容布局的卡片，可以通過服務卡片管理界面進行選擇，應用方可以指定某一個服務卡片作為默認展示。
【微尺寸】
圖2 微尺寸服務卡片
微尺寸卡片能提供簡單的數據信息，快捷指令和快捷入口。比如一個音樂應用可以提供一個微尺寸卡片，僅展示歌曲名字和歌手名字，以及歌曲縮略圖，運動健康展示步數數據，行程信息提供航班號和登機時間等。
【小尺寸】
圖3 小尺寸服務卡片
小尺寸卡片能提供精簡的服務信息內容、豐富的展示特性信息、即時信息或操作提示等。比如行程信息除了提供航班信息，還提供了查看詳情的操作。
【中尺寸和大尺寸】
圖4 中尺寸服務卡片
圖5 大尺寸服務卡片
中尺寸和大尺寸卡片能提供兩種以上緯度的服務信息展示和多個可交互的熱區展示，展示更加沉浸豐富的視覺圖片以及采用多個宮格和列表內容展示。比如運動健康采用中尺寸卡片展示了步數和運動強度兩個緯度的信息。玩機技巧采用宮格方式推薦了多個應用入口。
內容構成
服務卡片由多種設計元素組合而成，以下7種常見信息元素可以作為內容選擇：
圖標、數據、文本、按鈕、圖片、宮格、列表
在組織服務卡片內容的時候可以按照尺寸的大小來判斷應當選擇哪種元素，包括元素組合的數量。
圖6 卡片尺寸和元素對應關系圖
如上圖所示，對于微尺寸卡片，建議卡片上內容元素不超過2種，可以在“圖標、數據、文本、圖片”中選擇最多兩種元素進行組合，以達內容收益盡可能多且不顯得繁雜。對于小尺寸卡片，建議卡片上的內容不超過3種，可以在“圖標、數據、文本、按鈕、圖片”中選擇最多3種元素進行組合。中/大尺寸卡片可根據業務需要自由選擇。
服務卡片運行機制
1、服務卡片整體框架
服務卡片整體框架主要包含三部分：卡片使用方、卡片管理服務和卡片提供方。
● 卡片使用方
顯示卡片內容的宿主應用，控制卡片在宿主中展示的位置，如桌面、服務中心、搜索等。
● 卡片管理服務
用于管理系統中所添加卡片的常駐代理服務，包括卡片對象的管理與使用，以及卡片周期性刷新等。
● 卡片提供方
提供卡片顯示內容的HarmonyOS應用或原子化服務，控制卡片的顯示內容、控件布局以及控件點擊事件。
圖7 服務卡片整體框架
說明
卡片使用方和提供方不要求常駐運行，在需要添加/刪除/請求更新卡片時，卡片管理服務會拉起卡片提供方獲取卡片信息。
當卡片主動刷新時候，具體流程如下：
- 當卡片使用方如“桌面”，呼出服務卡片時，通過Java kit中的SDK客戶端向卡片管理服務請求卡片對象。
- 卡片管理服務會檢查其緩存管理模塊是否存在該卡片對象實例，如果存在，則會立即返回該卡片對象給卡片使用方;
- 如果不存在，則會通過卡片提供方kit，向卡片提供方索取該卡片數據，并生成卡片對象;
- 卡片管理服務會拉起服務卡片FA，回調刷新函數更新卡片數據，并將刷新數據返回給卡片管理服務;
- 卡片管理服務會檢查是否存在卡片使用方宿主，存在則會將卡片提供方數據刷新到卡片使用方宿主實例緩存中，不存在則可能是系統異常無法刷新;
- 卡片管理服務通過服務接口將卡片數據傳到卡片使用方(如“桌面”)，宿主應用界面顯示數據。
圖8 服務卡片主動刷新流程圖
當卡片定時/定點刷新時候，具體流程如下：
- 當一個服務卡片在config.json中配置了定時或者定點刷新時，timer事件會通知卡片管理服務;
- 卡片管理服務會去卡片提供方對象管理模塊中找到對應的卡片提供方;通過卡片提供方kit，回調卡片提供方的刷新函數，卡片提供方刷新數據返回給卡片管理服務。
- 卡片管理服務根據卡片名稱查找卡片使用方宿主，并刷新卡片使用方宿主對象緩存數據。
- 接著通過服務接口將卡片數據傳到卡片使用方中，宿主應用界面顯示數據。
圖9 服務卡片定時/定點刷新流程圖
服務卡片根據開發方式可以分為Java服務卡片和JS服務卡片，Java服務卡片返回的實例采用ComponentProvider方式顯示在服務卡片使用方上，JS服務卡片是通過ACE引擎加載和解析hap包的卡片資源，如hml、css和config.json文件，解析引擎解析完hml和css后進行渲染，結合數據生成InstantView顯示在服務卡片使用方指定的位置上。
2、服務卡片生命周期回調函數
卡片提供方控制卡片實際顯示的內容、控件布局以及控件點擊事件。應用或原子化服務想要成為一個卡片提供方，需要實現卡片相關的回調函數：
服務卡片關鍵回調函數如下：
服務卡片生命周期回調函數時序如下：
圖10 服務卡片生命周期回調函數時序圖
卡片管理服務不負責卡片應用進程保活，卡片管理服務在相應的時機拉起卡片提供方進程，調用創建、更新、刪除卡片等回調。
服務卡片開發過程
下面以JS服務卡片開發為例，介紹服務卡片的開發過程。
1、服務卡片開發環境
華為近期發布了最新的HarmonyOS IDE版本：DevEco Studio 2.1 Release，該版本已經支持了服務卡片的開發。DevEco Studio 開發卡片環境如下圖所示：
圖11 DevEco Studio 開發卡片環境圖
【創建服務卡片項目步驟】
1.新建一個Project，根據項目需要選擇JS或者Java的項目模板，建議選擇JS項目工程。
2.在“Configure your project”中，打開“Show In Service Center”，表示在服務中心中展示。
圖12 DevEco Studio 開發卡片設置圖
3.Finish之后就能創建一個帶有服務卡片的項目。
說明
如果在步驟1中采用Java項目，則默認創建Java服務卡片，如果采用JS項目，則默認創建JS服務卡片。
詳細創建項目過程可以參考官網資料【開發服務卡片】。
● 開發服務卡片
https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ide_service_widget-0000001078566997
2、JS服務卡片開發過程
JS服務卡片開發主要分為四步：
配置config.json
實現生命周期回調方法
開發卡片界面元素
實現卡片界面交互
1.配置config.json
config.json整體結構
采用DevEco Studio創建帶有服務卡片的Project之后，會生成下面的config.json的配置文件。
圖13 config.json文件內容
如上圖所示，config.json文件是項目創建之后生成的配置文件，其中”js”配置了兩個json對象，第一個name屬性值為”default”是JS UI的界面配置。name屬性值為“service_widget”的是服務卡片的配置，type的屬性值是form表示該JS配置是一個服務卡片。
JS服務卡片的工程目錄如下：
圖14 JS服務卡片工程目錄圖
● common目錄主要存放公共資源;
● i18n目錄是存放國際化資源;
● pages.index目錄(實際是pages/index)存放服務卡片界面開發主要文件，里面采用hml+css+json文件組合，構成JS服務卡片界面。
config.json中abilities配置forms細節
在abilities的json配置中，配置了forms屬性值，如下圖所示：
圖15 forms屬性值配置
forms配置在哪個Ability上，服務卡片聲明周期回調方法就會在哪個Ability上回調執行。
● formsEnable的值若設置為true，則表示該Ability支持服務卡片顯示。
● forms的值是一個json 數組，表示可配置多張服務卡片。
● jsComponentName是JS服務卡片名字，僅JS服務卡片上需要配置(Java卡片不需要配置)，其名字需要和js配置的name一致，表示js組件實例。
● isDefault為true表示該卡片是一個默認卡片。Ability可以配置多張服務卡片，其中僅有一張是默認卡片，即在圖標上滑呼出的卡片。
● scheduledUpdateTime表示卡片定時/定點觸發更新的時間。
● defaultDimension表示默認卡片的尺寸是22，其他的可選12，24，44尺寸。對于需要在服務中心露出的卡片，默認規格必須設置成2*2。
● type表示服務卡片類型，有JS和Java兩種，本次配置選擇為JS。
● updateDuration表示服務卡片刷新的時間間隔，以30min作為單位，1表示30min，2表示1個小時，以此類推。
forms的其他屬性參考官網資料【服務卡片-JS卡片開發】。
● 服務卡片-JS卡片開發
https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ability-service-widget-provider-js-0000001150602175
配置卡片編輯功能(可選功能)
有些服務卡片需要具備可編輯能力，如天氣App需要編輯所在城市。具體實現方法如下：
在config.json中，對某一個form的配置增加formConfigAbility的屬性配置，可實現編輯功能。formConfigAbility的值是一個url格式的Ability名稱。若不配置formConfigAbility，則不顯示編輯菜單。示例代碼如下：
圖16 示例代碼
實現效果如下圖所示：
長按服務卡片，會彈出編輯菜單選項：
圖17 JS服務卡片效果圖
2.實現生命周期回調方法
創建一個Form Ability，并覆寫Ability在服務卡片上相應的回調函數：
● onCreateForm(Intent intent)
● onUpdateForm(long formId)
● onDeleteForm(long formId)
● onCastTempForm(long formId)
● onEventNotify(Map
● onTriggerFormEvent(long formId, String message)
下面重點給大家介紹onCreatForm和onUpdateForm的使用方法，其他回調函數以此類推。
onCreateForm方法
當卡片使用方請求獲取卡片時，卡片提供方會被拉起并調用onCreateForm(Intent intent)回調，intent中會帶有卡片ID，卡片名稱和卡片外觀規格信息，可按需獲取使用。onCreateForm方法代碼示例如下：
圖18 onCreateForm方法代碼示例
可以通過intent變量獲取到卡片相關的信息，intent中攜帶的信息如下表：
首先，可以通過卡片名字區分不同的卡片，根據不同的卡片執行不同的業務邏輯。其次可以根據卡片的尺寸設置不同的卡片內容。最終需要刷新卡片數據時，需要創建一個ZSONObject對象，將key-value設置進去，其中key需要和index.json中的data數據中的key保持一致。然后創建一個ProviderFormInfo對象，將ZSONObject對象設置進去，返回ProviderFormInfo對象給onCreateForm方法。
onUpdateForm方法
當config.json中配置了定點更新或者定時更新，卡片服務會拉起卡片執行界面更新。系統會回調onUpdateForm方法，應用則調用updateForm去更新卡片內容。onUpdateForm方法代碼示例如下：
圖19 onUpdateForm方法代碼示例
將需要更新的數據設置到ZSONObject對象中，然后通過FormBindingData對象攜帶ZSONObject對象，調用updateForm()方法去更新界面。
當定時/定點觸發之后，以上代碼生效的效果界面如下：
圖20 定時觸發效果界面圖
同時日志輸出：
3.開發卡片界面元素
JS卡片頁面需要開發三個文件：hml、css、json，json文件主要配置數據和點擊事件。詳情請參考官網資料【JSON語法參考】。
● JSON語法參考
https://developer.harmonyos.com/cn/docs/documentation/doc-references/js-service-widget-syntax-json-0000001106228840
hml、css和json文件示例內容如下：
index.hml文件
圖21 index.hml
index.json
圖22 index.json
index.css文件：
圖22 index.css
其中hml文件中聲明了服務卡片布局：
● 如果json文件中mini屬性為true，則顯示class=”mini_container”的text控件。
否則不顯示該控件，從而顯示class="items_container"的div布局，該布局從上到下顯示了一張圖片，兩個文本。所以if語句可以作為多張卡片時的判斷條件，用于顯示不同的布局。
● css文件則定義hml布局中的樣式，如寬高度、顏色等。
● json文件中定義卡片支持的數據和點擊事件。
實例代碼運行效果如下(運行在模擬器上的顯示效果)：
圖23 模擬器效果顯示圖
4.實現卡片界面交互
服務卡片json文件提供數據綁定和界面交互。
卡片僅支持click觸發的事件，事件的定義只能是直接命令式，事件定義必須包含action字段，用以說明事件類型。卡片支持兩種事件類型：跳轉事件(router)和消息事件(message)。跳轉事件可以跳轉到卡片提供方的組件;消息事件可以將開發者自定義信息傳遞給卡片提供方。
跳轉事件格式如下：
消息事件的格式如下：
json的樣例代碼如下：
圖24 json的樣例代碼
其中定義了一個routerEvent事件和imageEvent事件，這兩個事件在hml文件中應用代碼如下：
圖25 routerEvent事件和imageEvent事件應用代碼
routerEvent事件表示點擊卡片后跳轉到其他界面過去，而imageEvent是給圖片賦予了點擊事件，該點擊事件會通過onTriggerFormEvent方法，回調到Ability中過去。
在跳轉事件中，params參數在onStart()中的intent中可以提取，如下所示：
圖26 params參數在onStart()中的intent中的提取
json文件中params中定義的json對象字符串是通過intent.getStringParam(“params”)獲得，是一個json格式的字符串，可以通過構建ZSONObject對象，獲取對應的value值。
在消息事件中，params參數可以在onTriggerFormEvent的message中提取，如下所示：
圖27 params參數在onTriggerFormEvent中的提取
json文件中params定義的json對象字符串通過message變量傳遞到Java側的Ability中，在onTriggerFormEvent方法中可以根據該json字符串，去做對應的業務邏輯。
如上面實例代碼所示，運行出來的卡片界面效果如下：
圖28 卡片界面效果
若點擊了服務卡片上的圖片，則圖片下面的文字會變成“點擊后的標題”和“這是通過json文件傳遞的內容”，該字符串是在index.json的params中定義的。
3、服務卡片模板
為了方便開發者快速開發服務卡片，DevEco Studio中推出了服務卡片模板，分為“Basic”和“Advance”兩類，開發者可以根據業務需要選擇不同的模板。
圖29 DevEco Studio中的服務卡片模板圖
Grid Pattern(宮格卡片模板)
宮格卡片模板在大尺寸的卡片上特征較為明顯，能夠有規律進行布局排列。例如展示多排應用圖標，每個熱區獨立可點擊，或展示影視海報等信息，以凸顯圖片為主，描述文本為輔。
Image With Info(圖文卡片模板)
圖文卡片模板主要在于展現圖片和一定數量文本的搭配，在這種布局下，圖片和文本屬于同等重要的信息。在不同尺寸下，圖片大小和文本數量會發生一定變化，用于凸顯關鍵信息。
Immersive Pattern(沉浸布局卡片模板)
圖片內容是更能夠吸引用戶的展現形式，因此，沉浸式的布局能夠擁有更好的代入感和展現形式。相比較圖文和宮格類，這種布局在造型上的制約會更小，設計形式上的發揮空間更大，但在不同設備下的適配需要注意展示效果。
List Pattern(列表卡片模板)
列表卡片模板是展示信息時的常用界面組件，通常會在列表的左側或右側帶有圖片或點綴元素。這類布局的優勢在于可以集中的展示較多信息量，并遵循有序的排列。常用于新聞類、搜索類應用，方便用戶獲取關鍵的文本信息。
Call(通話卡片模板)
通話卡片模板主要用于在桌面顯示自定義的聯系人圖片和通話按鈕，在這種場景下，可以直接點擊卡片上的通話按鈕進行快速呼叫。
Contact(聯系人卡片模板)
聯系人卡片模板主要用于在桌面顯示聯系人快捷按鈕，點擊某個聯系人快捷按鈕可快速進入聯系人詳情頁，實現通過卡片快速跳轉聯系人詳情頁的功能。
DataPattern(數據內容卡片模板)
數據內容卡片模板主要用于在桌面展示自定義內容的百分占比，這種卡片主體是一個環形百分比圖，用于凸顯關鍵的百分比信息。
Functions(功能卡片模板)
功能卡片模板主要用于在桌面上聚合不同功能的快捷入口，通過點擊卡片的某個功能，能夠實現快速跳轉至對應功能頁面。
MusicPlayer(音樂播放器卡片模板)
音樂播放器卡片模板主要用于在桌面展示一個音樂播放的控制界面，通過點擊卡片上的對應功能按鈕，能夠實現對音樂播放的控制。
Schedule(行程卡片模板)
行程卡片模板布局主要用于在卡片上展示行程關鍵信息，并帶有功能圖標，可通過點擊功能圖標查看詳細行程信息。
Shortcuts(捷徑卡片模板)
捷徑卡片模板布局主要用于在桌面展示多個快捷功能圖標，在這種布局下，每個熱區獨立可點擊，可快速進入相關功能。
更多卡片模板詳情和卡片模板使用方法可以參考官網資料【開發服務卡片】。
● 開發服務卡片
https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ide_service_widget-0000001078566997
4、服務卡片部署
上述的服務卡片代碼和資源，可與App一起打包成一個entry hap進行部署。同時，服務卡片還可以獨立成一個Module，作為HarmonyOS應用的feature進行獨立編譯和部署。無論是打包部署還是獨立部署，兩種方式構建的服務卡片都可在 AGC和HAG市場上架和更新。
卡片代碼部署工程界面如下圖所示：
圖30 DevEco Studio中的卡片代碼部署工程界面圖
小Tips：調試安裝時，需要和Entry一起安裝，參考以下命令行：
總結
服務卡片作為HarmonyOS應用和原子化服務的一部分對外呈現重要的信息，具有易用、智能、多端部署特性，能給用戶帶來嶄新的交互體驗。
本文整體介紹了HarmonyOS服務卡片的運行原理和開發方法，服務卡片運行過程中主要是卡片管理服務作為中間樞紐，連接著卡片使用方和卡片提供方。服務卡片開發過程主要分為配置config.json、實現生命周期回調方法、開發卡片界面元素和界面交互，基于HarmonyOS提供的回調函數方法，簡單的幾步就能開發出業務所需的服務卡片。
