UI 基础指南 · 变量控制、交互按钮与模板开发
工具更新提示：基础教程中
变量宝宝教程.ppt的部分内容已过时。目前推荐使用 Trae 或 Zoo 等新型开发工具。
一、变量 UI 控制器与动态状态同步
1.1 核心机制
变量 UI 不会直接读取世界书，而是读取 AI 在正文中输出并被正则隐藏的 <UI_DATA> 数据包。当剧情状态发生变化时，AI 将变化后的状态整理成 JSON，放进 <UI_DATA> 标签中输出。
1.2 触发时机
必须输出 <UI_DATA> 的情况：
| 变化类型 | 说明 |
|---|---|
| 角色变化 | 当前角色入场、离场、切换主要互动对象 |
| 场景变化 | 场景、地点、时间、章节、阶段发生变化 |
| 数值变化 | 角色心情、关系、好感、信任、压力、生命、体力、金钱等 |
| 外观变化 | 角色服装、装备、姿势、状态、伤势、身份变化 |
| 系统变化 | 背包、任务、地图、阵营、成就、羁绊 |
| 玩家行动 | 玩家的行动造成了明确、可记录的后果 |
| UI 更新 | UI 中需要展示的新内容出现 |
不要输出 <UI_DATA> 的情况：
- 普通对白、气氛描写、轻微心理活动
- 没有变化的字段不要重复写
- 只输出发生变化的字段
1.3 输出格式
AI 在正文正常回复后，在回复的最末尾输出同步数据包：
<UI_DATA>{ "scene": {}, "player": {}, "characters": {}, "activeCharacters": [], "inventory": {}, "quests": {}, "map": {}, "system": {}, "actions": []}</UI_DATA>规范要求：
- JSON 必须完全合法，不能有注释、多余逗号、中文引号
- AI 绝对不能在 JSON 外对
<UI_DATA>进行任何解释 - 在角色卡中设置正则替换，将数据包隐藏
1.4 推荐数据结构
优先使用对象（Object），避免滥用数组（Array）：
{ "characters": { "char_001": { "name": "小满", "mood": "害羞", "status": "站立" } }}1.5 更新策略
| 策略 | 说明 |
|---|---|
| 出场/换装/觉醒 | 输出完整的角色对象 |
| 普通对话变化 | 只输出变化的字段 |
| 角色切换 | 更新 activeCharacters 数组 |
| 地点变化 | 更新 scene 或 map |
| 物品获得/使用 | 更新 inventory |
| 任务推进 | 更新 quests |
| 交互操作 | 更新 actions |
| 无变化 | 不输出 <UI_DATA> |
1.6 正则替换设置（隐藏数据包）
将 AI 输出的 <UI_DATA> 转换为隐藏的 textarea，供前端 JS 读取：
<UI_DATA>([\s\S]*?)</UI_DATA>替换为：
<textarea class="ui-data-sync" style="display:none" data-ui="$1"></textarea>二、RPH 交互按钮与输入框开发
2.1 按钮点击事件
在 RPH 的 UI 渲染机制中，按钮的点击事件必须通过特定格式编写。
可用格式
HTML 属性直接写 onclick（推荐）：
<button onclick="top.eval('window.triggerSlash(\'1zhou1tian\')')">好啊，一起！</button>innerHTML 动态渲染：
cDiv.innerHTML = '<button class="choice-btn" onclick="top.eval(\'window.triggerSlash(\\\'1zhou1tian\\\')\')">好啊，一起！</button>';静态 HTML 中的按钮：
<div id="choices"> <button onclick="top.eval('window.triggerSlash(\'1zhou1tian\')')">好啊，一起！</button></div>不可用格式（避坑指南）
// 以下方式点击无反应 ❌b.onclick = function(){ top.eval(...) }overlay.onclick = function(e){ ... }overlay.setAttribute('onclick', '...')overlay.addEventListener('click', function(){})2.2 自定义输入框与发送按钮
HTML 结构：
<input id="customActionInput" placeholder="输入你想做的事..."><button onclick="sendCustomAction()">发送</button>JavaScript 脚本：
function sendCustomAction() { var val = document.getElementById('customActionInput').value.trim(); if (!val) return; if (window.triggerSlash) window.triggerSlash('/send ' + val); document.getElementById('customActionInput').value = '';}
document.getElementById('customActionInput').addEventListener('keydown', function(e) { if (e.key === 'Enter') sendCustomAction();});三、高级 UI 构建指南（焚诀）
3.1 核心原则
采用 “AI 原生应用（AI Native App）” 的构建标准，目标是生成交互丰富、视觉精美的独立界面。
3.2 视觉规范
| 要求 | 说明 |
|---|---|
| 风格 | 根据角色设定选择极致的风格化设计 |
| 动画 | 所有交互元素必须带 transition，关键元素应有 animation（淡入、滑入） |
| 图标 | 严禁使用 Emoji，必须使用 <svg> 标签绘制图标 |
3.3 必须实现的核心功能模块
| 模块 | 要求 |
|---|---|
| 多标签页导航 | 切换时内容区应有平滑过渡动画 |
| 动态仪表盘 | 包含可视化状态条（HP/MP/好感度），使用进度条或环形图 |
| 详情子界面与弹窗 | 使用 Modal 或侧边抽屉，背景带模糊遮罩 |
| 折叠与展开 | 作为复杂内容的展示方案 |
3.4 交互逻辑规范
| 类型 | 方式 | 说明 |
|---|---|---|
| UI 内部交互 | document.getElementById(...) 直接操作 DOM | 标签切换、弹窗展开、详情显示，严禁使用 triggerSlash |
| 剧情交互 | window.triggerSlash('/指令') | 只有”使用物品”、“发起攻击”等实质性操作才使用 |
鼓励输入框自定义 triggerSlash 内容，禁止生成假/空按钮。
3.5 HTML 结构完整性
在 First Message 的末尾，必须嵌入一个完整的 HTML 页面代码块：
<!DOCTYPE html><html>...</html>HTML 的 body 标签及首个元素必须设置
margin-top: 0且padding-top: 0，确保与正文无缝衔接。
3.6 必填常驻条目
UI 输出规则（Position=At Depth, Depth=0）：
- 每条回复末尾根据当前剧情状态输出更新后的 HTML UI 面板
- UI 结构和风格必须与上下文保持高度一致
- HTML 必须以
<!DOCTYPE html>开头，</html>结束 - 禁止出现过分闪烁
交互逻辑强制规定：
- UI 交互必须区分本地操作和剧情操作
- 功能面板打开/关闭、标签页切换、详情展开必须使用本地即时响应
- 只有剧情互动才使用 triggerSlash
样式规范（Position=At Depth, Depth=0, Constant=true）：
- 对话使用双引号（""）包裹
- 心理活动使用圆括号（（））包裹
四、UI 模板开发说明
4.1 什么是 UI 模板
UI 模板是固定的状态栏/剧情面板，由辅助模型快速生成。相比实时构建 UI，它可以：
- 将生成时间从 300 秒压缩到 20 秒
- 将每次对话的 Token 从 10000 压缩到 1000
4.2 变量与更新机制
变量就是随时需要改变的条目——好感度、心情、当前位置等。变量辅助模型分析剧情发展后，输出更新格式：
(更新：好感度 10——20)系统自动嵌入 UI 模板，完成 UI 更新，不必等待实时构建。
4.3 UI 模板 vs 正则 UI vs 实时构建 UI
| 对比项 | UI 模板 | 正则 UI | 实时构建 UI |
|---|---|---|---|
| 生成速度 | 快（约 20s） | 中等 | 慢（约 300s） |
| Token 消耗 | 低（约 1000） | 中等 | 高（约 10000） |
| 灵活性 | 固定模板，不可百变 | 高，灵活多变 | 高，可实时调整 |
| 额外消耗 | 会像记忆系统一样消耗小饼干 | 无 | 无 |
| 优势 | 速度快、可导入导出、对低注意力模型友好 | 灵活、可玩性高 | 完全自由定制 |
| 劣势 | 模板固定，不可百变 | 稳定性低，易掉正则 | 等待时间长 |
4.4 如何制作 UI 模板
推荐使用 VS Code 中的 Roocode 插件，准备好需求发送给 AI 一键完成，也可以自研慢慢打磨。
UI 模板可以随意导入导出，只要主题符合，可随意使用适合的 UI 模板，不再局限于与角色强绑定的模板。
如果这篇文章对你有帮助，欢迎分享给更多人！
部分信息可能已经过时