动态按钮与参数
用商品列表生成按钮,记住用户选择,并把所选商品交给下一个反应。
本页内容
机器人显示三件商品,每件都有“购买”按钮。用户选择连衣裙后,下一个反应应拿到连衣裙的 ID,即使机器人随后又显示过其他商品。动态按钮按列表生成按钮,Carry 则记住每个按钮对应的商品。两者都在发送消息动作的内容块中设置。
| 用户看到 | 按钮保存 |
|---|---|
| 大衣,12,000 ₽ · 购买 | product_id=101, price=12000 |
| 连衣裙,8,000 ₽ · 购买 | product_id=102, price=8000 |
| 运动鞋,6,000 ₽ · 购买 | product_id=103, price=6000 |
点击第二个按钮会传递 product_id=102,机器人无须从相同的“购买”文字推断是哪件商品。
从列表生成动态按钮
先从集合或外部服务取得商品列表,再用从列表生成动态按钮内容块逐项生成按钮。列表保存在当前反应的临时数据,即上下文 ctx 中。
| 设置 | 示例 | 作用 |
|---|---|---|
列表(over) | ctx.products | 使用数据源查询、Web 请求或计算动作预先准备的列表 |
元素别名(as) | item,默认值 | {{item.name}} 指当前商品名称 |
每行按钮数(columns) | 1,默认值 | 每件商品单独一行 |
| 按钮模板 | {{item.name}} · {{item.price}} ₽ | 把当前商品的值插入按钮文字等字段 |
同样的方式也可展示可预约课程、订单或菜单项目。
示例
假设 ctx.products 含 id、name 和 price:
- 列表填
ctx.products,元素别名填item,每行一按钮。 - 按钮文字填
{{item.name}} · {{item.price}} ₽。 - 类型选调用反应,并指定下单反应。
- 在 Carry 中加入
product_id,值为{{item.id}}。 - 下单反应读取
{{ctx.product_id}}。
先点第二个,再点第一个按钮,两次应分别得到各自的商品 ID。
点击时携带的数据(Carry)
Carry 就像每个按钮自己的标签:即使文字和目标反应都相同,保存的数据也各不相同。编辑器中称为点击时的数据。机器人在发送消息时计算并保存数据,用户点击时才把它放入新反应的 ctx。
- 键:保存值的名称,例如
product_id,点击后以{{ctx.product_id}}读取。 - 值:数字、文字或
{{item.id}}、{{param.order_id}}、{{ctx.x}}等替换内容;发送时求值。 - 一次性(
single_use):第一次点击后删除数据,无法再次使用。 - 有效期(
ttl_seconds):以秒计;3600是一小时,0使用默认的 30 天,并非无限期。
到期后按钮数据不可用,应让用户重新打开目录。每次发送的按钮都保存自己的数据,这在技术文档中叫 per-invocation。
点击按钮时设置参数(set_params)
如果选择需要在后续交谈中保留,例如配送城市,可在按钮的参数(set_params)中保存。点击后可用 {{param.city}} 读取。Carry 只供当前反应使用({{ctx.键名}}),set_params 则写入订阅者资料,供之后的反应使用。内容块本身也有 set_params,但它在发送消息时就写入,即使用户没有点击。
点击按钮也可添加或移除标签,与内容块的标签设置相同。
三种方式的区别
| 目的 | 选择 | 读取结果 |
|---|---|---|
| 把所选商品传给下一个反应 | Carry | {{ctx.product_id}} |
| 用户选城市后长期记住 | 按钮上的 set_params | {{param.city}} |
| 发送消息时立即保存 | 内容块上的 set_params | {{param.键名}} |