前言在智能体应用中除了文本回复外经常需要展示结构化的交互内容比如商品展示、订单信息、地图导航等。自定义卡片编辑器提供了一套可视化的拖拽式界面设计工具让开发者无需编写代码即可创建精美的交互式卡片。本文详细介绍自定义卡片编辑器的使用方法包括组件拖拽、变量绑定、事件配置和完整演示案例。卡片编辑器概述编辑界面布局自定义卡片编辑页面从左到右分为三个区域区域功能说明功能区左侧面板包含可拖拽的组件列表预览画布区中间区域实时展示卡片的视觉效果属性配置区右侧面板配置选中组件的属性和样式上图展示了自定义卡片编辑器的三区布局左侧为功能区、中间为预览画布、右侧为属性配置区。基本操作流程# 卡片创建流程图card_creation_flow[1. 新建自定义卡片,2. 从功能区拖拽组件到画布,3. 创建变量并绑定动态数据,4. 配置组件样式尺寸、颜色、间距等,5. 添加事件交互点击、加载等,6. 预览效果,7. 保存并发布]组件介绍布局组件布局组件用于组织卡片的整体结构组件说明使用场景行布局将元素横向排列的容器导航栏、标签行列布局将元素纵向排列的容器表单、文章列表堆叠组件将元素叠放在一起图片上加文字动态列表遍历数组生成列表商品列表、订单列表滚动容器超出内容可滚动长内容展示基础组件基础组件是构成卡片内容的核心元素组件说明属性配置文本展示文字内容字体大小、粗细、颜色、对齐方式图片展示图片尺寸、缩放类型、圆角图标展示图标图标标签、大小、颜色按钮可点击操作按钮文案、颜色、事件绑定标签标记分类信息文本、圆角、颜色高级组件{advanced_components:{map:{name:地图组件,description:展示地图并标记地点和路线,features:[地点标记,路线规划,实时定位]},tabs:{name:多页签组件,description:多页面切换展示,styles:[胶囊型,下划线型]},audio_video:{name:音视频组件,description:嵌入音频和视频播放,styles:[音频样式1,音频样式2]},dual_select:{name:选项组组件,description:单选或多选功能,types:[单选,多选]}}}变量绑定变量类型卡片可能需要根据场景动态调整参数因此需要创建变量用于在卡片中绑定动态变化的内容。真实的值通过调用时传入变量类型说明使用场景String字符串文本内容、图片URLNumber数字价格、数量Array数组列表数据、选项组Object对象复合数据结构Object聚合链接链接对象跳转链接配置Boolean布尔值开关状态、可见性创建和绑定变量# 变量定义示例variables{title:HUAWEI Pura 70 Ultra,# Stringprice:9999,# NumberimageUrl:https://example.com/phone.png,# Stringfeatures:[卫星通信,超聚光摄像头],# Arrayproduct:{# Objectname:HUAWEI Pura 70 Ultra,price:9999,color:黑色}}绑定规则为文本组件绑定变量时无法绑定数组变量和对象变量为图片组件绑定变量时只能绑定字符串类型图片URL。变量在画布中的应用新建变量后在内容区点击文本内容的右侧按钮选择变量绑定!-- 变量绑定的效果 --!-- 静态文本 --Text商品名称/Text!-- 动态文本绑定变量后 --Text{{title}}/Text!-- 渲染结果HUAWEI Pura 70 Ultra --右侧属性配置栏中文本内容中的蓝色字体表示引用的变量名称。事件配置事件概述事件功能使卡片具备交互能力例如给按钮设置点击事件触发点击后跳转到某个应用。事件触发方式触发方式说明点击时用户点击组件时触发加载时卡片加载时自动触发执行条件执行条件为可选项设置后只有满足条件时触发的事件才能执行# 执行条件配置condition{left_operand:前置事件返回值或变量,operator:,# 根据左操作数类型提供不同运算符right_operand:常量或变量}11种执行动作卡片目前支持以下执行动作动作说明典型场景跳转跳转到指定页面/应用点击广告跳转详情页给小艺对话或智能体发消息将消息发送给小艺或智能体点击后发起对话设置变量值更新指定变量的值切换选项后更新显示修改组件属性动态修改组件的样式属性展开/收起详情切换页面在多页卡片中切换页面分页浏览查询应用安装状态检查某应用是否已安装分享前检查调用插件调用已绑定的插件点击执行查询复制到剪切板将内容复制到系统剪贴板复制验证码预览图片全屏预览图片查看大图删除列表数据删除动态列表中的条目删除待办事项操作小艺调用小艺的能力语音播报{event_config_example:{component:确认购买按钮,trigger:点击时,action:跳转,params:{url:https://example.com/product/123,type:webLink}}}完整演示案例华为商城卡片整体设计将卡片分为顶部栏和商品栏上下两部分依次绘制。步骤一搭建顶部栏框架选择外层行布局将元素横向排列的容器在右侧属性栏中设置水平对齐方式为两端对齐内部嵌套两个行布局商城标签区和更多按钮区# 顶部栏结构top_bar{layout:row,justify_content:space_between,children:[{type:row,children:[{type:image,src:{{logo}},width:20},{type:text,content:商城,font_size:12,font_weight:700}]},{type:row,children:[{type:text,content:更多,font_size:10,font_weight:500},{type:icon,name:向右}]}]}步骤二样式配置/* 顶部栏样式参考 */.logo-image{width:20px;aspect-ratio:1/1;object-fit:contain;}.store-name{font-size:12px;font-weight:700;opacity:100%;}.more-text{font-size:10px;font-weight:500;opacity:60%;}步骤三商品栏-动态列表使用动态列表组件展示商品列表绑定数组变量{listContent:[{button3:购买,listLeftImage:https://example.com/phone1.png,listMainTitle:HUAWEI Pura 70 Ultra,listSubTitle1Sub1:超聚光伸缩摄像头超高速风驰闪拍,listSubTitle2Sub1:新品,listSubTitle2Sub2:12期0分期利息,listSubTitle3Sub1:¥9999.0},{button3:购买,listLeftImage:https://example.com/phone2.png,listMainTitle:HUAWEI Pura 70,listSubTitle1Sub1:超高速风驰闪拍第二代昆仑玻璃,listSubTitle2Sub1:新品,listSubTitle2Sub2:12期0分期利息,listSubTitle3Sub1:¥5999.0}]}技巧动态列表区块的数量与数组长度相同系统自动遍历数组并绘制列表。每个区块中的图片会自动根据数组中的对应字段生成不同的图片。步骤四地图组件配置当需要展示地理位置时可以使用地图组件# 地图组件配置map_config{locations:{mode:bind_variable,# 固定个数 / 绑定变量variable:locations,show_location_names:True,user_location:True# 显示用户实时定位},route:{enabled:False,variable:route_data}}# 地点数据格式location_data[{name:深圳华为基地,latitude:22.657,longitude:114.069,thumbnail:https://example.com/pin.png},{name:北京华为研究所,latitude:39.908,longitude:116.397,thumbnail:https://example.com/pin.png}]# 路线数据格式route_data[{status:1,# 0灰色,1绿色,2黄色,3红色,4深红色polyline:[{latitude:22.657,longitude:114.069},{latitude:22.700,longitude:114.100},{latitude:22.750,longitude:114.150}]}]步骤五选项组组件配置选项组DualSelect支持单选和多选模式{dual_select:{type:single,// single / multipleorientation:horizontal,// horizontal / verticaloptions:[{label:大熊猫,value:熊科,selected:true},{label:东北虎,value:猫科,selected:false},{label:金丝猴,value:猴科,selected:false}],interactive:true}}事件联动当选项变化时可以设置变量值事件将选中选项的值赋值给文本组件实现动态显示效果。卡片预览、保存与发布预览点击预览后可在弹出的窗口中预览卡片效果。Web预览展示了卡片在设备上的预期显示效果。保存与发布预览效果符合预期后点击保存并发布卡片。卡片发布后在智能体、插件和工作流绑卡时就可以关联到已发布的卡片。# 卡片发布流程card_publish_flow[1. 完成组件配置和变量绑定,2. 添加事件交互,3. 点击【预览】查看效果,4. 确认无误后点击【保存并发布】,5. 卡片状态变为已发布,6. 在插件/工作流绑卡时选择该卡片]开发技巧与最佳实践1. 组件间距调整在行布局的默认设置下可能会出现组件间距过小影响视觉体验的情况# 间距调整技巧spacing_tips{row_spacing:4,# 行布局组件间距设为4component_margin:0,# 图片组件和文本组件外边距设为0right_spacing:2# 右侧图片组件的右侧外间距设为2}2. 提高开发效率# 效率提升技巧efficiency_tips[复制组件选择需要复制的组件点击按钮再更换文本内容,变量绑定使用变量而非硬编码方便后期维护,深浅色适配配置深浅色效果提升视觉体验,结构树操作在结构树上拖拽改变组件父子关系]3. 深浅色效果配置/* 深浅色模式配置示例 */.light-mode{background-color:#FFFFFF;text-color:#000000;}.dark-mode{background-color:#1C1C1E;text-color:#FFFFFF;}常见问题FAQQ1动态列表组件绑定了数组变量但列表未显示答请检查1数组变量是否正确创建并赋值2绑定路径是否正确3数组中的字段名是否与组件绑定的字段匹配。Q2事件触发了但未执行预期动作答请检查1执行条件是否满足2变量引用是否正确3动作参数是否完整。可在预览模式下逐一排查。Q3卡片已发布但无法在插件绑卡时找到答请检查卡片是否已完成发布状态。发布后的卡片在绑卡界面才能被搜索到。Q4地图组件不显示地点答请检查1地点名称、经纬度是否正确2变量格式是否符合规范3是否已获取到定位权限显示用户实时定位时需要。总结本文详细介绍了自定义卡片编辑器的完整使用指南编辑器布局功能区、画布区、属性配置区的三区结构组件体系布局组件、基础组件、高级组件地图、多页签、选项组、音视频变量绑定6种变量类型及其在卡片的绑定规则事件配置11种执行动作和条件触发机制完整案例华为商城卡片的从零到一的构建过程最佳实践间距调整、深浅色适配、效率提升掌握自定义卡片编辑可以让你的智能体具备丰富的可视化交互能力大大提升用户体验。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源编辑组件编辑变量事件配置地图组件用法多页签组件用法选项组组件用法音视频组件用法卡片预览保存与发布卡片使用实践教程自定义卡片演示案例小艺开放平台