{T}

创建第一个自定义消息卡片

大家平时在扣子或者豆包上和 AI Bot 聊天的时候,有没有发现 AI Bot 有时候会发一些特别好看的卡片出来?就像下面这样:

这些漂亮的卡片不仅让聊天界面多了一些色彩,也让 AI Bot 传达的信息更加清晰直观。其实,这些卡片都是通过扣子的自定义卡片来定义出来的。

官方模板的局限性

虽然扣子提供了一些官方的卡片模板可以直接使用,但是对于一些需要更个性化展示的场景来说,总觉得差点意思。因为大家都是用同样的模板,除了内容不一样,好像也没啥特色。就像穿校服一样,虽然整齐划一,但还是想偷偷改改小配饰,秀一下我们的与众不同。官方模板虽然方便,但在样式、布局上受限太多,不够个性化。所以,为了满足大家个性化的需求,扣子推出了自定义卡片的功能。

自定义卡片就是我们偷偷改小配饰的法宝。我们可以自由发挥创意,设计独一无二的卡片样式,让我们的 AI Bot 更加出众。想要横向布局?分栏?自定义配色?统统满足。只要你脑洞大,卡片造型任你玩。

实际应用场景举例

说了这么多自定义卡片的好处,那到底在哪些场景下用得上呢?举个例子,假设你做了一个电影推荐 AI Bot,用官方模板的话可能是这样的:

虽然能看,但总觉得差点意思。那如果我们自己设计个卡片样式呢?

是不是感觉高级很多?电影海报、评分一应俱全,这就是自定义卡片的魅力,可以让我们的内容呈现更加丰富多样的细节。再比如,你的 AI Bot 是个旅行助手,自定义个卡片来显示详细的旅游攻略,是不是也比单纯的文字直观很多?

所以啊,在实际应用中,无论你的 AI Bot 是做新闻资讯、还是垂直领域的知识问答、抑或是个人助理,自定义卡片都能让它更出彩。

创建自定义消息卡片流程

因为自定义消息卡片很难去一步步讲解,以下的方式我先大概从原理方面告诉大家具体的流程做法,然后再到最后把这个案例的所有结构一一截图给大家,希望能让大家更好地去理解。

创建自定义消息卡片是一个循序渐进的过程,通过组合不同的组件和样式,我们可以构建出功能丰富、视觉吸引人的卡片。下面,我们将以刚刚上述的电影推荐卡片为例,详细讲解创建自定义消息卡片的完整流程。

首先,我们需要在扣子平台找到自定义卡片的入口。具体路径是:打开目标 AI Bot -> 选择对应的插件或工作流 -> 点击绑定卡片数据图标 -> 在弹出的窗口中选择新增。点击新增后,我们就进入了卡片编辑页面。

选择合适的布局组件

在卡片编辑页面的左侧,我们分别可以看到模板、组件、结构三栏

模板一栏的内容主要是方便我们快速选择一些常用的卡片样式来进行设计(不用重头开始):

结构一栏,是用来调整组件的排列顺序的:

而组件一栏,是构建所有卡片的基础,这个组件主要分为两大类:布局组件基础组件

布局组件决定了卡片的整体结构和内容分区。常用的布局组件包括:

  • 单列布局: 最基本的上下结构,适合单一、线性的内容展示。
  • 多列布局: 支持内容左右分栏,可以更灵活地组织和呈现不同类型的信息。
  • 列表布局: 以列表的形式展示内容,适合展示一系列相似或相关联的元素。
  • 网格布局: 以网格的形式规划空间,每个格子大小一致,适合展示结构化的内容。
  • 横滑布局: 以横向滚动的形式展示内容,适合展示一系列相似或相关联的元素。
  • 浮动布局: 以浮动的方式展示内容,可以灵活地调整位置和大小,适合展示非线性的内容。

对于我们的电影推荐卡片,单列布局是一个合适的选择(只要设计好一列的内容,然后用循环渲染的方式来填充成多列即可)。我们可以将电影海报放在左侧,右侧放置电影名称、评分等文字信息,使结构清晰、内容有序。

所以这里我们就添加了两个单列布局组件,第一个是用于设计卡片的今日电影推荐标题的,第二个是用于设计卡片的电影信息的。

这时候,从结构一栏中,我们就可以很清晰地看到,我们当前的卡片结构和布局组件的嵌套关系,这里我就拿成品的结构给大家看看,可以更加直观:

使用基础组件填充内容

选定布局后,我们需要向布局内填充具体的内容元素,这就要用到组件栏中的基础组件了。基础组件是构成卡片信息的基本单元,例如文本、图片、按钮等

在电影推荐卡片中,我们主要会用到以下几种基础组件:

  • 图片组件: 用于显示电影海报图像。
  • 文本组件: 用于呈现电影名称、评分、简介等文字信息。
  • 按钮组件: 可以引导用户进行交互,例如点击跳转到电影详情页。
  • 评分组件: 用于显示电影的评分信息。

我们可以将这些组件拖拽到之前选定的布局中,调整它们的位置和大小,使其符合我们的设计需求:

美化组件样式

单纯地摆放组件还不足以创建出美观、专业的卡片,我们还需要对组件的样式进行细致的调整和优化。每个组件都提供了一系列样式配置选项,例如:

  • 尺寸与间距: 控制组件的大小和内外边距,合理利用空间,避免拥挤或稀疏。
  • 字体与颜色: 选择适当的字体、大小、颜色,提升内容的可读性和视觉吸引力。
  • 对齐与圆角: 调整文本对齐方式,为图片添加圆角,增加视觉层次和美感。

通过调整这些样式参数,我们可以塑造卡片的整体风格,使其与我们的产品定位和设计语言保持一致。例如,对于电影推荐卡片,我们可能希望采用简约、大气的设计风格,突出电影信息本身。

卡片结构的使用技巧

在复杂的卡片设计中,仅通过可视化编辑器操作组件可能会比较困难。这时,我们可以利用编辑器左下角的卡片结构功能,它以树状结构直观地展示了卡片内部的组件层级和嵌套关系。

在卡片结构面板中,我们可以清晰地看到每个组件的位置和父子关系,方便地选中、移动、调整组件的顺序。这为我们提供了另一种维度来理解和优化卡片的结构。当可视化编辑器操作感到困惑时,不妨切换到卡片结构视图,从整体上梳理和调整卡片的组织方式。

定义与使用变量

为了让卡片具备动态内容呈现的能力,我们需要利用变量功能。变量作为占位符,允许我们在运行时动态地向卡片提供数据。以电影推荐卡片为例,我们可以将电影名称、海报图片 URL、评分等信息定义为变量。这样,每次用户请求时,我们的后端服务就可以根据实际数据,动态填充这些变量,生成个性化的卡片内容。

定义变量的步骤如下:

  1. 在编辑器左侧切换到变量面板,点击新增变量
  2. 填写变量名称,选择变量类型(如字符串、数字、数组等),提供默认值。
  3. 在组件属性中,选中要绑定变量的属性,点击绑定变量,选择之前定义的变量:

以下是此案例用到的变量 - 电影列表的详情:

变量类型 - Array 变量默认值:

json
[
  {
    "description": "电影讲述了少年牧真人的母亲葬身火海后,他随父亲与继母组成新家庭。深陷悲伤的真人阴郁孤僻,难以融入新环境。一次意外,他跟随一只会说话的苍鹭闯入废弃的神秘塔楼,却不料进入了奇幻的“亡灵世界”,开始了一场不可思议的冒险……",
    "director": "宫崎骏",
    "jump_url": "https://piao.cn/t/SuSmxpY/230297",
    "leading_role": "山时聪真,刘昊然,菅田将晖,大鹏",
    "now_playing_or_coming_soon": "1",
    "open_day": "2024-04-03 18:00:00",
    "poster": "https://gw.alicdn.com/i4/O1CN01hVBOaZ1OZLmXpCZFx_!!6000000001719-0-alipicbeacon.jpg",
    "score": "9.4",
    "show_name": "你想活出怎样的人生",
    "status": "NORMAL",
    "type": "剧情,奇幻,动画"
  },
  {
    "description": "一封没署名的遗书、一群看似无恙的学生,让中学老师郑Sir想起充满暴力与遗憾的童年往事。他亦面对妻子 离别、父亲  病危,同时必须找出企图轻生的同学,阻止悲剧重现。 ",
    "director": "卓亦谦",
    "jump_url": "https://piao.cn/t/SuSmxpY/1472386",
    "leading_role": "卢镇业,郑中基,陈汉娜,韦罗莎,黄梓乐",
    "now_playing_or_coming_soon": "1",
    "open_day": "2024-04-19 09:00:00",
    "poster": "https://gw.alicdn.com/i2/O1CN016Knthy1teA2ArmpUx_!!6000000005926-0-alipicbeacon.jpg",
    "show_name": "年少日记",
    "status": "NORMAL",
    "type": "剧情"
  },
  {
    "description": "继上一次的怪兽高燃对战之后,金刚和哥斯拉将再度联手对抗一个潜伏在世界中的巨大威胁,并逐步探索这些巨兽们的起源以及骷髅岛等地的奥秘。同时,上古之战的面纱也将会被揭晓,而正是那场战斗创造出了这些超凡的生物,并深刻影响了人类世界的命运。​​​",
    "director": "亚当·温加德",
    "jump_url": "https://piao.cn/t/SuSmxpY/1429194",
    "leading_role": "哥斯拉,金刚,丽贝卡·豪尔,布莱恩·泰里·亨利,丹·史蒂文斯,凯莉·霍特尔,亚历克斯·弗恩斯,陈法拉",
    "now_playing_or_coming_soon": "1",
    "open_day": "2024-03-29 09:00:00",
    "poster": "https://gw.alicdn.com/i3/O1CN01FKlN4X1oWlYTFe6m6_!!6000000005233-1-alipicbeacon.gif",
    "score": "9.5",
    "show_name": "哥斯拉大战金刚2:帝国崛起",
    "status": "NORMAL",
    "type": "动作,冒险,科幻"
  },
  {
    "description": "有笑有泪,生命万岁!韩延导演“生命三部曲”终章,当“没头脑”吕途遇上“不高兴”凌敏,两个身患重症却性格迥异的年轻人,因为“生命接力”的约定,阴差阳错地踏上了一段充满爱与力量的治愈之旅。",
    "director": "韩延",
    "jump_url": "https://piao.cn/t/SuSmxpY/1444866",
    "leading_role": "彭昱畅,李庚希,徐帆,高亚麟,刘丹",
    "now_playing_or_coming_soon": "1",
    "open_day": "2024-03-30 10:00:00",
    "poster": "https://gw.alicdn.com/i2/O1CN01NXpoVT1n1Kkz8kHOb_!!6000000005029-0-alipicbeacon.jpg",
    "score": "9.6",
    "show_name": "我们一起摇太阳",
    "status": "NORMAL",
    "type": "爱情,剧情,家庭"
  },
  {
    "description": "丈夫何山凭空消失了十年后,苔花(蒋勤勤饰)正要迈进新生,但命运却把她推向了另一重绝境——她前脚被情人(陈建斌饰)母亲从采茶园赶走,后脚就被最亲近的好姐妹金兰骗进了传销组织“蝴蝶国际”。母亲沉迷其中,让一边寻父一边救母的儿子目莲(吴磊饰)身心疲惫,而蝴蝶国际却如藤蔓疯长一般,将恶魔的种子根植在无数百姓心中。苔花也摇身一变,从衣着打扮到言行举止都宛如“新生”,疯癫的举动让目莲感到诧异。母亲如蝴蝶一般翩翩于梦中之际,儿子想尽一切办法奋力解救……这座人间炼狱究竟该怎样逃脱?现代版“目连救母”能否成功?",
    "director": "顾晓刚",
    "jump_url": "https://piao.cn/t/SuSmxpY/1418664",
    "leading_role": "吴磊,蒋勤勤",
    "now_playing_or_coming_soon": "1",
    "open_day": "2024-04-03 18:00:00",
    "poster": "https://gw.alicdn.com/i1/O1CN01qJELnI1r8tknhRY7F_!!6000000005587-0-alipicbeacon.jpg",
    "show_name": "草木人间",
    "status": "NORMAL",
    "type": "剧情,犯罪"
  }
]

通过变量绑定,我们实现了卡片模板与实际数据的分离,使得卡片可以灵活地适应不同的业务场景和数据源。

以上就是创建自定义消息卡片的完整流程,涵盖了布局选择、组件填充、样式美化、卡片结构使用以及变量绑定等关键步骤。通过合理运用这些技巧,我们可以创建出功能强大、视觉出众的消息卡片,为用户提供更加丰富和愉悦的交互体验。

上述案例具体结构与属性一览

  • Card

    • singlecolumn5

      • Column 1

        • icon5
      • Column 2

        • Text7
    • 1:25

      • Column 1

        • image1
      • Column 2

        • singlecolumn1

          • Column 1
        • singlecolumn2

          • Column 1

            • ColumnLayout1_22

              • Column 1

                • Text3
              • Column 2

                • Text4
            • singlecolumn3

              • Column 1

                • ColumnLayout1_23

                  • Column 1

                    • Text5
                  • Column 2

                    • Text6
                • ColumnLayout1_24

                  • Column 1

                    • Text8
                  • Column 2

                    • Text9
                • ColumnLayout1_28

                  • Column 1

                    • Text13
                  • Column 2

                    • Text14
                • ColumnLayout1_27

                  • Column 1

                    • Text12
                  • Column 2

                    • Rating1
                • ColumnLayout1_26

                  • Column 1

                    • Text10
                  • Column 2

                    • Text11
                • Button2

消息卡片的预览与发布

创建完成自定义消息卡片后,在正式应用到实际业务场景之前,我们还需要对卡片进行预览和发布。预览可以帮助我们检查卡片在不同平台和设备上的实际表现,而发布则使卡片在扣子平台上正式生效,供插件和工作流调用。

不同客户端的预览方法

扣子平台支持自定义消息卡片在豆包和飞书两个主流客户端内显示。由于不同客户端的渲染机制和样式规范可能略有差异,为了确保卡片的兼容性和一致性,我们需要在这两个平台分别进行预览。

卡片编辑器提供了便捷的预览功能。点击编辑器右上角的预览按钮,会弹出一个二维码。我们可以使用豆包或飞书手机客户端扫描该二维码,即可在相应的平台上查看卡片的实际渲染效果。

在预览过程中,我们需要特别关注以下几点:

  • 卡片整体布局是否完整、协调,在不同屏幕尺寸下是否能够自适应调整。
  • 文本内容的显示是否清晰、美观,字体大小、颜色是否恰当。
  • 图片是否能够正常加载显示,分辨率和裁剪是否合适。
  • 交互元素(如按钮)是否具备正确的响应区域和点击反馈。

通过仔细检查不同平台的预览效果,我们可以及时发现和解决样式兼容性问题,确保卡片能够在各种场景下正常运作。

发布前的注意事项

在点击发布按钮之前,我们还需要对卡片进行最后的检查和优化,确保它已经达到了正式上线的标准:

  • 内容准确性: 再次确认卡片上的文字、数字、链接等信息是否准确无误,变量绑定是否正确。
  • 样式优化: 根据预览结果,微调样式以适应不同平台,如调整边距、字号等,力求在各种环境下都有良好的显示效果。
  • 交互合理性: 评估卡片内的交互元素是否必要、合理,点击区域是否合适,避免过度设计或冗余的交互。
  • 性能优化: 对于包含大量图片或复杂交互的卡片,需要注意性能优化,如图片压缩、懒加载等,避免卡片渲染时出现卡顿或延迟。

做好以上检查和优化后,我们就可以放心地点击发布,让卡片在扣子平台正式上线。

发布与更新

点击发布按钮后,我们的自定义消息卡片就在扣子平台完成了注册,成为了一种可复用的消息组件。此时,它就可以被绑定到 AI Bot 的插件或工作流中,参与实际的消息交互流程。

如果在发布后我们发现卡片还有改进空间,或者需要添加新的功能,我们可以随时返回编辑器,对卡片进行修改和迭代。更新卡片的流程非常简单:

  1. 在卡片编辑器中进行必要的修改。
  2. 点击保存,保存当前的编辑状态。
  3. 点击发布,将改动同步到已发布的卡片版本。

值得一提的是,当我们发布卡片的更新版本时,所有已经绑定了该卡片的插件或工作流都会自动使用新版本,不需要重新进行绑定操作。这种自动同步机制确保了卡片改动的高效分发,大大提升了开发和迭代的灵活性。

至此,我们已经掌握了消息卡片的预览、发布、更新等操作,也了解了在这个过程中需要注意的事项和技巧,接下来我们来试试将这个自定义的消息卡片应用到我们的 AI Bot 中吧。

将自定义消息卡片应用到 AI Bot

如一开始我们就在 Bot 编排界面的指定工作流上绑定指定卡片数据,上述这个例子,我们就使用一个工作流例子来演示,如下图:

其实这个工作流就是调用了一个淘票票的插件获取当下最新的电影信息,经过这个插件查询后,将 JSON 格式的数据结果返回给 AI Bot,类似内容如下:

json
[
  {
    "description": "七只皇家御蛋被坏人掳走,阴差阳错落入实习造型师阿泰的手中,孵出七只小鸡。阿泰变身“临时奶爸”,他必须赶在黎明大典前护送小鸡回家,让桃都大地重迎光明。",
    "director": "阿图罗·埃尔南德斯,安德鲁•戈登,杰弗里·马修·苏,维拉帕特拉·基纳纳文",
    "duration": 87,
    "jump_url": "https://piao.cn/t/SuSmxpY/1471219",
    "leading_role": null,
    "now_playing_or_coming_soon": "1",
    "open_day": "2024-09-07 08:00:00",
    "poster": "https://gw.alicdn.com/i1/O1CN01QSKB2S1DFEeZZzoMx_!!6000000000186-0-alipicbeacon.jpg",
    "score": "9.3",
    "score_count": 1784,
    "show_id": 1471219,
    "show_name": "蛋宝大营救",
    "status": "NORMAL",
    "type": "喜剧,动画,冒险",
    "want_count": 9926
  },
  {
    "description": "恐怖新锐导演费德·阿尔瓦雷兹(Fede Alvarez)联手《异形》系列元老雷德利·斯科特(Ridley Scott)重磅打造传奇太空科幻新篇章。当年轻的太空殖民者在废弃太空站内与宇宙中最可怕的生命体——异形狭路相逢,原本承载希望的星际冒险之旅,瞬间演变为生存率近乎0%的绝境逃亡,一场实力悬殊的求生之战一触即发。",
    "director": "费德·阿尔瓦雷兹",
    "duration": 119,
    "jump_url": "https://piao.cn/t/SuSmxpY/1477096",
    "leading_role": "卡莉·史派妮,戴维·荣松,阿奇·雷诺,伊莎贝拉·默塞德,斯派克·费恩,吴爱玲",
    "now_playing_or_coming_soon": "1",
    "open_day": "2024-08-16 00:00:00",
    "poster": "https://gw.alicdn.com/i2/O1CN01vUPy0P1OyXbHSQnqP_!!6000000001774-0-alipicbeacon.jpg",
    "score": "9.1",
    "score_count": 149496,
    "show_id": 1477096,
    "show_name": "异形:夺命舰",
    "status": "NORMAL",
    "type": "科幻,恐怖,惊悚",
    "want_count": 143292
  },
  {
    "description": "影片取材自“流浪兄弟”真实事件,聚焦“社会困境儿童”群体。讲述了⼀段“⼩偷”哥哥和“孤⼉”弟弟的流浪路,⼀场温暖的守护与救赎。\r
独自流浪生活的男孩马亮(王俊凯 饰)机缘巧合下遇见了被家人遗忘、无人关照的孩子轩轩(关子勰 饰),相似的命运让两个孤独的少年渐行渐近,风雨中他们一起建立了一个小小的家,拥抱取暖彼此守护。然而一场意外打破了一切,一群不速之客闯入了他们的生活,马亮和轩轩的命运又将何去何从……",
    "director": "殷若昕",
    "duration": 127,
    "jump_url": "https://piao.cn/t/SuSmxpY/1496789",
    "leading_role": "王俊凯,邓家佳,陈永胜,潘斌龙",
    "now_playing_or_coming_soon": "1",
    "open_day": "2024-09-13 18:00:00",
    "poster": "https://gw.alicdn.com/i4/O1CN01F181a31wY9j1IPKDZ_!!6000000006319-0-alipicbeacon.jpg",
    "score": null,
    "score_count": null,
    "show_id": 1496789,
    "show_name": "野孩子",
    "status": "NORMAL",
    "type": "剧情",
    "want_count": 488023
  },
  {
    "description": "沈腾马丽合体爆改偷感夫妇,暑期开大贴脸开笑!!西虹市IP爆笑回归!!\r
困苦的爹,辛劳的妈,破烂的院子,破碎的他。西虹市做大做强的路上怎么把老马家落下了?!!!\r
“汤里没油,兜里没子”的马成钢(沈腾 饰)和春兰(马丽 饰),赶驴打工,家徒四壁,而儿子马继业(肖帛辰 饰)则是他们逆天改命的唯一希望!!!\r
小马很争气!年年好成绩!一点不娇气!意志贼坚毅!但随着小马一天天长大,他却逐渐发现身边的人们都越来越不对劲……",
    "director": "闫非, 彭大魔",
    "duration": 133,
    "jump_url": "https://piao.cn/t/SuSmxpY/1515745",
    "leading_role": "沈腾,马丽,史彭元,萨日娜,肖帛辰,张子栋,李嘉琦",
    "now_playing_or_coming_soon": "1",
    "open_day": "2024-07-16 09:00:00",
    "poster": "https://gw.alicdn.com/i4/O1CN01vzguDj1jOSJrZB5WW_!!6000000004538-2-alipicbeacon.png",
    "score": "9.4",
    "score_count": 449559,
    "show_id": 1515745,
    "show_name": "抓娃娃",
    "status": "NORMAL",
    "type": "喜剧,剧情",
    "want_count": 218921
  },
  {
    "description": "我已一无所有,所以破釜沉舟!张家辉阮经天带你一起认识黑暗深处,揭穿人性假面!
在隐蔽的缦城角落,利欲熏心的贩毒集团不择手段,致使无数人因沾染毒品而家庭破碎、坠落深渊。被毒贩迫害至家破人亡的张耀(张家辉 饰)为复仇,与缉毒队长安渡(阮经天 饰)暗中合作,二人联手做局狠辣除害,誓要将犯罪集团的榜一榜二大哥穆坤和安佩全部铲除。然而没想到在这背后竟藏着一场精心布置的复仇棋局,是同仇敌忾还是各怀鬼胎?在这场较量中,到底谁才是执棋人,谁又是被操作的棋子?当危机悄然而至,是沉沦还是警醒,一切请小心为上……",
    "director": "马浴柯",
    "duration": 115,
    "jump_url": "https://piao.cn/t/SuSmxpY/1478217",
    "leading_role": "张家辉,阮经天,张榕容,马浴柯,陈国坤,张俪,江易轩,维他亚·潘斯林加姆,纳瑞拉·库尔蒙科尔佩特",
    "now_playing_or_coming_soon": "1",
    "open_day": "2024-08-16 09:00:00",
    "poster": "https://gw.alicdn.com/i2/O1CN01DTHZxs1aNEjQMvkc9_!!6000000003317-0-alipicbeacon.jpg",
    "score": "9.0",
    "score_count": 51379,
    "show_id": 1478217,
    "show_name": "重生",
    "status": "NORMAL",
    "type": "犯罪",
    "want_count": 38297
  }
]

你会发现,这个数据格式跟我们一开始设计的自定义消息卡片的变量格式是基本一样的,要的就是这个效果。

我们接下来只要在 AI Bot 添加了这个工作流的编辑栏上点击绑定消息卡片,选择自己新建的消息卡片,就会跳到如下的数据源绑定界面:

我们只需要在这里配置对应的数据结构绑定对应的工作流输出数据的值,就可以绑定成功了。

我们试一下最终效果:

总结

通过以上步骤,我们成功地创建了一个自定义消息卡片,并将其应用到了 AI Bot 中。这个过程不仅展示了如何利用扣子平台进行消息卡片的开发和应用,还强调了在实际操作中需要注意的事项和技巧。

希望这个例子能够帮助你更好地理解和掌握消息卡片的开发和应用,同时也希望你能够利用扣子平台创造出更多有趣、实用的消息卡片,为 AI Bot 的交互体验增添更多色彩。