展现模板

为了更好的在有屏设备端上展现技能，DuerOS提供了多种展现模板供开发者使用。展现模板分body template和list template两种类型。其中body template由图片和文字组成，list template由一系列list item组成，每个list item由图片和文字组成。不同的展现模板适合不同的场景，开发者可以根据技能展现的需求选择合适的模板。本文详细地介绍DuerOS提供的各种模板，以及与模版有关的指令和事件。

版本变更

| 版本号 | 变更时间 | 变更描述 | | ------ | -------- | -------- |• | 1.1 | 2019-01-09 | ImageStructure 增加必选字段ratio，对widthPixels和heightPixels增加必选约束

目录

• 展现模板指令
  • BodyTemplate1模板
  • BodyTemplate2模板
  • BodyTemplate3模板
  • BodyTemplate4模板
  • BodyTemplate5模板
  • BodyTemplate6模板
  • ListTemplate1模板
  • ListTemplate2模板
  • ListTemplate3模板
  • ListTemplate4模板
  • 展现模板的元素结构
  • 展现模板相关说明
• 展现模板相关事件和指令
  • Hint指令
  • Display.ElementSelected事件
  • Display.ButtonClicked事件
  • Display.PushStack指令
  • RenderAudioList指令
  • RenderVideoList指令
  • RenderAlbumList指令

展现模板指令

展现模板指令如下所示，支持BodyTemplate1、BodyTemplate2、BodyTemplate3、BodyTemplate4、BodyTemplate5、BodyTemplate6、ListTemplate1、ListTemplate2、ListTemplate3、ListTemplate4十种展现模板。

{
    "directives": [
        {
            "type": "Display.RenderTemplate",
            "template": {
                "type": "{{STRING}}",
                "token": "{{STRING}}", 
                "backgroundImage": {{ImageStructure}},
                "title": "{{STRING}}",
                "textContent": {
                    "position": "{{ENUM}}",
                    "text": {{TextStructure}}
                }
            }
        }
    ]
}

说明：

1. 当用户与设备在一定时间无交互时，在屏幕上展现的信息会被端清理，交互时间由端上的协议决定。
2. 如果技能同时返回展现模板、card时，端上优先选用模板指令进行展现。
3. 每种展现模板都可以与Hint指令搭配使用。

4. 卡片中的文字都有规定的最大长度，展现时不一定将文字内容全部展现。最大长度的是DuerOS接受技能返回对应字段的长度。超过此长度的返回结果，可能会报返回消息错误。

   文字最终展现长度，在不同的屏幕端、不同的模板指令里会有区别，具体需要参考最终的渲染效果，超过展现长度的文字，会以...来表示。

BodyTemplate1模板

BodyTemplate1适用于仅展现文本信息的场景，包含以下内容。其中标题、技能图标、文本内容是必不可少的，其他内容可以根据技能的需要进行配置。

• 标题

  技能名称或者技能当前页面主题信息，支持中文、数字、字母和下划线。标题在顶部导航居中位置，字体大小是28px，长度不能超过40个字符。

• 技能图标

  技能图标，在顶部导航靠右位置，是开发者在技能发布时上传的。

• 文本内容

  技能交互时展现的文本信息，字体大小64px，长度不超过800个字符。文本内容展现在模板底部，文字左对齐，支持滚屏显示和触控上下滚动。

• 背景图片

  技能交互时展现的背景图片，支持JPEG和PNG两种格式，大小不超过2M。

• 引导词

  技能交互时展现的提示信息，引导用户与技能进行交互。引导词在底部居中位置展现，最多不能超过40个字符。每个技能支持配置多个引导词，这些引导词会循环展现在屏幕上，每5秒钟切换一次。

消息样例

{
    "type": "BodyTemplate1",
    "token": "{{STRING}}", 
    "backgroundImage": {{ImageStructure}},
    "title": "{{STRING}}",
    "textContent": {
        "position": "{{ENUM}}",
        "text": {{TextStructure}}
    }
}

参数说明

参数名称	描述	类型	是否必须
type	模板类型名称，这里取固定值BodyTemplate1。	string	是
token	模板的唯一标识。	string	是
backgroundImage	背景图片，宽高比例要求接近16:9。图片展现前会进行高斯模糊处理。	ImageStructure	否
title	卡片的标题，不超过40个字符。	string	是
textContent	文本信息结构。	-	是
textContent.position	文本垂直方向的位置，支持以下三种情况。 TOP-LEFT：文本位置置顶，文字左对齐。 CENTER：文本位置垂直居中，文字居中。 BOTTOM-LEFT：文本位置置底，文字左对齐。	enum	否
textContent.text	文本内容，支持纯文本格式，长度不超过800个字符。	TextStructure	是

展现示例

BodyTemplate2模板

BodyTemplate2模板适用于同时展现图片和文字的场景，其中图片展现在上方，文字展现在下方，模板包含以下内容。其中标题、技能图标、图片、文本内容是必不可少的，其他内容可以根据技能的需要进行配置。

• 标题

  技能名称或者技能当前页面主题信息，支持中文、数字、字母和下划线。标题在顶部导航居中位置，字体大小是28px，长度不能超过40个字符。

• 技能图标

  技能图标，展现在顶部导航靠右位置，是开发者在技能发布时上传的。

• 图片

  技能交互时展现的图片，居中展现，像素是200px*200px，大小不超过500K。

• 文本内容

  技能交互时展现的文本信息，长度不超过800个字符。文本内容展现在底部，文字左对齐。

• 背景图片

  技能交互时展现的背景图片，支持JPEG和PNG两种格式，大小不超过2M。

• 引导词

  技能展现的提示信息，引导用户与技能进行交互。引导词在底部居中位置展现，最多不能超过40个字符。每个技能支持配置多个引导词，这些引导词会循环展现在屏幕上，每5秒钟切换一次。

消息样例

{
    "type": "BodyTemplate2",
    "token": "{{STRING}}",
    "image": {{ImageStructure}},
    "backgroundImage": {{ImageStructure}},
    "title": "{{STRING}}",
    "content": {{TextStructure}}
}

参数说明

参数名称	描述	类型	是否必须
type	模板类型名称，这里取固定值BodyTemplate2。	string	是
token	模板的唯一标识。	string	是
image	技能交互时展现的图片，图片宽高比是1:1。	ImageStructure	是
backgroundImage	背景图片，宽高比要求接近16:9。图片展现前会进行高斯模糊处理。	ImageStructure	否
title	卡片的标题，不超过40个字符。	string	是
content	文本内容信息，支持纯文本格式。	TextStructure	是

展现示例

BodyTemplate3模板

BodyTemplate3模板适用于同时展现图片和文字的场景，其中图片展现在屏幕左侧，文字展现在屏幕右侧。模板包含以下内容，其中标题、技能图标、图片、文本内容是必不可少的，其他内容可以根据技能的需要进行配置。

• 标题

  技能名称或者技能当前页面主题信息，支持中文、数字、字母和下划线。标题在顶部导航居中位置，字体大小是28px，长度不能超过40个字符。

• 技能图标

  技能图标，展现在顶部导航靠右位置，是开发者在技能发布时上传的。

• 图片

  技能交互时展现的图片，大小不超过500K，展现在屏幕左侧。

• 文本内容

  技能交互时展现的文本信息，长度不超过4000个字符，展现在屏幕右侧，支持滚屏和触控上下滚动。

• 背景图片

  技能交互时展现的背景图片，支持JPEG和PNG两种格式，大小不超过2M。

• 引导词

  技能展现的提示信息，引导用户与技能进行交互。引导词在底部居中位置展现，最多不能超过40个字符。每个技能支持配置多个引导词，这些引导词会循环展现在屏幕上，每5秒钟切换一次。

消息样例

{
    "type": "BodyTemplate3",
    "token": "{{STRING}}",
    "image": {{ImageStructure}},
    "backgroundImage": {{ImageStructure}},
    "title": "{{STRING}}",
    "content": {{TextStructure}}
}

参数说明

参数名称	描述	类型	是否必须
type	模板类型名称，这里取固定值BodyTemplate3。	string	是
token	模板的唯一标识。	string	是
image	技能交互展现的图片，图片宽高比是3:4。	ImageStructure	是
backgroundImage	背景图片，宽高比要求接近16:9。图片展现前会进行高斯模糊处理。	ImageStructure	否
title	卡片的标题，不超过40个字符。	string	是
content	文本结构，支持纯文本格式。文字长度不超过800个字符。	TextStructure	是

展现示例

BodyTemplate4模板

BodyTemplate4模板适用于同时展现图片和文字的场景，其中图片展现在屏幕右侧，文字展现在屏幕左侧。模板包含以下内容，其中标题、技能图标、图片、文本内容是必不可少的，其他内容可以根据技能的需要进行配置。

• 标题

  技能名称或者技能当前页面主题信息，支持中文、数字、字母和下划线。标题在顶部导航居中位置，字体大小是28px，长度不能超过40个字符。

• 技能图标

  技能图标，展现在顶部导航靠右位置，是开发者在技能发布时上传的。

• 图片

  技能交互时展现的图片，大小不超过500K，展现在屏幕右侧。

• 文本内容

  技能交互时展现的文本信息，长度不超过4000个字符，展现在屏幕左侧，支持滚屏和触控上下滚动。

• 背景图片

  技能交互时展现的背景图片，支持JPEG和PNG两种格式，大小不超过2M。

• 引导词

  技能展现的提示信息，引导用户与技能进行交互。引导词在底部居中位置展现，最多不能超过40个字符。每个技能支持配置多个引导词，这些引导词会循环展现在屏幕上，每5秒钟切换一次。

消息样例

{
    "type": "BodyTemplate4",
    "token": "{{STRING}}",
    "image": {{ImageStructure}},
    "backgroundImage": {{ImageStructure}},
    "title": "{{STRING}}",
    "content": {{TextStructure}}
}

参数说明

参数名称	描述	类型	是否必须
type	模板类型名称，这里取固定值BodyTemplate4。	string	是
token	模板的唯一标识。	string	是
image	技能交互展现的图片，图片宽高比例是3:4。	ImageStructure	是
backgroundImage	背景图片，宽高比要求接近16:9。图片展现前会进行高斯模糊处理。	ImageStructure	否
title	卡片的标题，不超过40个字符。	string	是
content	文本结构，支持纯文本格式。文字长度不超过800个字符。	TextStructure	是

展现示例

BodyTemplate5模板

BodyTemplate5模板适用于展现图片的场景，可以展现多张图片。模板包含以下内容，其中技能图标、图片是必不可少的，其他内容可以根据技能的需要进行配置。

• 标题

  展现技能名称或者技能当前页面主题信息，支持中文、数字、字母和下划线。标题在顶部导航居中位置，字体大小是28px，长度不能超过40个字符。

• 技能图标

  技能图标，展现在顶部导航靠右位置，是开发者在技能发布时上传的。

• 图片

  技能交互时展现的图片，居中显示，大小不超过500KB。支持展现多张图片，可以滑动查看下一张或上一张图片。

• 背景图片

  技能交互时展现的背景图片，支持JPEG和PNG两种格式，大小不超过2M。

• 引导词

  技能展现的提示信息，引导用户与技能进行交互。引导词在底部居中位置展现，最多不能超过40个字符。每个技能支持配置多个引导词，这些引导词会循环展现在屏幕上，每5秒钟切换一次。

消息样例

{
    "type": "BodyTemplate5",
    "token": "{{STRING}}",
    "images": [
        {{ImageStructure}},
        {{ImageStructure}},
        ...
    ],
    "backgroundImage": {{ImageStructure}},
    "title": "{{STRING}}"
}

参数说明

参数名称	描述	类型	是否必须
type	模板类型名称，这里取固定值BodyTemplate5。	string	是
token	模板的唯一标识。	string	是
image	技能交互展现的图片，图片宽高比例是3:4。	ImageStructure	是
backgroundImage	背景图片，宽高比要求接近16:9。图片展现前会进行高斯模糊处理。	ImageStructure	否
title	卡片的标题，不超过40个字符。	string	是

展现示例

BodyTemplate6模板

BodyTemplate6模板适用于同时展现图片和文字的场景，其中图片展现在上方，文字展现在下方，图片可以在区域内进行自适应展示。模板包含以下内容，其中标题、技能图标、图片、文本内容是必不可少的，其他内容可以根据技能的需要进行配置。

• 标题

  技能名称或者技能当前页面主题信息，支持中文、数字、字母和下划线。标题在顶部导航居中位置，字体大小是28px，长度不能超过40个字符。

• 技能图标

  技能图标，展现在顶部导航靠右位置，是开发者在技能发布时上传的。

• 图片

  技能交互时展现的图片，居中展现，可以根据需要进行自适应展现。

• 文本内容

  技能交互时展现的文本信息，长度不超过800个字符。文本内容展现在底部，文字左对齐，支持滚动显示。

• 背景图片

  技能交互时展现的背景图片，支持JPEG和PNG两种格式，大小不超过2M。

• 引导词

  技能展现的提示信息，引导用户与技能进行交互。引导词在底部居中位置展现，最多不能超过40个字符。每个技能支持配置多个引导词，这些引导词会循环展现在屏幕上，每5秒钟切换一次。

消息样例

{
    "type": "BodyTemplate6",
    "token": "{{STRING}}",
    "image": {{ImageStructure}},
    "backgroundImage": {{ImageStructure}},
    "title": "{{STRING}}",
    "content": {{TextStructure}}
}

参数说明

参数名称	描述	类型	是否必须
type	模板类型名称，这里取固定值BodyTemplate6。	string	是
token	模板的唯一标识。	string	是
image	技能交互时展现的图片，可以根据需要进行缩放，需要满足图片展现要求。	ImageStructure	是
backgroundImage	背景图片，宽高比要求接近16:9。图片展现前会进行高斯模糊处理。	ImageStructure	否
title	卡片的标题，不超过40个字符。	string	是
content	文本内容信息，支持纯文本格式。	TextStructure	是

图片展现要求

图片应该满足以下要求：

1. 图片宽度最小不能小于200px，最大不能超过864px，高度最小不能小于200px，最大不能超过410px。即图片在自适应展示过程中，图片的宽度在200px到864px区间内，高度在200px到410px的区间内。
2. 当图片小于最小尺寸时，会对图片进行等比拉伸处理，保证图片的宽高不小于200px*200px。
3. 当图片大于最大尺寸时，会对图片进行等比压缩处理，保证图片的宽高不超过864px*410px。

展现示例

ListTemplate1模板

ListTemplate1是横向列表模板，适用于横向展现图片的场景。模板主要包含以下内容，其中标题、技能图标、图片、图片序号、一级文本是必不可少的，其他内容可以根据技能的需要进行配置。

• 标题

  技能名称或者技能当前页面主题信息，支持中文、数字、字母和下划线。标题在顶部导航居中位置，字体大小是28px，长度不能超过40个字符。

• 技能图标

  技能图标，展现在顶部导航靠右位置，是开发者在技能发布时上传的。

• 图标序号

  图片的序号，在图片的左上角，序号从1开始顺序标注。

• 图片

  技能交互时展现的图片，大小不超过500K。点击图片触发下一步交互或跳转页面。 支持宽高比为2:3、1:1、4:3三种规格的图片。

• 背景图片

  技能交互时展现的背景图片，支持JPEG和PNG两种格式，大小不超过2M。

• 文本

  • 一级文本
    • 加粗字体显示，字体大小及要求与图片的格式有关。
      • 当宽高比为2:3时, 字体大小是48px，最多展现2行，总数不能超过16个字符，超出的部分将以...的形式展现。
      • 当宽高比为1:1时，字体大小是48px，最多展现2行，总数不能超过24个字符，超出的部分将以...的形式展现。
      • 当宽高比为4:3时，字体大小是24px，最多展现3行，总数不能超过44个字符，超出的部分将以...的形式展现。
  • 二级文本
    • 正常字体显示，字体大小及要求与图片的格式有关。
      • 当宽高比为2:3时, 字体大小是48px，最多展现1行，总数不能超过8个字符，超出的部分将以...的形式展现。
      • 当宽高比为1:1时，字体大小是48px，最多展现1行，总数不能超过12个字符，超出的部分将以...的形式展现。
      • 当宽高比为4:3时，字体大小是24px，最多展现2行，总数不能超过22个字符，超出的部分将以...的形式展现。

• 引导词

  技能展现的提示信息，引导用户与技能进行交互。引导词在底部居中位置展现，最多不能超过40个字符。每个技能支持配置多个引导词，这些引导词会循环展现在屏幕上，每5秒钟切换一次。

消息样例

{
    "type": "ListTemplate1",
    "token": "{{STRING}}",
    "backgroundImage": {{ImageStructure}},
    "title": "{{STRING}}",
    "listItems": [
        {{ListItem}},
        {{ListItem}},
        ...
    ]
}

参数说明

参数名称	描述	类型	是否必须
type	模板类型名称，这里取固定值ListTemplate1。	string	是
token	模板的唯一标识。	string	是
backgroundImage	背景图片，宽高比要求接近16:9。图片展现前会进行高斯模糊处理。	ImageStructure	否
title	卡片的标题，不超过40个字符。	string	是
listItems	列表项，包含文本和图片信息。当用户点击列表中的图片时，DuerOS会向技能发送Display.ElementSelected事件请求。	ListItem	是

说明：

• ListItem中有三级文本，在ListTemplate1模板中仅展现一级文本和二级文本，三级文本不展现。
• 列表中图片的展现高度为200px，图片的宽高比分别为2:3，1:1，4:3三种情况。如果图片高度大于200px，将高度压缩到200px，如果宽度小于200px，将图片按宽高比2:3进行展现；如果宽度介于200px和266px之间，将图片按宽高比1:1进行展现；如果宽度大于等于266px，将图片按宽高比4:3进行展现。

展现示例

ListTemplate2模板

ListTemplate2是纵向列表模板，适用于纵向展现图片的场景。模板主要包含以下内容，其中标题、技能图标、一级文本是必不可少的，其他内容可以根据技能的需要进行配置。

• 标题

  技能名称或者技能当前页面主题信息，支持中文、数字、字母和下划线。标题在顶部导航居中位置，字体大小是28px，长度不能超过40个字符。

• 技能图标

  技能图标，展现在顶部导航靠右位置，是开发者在技能发布时上传的。

• 图标序号

  图片的标号，在图片的左上角，序号从1开始顺序标注。

• 图片

  技能交互时展现的图片，图片大小是150px*150px，图片大小不超过500K。

• 背景图片

  技能交互时展现的背景图片，支持JPEG和PNG两种格式，大小不超过2M。

• 文本

  • 一级文本
    字体加粗，字体大小是36px，最多展现3行，总数不能超过36个字符，超出的部分将以...的形式展现。
  • 二级文本
    正常字体，字体大小是24px，最多展现2行，总数不能超过24个字符，超出的部分将以...的形式展现。
  • 三级文本
    正常字体，字体大小是32px，最多展现1行，总数不能超过2个字符，超出的部分将以...的形式展现。
• 引导词
  技能展现的提示信息，引导用户与技能进行交互。引导词在底部居中位置展现，最多不能超过40个字符。每个技能支持配置多个引导词，这些引导词会循环展现在屏幕上，每5秒钟切换一次。

消息样例

{
    "type": "ListTemplate2",
    "token": "{{STRING}}",
    "backgroundImage": {{ImageStructure}},
    "title": "{{STRING}}",
    "listItems": [
        {{ListItem}},
        {{ListItem}},
        ...
    ]
}

参数说明

参数名称	描述	类型	是否必须
type	模板类型名称，这里取固定值ListTemplate2。	string	是
token	模板的唯一标识。	string	是
backgroundImage	背景图片，宽高比要求接近16:9。图片展现前会进行高斯模糊处理。	ImageStructure	否
title	卡片的标题，不超过40个字符。	string	是
listItems	列表项，包含文本和图片信息。当用户点击列表中的图片时，DuerOS会向技能发送Display.ElementSelected事件请求。	ListItem	是

展现示例

ListTemplate3模板

ListTemplate3是双层横向列表模板，适用于双层横向展现图片的场景。图片序号的顺序是第一行是奇数号，即，1、3、5、7，第二行是偶数序号，即2、4、6、8。模板主要包含以下内容，其中标题、技能图标、图片序号、文本是必不可少的，其他内容可以根据技能的需要进行配置。

• 标题

  技能名称或者技能当前页面主题信息，支持中文、数字、字母和下划线。标题在顶部导航居中位置，字体大小是28px，长度不能超过40个字符。

• 技能图标

  技能图标，展现在顶部导航靠右位置，是开发者在技能发布时上传的。

• 图标序号

  图片的标号，在图片的左上角，序号从1开始顺序标注。第一行是奇数序号，即，1、3、5、7，第二行是偶数序号，即2、4、6、8。

• 图片

  技能交互时展现的卡片，图片大小不超过500K。

• 背景图片

  技能交互时展现的背景图片，支持JPEG和PNG两种格式，大小不超过2M。

• 文本内容

  正常字体，字体大小是24px，最多展现2行，总数不能超过24个字符，超出的部分将以...的形式展现。

• 引导词
  技能展现的提示信息，引导用户与技能进行交互。引导词在底部居中位置展现，最多不能超过40个字符。每个技能支持配置多个引导词，这些引导词会循环展现在屏幕上，每5秒钟切换一次。

消息样例

{
    "type": "ListTemplate3",
    "token": "{{STRING}}",
    "backgroundImage": {{ImageStructure}},
    "title": "{{STRING}}",
    "listItems": [
        {
            "token": "{{STRING}}",
            "image": {{ImageStructure}},
            "content": {{TextStructure}}
        },
        {
            "token": "{{STRING}}",
            "image": {{ImageStructure}},
            "content": {{TextStructure}}
        },
    ...
    ]
}

参数说明

参数名称	描述	类型	是否必须
type	模板类型名称，这里取固定值ListTemplate3。	string	是
token	模板的唯一标识。	string	是
backgroundImage	背景图片，宽高比要求接近16:9。图片展现前会进行高斯模糊处理。	ImageStructure	否
title	卡片的标题，不超过40个字符。	string	是
listItems	列表项，包含文本和图片信息。当用户点击列表中的图片时，DuerOS会向技能发送Display.ElementSelected事件请求。	ListItem	是
listItems[].token	列表卡片的唯一标识。	string	是
listItems[].image	列表卡片的图片。	string	是
listItems[].content	列表卡片的文本内容，不超过4000个字。	string	是

图片展现要求

列表卡片中的图片需要满足以下要求：

1. 列表中图片的展现高度为150px，图片的宽高比分别为2:3，1:1，4:3三种情况。
2. 如果图片高度大于150px，需要将图片高度压缩到150px，如果宽度小于150px，将图片按宽高比2:3进行展现；如果宽度介于150px和200px之间，将图片按宽高比1:1进行展现；如果宽度大于等于200px，将图片按宽高比4:3进行展现。

展现示例

ListTemplate4模板

ListTemplate4是双层纵向列表模板，适用于双层纵向展现图片的场景。图片序号的顺序是第一列是奇数号，即，1、3、5、7，第二列是偶数序号，即2、4、6、8。模板主要包含以下内容，其中标题、技能图标、图片序号、文本是必不可少的，其他内容可以根据技能的需要进行配置。

• 标题

  技能名称或者技能当前页面主题信息，支持中文、数字、字母和下划线。标题在顶部导航居中位置，字体大小是28px，长度不能超过40个字符。

• 技能图标

  技能图标，展现在顶部导航靠右位置，是开发者在技能发布时上传的。

• 序号

  序号从1开始顺序标注。第一列是奇数序号，即，1、3、5、7，第二列是偶数序号，即2、4、6、8。

• 背景图片

  技能交互时展现的背景图片，支持JPEG和PNG两种格式，大小不超过2M。

• 文本内容

  正常字体，字体大小是26px，最多展现2行，总数不能超过24个字符，超出的部分将以...的形式展现。

• 引导词
  技能展现的提示信息，引导用户与技能进行交互。引导词在底部居中位置展现，最多不能超过40个字符。每个技能支持配置多个引导词，这些引导词会循环展现在屏幕上，每5秒钟切换一次。

消息样例

{
    "type": "ListTemplate4",
    "token": "{{STRING}}",
    "backgroundImage": {{ImageStructure}},
    "title": "{{STRING}}",
    "listItems": [
        {
            "token": "{{STRING}}",
            "content": {{TextStructure}}
        },
        {
            "token": "{{STRING}}",
            "content": {{TextStructure}}
        },
        ...
    ]
}

参数说明

参数名称	描述	类型	是否必须
type	模板类型名称，这里取固定值ListTemplate4。	string	是
token	模板的唯一标识。	string	是
backgroundImage	背景图片，宽高比要求接近16:9。图片展现前会进行高斯模糊处理。	ImageStructure	否
title	卡片的标题，不超过40个字符。	string	是
listItems	列表项，每个列表卡片仅包含文本内容。当用户点击列表中卡片时，DuerOS会向技能发送Display.ElementSelected事件请求。	ListItem	是
listItems[].token	列表项的唯一标识。	string	是
listItems[].content	列表项的文本内容，不超过4000个字。	string	是

展现示例

展现模板的元素结构

ListItem

列表模板中的ListItem，包含图片和文本信息。

消息样例

{
    "token": "{{STRING}}",
    "image": {{ImageStructure}},
    "textContent": {
        "primaryText": {{TextStructure}},
        "secondaryText": {{TextStructure}},
        "tertiaryText": {{TextStructure}}
    }
}

参数说明

参数名称	描述	参数类型	是否必须
token	listItem的唯一标识。	string	是
image	展现的图片。	ImageStructure	否
textContent	文本信息。	-	是
textContent.primaryText	一级文本内容，不超过4000个字符。	TextStructure	是
textContent.secondaryText	二级文本内容，不超过4000个字符。	TextStructure	否
textContent.tertiaryText	三级文本内容，不超过4000个字符。	TextStructure	否

ImageStructure

模板中使用的图片结构体信息。

消息样例

{
    "url": "{{STRING}}",
    "widthPixels": {{INTEGER}},
    "heightPixels": {{INTEGER}},
    "ratio": "{{STRING}}",
    "tags":[
        {
            "type": "{{ENUM}}",
            "text": "{{STRING}}",
            "color": "{{STRING}}",
            "backgroundColor": "{{STRING}}"
        }
    ]
}

参数说明

参数名称	描述	参数类型	是否必须
url	图片地址，要求为https的地址。	string	是
widthPixels	图片的宽度，单位像素。	int	没有ratio时必选
heightPixels	图片的高度，单位像素。	int	没有ratio时必选
ratio	图片的宽高比例	string	没有widthPixels和heightPixels必选，目前UE提供可选值： 1、 2/3 、 4/3 、 2/1
tags	标签展示。	structure	否
tags.type	标签类型，支持以下标签类型。 FREE：免费标签 PAY：付费标签 NEW：最新标签 HOT：最热标签 VIP:会员标签 PURCHASED：已购标签 TIME：时间标签 AMOUNT：价格标签 AUDITION：试听标签 CUSTOM：自定义标签，可以自定义文本、颜色、背景色	enum	是
tags.text	标签文本内容，仅在TIME、AMOUNT、CUSTOM标签类型中使用。	string	否
tags.color	标签字体颜色，用于自定义标签，十六进制颜色码，例如"#800080"。	string	否
tags.backgroundColor	标签背景色，用于自定义标签，十六进制颜色码，例如"#FFFFFF"。	string	否

说明：
如果配置了widthPixels和heightPixels两个参数，在对图片处理时，将使用该两个参数的值，而不使用图片原始的宽度和高度，如果填写错误，可能会造成图像比例失真，请确保参数值与图片原始信息保持一致。

TextStructure

模板使用的文本结构。

消息样例

{
    "type": "{{ENUM}}",
    "text": "{{STRING}}"
}

参数说明

参数名称	描述	参数类型	是否必须
type	文本类型。 PlainText：纯文本。	enum	是
text	文本内容。	string	是

展现模板相关说明

图片展现

前景图片的展现，在确定图片展现比例和容器的高度之后，按如下方法来裁剪图片。

• 如果图片高度无法达到容器高度，不进行拉伸。
• 按容器比例和容器高度计算出图片压缩之后的宽度。
• 处理后的图片宽度大于容器宽度，直接按容器宽度裁剪图片左右像素。
• 处理后的图片宽度小于容器宽度，水平居中显示图片。

展现模板相关事件和指令

Hint指令

Hint指令功能是展现技能的引导词。技能引导词是技能展现的提示信息，引导用户与技能进行交互。每个技能都可以设计引导词，让用户更快速的使用技能。

引导词通常是以文字的形式展现在屏幕上，展现形式是"唤醒词"+“引导语”，如“小度小度，打电话给爸爸”、“小度小度，历史上的今天发生什么大事”等。

Hint指令一般与card、template结合使用，在设备端的屏幕上进行展现。当Hint指令与card结合展现时，如果card协议中也包含了cueWords，在设备端屏幕上优先展现Hint指令的内容，而不展现cueWords的内容。引导词能够提升用户的体验，但也不是必需存在的。

消息样例

{
    "directives": [
        {
            "type": "Hint",
            "hints": [
                {
                    "type": "PlainText",
                    "text": "string"
                }
            ]
        }
    ]
}

参数说明

参数名称	描述	参数类型	是否必须
type	指令类型，这里取固定值"Hint"。	string	是
hints.type	引导词的类型，这里是固定值"PlainText"，普通文本。	string	是
hints.text	引导词的内容。	string	是

Display.ElementSelected事件

当点击列表中的卡片时，DuerOS会向技能发送Display.ElementSelected事件，请求技能进行相应的处理。

消息样例

{
    ...
    "request": {
        "type": "Display.ElementSelected",
        "requestId": "{{STRING}}",
        "timestamp": "{{STRING}}",
        "token": "{{STRING}}"
    }
    ...
}

参数说明

参数名称	描述	参数类型	是否必须
type	事件类型，这里取固定值Display.ElementSelected。	string	是
requestId	标识本次请求的唯一ID。	string	是
timestamp	请求时间戳，单位是秒，是一个全部是数字的字符串。	string	是
token	点击的ListItem的token。	string	是

Display.ButtonClicked事件

在打开音频播放列表中点击收藏按钮时，DuerOS会向技能发送该事件。

消息样例

{
    ...
    "request": {
        "type": "Display.ButtonClicked",
        "requestId": "{{STRING}}",
        "timestamp": "{{STRING}}",
        "token": "{{STRING}}",
        "buttonType": "{{ENUM}}"
    }
    ...
}

参数说明

参数名称	描述	参数类型	是否必须
type	事件类型，这里取固定值Display.ButtonClicked。	string	是
requestId	标识本次请求的唯一ID。	string	是
timestamp	请求时间戳，单位是秒，是一个全部是数字的字符串。	string	是
token	资源对应token标识。	string	是
buttonType	收藏按钮类型，取值如下： FAVORITE：收藏。 UNFAVORITE：取消收藏。	enum	是

Display.PushStack指令

当设备端有新的页面B展示时，使用该指令可以把当前页面A压入栈中，当页面B返回后，页面A会重新展现在设备上。

消息样例

{
    "directives": [
        {
            "type": "Display.PushStack"
        }        
    ]
}

参数说明

参数名称	描述	参数类型	是否必须
type	指令类型，这里取固定值Display.PushStack。	string	是

RenderAudioList指令

渲染音频列表状态的指令。在音频播放过程中打开音频播放列表时，技能会向DuerOS发送该指令。

消息样例

{
    "directives": [
        {
            "type": "Display.RenderAudioList",
            "token": "{{STRING}}",
            "title": "{{STRING}}",
            "behavior": "{{ENUM}}",
            "size": {{LONG}},
            "audioItems":[
                {
                    "title": "{{STRING}}",
                    "titleSubtext1": "{{STRING}}",
                    "titleSubtext2": "{{STRING}}",
                    "isFavorited": {{BOOLEAN}},
                    "isMusicVideo": {{BOOLEAN}},
                    "image": 
                    {
                        "src": "{{STRING}}"
                    },
                    "token": "{{STRING}}"
                },
                ...
            ]
        }
    ]
}

参数说明

参数名称	描述	参数类型	是否必须
type	指令类型，这里取固定值"Display.RenderAudioList"。	string	是
token	列表的唯一标识。	string	是
title	列表的标题。	string	是
behavior	列表的渲染模式。 REPLACE: 先清空当前的列表，然后再渲染，适用于首页的第一次渲染场景。 APPEND: 当前列表不变，在当前的列表后面渲染，适用于往后翻页的渲染场景。 PREPEND: 当前列表不变，在当前的列表前面渲染，适用于往前翻页的渲染的场景。	enum	是
size	列表的总大小。指列表中包含的所有页面的大小的和。	long	是
audioItems[].title	音频项目的标题，如音乐的歌曲名《告白气球》。	string	是
audioItems[].titleSubtext1	音频项目的子标题1，如音乐的歌手名周杰伦。	string	是
audioItems[].titleSubtext2	音频项目的子标题2，如专辑名称八度空间。	string	否
audioItems[].isFavorited	是否收藏音频。取值如下 true：收藏资源并进行渲染，如将红心点亮。 false：不收藏或取消收藏资源，不进行渲染，若已经渲染需要取消渲染，如将红心变暗。	bool	否
audioItems[].isMusicVideo	是否为音乐MV资源。取值如下： true：是音乐MV资源，列表上显示MV标志。 false：不是音乐MV资源，列表上不显示MV标志。	bool	否
audioItems[].image	音频项目的图片，比如音乐里面歌曲的专辑封面图。	structure	否
audioItems[].image.src	图片地址。	string	是
audioItems[].token	音频项目的唯一标识token。当触发Display.ElementSelected事件时，会使用该token。	string	是

音频列表示例图片

说明：

1. 在音频列表页面，所有展现的音频项都是可以点击播放的。点击播放时DuerOS会向技能发送Display.ElementSelected事件，技能收到事件后，会返回AudioPlayer.Play指令。
2. 在音频列表页面，当用户点击收藏按钮时，DuerOS会向技能发送Display.ButtonClicked事件，技能收到事件后，会返回RenderAudioList指令。
3. 该指令目前仅适用小度在家设备端。

RenderVideoList指令

渲染视频列表状态的指令。在视频播放过程中打开视频播放列表时，技能会向DuerOS发送该指令。

消息样例

{
    "directives": [
        {
            "type": "Display.RenderVideoList",
            "token": "{{STRING}}",
            "title": "{{STRING}}",
            "behavior": "{{ENUM}}",
            "size": {{LONG}},
            "videoItems":[
            {
                "title": "{{STRING}}",
                "mediaLengthInMilliseconds": {{LONG}},
                "titleSubtext1": "{{STRING}}",
                "titleSubtext2": "{{STRING}}",
                "image": 
                {
                    "src": "{{STRING}}"
                },
                "token": "{{STRING}}"
            },
            ...
            ]
        }        
    ]
}

参数说明

参数名称	描述	参数类型	是否必须
type	指令类型，这里取固定值"Display.RenderVideoList"。	string	是
token	列表的唯一标识。	string	是
title	列表的标题。	string	是
behavior	列表的渲染模式。 REPLACE: 先清空当前的列表，然后再渲染，适用于首页的第一次渲染场景。 APPEND: 当前列表不变，在当前的列表后面渲染，适用于往后翻页的渲染场景。 PREPEND: 当前列表不变，在当前的列表前面渲染，适用于往前翻页的渲染的场景。	enum	是
size	列表的总大小。指列表中包含的所有页面的大小的和。	long	是
videoItems[]	列表项目信息。	structure	是
videoItems[].title	视频项目的标题，比如新闻的标题。	string	是
videoItems[].mediaLengthInMilliseconds	视频的播放时间，单位为ms。默认使用设备端返回的视频流的实际长度。	long	是
videoItems[].titleSubtext1	视频项目的子标题1，比如新闻的副标题。	string	是
videoItems[].titleSubtext2	视频项目的子标题2，比如新闻的作者和时间等。	string	是
videoItems[].image	视频缩略图。	structure	否
videoItems[].image.src	图片地址。	string	是
videoItems[].token	视频项目的唯一标识token。当触发Display.ElementSelected事件时，会使用该token。	string	是

视频列表示例图片

说明：

1. 在视频列表页面，所有展现的视频项都是可以点击播放的。点击播放时DuerOS会向技能发送Display.ElementSelected事件，技能收到事件后，会返回VideoPlayer.Play指令。
2. 该指令目前仅适用小度在家设备端。

RenderAlbumList指令

用于渲染音频专辑列表的指令。专辑列表中每个item是可点击，点击后应该上报，设备端收到事件后返回Play指令。

消息样例

"directive": {
    "type": "Display.RenderAlbumList",
    "token": "{{STRING}}",
    "title": "{{STRING}}",
    "behavior": "{{ENUM}}",
    "size": {{LONG}},
    "previousPageUrl": "{{STRING}}",
    "nextPageUrl": "{{STRING}}",
    “albumListType”: "{{ENUM}}",
    "albums":[
      {
        "numeration": {{LONG}},
        "audioAlbumId": "{{STRING}}",
        "title": "{{STRING}}",
        "titleSubtext1": "{{STRING}}", 
        "titleSubtext2": "{{STRING}}", 
        "image": {{ImageStructure}},
        "url": "{{STRING}}",
        "albumPlayUrl": "{{STRING}}"
      },
      ...
    ]
  }
}

Payload参数说明

• token
  • 本页面的唯一标识
• title
  • 列表的标题
• size
  • list的总大小，注意不是第一页的大小，而是翻页完的总大小

• behavior

  • 列表的渲染模式
    • REPLACE: 清空当前的列表，再渲染，用于首次第一页数据的渲染
    • APPEND: 当前列表不变，在当前的列表后面渲染，用于往后翻页的渲染
    • PREPEND: 当前列表不变，在当前的列表前面渲染，用于往前翻页的渲染
• albums[].numeration
  • 编号
• albums[].audioAlbumId
  • 专辑ID
• albums[].title
  • 专辑的标题，比如音乐的专辑名，样例值：依然范特西
• albums[].titleSubtext1
  • 专辑的子标题1，比如音乐的歌手名，样例值：周杰伦
• (optional) albums[].titleSubtext2
  • 专辑的子标题2，比如订阅个专辑后显示有哪些更新，样例值：2个更新

• albums[].image

  • 专辑的图片，比如音乐的专辑封面图
• albums[].url
  • url不需要渲染出来，点击专辑项目后上报LinkClicked事件给服务端，事件参数里带上此url
• (optional) albums[].albumPlayUrl
  • url不需要渲染出来，需要直接播放此专辑，上报LinkClicked事件给服务端，事件参数里带上此url