HarmonyOS应用开发（鸿蒙JS实战）（微课版）课件 项目5 服务卡片

《鸿蒙JS应用开发》项目5服务卡片5.1任务掌握服务卡片概念服务卡片可以看作是原子化服务的可视化界面表达，它将原子化服务的核心信息和操作直观地展示在用户视线内，达到服务直达的效果，并简化用户的操作流程。服务卡片有多种应用场景。目前，服务卡片支持嵌入到系统应用。同时，服务卡片具有一定的交互功能，例如启动新的页面、发送消息等。任务5.1.1服务卡片的概念服务卡片可以理解为主应用的快捷方式，运行机制如图所示：任务5.1.2服务卡片运行机制与原理呼应服务卡片在HarmonyOS中具备灵活的尺寸设计，它提供了四种不同的卡片尺寸以适应各种使用场景，如表所示：任务5.1.3服务卡片尺寸卡片尺寸对应宫格数使用场景微卡片1*2宫格适合展示极简单的信息，如日期、天气等。小卡片2*2宫格此尺寸在不同设备上具有最佳的兼容性，因此，每个服务卡片在上架时必须至少包含一个这种尺寸的卡片。中卡片2*4宫格适用于需要展示更详细信息的场景。大卡片4*4宫格适用于信息展示最为丰富的场景，比如新闻、图文等。5.2任务使用服务卡片在HarmonyOS中，服务卡片在桌面上的显示主要分为两种状态：临时显示和常驻显示。任务5.2.1服务卡片显示当用户对一个应用的图标进行上滑操作时，应用的服务卡片就会在桌面上临时展示。这种方式非常便捷轻量，可以直接向用户呈现服务内容，而不会影响用户的现有桌面使用习惯。当用户点击卡片以外的区域时，这个临时展示的卡片就会被收起，返回到原来的桌面界面。对于用户需要持续关注的服务内容，临时显示的卡片提供了一个"Pin"图标。用户可以通过点击这个图标，将临时态的卡片固定到桌面上，使其常驻显示。此外，用户也可以直接将服务卡片拖动到桌面，让它在桌面上持续展示。1.临时显示2.常驻显示任务5.2.2服务卡片堆叠创建堆叠如果想要将两个同尺寸的服务卡片堆叠起来，只需要长按其中一个卡片，然后拖拽它到另一个卡片上并短暂停留，这样这两个卡片就会自动形成一个堆叠。切换卡片在卡片堆叠中，可以通过上下轻滑的操作来在不同的卡片之间进行切换，这样就可以轻松地查看堆叠中的各个服务卡片。查看堆叠如果想要查看堆叠中的所有卡片，可以在任何一个卡片上进行向下的长滑操作，这样就会展示出堆叠中的全部卡片。移除和拆分在卡片堆叠视图中，还可以将某个卡片从堆叠中移除或者拆分出来，操作简单易行。任务5.2.3服务卡片组合编辑组合：在组合窗口内，可以自由地增加或删除卡片和应用快捷方式。通过这种方式，可以根据自己的需求和喜好，创建出一种属于自己的卡片组合方式。创建组合：如果想要创建一个新的卡片组合，需要首先长按服务卡片或者应用快捷方式，然后拖拽它们靠近其他卡片或快捷方式，等待数秒后，就会看到出现一个组合窗口。5.3任务创建服务卡片工程在开始开发服务卡片时，以下API接口将是强大工具。可以借助这些接口完成各种操作，例如创建新的服务卡片，更新现有的服务卡片，或者管理服务卡片的生命周期。任务5.3.1相关API介绍FormAbility类提供了一组生命周期接口，这些接口允许在卡片的生命周期内执行各种操作，例如在创建、更新或销毁卡片时执行特定的行为。formProvider类提供了一组用于管理服务卡片的接口。通过这些接口，可以设置卡片的下一次更新时间，或者更新卡片的数据。formBindingData类提供了一个接口，允许创建一个FormBindingData对象，这个对象用于存储卡片的数据。任务5.3.1相关API介绍接口名描述onCreate(want:Want):formBindingData.FormBindingData卡片提供方接收创建卡片的通知接口。onCastToNormal(formId:string):void卡片提供方接收临时卡片转常态卡片的通知接口onUpdate(formId:string):void卡片提供方接收更新卡片的通知接口。onVisibilityChange(newStatus:{[key:string]:number}):void卡片提供方接收修改可见性的通知接口。onEvent(formId:string,message:string):void卡片提供方接收处理卡片事件的通知接口。onDestroy(formId:string):void卡片提供方接收销毁卡片的通知接口。onAcquireFormState(want:Want):formInfo.FormState卡片提供方接收查询卡片状态的通知接口。onShare?(formId:string):{[key:string]:any}卡片提供方接收卡片分享的通知接口。1.FormAbility生命周期接口任务5.3.1相关API介绍接口名描述setFormNextRefreshTime(formId:string,minute:number,callback:AsyncCallback<void>):void;设置指定卡片的下一次更新时间。setFormNextRefreshTime(formId:string,minute:number):Promise<void>;设置指定卡片的下一次更新时间，以promise方式返回。updateForm(formId:string,formBindingData:FormBindingData,callback:AsyncCallback<void>):void;更新指定的卡片。updateForm(formId:string,formBindingData:FormBindingData):Promise<void>;更新指定的卡片，以promise方式返回。2.formProvider类任务5.3.1相关API介绍接口名描述createFormBindingData(obj:Object|string):FormBindingData创建一个FormBindingData对象。3.formBindingData类单击NewProject>Application创建一个新的工程，对工程进行相应的配置，如图所示：任务5.3.2为应用创建卡片选择模块（如entry模块）下的任意文件，单击菜单栏File（或单击右键）>New>ServiceWidget创建服务卡片。在ChooseaTemplateforYourServiceWidget界面中，选择卡片模板，单击Next。任务5.3.2为应用创建卡片API9提供如下三种类型的卡片模板：任务5.3.2为应用创建卡片模板名称支持的设备支持的开发语言模板描述HelloWorldPhone、TabletArkTS、JS支持低代码开发的HelloWorld卡片。ImageWithInformation（图文卡片模板）Phone、TabletArkTS、JS图文卡片模板主要在于展现图片和一定数量文本的搭配，在这种布局下，图片和文本属于同等重要的信息。在不同尺寸下，图片大小和文本数量会发生一定变化，用于凸显关键信息。ImmersiveInformation（沉浸图文卡片模板）Phone、TabletArkTS、JS沉浸式卡片的装饰性较强，能够较好的提升卡片品质感并起到装饰桌面的作用，合理的去布局信息与背景图片之间的空间比例，可以提升用户的个性化使用体验。对服务卡片进行相应的配置，单击Finish完成卡片的创建。如图所示：任务5.3.2为应用创建卡片在ConfigureYourServiceWidget界面中，配置卡片的基本信息，包括：Servicewidgetname：卡片的名称，在同一个应用/服务中，卡片名称不能重复，且只能包含大小写字母、数字和下划线。Description：卡片的描述信息。EnableSuperVisual：是否选择低代码方式开发。Language：界面开发语言，可选择创建ArkTS/JS卡片。Supportdimension：选择卡片的规格。部分卡片支持同时设置多种规格。Abilityname：选择一个挂靠服务卡片的FormAbility，或者创建一个新的FormAbility。Modulename：卡片所属的模块。创建完成后，工具会自动创建出服务卡片的布局文件，如图所示：任务5.3.2为应用创建卡片任务5.3.2为应用创建卡片创建完成后，工具会自动创建出服务卡片的布局文件，并在config.json配置文件中写入服务卡片的属性字段，配置文件代码如下所示：{"app":{//...省略}},"deviceConfig":{},"module":{//...省略"abilities":[{"skills":[{"entities":["entity.system.home"],"actions":["action.system.home"]}],"orientation":"unspecified","formsEnabled":false,"name":".MainAbility","srcLanguage":"js","srcPath":"MainAbility","icon":"$media:icon","description":"$string:MainAbility_desc","label":"$string:MainAbility_label","type":"page","visible":true,"launchType":"standard"},{"name":".FormAbility","srcPath":"FormAbility","description":"$string:FormAbility_desc","icon":"$media:icon","label":"$string:FormAbility_label","type":"service","formsEnabled":true,"srcLanguage":"js","forms":[{"jsComponentName":"widget","isDefault":true,"scheduledUpdateTime":"10:30","defaultDimension":"2*2","name":"widget","description":"Thisisaservicewidget.","colorMode":"auto","type":"JS","formVisibleNotify":true,"supportDimensions":["2*2"],"updateEnabled":true,"updateDuration":1}]}],"js":[{"pages":["pages/index/index"],"name":".MainAbility","window":{"designWidth":720,"autoDesignWidth":false}},{"name":"widget","pages":["pages/index/index"],"window":{"designWidth":720,"autoDesignWidth":true},"type":"form"}]}}单击NewProject>AtomicService创建一个新的原子化服务时，会同步创建一个2*2的服务卡片模板，并创建入口卡片、配置工程。任务5.3.3为原子化服务创建卡片原子化应用创建完成后，会在工程目录下生成

EntryCard

目录。任务5.3.3为原子化服务创建卡片在该目录下，每个拥有EntryCard的模块，都会生成一个和模块名相同的文件夹，同时还会默认生成一张2x2的快照型EntryCard图片（png格式）。开发者可以将其替换为提前设计好的2x2快照图：将新的快照图拷贝到上图目录下，删除默认图片，新图片命名遵循格式“卡片名称-2x2.png”。在已有的AtomicService工程中添加新模块时，会自动创建新服务卡片和EntryCard。HarmonyOSTHANKS《鸿蒙JS应用开发》项目5服务卡片5.4任务预览服务卡片在开发服务卡片过程中，支持对卡片进行实时预览。服务卡片通过HML+CSS+JSON进行布局设计，在开发过程中，可以对布局HML+CSS+JSON文件进行实时预览，只要在HML+CSS+JSON布局文件中保存了修改的源代码，在预览器中就可以实时查看布局效果。在

Phone和Tablet服务卡片的预览效果中，每个尺寸的服务卡片提供3种场景的预览效果，分别为极窄（Minimum）、默认（Default）、极宽(Maximum)，开发者应确保三种尺寸的显示效果均正常，以便适应不同屏幕尺寸的设备。任务5.4预览服务卡片5.5任务开发服务卡片代码任务5.5服务卡片代码开发步骤1卡片数据交互卡片数据交互主要通过updateForm()函数实现。开发者可以通过此函数更新卡片显示的信息，如天气应用的卡片可以定时通过这个函数更新天气信息。开发卡片页面卡片页面的开发主要使用HML+CSS+JSON技术。开发者可以设计自己的卡片布局，定制卡片的样式，然后使用JSON描述卡片的数据。开发卡片事件这一步骤主要是为卡片添加事件处理，包括router事件和message事件。router事件主要用于处理卡片内部的导航，例如跳转到其他页面；message事件主要用于处理卡片与宿主应用之间的消息交互。实现卡片生命周期接口这一步骤涉及到开发FormAbility生命周期回调函数。FormAbility类提供了一套与服务卡片生命周期相关的接口，如创建、更新和销毁卡片等。开发者需要在这些回调函数中定义卡片在不同生命周期阶段的行为。配置卡片配置文件这一步骤涉及配置应用配置文件config.json。配置文件主要用于定义卡片的属性，如卡片类型（临时卡片、常态卡片）、刷新策略等。卡片信息的持久化在这一步骤中，开发者需要对卡片信息进行持久化管理，包括存储卡片的当前状态、卡片数据等。当卡片被销毁后，这些信息可以用于在重新创建卡片时恢复卡片的状态。23654基于FA模型的卡片提供方开发的详细步骤任务5.5.1实现卡片生命周期接口创建FA模型的卡片，需实现卡片的生命周期接口。在form.js中，导入相关模块。importformBindingDatafrom'@ohos.app.form.formBindingData';

importformInfofrom'@ohos.app.form.formInfo';

importformProviderfrom'@ohos.app.form.formProvider';

importdataStoragefrom'@ohos.data.storage';任务5.5.1实现卡片生命周期接口在form.js中，实现卡片生命周期接口。//引入相应的模块

importformBindingDatafrom'@ohos.app.form.formBindingData';//导入formBindingData模块，用于创建绑定数据

importformInfofrom'@ohos.app.form.formInfo';//导入formInfo模块，用于获取表单信息

importformProviderfrom'@ohos.app.form.formProvider';//导入formProvider模块，用于提供表单数据

importdataStoragefrom'@ohos.data.storage';//导入dataStorage模块，用于数据存储

exportdefault{

onCreate(want){//当使用方创建卡片时，会触发该函数

('FormAbilityonCreate');//输出创建信息

//提供方需要返回卡片数据绑定类

letobj={//定义一个包含标题和详情的对象

"title":"titleOnCreate",

"detail":"detailOnCreate"

};

letformData=formBindingData.createFormBindingData(obj);//创建表单绑定数据

returnformData;//返回创建的表单数据

},

onCastToNormal(formId){//当使用方将临时卡片转换为常态卡片时，会触发该函数

('FormAbilityonCastToNormal');//输出信息

},任务5.5.1实现卡片生命周期接口注意：FormAbility不能常驻后台，即在卡片生命周期回调函数中无法处理长时间的任务。

letobj={//定义一个包含标题和详情的对象

"title":"titleOnUpdate",

"detail":"detailOnUpdate"

};

letformData=formBindingData.createFormBindingData(obj);//创建表单绑定数据

formProvider.updateForm(formId,formData).catch((error)=>{//使用formProvider更新表单数据

('FormAbilityupdateForm,error:'+JSON.stringify(error));//若出现错误，输出错误信息

});

},

onVisibilityChange(newStatus){//当使用方发起可见或者不可见通知时，会触发该函数

('FormAbilityonVisibilityChange');//输出可见性更改信息

},

onEvent(formId,message){//若卡片支持触发事件，则需要重写该方法并实现对事件的触发

('FormAbilityonEvent');//输出事件信息

},

onDestroy(formId){//当卡片被销毁时，会触发该函数

('FormAbilityonDestroy');//输出销毁信息

},

onAcquireFormState(want){//获取表单状态

('FormAbilityonAcquireFormState');//输出获取状态信息

returnformInfo.FormState.READY;//返回表单状态为READY

},

}任务5.5.2配置卡片配置文件属性名称含义数据类型是否可缺name表示JSComponent的名字。该标签不可缺省，默认值为default。字符串否pages表示JSComponent的页面用于列举JSComponent中每个页面的路由信息[页面路径+页面名称]。该标签不可缺省，取值为数组，数组第一个元素代表JSFA首页。数组否window用于定义与显示窗口相关的配置。对象可缺省type表示JS应用的类型。取值范围如下：normal：标识该JSComponent为应用实例。form：标识该JSComponent为卡片实例。字符串可缺省，缺省值为“normal”mode定义JS组件的开发模式。对象可缺省，缺省值为空js模块，用于对应卡片的js相关资源，内部字段结构说明如表：卡片需要在应用配置文件config.json中进行配置。任务5.5.2配置卡片配置文件配置示例："js":[{

"name":"widget",

"pages":["pages/index/index"],

"window":{

"designWidth":720,

"autoDesignWidth":true

},

"type":"form"

}]任务5.5.2配置卡片配置文件属性名称含义数据类型是否可缺name表示卡片的类名。字符串最大长度为127字节。字符串否description表示卡片的描述。取值可以是描述性内容，也可以是对描述性内容的资源索引，以支持多语言。字符串最大长度为255字节。字符串可缺省，缺省为空。isDefault表示该卡片是否为默认卡片，每个Ability有且只有一个默认卡片。true：默认卡片。false：非默认卡片。布尔值否type表示卡片的类型。取值范围如下：JS：JS卡片。字符串否colorMode表示卡片的主题样式，取值范围如下：auto：自适应。dark：深色主题。light：浅色主题。字符串可缺省，缺省值为“auto”。supportDimensions表示卡片支持的外观规格，取值范围：1*2：表示1行2列的二宫格。2*2：表示2行2列的四宫格。2*4：表示2行4列的八宫格。4*4：表示4行4列的十六宫格。字符串数组否defaultDimension表示卡片的默认外观规格，取值必须在该卡片supportDimensions配置的列表中。字符串否updateEnabled表示卡片是否支持周期性刷新，取值范围：true：表示支持周期性刷新，可以在定时刷新（updateDuration）和定点刷新（scheduledUpdateTime）两种方式任选其一，优先选择定时刷新。false：表示不支持周期性刷新。布尔类型否abilities模块，用于对应卡片的FormAbility，内部字段结构说明如表：任务5.5.2配置卡片配置文件属性名称含义数据类型是否可缺scheduledUpdateTime表示卡片的定点刷新的时刻，采用24小时制，精确到分钟。updateDuration参数优先级高于scheduledUpdateTime，两者同时配置时，以updateDuration配置的刷新时间为准。字符串可缺省，缺省值为“0:0”。updateDuration表示卡片定时刷新的更新周期，单位为30分钟，取值为自然数。当取值为0时，表示该参数不生效。当取值为正整数N时，表示刷新周期为30*N分钟。updateDuration参数优先级高于scheduledUpdateTime，两者同时配置时，以updateDuration配置的刷新时间为准。数值可缺省，缺省值为“0”。formConfigAbility表示卡片的配置跳转链接，采用URI格式。字符串可缺省，缺省值为空。formVisibleNotify标识是否允许卡片使用卡片可见性通知。字符串可缺省，缺省值为空。jsComponentName表示JS卡片的Component名称。字符串最大长度为127字节。字符串否metaData表示卡片的自定义信息，包含customizeData数组标签。对象可缺省，缺省值为空。customizeData表示自定义的卡片信息。对象数组可缺省，缺省值为空。abilities模块，用于对应卡片的FormAbility，内部字段结构说明如表：任务5.5.2配置卡片配置文件配置示例："colorMode":"auto",

"defaultDimension":"2*2",

"description":"Thisisaservicewidget.",

"formVisibleNotify":true,

"isDefault":true,

"jsComponentName":"widget",

"name":"widget",

"scheduledUpdateTime":"10:30",

"supportDimensions":["2*2"],

"type":"JS",

"updateEnabled":true

}]

}]"abilities":[{

"name":"FormAbility",

"description":"ThisisaFormAbility",

"formsEnabled":true,

"icon":"$media:icon",

"label":"$string:form_FormAbility_label",

"srcPath":"FormAbility",

"type":"service",

"srcLanguage":"ets",

"formsEnabled":true,

"formConfigAbility":"ability://com.example.entry.MainAbility","forms":[{任务5.5.3卡片数据交互当卡片应用需要更新数据时（如触发了定时更新或定点更新），卡片应用获取最新数据，并调用updateForm()接口更新主动触发卡片的更新。onUpdate(formId){

//若卡片支持定时更新/定点更新/卡片使用方主动请求更新功能，则提供方需要重写该方法以支持数据更新

('FormAbilityonUpdate');

letobj={

"title":"titleOnUpdate",

"detail":"detailOnUpdate"

};

letformData=formBindingData.createFormBindingData(obj);

//调用updateForm接口去更新对应的卡片，仅更新入参中携带的数据信息，其他信息保持不变

formProvider.updateForm(formId,formData).catch((error)=>{

('FormAbilityupdateForm,error:'+JSON.stringify(error));

});

}任务5.5.4开发卡片UI页面开发者可以使用类Web范式（HML+CSS+JSON）开发JS卡片页面。生成如图5-18卡片页面，可以这样配置卡片页面文件：注意：当前仅支持JS扩展的类Web开发范式来实现卡片的UI界面。HMLCSSJSON任务5.5.4开发卡片UI页面HML：使用类Web范式的组件描述卡片的页面信息。<divclass="container">

<stack>

<divclass="container-img">

<imagesrc="/common/widget.png"class="bg-img"></image>

</div>

<divclass="container-inner">

<textclass="title">{{title}}</text>

<textclass="detail_text"onclick="routerEvent">{{detail}}</text>

</div>

</stack>

</div>任务5.5.4开发卡片UI页面CSS：HML中类Web范式组件的样式信息。.container{

flex-direction:column;

justify-content:center;

align-items:center;

}

.bg-img{

flex-shrink:0;

height:100%;

}

.container-inner{

flex-direction:column;

justify-content:flex-end;

align-items:flex-start;

height:100%;

width:100%;

padding:12px;

}.title{

font-size:19px;

font-weight:bold;

color:white;

text-overflow:ellipsis;

max-lines:1;

}

.detail_text{

font-size:16px;

color:white;

opacity:0.66;

text-overflow:ellipsis;

max-lines:1;

margin-top:6px;

}任务5.5.4开发卡片UI页面JSON：卡片页面中的数据和事件交互。{

"data":{

"title":"TitleDefault",

"detail":"TextDefault"

},

"actions":{

"routerEvent":{

"action":"router",

"abilityName":"com.example.entry.MainAbility",

"params":{

"message":"adddetail"

}

}

}

}任务5.5.5开发卡片事件卡片支持为组件设置交互事件(action)，包括router事件和message事件，其中router事件用于Ability跳转，message事件用于卡片开发人员自定义点击事件。关键步骤说明如下：1.在hml中为组件设置onclick属性，其值对应到json文件的actions字段中。2.如何设置router事件：action属性值为"router"；abilityName为跳转目标的Ability名（支持跳转FA模型的PageAbility组件和Stage模型的UI