智慧桌面卡片开发文档 - vivo ·...

智慧桌面卡片开发文档


V1.0.1


版本记录

版本修改日期描述软件是否修改

1.0 2017-5-23 新增卡片与快应用账号绑定内容(3.3 章节)。否

1.0 2017-6-20 ImageView 新增 property:src_original 属性（2.2.4.1

章节）是

1.0 2018-7-12 新增卡片上动态显示(隐藏)某个区域的功能的说明是


目录

第 1 章智慧桌面及智慧桌面卡片 --------------------------------------- 5

1.1 智慧桌面介绍 -------------------------------------------------- 6

1.2 智慧桌面卡片 -------------------------------------------------- 6

1.2.1 智慧桌面卡片开发 ------------------------------------------- 6

1.2.2 智慧桌面卡片特色 ------------------------------------------- 6

1.3 卡片开发准备 -------------------------------------------------- 7

第 2 章卡片代码组成 ------------------------------------------------- 8

2.1 zip 包基本介绍 ------------------------------------------------- 9

2.1.1 zip 包的组成 ------------------------------------------------ 9

2.1.2 正确打包方式 ----------------------------------------------- 9

2.2 布局文件语法 ------------------------------------------------- 10

2.2.1 manifest.xml 简介 ------------------------------------------- 10

2.2.2 manifest.xml 整体布局 --------------------------------------- 10

2.2.3 Applet 标签 ------------------------------------------------ 11

2.2.4 ViweGroup 和 View 标签 ------------------------------------- 15

2.3 JSON 默认配置 ------------------------------------------------ 22

2.4 资源文件 ----------------------------------------------------- 23

2.4.1 图片资源 -------------------------------------------------- 23

2.4.2 dimens 资源 ----------------------------------------------- 24

第 3 章服务端 API 设计 ---------------------------------------------- 26


3.1 NUWA 引擎工作流程 ------------------------------------------- 27

3.2 服务端 API 结构设计 -------------------------------------------- 27

3.2.1 Json 语法 -------------------------------------------------- 27

3.2.2 updateCommonValues -------------------------------------- 28

3.2.3 functions -------------------------------------------------- 30

3.3 卡片与快应用的账号绑定 --------------------------------------- 31

3.3.1 token 的生成与传输 ----------------------------------------- 31

3.3.2 token 的使用 ----------------------------------------------- 32

第 4 章卡片开发流程 ------------------------------------------------ 34

4.1 开发基本流程介绍 --------------------------------------------- 35

4.2 概略设计卡片布局 --------------------------------------------- 35

4.3 设计服务器 api 结构 -------------------------------------------- 39

第 5 章 vivo 智慧桌面预览工具 ---------------------------------------- 44

5.1 预览工具简介 ------------------------------------------------- 45

5.2 预览工具使用 ------------------------------------------------- 45

5.3 异常提示解析 ------------------------------------------------- 46

第六章规范 -------------------------------------------------------- 49


第 1 章智慧桌面及智慧桌面卡片

vivo 智慧桌面指的是当手机处于桌面形态时，向左滑动到的最左边的屏幕。

vivo 智慧桌面中的内容以卡片的方式展示，除一些定制卡片外，智慧桌面的强大

之处更表现在他能够支持第三方卡片的接入。第三方只需提供一个标准的 zip 包，

智慧桌面将会通过 nuwa 引擎将其渲染成卡片展示在智慧桌面上。


1.1 智慧桌面介绍

vivo 智慧桌面除了具备传统负一屏的应用建议、情景智能、天气等功能外，

其强大之处在于它的可扩展性，随着第三方卡片的接入，vivo 智慧桌面将为用户

提供更个性化的服务。同时，vivo 智慧桌面卡片支持快应用的跳转，这让 vivo 智

慧桌面在快应用这一新型应用生态下有了更大的发展空间。

1.2 智慧桌面卡片

1.2.1 智慧桌面卡片开发

智慧桌面卡片开发成本并不高，对于有安卓开发经验的开发者来说，只要遵

循后续第二章节讲解的代码设计原则，按要求设计出规范的 zip 包，并在服务端

返回标准格式的数据，便可通过开发者调试工具预览与调试卡片了。

1.2.2 智慧桌面卡片特色

对用户来说，智慧桌面卡片支持跳转快应用，用户无需下载安装 apk，即可

享受原生应用的性能体验。

对第三方来说，智慧智慧桌面卡片提升了第三方应用服务的转化效率，可为

第三方应用拉活拉新。


1.3 卡片开发准备

开发智慧桌面卡片的第一步，就是到开发者平台下载“vivo 智慧桌面预览

工具”。需要注意的是，预览工具在安卓手机上仅支持 android 6.1 及以上版

本。

安装完成后，首次登陆会弹出请求读写 SD 卡权限对话框，如图 1.1 所示，

开启权限后，就可以使用预览工具来调试卡片了。如果未同意权限请求，预览

工具将无法读取导入的 zip 包，开发者需要到设置中开启此权限。

图 1.1

接下来，开发者需要的就是准备一个标准的 zip 包了。下面的第二章节将会

细致讲解如何设计出标准的 zip 包，第三章节讲解服务端的处理方式，第四章大

致介绍了卡片开发流程，给了一个简单的示例供开发者参考。第五章介绍预览工

具使用的相关事项。第六章介绍了开发者开发过程需要遵循的相关规范。


第 2 章卡片代码组成

卡片代码由布局文件、资源文件、默认配置文件组成，这些文件被压缩成 zip

包，该 zip 包可被 NUWA 引擎渲染为智慧桌面卡片。本章节将介绍卡片代码的

语法规则及注意事项。


2.1 zip 包基本介绍

2.1.1 zip 包的组成

zip 文件格式是 NUWA 引擎唯一可识别的压缩格式，zip 包中需包含存放本

地资源的 images 和 values 文件夹，描述卡片布局的文件 manifest.xml，默认的

配置文件 default_json.json。zip 包中文件结构如图 2.1：

图 2.1

2.1.2 正确打包方式

在 zip 文件打包时，确保图 2.1 的文件齐全。打包的目录层级应该为四个文

件的直接层级，不可在上一层级下打包，否则会 NUWA 引擎无法解析。

打包过程如下图 2.2，直接选中四个文件--右击—点击添加到压缩文件，然

后执行正常的打包流程即可。

图 2.2

2.2 布局文件语法

此处的布局文件指的是 zip 包中的 manifest.xml 文件。

2.2.1 manifest.xml 简介

zip 包中的 manifest.xml 文件是卡片的渲染脚本，这和 Android 工程中的

manifest 文件不同，它描述了卡片的布局结构和样式，更像是 android 工程中的

界面布局的 xml 文件。其整体的语法规则与 android 原生布局文件的语法类似。

2.2.2 manifest.xml 整体布局

布局文件必须包含一个根节点<Applet></Applet>，根节点内部子节点支持

<ViewGroup></ViewGroup> 和 <View/> 两个标签，其中

<ViewGroup></ViewGroup>标签可以包含<View/>标签。

一条完整的语句由一段开始标签和一段结束标签组成，这和 android 原生的

节点标签类似，ViewGroup 可类比于 LinearLayout 等布局，View 可类比于

TextView 等控件。不带有任何逻辑功能的基本语法如下：

<标签名属性名 1="属性值 1" 属性名 2="属性值 2" ...> ...</标签名>

manifest.xml 整体模板示例如下：

<?xml version="1.0" encoding="utf-8"?>

<Applet xmlns:property="http://schemas.android.com/apk/res/property"

xmlns:hiboard="http://schemas.android.com/apk/res/hiboard"

xmlns:action="http://schemas.android.com/apk/res/action"

...>



<ViewGroup

property:name="LinearLayout"

...>



...


</ViewGroup>

</Applet>

需要注意的是 <Applet></Applet> 标签下，最外层应该包含一个

<ViewGroup></ViewGroup>标签，这和 NUWA 引擎的解析原理有关。

省略号部分添加描述标签属性，可参考 android 中布局文件语法。

2.2.3 Applet 标签

Applet 标签作为 manifest.xml 文件的根节点，与 Android 布局文件的根节点

类似。Applet 标签下定义了 xml 三种不同类型的命名空间，不同的命名空间来区

分不同的操作。

标签内部自定义的 xmlns 应统一写成如下形式：





...>

</Applet>

下表列出了三种命名空间的作用和使用环境，Applet 标签内部省略号部分

均使用 hiboard 命名空间的属性：

nameSpace 作用使用环境

property 对卡片 view 的属性设置 ViewGroup、View 标签

hiboard 设置卡片相关的信息以及跳转时用到

的包名类名

Applet 标签

action 设置点击事件 ViewGroup、View 标签

除了定义的 xmlns 命名空间，Applet 标签下需要设置卡片信息相关属性，该

标签中均使用 hiboard 命名空间。以下列出了 hiboard 下的所有属性及含义：


属性名必填描述

appletName 是卡片的名称，会显示在快应用卡片的标题

位置

appletIcon 是卡片的图标，属性值设置为“icon.png”,图

片资源放在 images 文件夹中并以 icon 命

名，图片格式为 png 格式。

appletVersion 是卡片的版本号，相当于 versionCode。第一

版可设置为“1”, 推荐每次重新上传包时

applerVersion+1

appletVersionName 是卡片的版本号，相当于 versionName，三位，

第一版可设置为“1.0.0”。

minEngineVersion 是智慧桌面快应用解析器的版本号，目前为

“1”。

minHeight 是卡片折叠状态下的高度。

maxHeight 是卡片展开状态下的高度。

flexibleHeight 否如果您需要卡片上某个 layout( 比如

banner)可以动态配置显示或隐藏，则需要

设置该值，该值表示需要动态显示的 layout

的高度

updateUrl 是请求更新数据的链接。卡片更新时，会去该

链接请求 json 数据,若不需要和服务器交

互，此值置 “”


refreshDuration 是移动网络下向服务器请求数据的间隔。

单位为 s（秒）

refreshDurationInWifi 否 Wifi 下向服务器请求数据的间隔。

单位为 s（秒），默认为 5 分钟

appletPackageName 是点击卡片启动快应用平台上页面需要的包

名。

上面列出的必填属性在 Applet 标签中均需要定义，属性值均为 string 类型。

几个属性的注意点：

① minHeight、maxHeight 均是指卡片真正高度减去 44dp，44dp 并非指标

题栏高度，标题栏高度为 37dp，44dp 除了影响这两个属性值的设置，

没有任何其他作用。这和 NUWA 引擎解析原理有关，此处不做具体介

绍，设置值应遵循此规则。若卡片无展开、折叠两种状态，设置两个值

相同即可。

② updateUrl 为请求更新数据的链接，第三方服务器的访问方式为 https，

不能是 http。

③ hiboard:refreshDuration="300"，表示移动网络下向服务器请求数据的间

隔为 300s，单位为秒。卡片的刷新规则将在第六章介绍，开发者需权衡

后设置该时间。

下图 2.3 展示了 i 音乐卡片的展开和折叠概念图，点击标题栏的展开按钮，

折叠的部分将展开来，折叠状态的卡片总高度为 156dp,则 minHeight 应设置为

（156-44）dp，即 112dp。


图 2.3

Applet 标签代码示例：





hiboard:appletIcon="icon.png"

hiboard:appletName="热门影视剧"

hiboard:appletPackageName="com.**.**.**"

hiboard:appletVersion="1"

hiboard:appletVersionName="1.0.0"

hiboard:maxHeight="185dp"

hiboard:minHeight="185dp"

hiboard:minEngineVersion="1"

hiboard:refreshDuration="3600"

hiboard:refreshDurationInWifi="300"

hiboard:updateUrl="https://api.***4dc3" >

<ViewGroup


...>

...

</ViewGroup>

</Applet>

Applet 标签下最外层的 VeiwGroup 标签实际代表了卡片内部去掉标题栏部

分的最外层布局（即 37dp 高度的标题栏 NUWA 引擎已经自动生成，开发者只

需提供 icon 和标标题名称即可）。图 2.3 已标识。


2.2.4 ViweGroup 和 View 标签

ViewGroup 及 View 标签是布局文件的子节点，使用属性的命名空间为

property 和 action。

2.2.4.1 property 属性

ViewGroup/View 目前支持设置的 property 属性如下表所示：

View style 相关属性

layout_width, layout_height, paddingLeft,

paddingRight, paddingTop, paddingBottom, padding,

layout_marginLeft, layout_marginRight,

layout_marginTop, layout_marginBottom,

layout_margin, background, enabled, selected,

clickable, scaleX, scaleY, minWidth, minHeight,

visibility

TextView 相关属性

text, textColor, textSize, textStyle, ellipsize, maxlines,

gravity, drawableTop, drawableLeft, drawableRight,

drawableBottom

ImageVIew 相关属性 src, scaleType, adjustViewBounds，src_original

Layout 相关属性

layout_above, layout_alignBaseline,

layout_alignBottom, layout_alignEnd, layout_alignLeft,

layout_alignParentBottom, layout_alignParentEnd,

layout_alignParentLeft, layout_alignParentRight,

layout_alignParentStart, layout_alignParentTop,

layout_alignRight, layout_alignStart, layout_alignTop,


layout_alignWithParentIfMissing, layout_bellow,

layout_centerHorizontal, layout_centerInParent,

layout_centerVertical, layout_toEndOf, layout_toLeftOf,

layout_ToRightOf, layout_toStartOf, layout_gravity,

layout_weight, orientation

特殊属性 id , name

特殊属性说明：

property:name 属性表示该 ViewGroup 或 View 的正式名称，ViewGroup 或

者 View 标签下必须包含该属性。属性值则为控件在 android 中的命名。

示例：

property:name = “TextView” 表示该 View 标签为 TextView 控件

property:name = “LinearLayout” 表示该 ViewGroup 标签为线性布局

property：name 属性使用的几个注意点：

①当 property:name 属性值为 ImageView 时，若该控件支持点击操作，需

要将 property:name 属性值设置为“com.vivo.hiboard.util.ClickableImageView”；

当 property:name 属性值为 TextView 时，若该控件支持点击操作，需要将

property:name 属性值设置为“com.vivo.hiboard.util. ClickableTextViewBG”；

属性值为 LinearLayout 时，若布局支持点击操作，需要将 property:name

属性值设置为 “ com.vivo.hiboard.util.ClickableViewGroup ” 或者

“com.vivo.hiboard.util. ClickableViewGroupAlpha”。前者对 linearLayout 点击时

布局 background 会变化，同时布局内部图片文字有 30%透明度变化；后者

LinearLayout 布局内部仅图片和文字有 30%透明度变化。开发者根据需要选择控


件。注意当 linearLayout 支持点击时，即该 viewGroup 标签设置了 action 属性，

其内部的控件不能在设置 action 属性。

以上封装的控件（布局）会有点击效果。

②property:name 的属性值不可设置为 ListView 或 GridView，NUWA 引擎

不支持该两种控件。

property:id 属性表示该控件的唯一标识，该属性不强制设置。若某控件或

布局支持点击操作或者需要内容更新时，则必须设置该属性，用来区分响应的控

件或布局。简单来说，如果标签下设置了 action 属性，则必须设置 property:id 属

性，如果某个控件需要从服务器获取动态值，则必须设置 property:id 属性。属性

值由开发者定义，该属性的属性值在服务器 api 中需要用到，后续会详细介绍。

ImageView 属性说明：

property:src_original 该属性是针对于 ImageView 控件的属性，使用

property：src 时智慧引擎会圆角化处理卡片的图片资源，如果图片不想被处理，

可使用该属性。

property:scaleType 属性值可设为 center、center_inside、center_crop、matrix、

fit_xy、fit_start、fit_center、fit_end。

其他非特殊属性说明：

上述表格中的 TextView 和 ImageView 相关属性只可在 View 标签下使用，

View style 相关属性及 Layout 相关属性在 ViewGroup 和 View 标签下通用。除特

殊属性外，其他属性值和 android xml 布局的属性值相同。

需要注意的是，property 属性值的双引号内不要加空格，否则会无法正确解

析布局。


错误示例：

property:layout_height="match_parent "

上面的写法解析出错，因为引号内部最后有空格，导致无法正确解析属性值。

ViewGroup 标签代码示例：

<ViewGroup

property:id="out_layout"


property:layout_width="match_parent"

property:layout_height="match_parent"

property:orientation="vertical">

<ViewGroup...>

…

</ViewGroup>

<View.../>

</ViewGroup>

上节提到，Applet 标签下面最外层的 ViewGroup 是卡片去掉标题栏部分的

外层布局，事实上，除了标题栏的高度 37dp，NUWA 引擎也设定好该层布局边

界距离卡片左右边界的距离，数值为 13dp。

View 标签代码示例：

<View

property:name= "TextView"

property:layout_height="wrap_content"

property:layout_width="wrap_content"

property:textColor="#FF5A5A5A"

property:textSize="@dimen/grade_text_size"

property:layout_marginLeft ="@dimen/grade_name_layout_marginLeft"

property:text = "评分:"/>

该代码中出现的 dimen 资源存放在 zip 包的 values 文件夹下，规则和 android

中类似，values 文件夹资源的存放后续章节讲解。

2.2.4.2 action 属性

命名空间为 action 的属性表示对该控件会进行的操作，目前只支持点击操


作，点击操作分为两种情形：

action:click_jump 点击跳转到快应用的相应页面

action:click_update 点击更新，点击卡片上某个按钮触发更新卡片上的整体或

者部分 view 控件的内容

不需要内容更新或跳转的控件不需要设置这两种属性。

1）action:click_jump 属性：

该属性的属性值和跳转逻辑以及控件展示需求有关，下面介绍属性值的设置。

需要注意的是，智慧桌面卡片只支持跳转快应用。

A）属性值的设置

根据第三方需求，可分为如下情况。

跳转快应用，控件内容不更新属性值设置为快应用相应页面 path。

跳转快应用，控件内容更新属性值设置为快应用相应页面 path 的开头某部

分。服务器需返回 valueId

从表格看出，卡片跳转快应用时，action:click_jump 属性值设置和快应用的

path 相关。卡片跳转快应用时，NUWA 引擎会根据 path 跳转到快应用相应页

面，第三方不需要做额外的逻辑处理。

注意到上面表格的备注中的“服务器需返回 valueId”，只有在控件内容需要

更新并且需要跳转时才需要 valueId，也就是说每次点击控件或布局跳转页面不

同则需要 valueId。关于服务器如何返回 valueId 具体内容见 3.2 章节，该部分讲

解如何设置“valueId”。

看一个例子：


图 2.4

分析上面卡片的需求，卡片下方的“更多热门影视”TextView 控件内容不需

要动态更新，点击跳转到快应用首页，因此该控件属于表格中第一种情况。该控

件的跳转页面是固定的，action:click_jump 属性值设置为快应用首页的 path，

NUWA 引擎会取出该属性值跳转至快应用指定页面。

下面代码描述了该 TextView 控件：

<View

property:id = "more_popular_film"

property:name = "com.vivo.hiboard.util.ClickableTextViewBG"

property:layout_height = "@dimen/bottom_layout_height"

property:layout_gravity = "center"

property:gravity = "center_vertical"

property:layout_width = "wrap_content"

property:textColor="#FF0971D4"

property:textSize="@dimen/more_film_text_size"

property:text = "更多热门影视剧"

action:click_jump = "/"/>

展示影视海报内容的控件 ImageView 需要动态更新，点击该控件可跳转至

影视内容详情页，因此该控件属于上面表格中的第二种情况。该控件的跳转页面

不固定，固 action:click_jump 的属性值无法设置固定 path。为了解决这个问题，

可将 action:click_jump 设置为 path 前面相同部分，整个 path 剩下的部分就是


valueId 了，valueId 标识了控件跳转的具体详情页。manifest 中没有 valueId 属

性，那 valueId 在哪里设置呢，该值设置在卡片请求更新的 json 文件中。3.2 章

节将详细讲解 json 文件的格式。NUWA 引擎会将两个字符串连接为完整的 path

跳转到快应用相应页面。

图 2.5

分析图 2.5 中影视的 path ， path 字符串前面相同部分都可作为

action:click_jump 的属性值。下面代码描述了该 ImageView 控件：

<View

property:id="first_poster"

property:name="com.vivo.hiboard.util.ClickableImageView"


property:layout_height="@dimen/poster_height"

property:scaleType="center_crop"

action:click_jump="Movie" />

上面介绍了在可跳转快应用时,action:click_jump 的属性值和 valueId 设置，

只要保证两个值的正确性，NUWA 引擎便会根据 path 跳转到快应用相应页面。

B）属性值注意事项

如果属性值是 url 参数的形式的话，那参数中的双引号”要替换成"（不

要漏了分号） &要替换成 & 否则 xml 会解析失败。

示例：

原始参数：

/ShopList?navColor=&search_source=1&target={\"is_premium\":1,\"specified_attribu


tes\":[8],\"support_ids\":[8]}&title=大牌 5 折&navType=0&color_type=2&target_name=大牌

5 折&banner_type=0&entry_id=20006761&business_flag=23&animation_type=1

替换后的参数：

/ShopList?navColor=&search_source=1&target={\"is_premium\":1,\

"specified_attributes\":[8],\"support_ids\":[8]}&title=大牌5

折 &navType=0&color_type=2&target_name= 大牌 5 折

&banner_type=0&entry_id=20006761&business_flag=23&animation_type=1

2.3 JSON 默认配置

如果卡片上有需要动态更新的内容，zip 包中则需要 default_json.json 来配

置卡片默认内容。该文件是在无网络情况下获取不到更新内容时，会默认展示的

内容。因此文件中不能包含网络资源。default_json.json 的文件格式和卡片请求

的更新 json 文件相同。具体格式将在 3.2 章节中介绍。以下给出 default_json.json

的一个示例，建议在阅读完 3.2 章节再看示例。

{

"updateCommonValues": [{

"valueId": "?type=movie&id=25829175",

"type": "image",

"id": "first_poster",

"value": "first_poster.webp"

}, {

"type": "text",

"id": "first_name",

"value": "西游记女儿国"

}, {

"type": "text",

"id": "first_grade_number",

"value": "4.5"

}, {


"type": "image",

"id": "second_poster",

"value": "second_poster.webp"

}, {

"type": "text",


"id": "second_name",

"value": "Unnatural"

}, {

"type": "text",

"id": "second_grade_number",

"value": "9.2"

}, {


"type": "image",

"id": "third_poster",

"value": "third_poster.webp"

}, {

"type": "text",

"id": "third_name",

"value": "全美超模大赛第二十四季"

}, {

"type": "text",

"id": "third_grade_number",

"value": "7.2"

}],

"functions": []

}

2.4 资源文件

manifest.xml 和 default_json.json 文件中定义的图片资源放到 images 文件夹

下，manifest.xml 中 dimens 资源放到 values 文件夹下。

2.4.1 图片资源

图片资源的存放：

本地的图片资源存放在 zip 包的根目录下的 images 文件夹中，该文件夹中

的文件目录如下：


不同分辨率的图片放在对应的目录中，目前支持 png 和.9.png 等图片格式。

该文件夹中必须包含卡片标题栏图的图片标资源，并命名为 icon.png。在介绍

applet 标签下的 hiboard:appletIcon 属性时已做说明。除 icon 必须使用 png 格

式外，其他图片资源不做强制限制。

图片资源的引用：

引用时，属性值直接设置为图片名称即可，需要注意的是，后缀也是属性值

的一部分，否则会解析错误。

示例：各分辨率 drawable 文件夹中定义了下图的图片资源，下面代码演示

对图片资源的引用。

<View

property:name="ImageView"



property:layout_gravity="center_vertical"

property:src="star.png"/>

2.4.2 dimens 资源

dimens 资源的存放：

本地的 dimens 资源存放在 zip 包的根目录下的 values 文件夹中，该文件夹

中的文件目录如下：


不同分辨率的 value 资源放在对应分辨率的文件夹下。存放 value 资源的文

件命名为 dimens.xml，dimens.xml 中资源的命名和 Android res 中的命名一致即

可：

代码示例：

<resources>

<dimen name="line_height">1dp</dimen>

<dimen name="line_width">318dp</dimen>

<dimen name="line_margin_left">0dp</dimen>

<dimen name="line_margin_top">14dp</dimen>

</resources>

dimens 资源的引用:

dimens 中定义的 values 资源引用和 android 布局中对 dimens 中资源引用

类似。下面代码演示对 dimens 资源的引用。

<View


property:layout_width="@dimen/line_width"

property:layout_height="@dimen/line_height"

property:layout_marginLeft="@dimen/line_margin_left"

property:background="divider_line.9.png" />


第 3 章服务端 API 设计

第三方服务器需要返回固定格式的数据给智慧桌面卡片，本章重点介绍服务

端的设计，开发者需要根据该章节中的规则设计服务端 API 结构。后续会随着

NUWA 引擎的完善，此章节会更新账号关联相关的内容。


3.1 NUWA 引擎工作流程

NUWA 引擎是为了在智慧桌面上引入第三方卡片而设计的渲染工具。NUWA

引擎集渲染卡片与更新卡片于一体，基本满足了第三方卡片的需求，自身也在不

断的完善中。

开始解析卡片

去本地目录读取zip包

开始解析zip包的xml文件并转成native view

添加到智慧桌面上

划入智慧桌面，开始加载，

向服务器请求数据

解析数据，刷新卡片

3.2 服务端 API 结构设计

智慧桌面卡片上的内容支持动态更新，每次更新时会去 updateUrl 中定义的

链接去请求 json 数据，第三方服务器端根据是否需要更新以及更新什么内容返

回不同的 json 数据，智慧桌面卡片会根据不同的数据更新不同的 view 上的内容。

服务端 API 结构的设计可参照第四章的实例讲解。

3.2.1 Json 语法

JSON 格式最大的优点是易于人的阅读和编写，通常不需要特殊的工具，就


能读懂和修改，是一种轻量级的数据交换格式。JSON 文件都是被包裹在一个大

括号中 {}，通过 key-value 的方式来表达数据。JSON 语法是 JavaScript 语法的子

集。JSON 语法规则：

数据在名称/值对中

数据由逗号分隔

花括号保存对象

方括号保存数组

第三方服务器返回的 json 数据包含两个数组对象，对象之间用对象隔开如

下所示：

{

"updateCommonValues": [],

"functions": []

}

每个对象数组内部可包含多个对象，也可为空。Json 数据的详细语法开发者

可自行学习。下面会对上述两个数组对象做详细说明。

3.2.2 updateCommonValues

tag 为 updateCommonValues 的数组中的对象，从需求来看有两个作用：

一个是更新卡片上 TextView/ImageView 上的内容，包含所有需要更新的

view 的信息，更新相关的对象名为 “ value ”；另一个是为了支持在

textView/ImageView 中内容更新情况下，控件会根据内容跳转到不同页面的需求，

跳转相关的对象名为“valueId”。代码示例：

{


"type": "image",

"value":"https://img1.doubanio.com\/view\/photo\/s_ratio_poster\/p

ublic\/p2510604929.webp",

"valueId": "?type=movie&id=27140017"


}

每个数据中包含 id，type 和 value 和 valueId 四个对象。

id 表示需要更新或者需要跳转控件的 id，这也是为什么 manifest.xml 中定义

action 属性的标签需要定义 id 属性的原因了。

type 表示需要跳转或者更新控件的类型，目前支持更新 text、image、

viewgroup；需要注意的是，type 为 viewgroup 时不需要 value 对象，该类型是

为支持某个线性布局的跳转。type 的值和 property：name 属性对应如下：

property:name 的属性值 type 对象的值

TextView、

com.vivo.hiboard.util.ClickableTextViewBG

text

ImageView、

com.vivo.hiboard.util.ClickableImageView

image

com.vivo.hiboard.util.ClickableViewGroup

com.vivo.hiboard.util.ClickableViewGroupAlpha

viewgroup

value 是更新的内容，text 类型的就是字符串，image 类型的可以是 zip 包中

的本地图片 xxx.png 或者是以 http 开头的服务器上的图片。不需要 value 时可以

不写或置空。

valueId 是卡片跳转的标识，只有需要动态更新，并且跳转目的地由控件显

示内容决定的控件，才需要改值作为标识。也就是说，控件的跳转目的地不是固

定的，需要由服务器返回的 valueId 来标识控件所跳转的目的地。不需要 valueId

时可以不写或置空，如下两种方式都可以：

形式一：

{

"type": "text",


"id": "third_name",


}

形式二：

{

"type": "text",

"id": "third_name",


"valueId": ""

}

关于 valueId 的设置，在 2.2.4.2 节已经详细说明。

第四章给出完整的 updateCommonValues 标签示例。

3.2.3 functions

tag 为 functions 的数组对象，可以动态调用卡片上 view 的一些简单方法，

目前只支持设置 visibility，后续会视需求支持更多方法，格式如下：

"functions": [

{

"id": "login_layout",

"function": "setVisibility",

"args": [

{

"primitive":"Integer",

"value": "0"

}

]

},

{

"id": "orderlist_layout",

"function": "setVisibility",

"args": [

{

"primitive":"Integer",

"value": "8"

}

]

}

]


Id 表示调用方法的 View 的 id， function 表示调用的方法名， args 表示参

数，如果是基本类型的则 tag 是 primitive，否则 tag 是 class。

如上实例，value 值为 0 表示 Visible，4 表示 Invisible , 8 表示 Gone 。

应用：如果需要卡片上某个 layout 区域动态显示或者隐藏，可以在服务端调

用此方法来控制，注意：一定要设置 flexibleHeight 这个属性，否则卡片高度会

有问题。

3.3 卡片与快应用的账号绑定

注：本地调试此功能时需要配合 v1.1 版本的预览工具和 v1.2 版本的负一屏

智慧桌面的卡片上有根据不同用户显示定制化内容的需求，卡片与快应用账

号的绑定主要是将快应用中登录生成的 token 信息传递给智慧桌面，智慧桌面会

将该 token 传递给卡片服务端以请求定制化内容。

3.3.1 token 的生成与传输

token 是在快应用中生成，用户点击卡片跳转到快应用中登录之后，快应用

端需要根据用户账户信息生成一个 string 类型的 token，然后调用快应用平台的

接口将该 token 写入到智慧桌面的数据库中(该 token 只会被用于传递给卡片服

务端，建议该 token 与真实的账号信息隔离开来并对该 token 设置有效期，经常

更新该 token)。

示例代码：

1. setStorage: function () {

2. var that = this;

3. if (this.storageValue) {

4. storage.setGlobal({

5. key: "token",

6. value: this.storageValue,


7. success: function (ret) {

8. prompt.showToast({

9. message: "token:" + that.storageValue + "}",

10. })

11. }

12. })

13. } else {

14. prompt.showToast({

15. message: "请输入 token 值"

16. })

17. }

18. },

3.3.2 token 的使用

Token 是在卡片请求服务端时被使用，我们会查询数据库中对应的卡片有

没有 token 信息，有 token 的话则会在 url 的最后拼接上 token 信息：

请求的 url = manifest 中定义的 url + “&token=” + token;

服务端在收到请求时，应该提取出 token 信息，并根据 token 信息返回定制


化的内容给卡片显示。


第 4 章卡片开发流程

在本章会就介绍智慧桌面卡片的基本开发流程，当然并不是要完全按照给

定的开发流程来开发，高效的开发流程有很多种方式，一般是根据整个团队的工

作节奏来选择和开展，我们这一节讨论到的流程只是其中常见的开发流程。


4.1 开发基本流程介绍

在启动开发前，我们要对智慧桌面卡片的产品体验有一个清晰的规划和定义。

开发时，一般会先设计出卡片的概念图，根据概念图设计卡片的粗略布局。由卡

片的跳转逻辑和布局中对应的控件 id，就可以设计出服务器 api 的结构框架。然

后就可以布局的调整和服务器接口开发就可以并行进行了。流程如下：

分析需求

设计概念图

评估卡片可行性

概略设计卡片布局

设计服务器api结构

详细设计卡片布局

调试

4.2 概略设计卡片布局

概略设计卡片布局的主要目的是设计服务器 api 的结构，需要明确 api 返回

的 value 或 valueId 的 id，即 manifest.xml 中 property：id 的属性值。下面以某


卡片示例，卡片概念图如下：

在 2.2 章节介绍 manifest.xml 布局时已经提到，需要保证 Applet 标签下最外

层为 ViewGroup 标签，最外层的 viewGroup 标签代表了图中红色框部分。在最

外层 viewGroup 内部可分为上中下三个绿色框标出的并列布局，最上方的绿色

框内部又可包含三个并列的蓝色框布局。manifest.xml 文件大致可设计：





hiboard:appletIcon="icon.png"

hiboard:appletName="热门影视剧"

... >

<ViewGroup



property:layout_height="match_parent"

property:orientation="vertical" >

<ViewGroup

property:id="top_layout"


property:orientation="horizontal" >

<ViewGroup


property:id="ranking_first"



<View




<View

property:id="first_name"

property:name="TextView"/>

<ViewGroup

property:id= "first_grade"

property:name= "LinearLayout"

property:orientation="horizontal">

<View



<View



<View

property:id = "first_grade_number"

property:name = "TextView"/>

</ViewGroup>

</ViewGroup>

<ViewGroup

property:id="ranking_second"

property:name="LinearLayout">

<View

property:id="second_poster"



<View

property:id="second_name"


<ViewGroup

property:id= "second_grade"



<View



<View


<View

property:id = "more_popular_film"

property:name = "com.vivo.hiboard.util.ClickableTextViewBG"

property:layout_height = ""

property:layout_width = "wrap_content"

property:text = "更多热门影视剧"

action:click_jump = "/"/>

</ViewGroup>

</Applet>

为方便查看，上面代码将统一层级的标签用相同颜色表示。

4.3 设计服务器 api 结构

分析概念图的需求，上方三各影视信息代表了 manifest.xml 文件中三个蓝色

viewGroup 标签。分析其中一个：

<ViewGroup

property:id="ranking_first"



<View




<View

property:id="first_name"


<ViewGroup

property:id= "first_grade"



<View



<View



<View

property:id = "first_grade_number"


</ViewGroup>

</ViewGroup>


id 为“first_poster”的控件表示影视的海报，展示的内容需要更新，点击该

控件进入所展示影视详情页，因此每次控件跳转的目的地不同。则服务器需要返

回 value 和 valueId。

Id 为“first_name”和“first_grade_number”的控件表示影视的名字，展示

的内容需要更新，不要点击的操作，则服务器只返回 value 即可。

其他两个影视信息和第一个相同，此处不再赘述。概念图的最下方，“更多

热门影视剧”控件，该控件内容不需要更新，且点击跳转到的页面固定，因此服

务器不需要返回该控件的数据。

根据 manifest.xml 文件设计出对应 api 结构如下：

{

"updateCommonValues": [{

"id": "first_poster",

"type": "image",

"value": "", <!—此处是获取海报图片的地址-->

"valueId": ""

}, {

"id": "first_name",

"type": "text",

"value": ""

}, {

"id": "first_grade_number",

"type": "text",

"value": ""

}, {


"type": "image",

"value": "",

"valueId": ""

}, {

"id": "second_name",

"type": "text",

"value": ""

}, {

"id": "second_grade_number",

"type": "text",


"value": ""

}, {

"id": "third_poster",

"type": "image",

"value": "",

"valueId": ""

}, {

"type": "text",

"id": "third_name",

"value": ""

}, {

"id": "third_grade_number",

"type": "text",

"value": ""

}],

"functions": []

}

下面会解释一下什么情况下只需要服务器返回 valueId 而不需要 value，听

起来好像很矛盾，既然不需要动态更新控件，跳转目的地为什么会不同呢？

看下方的概念图：

红色框标出的 viewGroup 需要支持点击，动态更新的控件是 viewGroup 内

部的子控件，因此该 viewGroup 只需要服务器返回 valueId 即可。Type 类型为

“viewgroup”，该类型在 3.2.2 章节已作介绍。

需要注意的是，由于 viewGroup 支持点击，则该 viewGroup 需要有


action:click_jump 属性。此时，该 viewGroup 内部的子 view 中不能包含 action 属

性，否则会点击冲突。如果内部的 view 需要更新，则必须有 property:id 属性。

上面红框部分在 manifest.xml 中的布局为：

<ViewGroup

property:id="list_one"

property:name="com.vivo.hiboard.util.ClickableViewGroup"

action:click_jump="mofanginfo?id="



property:orientation="horizontal" >

<View

property:id="list_img_one"


property:layout_width="@dimen/list_item_image_width"

property:layout_height="@dimen/list_item_image_height"

property:layout_marginBottom="12dp"

property:layout_marginTop="12dp"

property:scaleType="center_Crop" />

<ViewGroup

property:id="content_layout"




property:layout_marginBottom="12dp"

property:layout_marginLeft="22dp"

property:layout_marginTop="12dp"

property:orientation="vertical"

property:paddingRight="0dp" >

<View

property:id="list_title_one"

property:name="TextView"



property:ellipsize="end"

property:maxLines="1"

property:textColor="#FF000000"

property:textSize="@dimen/list_item_title_size" />


<View

property:id="list_summary_one"

property:name="TextView"



property:layout_marginTop="@dimen/list_item_summary_margin_top"

property:ellipsize="end"

property:maxLines="1"

property:textColor="#FF343434"

property:textSize="@dimen/list_item_summary_size" />

</ViewGroup>

</ViewGroup>

由于是点击整个红框部分跳转，则 valueId 返回给标识红框部分的 viewGroup

布局，该部分默认 default_json.json 文件如下，第三方服务器返回的 api 结构类

似：

{

"id": "list_one",

"type": "viewgroup",

"valueId": "2147"

}, {

"id": "list_img_one",

"type": "image",

"value":"http://i3.meishichina.com/attachment/mofang/2018/04/03/201

80403152272267959113.jpg@!c200"

}, {

"id": "list_title_one",

"type": "text",

"value": "滋阴润燥，4 种食物去春燥"

}, {

"id": "list_summary_one",

"type": "text",

"value": "随着气温回升，万物复苏，此时天气还是变化不定，早晚温差大，加"

}


第 5 章 vivo 智慧桌面预览工具

vivo 智慧桌面预览工具是面向开发者的一款智慧桌面卡片开发调试工具，该

调试工具引入了 NUWA 引擎，可以模拟智慧桌面，对 zip 包进行渲染并以卡片

的形式展示。为方便开发者调试，预览工具还增加了一些异常提示，让开发者更

高效的设计出满意的智慧桌面卡片。


5.1 预览工具简介

预览工具解析卡片的流程和智慧桌面类似，还原了卡片在智慧桌面上的效果。

虽然基本还原了卡片的效果，但是以提高开发者开发效率为原则，卡片的跳转逻

辑与智慧桌面不尽相同。

调试时，开发者需要手动导入 zip 包到根目录的 appletCardDebug 文件夹路

径下。初次使用软件，app 会在根目录下创建名为 appletCardDebug 的文件夹。

经测试，绝大部分机型都会在根目录成功创建 appletCardDebug 文件夹。由于手

机厂商自身原因，个别华为机型创建的文件夹在电脑端显示为文件格式（手机端

显示文件夹格式），电脑端无法对文件夹进行移入文件操作，针对此情况，开发

者可手动删除该文件，在根目录下创建 appletCardDebug 文件夹。

5.2 预览工具使用

第 1 章已经强调，预览工具需开启 SD 卡权限才能正常使用。使用时点击首

页的添加卡片进入选择文件界面，选择 zip 包进行渲染。如下图 5.1 所示：

图 5.1


可一次选择多个卡片进行渲染，点击确定后，NUWA 引擎会根据选择文件的

先后顺序依次进行解析，渲染出来的卡片按顺序展示在首页。

如果选择的 zip 文件有异常，会弹出异常提示框，开发者可以根据提示修改

zip 包中可能有错误的地方。卡片右上方按钮可删除卡片，如图 5.2，点击删除卡

片后，其他卡片会重新解析。

5.3 异常提示解析

下面列出开发过程中可能出现的异常提示，并提供可能与之相对应的解决方

法，解决方法不一定涵盖所有情况。主要检查布局文件的语法是否错误，代码是

否规范，资源文件定义是否规范等。

1. xml 格式异常，可能是 tag 不匹配或书写错误，请检查修改后再试。

检查 manifest 文件下的标签形式是否正确，三种标签形式如下：

<Applet></Applet>、 <ViewGroup></ViewGroup>和<View/>。

action:click_jump 如果属性值是 url 参数的形式，检查属性值中的双引号”

是否替换成"（不要漏了分号） &是否替换成 & （不要漏了分号）

3. manifest 中 view/viewGroup 节点:***类名书写错误，导致找不到控

件，请检查修改后再试。

检查 property:name 属性的属性值书写是否正确，该属性值应该是 android

中定义的控件或者智慧桌面封装的控件，详细信息见 2.2.4.1 章节介绍。

检查 property:name 属性的属性值引号内部是否包含空格等字符。如下的写

法是错误的：

property:name="ImageView "

正确写法需要去掉引号内部的空格。

2. manifest 布局文件最外层没有包含一个 ViewGroup 的 tag，请检查

修改后再试。

检查 Applet 标签里面的最外层是否为 ViewGroup。2.2.2 章节有具体讲解。

规范写法应该如下：





...>



<ViewGroup


...>



...

</ViewGroup>

</Applet>

4. manifest 中定义了非法的资源值:***，在资源文件中找不到，请检查

修改后再试。

检查 manifest 文件中的属性值引号内部是否包含空格，错误示例：

property:layout_height="match_parent "

检查 manifest 文件中的属性值是否规范，错误示例：

property:textColor="fffff"

检查 manifest 文件中属性书写是否合法，错误

检查 dimens 文件中的资源值书写是否规范；

如果出现多个弹框提示错误，很大可能是 dimens 文件出现的问题。

5. ***属性在资源文件中的值非法，请检查修改后再试。

检查提示属性的值在 manifest 的定义是否合法（color、size 值等…）。属性

值应该和 android 原生控件的属性保持一致。


6.“***”点击事件中没有定义 id，请检查修改后再试。

检查定义了点击事件的控件是否定义了 id。详细信息参照 2.2.4.1 节

property:id 属性的介绍。错误示例：

<View



property:layout_height="@dimen/poster_height"

property:scaleType="center_crop"


上面的控件设置了 action:click_jump 属性，表示该控件支持点击操作，则必

须为该控件定义 property:id 属性。

7.“***”缺失 manifest 文件，请检查修改后再试。

检查 zip 包是否多一层目录，点击 zip 压缩包应该与下图左侧一致，右侧则

多了一层目录。正确的打包方式参照 2.1.2 节。

检查 manifest 书写是否正确，是否为 xml 格式。

8. 点击预览工具生成的卡片跳转不成功。

检查和快应用相关的参数，即快应用的包名、跳转路径等是否正确。跳转路

径包括 action 定义的属性值，以及服务器返回的 valueId。

跳转不成功的表现不一，跳转到小程序界面显示网络不给力、点击卡片无反

应等现象均有可能。


第六章规范

本章节介绍了卡片开发过程中的一些规范，开发者需要遵循以下规范来设计

开发。


开发者平台卡片包的最大限制是 1M，请确保提供的 zip 包小于 1M。

第三方服务器的访问方式为 https，不能是 http。

卡片刷新规则：

Wifi 下：刷新时间为 manifest.xml 文件中 hiboard：refreshDurationInWifi

属性的设定值。若未设置，默认为 5 分钟。

移动网络下：刷新时间为 manifest.xml 文件中 hiboard：refreshDuration

属性的设定值。如果移动网络下卡片刷新导致流量消耗过大，后台会根据具体情

况配置该卡片的刷新时间，此时移动网络下的刷新时间由后台配置的时间决定。

开发者需根据需求合理设置该属性值，建议刷新间隔设置大于等于 1 小时。若刷

新间隔设为 1 小时： hiboard：refreshDuration=“3600”。

智慧桌面卡片开发文档 - vivo ·...

Documents