spherse-write-html

编写 HTML 页面 — 数据读写与 App 能力调用

本 skill 只规范 HTML 页面如何读取/写入数据、如何调用 App 内能力，不约束页面视觉风格、布局或代码风格。

强制：声明字符编码

所有 HTML 页面必须在 <head> 中添加 <meta charset="UTF-8">，且尽量靠近 <head> 起始位置，避免中文乱码。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>页面标题</title>
</head>
<body>
  <!-- ... -->
</body>
</html>

强制：不要禁止页面滚动

HtmlCard 在固定高度的 iframe 中渲染（默认 400px，上限 600px）。当页面内容超出卡片高度时，必须能滚动查看全部内容——切勿设置 body { overflow: hidden } 或 html { overflow: hidden }，否则超出部分被裁剪、无法滚动，用户看不到完整内容。

/* ❌ 错误：卡片内内容会被裁剪，无滚动条 */
body { overflow: hidden; }

/* ✅ 正确：保持默认（visible）或显式允许滚动 */
body { overflow-y: auto; }

即便不加 overflow:hidden，App 也会在渲染时强制注入 html,body{overflow-y:auto!important} 作为兜底；但请勿依赖兜底，页面自身就应保持可滚动。自定义侧边面板（约 260px 窄栏、占满面板高度、原生滚动）没有这层兜底注入，更要保持可滚动，不要设 overflow: hidden 裁剪内容。

区分两种渲染模式

Spherse 中的 HTML 有两种加载方式，决定了数据能否通过 fetch 访问同目录文件：

模式	加载方式	能否 fetch 同目录文件	典型场景
文件模式	HTML 落在项目目录，经 preview 路由以 src 加载（真实 origin）	✅ 可以	Welcome Page、自定义侧边面板、Content Browser 预览、HtmlCard 带 file_path
字符串模式	纯 HTML 字符串经 srcDoc 加载（无真实 origin）	❌ 不可以	Chat HtmlCard 无 file_path

判断方法：如果页面是作为文件写入用户项目目录（而非内联字符串），按「文件模式」处理。

何时将数据与渲染分离

实现一个 HTML 页面前，先判断它属于哪类，决定数据是「外置 JSON」还是「内联进 HTML」：

倾向	适用场景	做法
外置 JSON（推荐）	信息量较大（多条目列表/表格/清单）、预计需要长期维护与更新、数据可能被其它页面复用	数据存成独立的 {页面名}.data.json 文件，HTML 只负责渲染并用 fetch 加载数据
内联进 HTML	少量一次性展示内容、纯结构展示、字符串模式且无需持久化	数据直接写进 <script> 中的 JS 对象或 DOM

外置的好处：数据与结构解耦，后续只改 JSON 即可更新内容，无需触碰 HTML；JSON 也可被其它页面 fetch 复用。

实现时务必用 write 工具分别落盘两个文件：HTML 页面（如 world/atlas.html）和数据文件（如 world/atlas.data.json），不要只写 HTML。

只读展示数据：外置为同目录 JSON（文件模式推荐）

文件模式下，把页面需要的展示数据外置到同目录的 .json 文件，用 fetch 加载。这样数据与结构分离，便于维护和更新，也避免把大段数据塞进 HTML。

约定：数据文件名形如 {页面名}.data.json，与 HTML 同级。

假设页面为 world/atlas.html，数据文件为 world/atlas.data.json：

{
  "regions": [
    { "name": "北境", "climate": "寒带", "faction": "守夜人" },
    { "name": "南境", "climate": "亚热带", "faction": "商会联盟" }
  ]
}