一篇文章了解HarmonyOS业务卡的工作原理和开发方法卡HarmonyOS2的到来吸引了众多开发者的目光。HarmonyOS2推出的服务卡片是FA（FeatureAbility）的界面展示形式，将FA的重要信息或操作放在卡片上，达到直接服务的目的。卡的实际接口如下图所示。图1有服务卡片的桌面如图所示，服务卡片和应用程序图标混杂在桌面上。例如，上面的天气服务卡片显示了多个时段的天气；运动健康服务卡显示运动步数等重要信息。如果应用图标下方有提示栏，说明应用内嵌了服务卡片，手指在图标上滑动即可调出服务卡片，如天气、图库、运动健康、备忘录、上图中等，向上滑动图标即可调出服务卡。服务卡具有使用方便可视、智能可选、多端可变三大特点。易用可见：突出服务信息内容，减少跳级。智能可选：全天可变数据信息，支持自定义类型服务卡片设计。多端变量：适应多端设备的自适应特性。2、服务卡设计规范数量的选择【每个应用可以配置多个服务卡，但每个PageAbility配置的服务卡总数不能超过16个】例如：一个天气应用可以创建本地天气，多个-时段天气、多日天气、穿衣提醒等不同内容的卡牌信息，但如果这些卡牌配置在同一个能力页面，则总数不能超过16张。【每张服务卡可选择4张服务卡sizes]例如：系统为每个应用程序提供了4种尺寸可供选择，需要选择小尺寸的卡片尺寸。【用户使用每张服务卡时可以创建多个实例】比如用户手动添加本地天气服务卡，可以通过重复添加单个服务卡实现多个实例。尺寸选择在为每个应用选择服务卡时，根据需要选择相应的尺寸，以确保最大的内容利益。服务卡的尺寸分为微型（1×2）、小型（2×2）、中型（2×4）、大型（4×4）四种，其中小尺寸为必填项。同一个尺寸还支持多张不同内容布局的卡片，可以通过服务卡片管理界面进行选择，应用端可以指定某一张服务卡片作为默认展示。【微型】图2微型服务卡微型服务卡可以提供简单的数据信息、快捷指令和快捷入口。例如，音乐应用程序可以提供一个微型卡片，只显示歌曲名称和艺术家姓名，以及歌曲的缩略图，运动和健康显示步数数据，行程信息提供航班号[小尺寸]图3小尺寸服务卡小尺寸卡可以提供简化的服务信息内容、丰富的显示特征信息、即时信息或操作提示等。例如行程信息不仅提供航班信息，还提供了查看详情的操作。【中大尺寸】图4中尺寸服务卡图5大尺寸服务卡中大尺寸卡可提供多于两个纬度的服务信息显示和多个交互热区显示，显示更沉浸、更丰富使用多个网格和列表的视觉图像和内容呈现。比如运动健康，用中型卡片展示步数和运动强度两个纬度的信息。玩机技巧以网格形式推荐多个应用入口。内容构成服务卡由多种设计元素组成。内容可以选择以下七种常见的信息元素：图标、数据、文本、按钮、图片、网格和列表。在组织服务卡的内容时，可以根据大小来决定选择哪个元素，包括元素组合的数量。图6卡片大小与元素的对应关系如上图所示，对于微型卡片，建议卡片上的内容元素不超过两个，最多可以从“图标”中选择两个元素，数据、文本、图片”进行组合。在不显得复杂的情况下，尽可能多地表达内容收益。小尺寸卡片，建议卡片内容不超过3种，最多可选择“图标、数据、文字、按钮、图片”中的3种元素进行组合。可根据业务需要自由选择中/大尺寸卡片。服务卡运行机制1.服务卡总体框架服务卡总体框架主要包括三部分：卡用户、卡管理服务和卡提供者。●卡片用户是展示卡片内容的宿主应用，控制卡片在宿主中的显示位置，如桌面、服务中心、搜索等。●卡片管理服务用于管理常驻代理系统新增卡片的服务，包括卡片对象的管理和使用，卡片的周期刷新等。●卡片提供商提供卡片显示内容的HarmonyOS应用或原子服务，控制卡片显示内容，控制布局，控制点击事件。图7服务卡的整体框架显示卡的用户和提供者不需要永久运行。当需要添加/删除/请求更新卡片时，卡片管理服务会拉取卡片提供商获取卡片信息。卡片主动刷新时，具体过程如下：当“桌面”等卡片用户调出服务卡片时，Javakit中的SDK客户端向卡片管理服务请求卡片对象。卡片管理服务将检查卡片对象实例是否存在于其缓存管理模块中。如果存在，则立即将卡片对象返回给卡片用户；如果不存在，则通过卡提供者工具包数据向卡提供者请求卡，并生成卡对象；卡片管理服务拉取服务卡片FA，回调刷新函数更新卡片数据，并将刷新数据返回给卡片管理服务；卡片管理服务会检查是否存在卡片用户主机，如果存在，则将卡片提供商的数据刷新到卡片用户的主机实例缓存中。如果不存在，可能是系统异常，无法刷新；卡片管理服务通过服务接口将卡片数据传输给卡片用户（如“桌面”），主机应用界面显示数据。图8服务卡主动刷新流程图当服务卡定时或定点刷新时，具体流程如下：当服务卡在config.json中配置了定时或定点刷新时，定时器事件将通知卡管理服务；卡片管理服务会去卡片提供商对象管理模块中找到对应的卡片提供商；通过卡商工具包，回调卡商的刷新函数，卡商的刷新数据会返回给卡管理服务。卡片管理服务根据卡片名称找到卡片用户主机，并刷新卡片用户主机对象缓存数据。然后通过服务接口将卡片数据传输给卡片用户，主机应用界面显示数据。图9服务卡定时/定点刷新流程图服务卡按开发方式可分为Java服务卡和JS服务卡。Java服务卡片返回的实例以ComponentProvider的形式展示在服务卡片的用户端，JS服务卡片通过ACE引擎展示在服务卡片的用户端。加载并解析hap包的card资源，如hml、css、config.json文件。解析引擎在解析完hml和css之后渲染hml和css。结合数据生成InstantView，显示在服务卡用户指定的位置。2.服务卡片生命周期回调函数卡片提供者控制卡片的实际显示内容、控件布局和控制点击事件。应用或原子服务如果想成为卡片提供者，需要实现卡片相关的回调函数：服务卡片的关键回调函数如下：服务卡片生命周期的回调函数时机如下:图10服务卡生命周期回调函数时序图Cardmanagementservice不负责卡应用进程的保活。卡片管理服务在相应的时间拉起卡片提供者进程，调用创建、更新、删除卡片等回调。服务卡开发流程下面以JS服务卡开发为例，介绍服务卡开发流程。1、业务卡开发环境华为近期发布了HarmonyOSIDE最新版本：DevEcoStudio2.1Release，已经支持业务卡的开发。DevEcoStudio开发卡环境如下图所示：图11DevEcoStudio开发卡环境图【创建服务卡项目步骤】1.新建一个Project，根据项目需要选择JS或Java项目模板，即可建议选择JS工程项目。2.在“Configureyourproject”中，打开“ShowInServiceCenter”，在服务中心展示。图12DevEcoStudio开发卡设置图3.Finishing后，可以创建带有服务卡的项目。注意如果步骤1中使用了Java项目，默认会创建一个Java服务卡；如果使用JS项目，默认会创建一个JS服务卡。详细的项目创建过程请参考官网信息【开发服务卡】。●开发服务卡https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ide_service_widget-00000010785669972，JS服务卡开发流程JS服务卡开发主要分为四步：配置config.json实现生命周期回调方法开发卡片界面元素，实现卡片界面交互1.配置config.jsonconfig.json整体结构使用DevEcoStudio创建带有服务卡片的项目后，会生成如下config.json配置文件。图13config.json文件内容如上图所示。config.json文件是项目创建后生成的配置文件，其中“js”配置了两个json对象，第一个name属性值为“default”，即JSUI界面配置。name属性值为“service_widget”为服务卡片的配置，type属性值为form，表示该JS配置为服务卡片。JS服务卡项目目录如下：图14JS服务卡项目目录图●common目录主要存放公共资源；●i18n目录存放国际资源；●pages.index目录（实际是pages/index）存放服务卡片界面开发主文件使用hml+css+json文件组合构成JS服务卡片界面。config.json中abilities配置表单详解在abilities的json配置中，配置了forms属性值，如下图：图15Forms属性值配置Forms配置在哪个Ability上，以及服务卡声明循环回调方法会在哪个Ability上执行回调。●如果formsEnable的值为true，则表示该能力支持显示业务卡片。●forms的值为json数组，表示可以配置多个业务卡。●jsComponentName为JS服务卡的名字，只需要在JS服务卡上配置（Java卡不需要配置），名字需要和js中配置的名字一致，表示js组件实例。●isDefault为true表示该卡是默认卡。能力可以配置多张服务卡，其中只有一张是默认卡，也就是在图标上滑动调出的卡。●scheduledUpdateTime表示卡片定时/定点触发更新时间。●defaultDimension表示默认卡片大小为22，其他选项为12、24、44大小。对于需要在服务中心曝光的卡片，默认尺寸必须设置为2*2。●type业务卡类型，有JS和Java两种，本配置选择JS。●updateDuration表示刷新业务卡的时间间隔，以30分钟为单位，1表示30分钟，2表示1小时，以此类推。表单的其他属性可以参考官网【服务卡-JS卡开发】。●服务卡-JS卡开发https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ability-service-widget-provider-js-0000001150602175配置卡编辑功能（可选功能）部分服务卡它需要可编辑，例如天气应用需要编辑所在城市。具体实现方法如下：在config.json中，将formConfigAbility的属性配置添加到某个表单的配置中，实现编辑功能。formConfigAbility的值是url格式的Ability名称。如果不配置formConfigAbility，则不会显示编辑菜单。示例代码如下：图16示例代码实现效果如下图所示：长按服务卡，会弹出编辑菜单选项：图17JS服务卡渲染2.实现生命周期回调方法创建一个FormAbility，并在服务卡对应的回调函数中覆盖该Ability：●onCreateForm(Intentintent)●onUpdateForm(longformId)●onDeleteForm(longformId)●onCastTempForm(longformId)●onEventNotify(Map●onTriggerFormEvent(longformId,Stringmessage)onCreatForm和onUpdateForm的用法，其他回调函数等等OnCreateForm方法当卡用户请求取卡时，会拉起卡提供者调用onCreateForm(Intentintent)回调，Intent中会包含卡片ID，卡片名称和卡片外观规格信息可以根据需要获取和使用，onCreateForm方法的代码示例如下：图18conCreateForm方法的示例可以通过intent变量获取卡片相关信息。Intent中携带的信息如下：首先，可以通过卡名来区分不同的卡，根据不同的卡执行不同的业务逻辑。其次，可以根据卡片的大小设置不同的卡片内容。最后，当需要刷新卡片数据时，需要创建一个ZSONObject对象，并在其中设置key-value。key需要和index.json中data数据中的key一致。然后创建一个ProviderFormInfo对象，将ZSONObject对象设置进去，将ProviderFormInfo对象返回给onCreateForm方法。当onUpdateForm方法在config.json中配置了定点更新或者定时更新时，卡片服务会拉起卡片来更新接口。系统会回调onUpdateForm方法，应用会调用updateForm更新卡片内容。onUpdateForm方法的代码示例如下：图19onUpdateForm方法的代码示例将要更新的数据设置到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-0000001106228840hml、css和json文件示例内容如下：index.hml文件图21index.hmlindex.json图22index.jsonindex.css文件：图22index.csshml文件中声明了服务卡布局：●如果json文件中的mini属性为true，则文本控件带有class将显示="mini_container"。否则不显示控件，显示class="items_container"的div布局，从上到下显示一张图片和两条文字。所以if语句可以作为多张卡片显示不同布局的判断条件。●css文件定义了hml布局中的样式，如宽度、高度、颜色等。●卡片支持的数据和点击事件定义在json文件中。示例代码运行效果如下（在模拟器上运行显示效果）：图23模拟器效果展示图4.实现卡片界面交互服务卡片json文件提供数据绑定和界面交互。卡片只支持点击触发的事件。事件定义只能是直接命令。事件定义必须包含一个操作字段来描述事件类型。卡片支持两种事件类型：跳转事件（router）和消息事件（message）。跳转事件可以跳转到卡片提供者的组件；message事件可以将开发者的自定义信息传递给卡片提供商。跳转事件格式如下：消息事件格式如下：json示例代码如下：图24json示例代码定义了一个routerEvent事件和一个imageEvent事件，应用代码html文件中这两个事件如下：图25RouterEvent事件和imageEvent事件应用代码routerEvent事件是点击卡片跳转到其他界面，imageEvent是给图片分配一个点击事件，点击事件会通过onTriggerFormEvent方法回调到Ability。在跳转事件中，可以在onStart()中提取intent中的params参数，如下图：图26在onStart()中提取intent中的params参数json文件中params中定义的json对象字符串为通过Intent.getStringParam("params")得到，是一个json格式的字符串，可以通过构造ZSONObject对象得到对应的值。在一个message事件中，可以从onTriggerFormEvent的message中提取params参数，如下图：图27onTriggerFormEvent中params参数的提取将json文件中params定义的json对象字符串通过传递给Java端的Ability消息变量。在onTriggerFormEvent方法中，可以根据json串做相应的业务逻辑。如上例代码所示，运行后的卡片界面效果如下：图28卡片界面效果点击服务卡片上的图片，图片下方的文字会变成“点击后的标题”和“thisisthroughthejsonfilePassedcontent”，字符串定义在index.json的params中。3.服务卡模板为了方便开发者快速开发服务卡，DevEcoStudio引入了服务卡模板，分为“Basic”和“Advance”两种。开发者可以根据业务需求选择不同的模板。图29DevEcoStudio中的服务卡片模板GridPattern（网格卡片模板）网格图案卡片模板在大尺寸卡片上的特点比较明显，可以有规律地排列。比如展示多行应用图标，每个热点区域可以独立点击，或者展示影视海报等信息，以突出图片为主，辅以描述文字。ImageWithInfo（图文名片模板）图文名片模板主要是展示图片和一定数量的文字的组合。在这种布局中，图片和文字是同等重要的信息。不同尺寸下，图片的大小和文字的多少都会发生一定的变化，以突出关键信息。ImmersivePattern（沉浸式布局卡片模板）图片内容是一种更能吸引用户的呈现形式。因此，沉浸式布局可以有更好的代入感和呈现形式。与图形和网格相比，这种布局对样式的限制更少，在设计形式上的发挥空间更大，但在适配不同设备时需要注意显示效果。ListPattern（列表卡片模板）列表卡片模板是展示信息时常用的界面组件，通常在列表的左侧或右侧带有图片或点缀元素。这种布局的优点是可以集中展示大量的信息，并且排列有序。常用于新闻和搜索应用，方便用户获取关键文本信息。来电（名片模板）名片模板主要用于在桌面显示自定义的联系人图片和呼叫按钮。在这种场景下，您可以直接点击卡片上的通话按钮进行快速通话。联系人(ContactCardTemplate)联系人卡片模板主要用于在桌面上显示一个联系人快捷按钮。点击联系人快捷按钮可快速进入联系人详情页面，实现通过名片快速跳转到联系人详情页面的功能。DataPattern（数据内容卡片模板）数据内容卡片模板主要用于在桌面显示自定义内容的百分比。这张卡片的主体是一个圆形的百分比图，用来突出关键的百分比信息。Functions（功能卡片模板）功能卡片模板主要用于聚合桌面不同功能的快捷方式。通过点击卡片的某个功能，可以快速跳转到相应的功能页面。MusicPlayer(MusicPlayerCardTemplate)音乐播放器卡片模板主要用于在桌面显示一个音乐播放器控制界面。通过点击卡片上相应的功能按钮，可以控制音乐播放器。Schedule（行程卡片模板）日程卡片模板的版面主要用于在卡片上展示行程的关键信息，带有功能图标，点击功能图标可以查看详细的行程信息。Shortcuts（快捷方式卡片模板）快捷方式卡片模板的布局主要用于在桌面上显示多个快捷功能图标。在此布局中，每个热区都可以独立单击以快速访问相关功能。更多卡片模板及卡片模板使用方法，请参考官网【卡片开发服务】。●开发服务卡https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ide_service_widget-00000010785669974服务卡部署以上服务卡代码和资源可以和App一起打包成一个入口hap用于部署。同时，业务卡还可以独立组成模块，作为HarmonyOS应用的一个特性，可以独立编译部署。无论是打包部署还是独立部署，两种方式构建的业务卡都可以在AGC和HAG市场上市更新。卡片代码部署工程界面如下图所示：图30DevEcoStudio中卡片代码部署工程界面图小提示：调试安装时，需要和Entry一起安装。参考如下命令行：服务卡片概括为HarmonyOS应用和原子服务的一部分，对外呈现重要信息，具有易用、智能、多设备部署的特点，可以为用户带来全新的交互体验。本文从整体上介绍了HarmonyOS服务卡的工作原理和开发方法。在服务卡运行过程中，卡管理服务主要作为中间枢纽，连接卡用户和卡提供者。业务卡片开发流程主要分为配置config.json、实现生命周期回调方法、开发卡片界面元素和界面交互。基于HarmonyOS提供的回调函数方式，简单几步即可开发出业务所需的服务卡片。更多信息请访问：Harmonyos.51cto.com，与华为官方合作打造的鸿蒙技术社区
