标签交互指令

平台不支持在美化内容里执行 JavaScript。

如果你想做点击交互，请直接在 HTML 标签上使用 data-* 指令。

适用场景

元素显示、隐藏、切换
类名添加、移除、切换
点击发送消息
采集表单数据

提示

这套指令既可以配合 JSON 美化使用，也可以配合正则美化使用。

对新手来说，更稳的方式是先做最小交互，不要一上来就把多个指令堆在同一个元素上。

点击交互：发送消息

功能说明

在需要点击的标签上写 data-action-send，就可以把它标记为可发送元素。

点击后，文本会被放入聊天输入框。

如果同时写了 data-auto，则会直接发送，不再停留在输入框里。

属性总览

属性	作用
`data-action-send`	获取标签内文本，并放入聊天输入框
`data-action-send="文本"`	发送指定文本，而不是标签里显示的文字
`data-auto`	自动发送消息；非必须时不建议添加

使用方法

语法

html

<!-- 获取标签内文本发送至输入框 -->
<p data-action-send>搜集线索</p>

<!-- 使用属性里指定的文本 -->
<p data-action-send="前往村庄的啤酒馆，听取更多情报">搜集线索</p>

<!-- 正则美化：发送捕获到的文本 -->
<p data-action-send="$1">$1</p>

<!-- JSON 美化：发送模板渲染后的字段内容 -->
<p data-action-send="{{item}}">{{item}}</p>

应用示例

html

<p>你想要怎么做？</p>
<p data-action-send="我选择战斗">⚔️ 战斗</p>
<p data-action-send="我选择逃跑">🏃 逃跑</p>
<p data-action-send="我选择谈判">💬 谈判</p>

html

<div data-action-send="接受任务" data-auto>
  <p>✅ 接受任务</p>
  <p><small>点击后直接发送</small></p>
</div>

提示

写了 data-action-send="文本" 时，实际发送的是属性里的内容，不是标签里显示的文字
data-auto 会直接发送消息，只在你确定不需要用户二次确认时再用
如果只是给用户一个“快捷填入”的按钮，通常不要加 data-auto

表单交互：提交表单

功能说明

在 form 标签内部，使用 data-action-submit 标记任意元素。

点击后，系统会收集表单内带 name 属性的字段，并整理成一条消息放入聊天输入框。

如果同时写了 data-auto，则会在收集完成后直接发送。

属性总览

属性	作用
`data-action-submit`	标记为表单提交触发器，收集表单字段并放入聊天输入框
`data-action-submit="身份设定"`	额外添加一段头部文字，显示在消息最前面
`data-auto`	自动发送消息

表单字段要求

属性	必填	说明
`name`	是	字段名称，使用英文标识，例如：`name="user_name"`；未填写时不会被采集
`data-label`	否	采集时显示的标题，例如：`data-label="姓名"`；未设置时使用 `name`

使用方法

示例

html

<form>
  <input name="user_name" data-label="姓名" value="" />
  <input name="age" value="" />
  <button data-action-submit="用户信息">提交表单</button>
</form>

输出结果

text

用户信息
姓名: 用户输入的姓名
age: 用户输入的年龄

提示

提交触发元素必须放在 form 标签内部
只有带 name 的表单字段才会被采集
空值字段默认不会输出到最终消息里
推荐使用 data-label 设置中文显示名称
支持常见表单控件，例如输入框、单选、复选、下拉等
布尔值会自动转换为中文：true -> 是，false -> 否
多选字段会逐项输出每个被选中的值

类名操作：`class`

功能说明

通过类名指令，你可以为元素添加、移除或切换类名，再交给 CSS 去表现状态变化。

指令总览

指令	作用
`data-add-class`	为目标元素添加类名
`data-remove-class`	从目标元素移除类名
`data-toggle-class`	切换目标元素上的类名

多个类名用空格分隔，例如：data-add-class="active selected"。

同一元素上如果同时声明了多条类名指令，执行顺序固定为：remove -> add -> toggle。

目标属性

属性	作用
`data-target`	通用目标，适用于 `add / remove / toggle`
`data-add-target`	单独指定 `data-add-class` 的目标元素
`data-remove-target`	单独指定 `data-remove-class` 的目标元素

没有写目标属性时，类名指令默认作用于触发元素自身
多条指令共用同一批目标时，直接写 data-target 最省事
需要把“移除”和“添加”分开控制时，再使用 data-remove-target 和 data-add-target

使用示例

自身切换背景

css

.example {
  user-select: none;
  cursor: pointer;
  padding: 12px;
  border: 2px solid #2d5e90;
  border-radius: 8px;
}

.highlight {
  background: #9ebcdf;
  color: #000;
  transition: all 0.5s;
}

在元素上使用 data-toggle-class：

html

<div class="example" data-toggle-class="highlight">
  点击我切换背景
</div>

控制其他元素

先定义面板的默认状态和显示后的类名：

css

button {
  padding: 8px 15px;
  border: 1px solid #dcdfe6;
  background: #f4f4f5;
  cursor: pointer;
  border-radius: 4px;
  margin-right: 4px;
}

.panel {
  display: none;
  margin-top: 8px;
  padding: 12px;
  border: 2px solid #4a7b70;
  border-radius: 8px;
}

.panel.show {
  display: block;
}

然后通过 data-target 指定目标元素，并控制类名的添加与移除：

html

<button data-add-class="show" data-target=".panel-1, .panel-2">
  显示面板
</button>

<button data-remove-class="show" data-target=".panel-1, .panel-2">
  隐藏面板
</button>

<div class="panel panel-1">面板 1</div>
<div class="panel panel-2">面板 2</div>

提示

如果只是做显示 / 隐藏，优先使用下面的 display 指令
不建议在同一个元素上混用 data-toggle-class 和 data-add/remove-class
写排他高亮时，最常见的写法是“先移除全部，再为当前项添加”

显示 / 隐藏：`display`

功能说明

通过 data-display-* 指令，你可以为目标元素添加或移除隐藏类 is-hidden，实现显示、隐藏、折叠和面板切换。

平台内置了：

css

.is-hidden { display: none !important; }

指令总览

指令	作用
`data-display-hide`	为目标元素添加 `is-hidden`
`data-display-show`	从目标元素移除 `is-hidden`
`data-display-toggle`	在隐藏和显示之间切换

display 指令必须指定目标选择器
如果某个面板默认就是隐藏状态，请直接给它加上 is-hidden
多个目标元素使用逗号分隔，例如：.box-1, .box-2
同一元素上如果同时声明了多条显示指令，执行顺序固定为：hide -> show -> toggle
Tab 切换最常见的写法是：先 hide 全部，再 show 当前

使用示例

基础显示 / 隐藏

先定义按钮和面板的基础样式：

css

button {
  padding: 8px 15px;
  border: 1px solid #dcdfe6;
  background: #f4f4f5;
  cursor: pointer;
  border-radius: 4px;
  margin-right: 4px;
}

.box {
  padding: 10px;
  margin-top: 8px;
  border: 1px solid #409eff;
  border-radius: 8px;
  background: #ecf5ff;
}

然后通过 data-display-toggle 控制目标面板在显示与隐藏之间切换：

html

<button data-display-toggle=".box">面板显示 / 隐藏</button>

<div class="box">
  <h3>目标面板</h3>
  <p>这个面板的显示状态由上面的按钮控制。</p>
</div>

Tab 面板切换

先定义按钮和面板的基础样式：

css

.tab-header button {
  padding: 8px 15px;
  border: 1px solid #dcdfe6;
  background: #f4f4f5;
  cursor: pointer;
  border-radius: 4px;
  margin-right: 4px;
}

.tab {
  margin-top: 8px;
  padding: 20px;
  border: 2px solid #4a7b70;
  border-radius: 8px;
}

然后先隐藏全部面板，再显示当前目标面板：

html

<div class="tab-header">
  <button data-display-show=".tab-1" data-display-hide=".tab">
    数据概览
  </button>
  <button data-display-show=".tab-2" data-display-hide=".tab">
    详细配置
  </button>
  <button data-display-show=".tab-3" data-display-hide=".tab">
    日志记录
  </button>
</div>

<div class="tab tab-1">
  <h3>面板一：数据概览</h3>
  <p>这个面板初始是显示的。</p>
</div>

<div class="tab tab-2 is-hidden">
  <h3>面板二：详细配置</h3>
  <p>这个面板初始是隐藏的。</p>
</div>

<div class="tab tab-3 is-hidden">
  <h3>面板三：日志记录</h3>
  <p>这个面板初始是隐藏的。</p>
</div>

提示

不要把触发按钮本身也写进 data-display-hide 的选择器里，否则会把自己一起隐藏
display 指令负责显隐，class 指令负责外观状态，两者分开写通常最清楚

综合示例：Tab 切换 + 选中高亮

一个完整的 Tab 交互，通常会同时用到两组指令：

显示 / 隐藏：使用 display 指令控制面板切换
选中高亮：使用 class 指令控制按钮状态

两组指令可以同时写在同一个按钮上，分别处理“面板切换”和“按钮高亮”，互不影响。

示例

先定义 Tab 按钮、面板区域和选中态样式：

css

.tab-header {
  display: flex;
  gap: 8px;
  margin-bottom: 12px;
}

.tab-btn {
  padding: 8px 12px;
  border: 1px solid #d7dbe7;
  border-radius: 6px;
  background: #f7f8fb;
  color: #4a4f62;
  cursor: pointer;
  transition: all 0.2s ease;
}

.tab-btn:hover {
  background: #eef2ff;
  border-color: #b4c4ff;
}

.tab-btn.active {
  background: #5b7bff;
  border-color: #4c6aff;
  color: #fff;
}

.tab-body {
  padding: 12px;
  border: 2px solid #4a7b70;
  border-radius: 8px;
}

然后在同一个按钮上同时声明 class 和 display 指令：

html

<div class="tab-header">
  <button
    class="tab-btn tab-btn-1 active"
    data-remove-class="active"
    data-remove-target=".tab-btn"
    data-add-class="active"
    data-add-target=".tab-btn-1"
    data-display-hide=".tab-panel"
    data-display-show=".tab-panel-1"
  >
    概览
  </button>

  <button
    class="tab-btn tab-btn-2"
    data-remove-class="active"
    data-remove-target=".tab-btn"
    data-add-class="active"
    data-add-target=".tab-btn-2"
    data-display-hide=".tab-panel"
    data-display-show=".tab-panel-2"
  >
    配置
  </button>

  <button
    class="tab-btn tab-btn-3"
    data-remove-class="active"
    data-remove-target=".tab-btn"
    data-add-class="active"
    data-add-target=".tab-btn-3"
    data-display-hide=".tab-panel"
    data-display-show=".tab-panel-3"
  >
    日志
  </button>
</div>

<div class="tab-body">
  <div class="tab-panel tab-panel-1">面板 1</div>
  <div class="tab-panel tab-panel-2 is-hidden">面板 2</div>
  <div class="tab-panel tab-panel-3 is-hidden">面板 3</div>
</div>

提示

上面的示例主要用于演示多种指令组合后的效果
在实际使用中，通常不需要手动写出这么复杂的结构
类似需求更多时候可以通过模板语法遍历来实现
也可以在平台中使用 JSON 美化助手，通过对话生成你想要的交互效果

标签交互指令 ​

适用场景 ​

点击交互：发送消息 ​

功能说明 ​

属性总览 ​

使用方法 ​

表单交互：提交表单 ​

功能说明 ​

属性总览 ​

表单字段要求 ​

使用方法 ​

类名操作：class ​

功能说明 ​

指令总览 ​

目标属性 ​

使用示例 ​

显示 / 隐藏：display ​

功能说明 ​

指令总览 ​

使用示例 ​

综合示例：Tab 切换 + 选中高亮 ​

标签交互指令

适用场景

点击交互：发送消息

功能说明

属性总览

使用方法

表单交互：提交表单

功能说明

属性总览

表单字段要求

使用方法

类名操作：`class`

功能说明

指令总览

目标属性

使用示例

显示 / 隐藏：`display`

功能说明

指令总览

使用示例

综合示例：Tab 切换 + 选中高亮