开发卡片

简介

卡片是一种新的服务形态，提供一种比APP更细粒度的服务能力，以可交互的卡片形式直接将用户最关心的服务或内容展示给用户。卡片可以嵌入各种APP或交互场景中，更好的满足用户需求，提供智慧化服务能力。

卡片和快应用主程序打包在同一个RPK文件中，发布时上传RPK文件。

卡片使用场景如下所示。

准入条件

在进行卡片开发前，请先完成如下准备工作：

开发规范

文件组织

卡片是快应用程序的一部分，一个快应用程序可能包含多个卡片，每个卡片仅且只能对应一个页面（page）。卡片的定义通过manifest.json中的widgets字段定义，widgets是一个100大小的数组，其字段说明如下表所示。请参考快应用规范“Manifest文件 > router”将卡片对应的page定义完整（即将卡片的path字段与对应页面的path字段进行关联）。

属性

类型

是否必填

描述

name

String

是

卡片的名称。

id

String

是

卡片的唯一标识，英文或数字组成的字符串，在快应用包内唯一，长度不允许超过255。

path

String

是

卡片对应的页面路径，与router.page中的path字段进行对应，每张卡片仅且只能对应一个页面。

component

String

否

卡片对应的页面名称。

targetManufactorys

Array[100]

是

由于各厂商的UI风格有不同的要求，应用开发商可能会针对不同的厂商提供不同的卡片，因此需要一个字段明确说明卡片所适用的厂商范围，防止不必要的审核及驳回流程。

示例：["huawei"]

desc

String

否

卡片的详细描述，包括功能描述、如何填写入参信息等。

params

list[100]

否

卡片运行需要传入的参数信息，运营人员或自动化测试工具可以运行卡片或进行功能性验证，详细描述参见“params说明”。

minPlatformVersion

Integer

是

支撑的最小平台版本号。

params说明：

属性

类型

是否必填

描述

name

String

是

参数名称。

mandatory

Boolean

否

是否必填。缺省为是。

valueSample

String

是

参数值示例，用于指导测试运营输入验证、自动化测试工具使用。

desc

String

是

参数描述。

示例代码如下：

"router": { "entry": "Hello", "pages": { "Hello": { "component": "hello" }, "widget1": { "component": "Widget1", "path": "/widget1" }, "widget2": { "component": "Widget2", "path": "/widget2" } } }, "widgets":[ { "id":"ExpressInfor", "name":"物流信息展示", "path":"/widget1", "component":"Widget1", "targetManufactorys":["huawei"], "params":[{"name":"keyName1", "mandatory": true, "valueSample": "宝马X5", "desc": "参数描述"},{"name": "keyName2", "mandatory": true, "valueSample": "深圳", "desc": "参数描述"}], "uses-permission":["ACCESS_FINE_LOCATION", "WRITE_CALENDAR"], "minPlatformVersion": 1050 }， { "id":"OrderInfo", "name":"订单实时展示", "path":"/widget2", "component":"Widget2", "targetManufactorys":["huawei"], "uses-permission":["ACCESS_FINE_LOCATION"], "minPlatformVersion": 1050 } ]

除widget自身的属性说明外，widget作为快应用程序的一部分，widget也会和快应用主体程序共用如下表所示信息。

属性

类型

默认值

是否必填

描述

package

String

-

是

应用包名，是区别于其他应用的唯一标识，推荐采用com.company.module的格式，如：com.deviceunion.demo。

name

String

-

是

应用名称，一般是中文，用于在桌面图标、弹窗等处显示应用名称。

icon

String

-

是

应用图标，提供192x192大小的即可。

versionName

String

-

否

应用版本名称。

versionCode

Integer

-

是

应用版本号。

说明

卡片作为快应用程序的附属属性，开发者开发的快应用程序包必须包含主体程序及可选的多个卡片程序。

开发原则

一个卡片是一段嵌入在其他应用中执行、渲染的页面脚本，因此必须能够独立渲染和运行。卡片具有的能力是快应用页面能力的子集，按照负面清单的方式对卡片能力进行约束：

卡片开发整体原则如下：

框架约束

公共对象使用约束：

属性

类型

备注

$app

Object

app是快应用的全局对象，在卡片场景下不可用。

$page

Object

用于快应用页面对象的通用功能，在卡片场景下不可用。

页面生命周期使用约束：

属性

类型

备注

onBackPress

Function

卡片内嵌在各超级应用中，不适合监听back事件。

onMenuPress

Function

卡片内嵌在各超级应用中，不适合监听menu点击事件。

onMenuButtonPress

Function

卡片内嵌在各超级应用中，不适合监听遥控器的menu点击事件。

应用生命周期使用约束：

属性

类型

备注

onCreate

Function

卡片内嵌在各超级应用中，不适合快应用的onCreate事件。

onDestroy

Function

卡片内嵌在各超级应用中，不适合快应用的onDestroy事件。

消息通道使用约束：

属性

类型

备注

onmessage

Function

BroadcastChannel适用于页面间通讯，不适用于卡片场景。

postMessage

Function

BroadcastChannel适用于页面间通讯，不适用于卡片场景。

close

Function

BroadcastChannel适用于页面间通讯，不适用于卡片场景。

UI组件约束

通用事件使用约束：

名称

类型

备注

appear

事件

框架约束，暂不支持。

disappear

事件

框架约束，暂不支持。

swipe

事件

框架约束，暂不支持。

通用样式使用约束：

名称

类型

备注

position

none | fixed

框架约束，不支持fixed类型。

UI组件使用约束

目前在卡片中仅允许使用下表所列的组件，相关使用限制请参见“备注”列。

名称

备注

div

-

image

受限使用。无法加载本地路径图片。

input

1070版本前只支持button类型，1070版本开始，新增支持text，email，date，time，number，password类型。

list

受限使用。如果集成卡片的应用有滑动的效果，卡片中再使用list可能导致滑动冲突，请务必与卡片集成方说明，并进行调试。

list-item

同上。

marquee

支持。

picker

Activity context可以显示使用。

popup

支持。

progress

支持。

rating

受限使用。仅支持base64图片。

span

受限使用。只能作为 <text-item> 的子组件。

stack

支持。

swiper

支持。

text

卡片中不支持使用text组件的letter-spacing样式，需版本升级至1030版本方可使用。

video（1078+）

受限使用。poster属性无法加载本地路径图片。

API接口约束

名称

备注

system.app

app.getPackageInfo接口卡片场景适用，app.getInfo接口卡片场景不适用。

system.router:back

卡片场景不适用。

system.router:replace

卡片场景不适用。

system.router:clear

卡片场景不适用。

system.router:getLength

卡片场景不适用。

system.router:getPages

卡片场景不适用。

system.router:getState

卡片场景不适用。

system.decode:decode

卡片场景不适用。

system.notification

不适用于发送状态栏通知。

system.fetch:fetch(OBJECT)

当OBJECT中data类型为arraybuffer时，卡片场景不适用。

system.request

卡片场景暂不支持。

system.websocket:send(OBJECT)

当OBJECT中data类型为arraybuffer时，卡片场景不适用。

system.websocket:onmessage(OBJECT)

当OBJECT中data类型为arraybuffer时，卡片场景不适用。

system.requesttask:request

卡片场景不适用。

system.file

在主程序中使用，卡片场景不能使用。

system.webview

通过进入主程序打开webview。

system.sensor

卡片场景不适用。

system.shortcut

卡片场景不适用于桌面图标的查询和创建。

system.device:getId

卡片场景不适用。

system.device:device:getDeviceId

卡片场景不适用。

system.device:device:getUserId

卡片场景不适用。

system.record

录音权限比较敏感，统一在主程序中调用。

system.bluetooth:getDevices

卡片场景不适用。

system.bluetooth:writeBLECharacteristicValue

卡片场景不适用。

system.bluetooth:onblecharacteristicvaluechange

卡片场景不适用。

system.cipher:aes

卡片场景不适用。

system.media

卡片场景不适用，通过进入主程序实现业务诉求。

service.wxpay

卡片场景不适用，支付一般需要二次确认，进入主程序再进行支付。

service.alipay

卡片场景不适用，支付一般需要二次确认，建议进入主程序再进行支付。

system.sms

卡片场景不适用，在主程序中使用。

system.share

卡片场景不适用，在主程序中使用。

service.share

卡片场景不适用，在主程序中使用。

system.wifi

卡片场景不适用，在主程序中使用。

system.contact

卡片场景不适用，在主程序中使用。

system.package:hasInstalled

受限使用，只能查询HarmonyOS应用或Android应用是否有安装，不能查询快应用是否有安装。

system.storage

不同厂商对此接口的实现稍有差异，某些厂商的卡片存储与快应用中心的快应用是共享的，即在快应用中通过此接口写入的值在对应的卡片中也可以进行读写，某些厂商的卡片存储嵌入在卡片所集成的宿主应用中，两边是隔离的。

华为采用隔离的方式。

system.device:getSerial

卡片场景不适用，在主程序中使用。

system.ai

卡片场景不适用，在主程序中使用。

system.geolocation

受限使用，使用前请务必先联系华为进行安全评估。

system.image:pickColor

受限使用，必须使用1045+版本。

service.account

卡片场景不适用，在主程序中使用。

service.pay

卡片场景不适用，在主程序中使用。

service.push

卡片场景不适用，在主程序中使用。

service.ad

卡片场景不适用，在主程序中使用。

开发指导

使用快应用IDE开发卡片的操作如下，更详细的内容请参见“卡片类快服务接入指南”。

打包正式版本

确保开发的卡片功能没有问题，即可使用华为快应用IDE打包发布成rpk包，提交华为应用市场进行上架审核，详细打包过程参见“打包快应用”。

相关链接

FAQ

案例