页面代码：数据、素材与交互

页面代码决定模板的固定结构、排版和样式，也把当前帧的数据变成玩家看到的文字、图片和按钮。模板中间区域可以在“预览”和“代码”之间切换。

101 提供可以整段复制的页面代码。只有需要自定义布局或交互时，才需要自己修改代码。

页面代码处在作品的哪一层

页面代码只负责“根据当前数据渲染什么”。修改变量、切换帧、跳转界面和触发 AI 回复仍由触发器规则负责。

运行时提供的三个对象

页面组件默认导出一个函数。运行时会把三个只读对象交给它：

对象	包含什么	常见读取
`frame`	当前可播放帧的数据，由触发器规则写入	当前台词、背景、立绘、选项
`state`	当前作品状态，会在页面节点之间保留	玩家姓名、好感度、已获得线索
`playback`	当前这一批帧的播放位置	`cursor`、`frameCount`

它们不是字符串模板，也不需要额外请求。页面代码直接读取对象属性。

interface PageProps {
  frame?: {
    speaker?: string
    text?: string
  }
  state?: {
    player_name?: string
  }
  playback?: {
    cursor?: number
    frameCount?: number
  }
}

export default function StoryPage({
  frame = {},
  state = {},
  playback = {}
}: PageProps) {
  const speaker = frame.speaker || "旁白"
  const text = frame.text || ""
  const playerName = state.player_name || "你"
  const current = Number(playback.cursor ?? 0) + 1
  const total = Number(playback.frameCount ?? 0)

  return (
    <main className="page-root">
      <p>{playerName}</p>
      <h2>{speaker}</h2>
      <p>{text}</p>
      <small>{current} / {total}</small>

      <style>{`
        * { box-sizing: border-box; }
        .page-root {
          width: 100%;
          height: 100%;
          min-width: 0;
          min-height: 0;
          overflow: auto;
          padding: 24px;
        }
      `}</style>
    </main>
  )
}

普通数据：直接读取变量

文字、数字、布尔值、对象和数组都使用普通的 JavaScript 属性访问：

const title = frame.title || "未命名章节"
const affection = Number(state.affection ?? 0)
const choices = Array.isArray(frame.choices) ? frame.choices : []
const hasClue = Boolean(state.has_clue)

在 JSX 中同样直接使用：

<h1>{frame.title}</h1>
<p>{state.player_name || "你"}</p>

不要把普通变量写成字符串：

// 错误：这不是页面代码读取普通变量的方式
const title = "{{frame.title}}"
const playerName = "{{state.player_name}}"

变量可能尚未写入，因此要提供默认值，并在遍历前确认它确实是数组。

动态素材：使用 media_url

Frame 或 State 媒体变量保存的是素材 ID，不是浏览器可以直接加载的 URL。编辑器界面把这种可读 ID 显示为“素材名称”。完成素材绑定后，使用 media_url() 取得地址：

interface MediaPageProps {
  frame?: {
    background?: string
    portrait?: string
  }
  state?: {
    player_avatar?: string
  }
}

export default function MediaPage({ frame = {}, state = {} }: MediaPageProps) {
  const backgroundUrl = frame.background ? media_url(frame.background) : ""
  const portraitUrl = frame.portrait ? media_url(frame.portrait) : ""
  const avatarUrl = state.player_avatar ? media_url(state.player_avatar) : ""

  return (
    <main className="media-root">
      {backgroundUrl ? <img className="background" src={backgroundUrl} alt="" /> : null}
      {portraitUrl ? <img className="portrait" src={portraitUrl} alt="" /> : null}
      {avatarUrl ? <img className="avatar" src={avatarUrl} alt="玩家头像" /> : null}
    </main>
  )
}

media_url 是页面代码编译器识别的特殊函数，不需要导入。保存或预览时，编译器会把它改写成对应 Frame / State 媒体绑定的 URL 解析调用。它有三个限制：

只传一个直接来自 frame 或 state 的字段；
该字段要先在“变量配置”中联动素材库；
传入的是变量本身，不是素材名字符串或拼接后的表达式。

写法	结果
`media_url(frame.background)`	正确；按 `frame.background` 自己的素材绑定解析
`media_url(state.player_avatar)`	正确；按 State 媒体绑定解析
`src={frame.background}`	错误；把素材 ID 当成 URL
把固定素材 ID 字符串传给 `media_url`	错误；没有说明使用哪一个媒体变量的绑定
`media_url(frame.background		state.default_background)`	错误；参数不是一个直接的变量路径

如果素材固定不随 Frame 或 State 改变，可以使用已经确认存在的素材 ID：

<img src="{{asset:固定素材ID}}" alt="" />

固定素材和动态素材不要混用。动态背景、立绘、头像和音频通常应经过变量与素材绑定。

数组数据：把一帧中的多项内容渲染出来

触发器规则可以用 append 把多条“选项”指令加入 frame.choices。页面代码需要遍历这个数组：

interface Choice {
  text: string
  value: string
  prompt?: string
}

const choices = Array.isArray(frame.choices) ? frame.choices : []

return (
  <div className="choice-list">
    {choices.map((choice: Choice, index: number) => (
      <button
        className="story-choice"
        data-value={choice.value}
        data-prompt={choice.prompt || choice.text}
        type="button"
        key={`${choice.value}-${index}`}
      >
        {choice.text}
      </button>
    ))}
  </div>
)

显示文案可以变化，交互值应保持稳定。规则可以匹配 .story-choice[data-value=letter]，不要匹配按钮上会变化的中文句子。

玩家操作：页面提供元素，规则执行作品行为

需要切换帧、更新 State、跳转页面或触发 AI 时，页面代码只提供原生元素和稳定选择器：

<button className="story-next" type="button">继续</button>

触发器规则再配置：

触发时机：用户交互
事件类型：click — 点击
Element Selector：.story-next
动作：切换帧 1

不要在 React 的 onClick 中直接修改 frame / state，也不要自行实现跳转、切换帧或 AI 请求。页面内临时展开一个说明面板、切换标签等不改变作品事实的纯界面操作，才适合使用组件自己的 useState。输入框同样使用原生元素。规则可以用 #message-input::value 采集值：

<form id="message-form">
  <input id="message-input" name="message" />
  <button type="submit">发送</button>
</form>

playback：只读取，不自行修改

playback.cursor 是从 0 开始的当前帧下标，playback.frameCount 是本批内容的总帧数。它们适合显示进度或决定是否显示按钮：

const cursor = Number.isInteger(playback.cursor) ? Number(playback.cursor) : 0
const frameCount = Number.isInteger(playback.frameCount) ? Number(playback.frameCount) : 0
const isLastFrame = frameCount > 0 && cursor === frameCount - 1

页面代码不能修改 cursor。前进或后退仍由“切换帧”动作完成。cursor === 0 只表示当前在第一帧，不代表组件刚刚打开或 AI 刚返回新内容。

页面尺寸与样式边界

编辑器和玩家侧会把页面放入一个可变化的渲染窗口。平台已经管理 html、body 和 #root；页面代码只需要设置自己的最外层容器：

.page-root {
  width: 100%;
  height: 100%;
  min-width: 0;
  min-height: 0;
  overflow: hidden;
}

继续遵守以下约束：

长内容放进页面自己的滚动区域；
图片设置尺寸边界和 object-fit；
使用 flex、grid、百分比、媒体查询或容器查询适配窄而矮的窗口；
不给页面根容器设置会反向撑大窗口的固定 min-width / min-height；
不用 100vh 猜测 iframe 高度，也不改写 html、body 和 #root。

需要按模板窗口而不是浏览器窗口设置断点时，可以使用平台提供的容器名：

@container frame-viewport (max-width: 720px) {
  .page-layout { grid-template-columns: 1fr; }
}

编译、保存与运行预览

从“代码”切回“预览”时，编辑器会编译当前草稿并刷新作品实时预览。编译失败后：

编辑器回到代码页；
底部显示可滚动的错误详情；
当前代码仍会保留；
继续编辑会清除旧错误提示。

作品实时预览只检查当前模板。跨页面跳转和真实 AI 生成需要保存作品后，在运行预览中检查。点击顶部“保存作品”或关闭模板标签时选择“保存并关闭”，编辑器会编译页面代码、保存模板和规则组，并生成模板预览图。任一步失败时，先保留当前标签并查看提示。

页面没有按预期显示时

按数据流从前往后检查：

在调试面板确认目标 frame.x 或 state.x 已有正确值；
如果是媒体，确认该变量已经联动素材库；
确认普通数据直接读取，媒体才调用 media_url()；
确认按钮的类名或 data-* 与 Element Selector 一致；
确认根容器没有固定尺寸或错误滚动导致内容被裁掉。

MoMo：图片不显示时，先看变量里的素材 ID，再看素材绑定，最后看 media_url()。按这个顺序排查。

从这里开始

101｜完成第一篇作品

编辑器详细文档

页面代码：数据、素材与交互

页面代码处在作品的哪一层

运行时提供的三个对象

普通数据：直接读取变量

动态素材：使用 media_url

数组数据：把一帧中的多项内容渲染出来

玩家操作：页面提供元素，规则执行作品行为

playback：只读取，不自行修改

页面尺寸与样式边界

编译、保存与运行预览

页面没有按预期显示时