投稿模板

模板本质上是一个 HTML 文件，加上一份参数声明和可选的数据表声明。用户从模板创建作品时，PlayPage 会把 HTML 里的占位符替换为用户填写的参数。

建议先点“套用静态页面示例”或“套用留言板示例”，再按需要修改。

1. 模板基本信息

模板名称链接名只用于模板详情页地址，不是用户作品地址。分类 ID英文或拼音，例如 site、tool、game、community。分类显示名

一句话简介详细说明标签

需要互动功能建议开启统计

2. 参数声明

参数会出现在创建作品页面。比如声明了 themeColor，HTML 里写 {{themeColor}}，创建时就会被替换成用户选择的颜色。

参数 1

参数名显示标签类型默认值

提示文字帮助说明

必填

参数 2

参数名显示标签类型默认值

提示文字帮助说明

必填

参数 3

参数名显示标签类型默认值

提示文字帮助说明

必填

高级：直接编辑参数声明 JSON

参数声明 JSON

3. 数据表声明

只有留言板、论坛、排行榜、云存档这类需要在线保存数据的模板才需要声明数据表。静态页面保持空数组 [] 即可。

数据表声明不是“示例数据”，而是告诉 PlayPage：用户从这个模板创建作品时，要自动为这个作品创建哪些数据集合。

数据表声明 JSON

数据集合声明怎么写

整体必须是数组。数组里的每一项代表一个数据集合。集合创建后，模板 HTML 里的 JS 可以通过互动 API 读写它。

name：集合名，只建议用英文、数字、下划线，例如 messages、posts、scores。
permissions.publicRead：访客是否可以读取。留言板、论坛、排行榜通常设为 true。
permissions.publicWrite：访客是否可以新增或修改。允许发帖、评论、留言时必须设为 true。
fields：字段声明数组。每个字段描述一项业务数据，比如标题、正文、作者、分数。

字段支持常用类型：string 短文本、text 长文本、number 数字、boolean 布尔值。required 表示写入时必须提供，isList 表示这个字段是否是数组，普通字段一般写 false。

例子：论坛通常需要两个集合。posts 保存帖子，comments 保存回复；回复通过 postId 关联到帖子 ID。

[
  {
    "name": "posts",
    "permissions": { "publicRead": true, "publicWrite": true },
    "fields": [
      { "name": "title", "type": "string", "required": true, "isList": false },
      { "name": "content", "type": "text", "required": true, "isList": false },
      { "name": "author", "type": "string", "required": true, "isList": false }
    ]
  },
  {
    "name": "comments",
    "permissions": { "publicRead": true, "publicWrite": true },
    "fields": [
      { "name": "postId", "type": "string", "required": true, "isList": false },
      { "name": "content", "type": "text", "required": true, "isList": false },
      { "name": "author", "type": "string", "required": true, "isList": false }
    ]
  }
]

4. 模板源码

源码方式

粘贴 HTML 上传 HTML 上传 ZIP

HTML 代码

模板开发规范

必须知道的规则

模板必须是完整 HTML 页面，建议包含 <!doctype html>、<html lang="zh-CN">、<meta charset="utf-8">。
参数占位符格式固定是 {{参数名}}，参数名要和参数声明里的 name 完全一致。
颜色参数请使用 type: "color"，默认值必须是 #RRGGBB，例如 #2563eb。
需要互动数据时，勾选“需要互动功能”，并声明要创建的数据表。
投稿不会执行任何后端代码；模板里的 JS 只会在用户作品页面的浏览器中运行。

系统占位符

{{PLAYPAGE_API_BASE}}：当前作品互动 API 基础地址，例如 /api/v1/public/projects/作品ID。
{{PLAYPAGE_PUBLIC_KEY}}：当前作品公开互动密钥，用在 X-Project-Key 请求头。
{{PLAYPAGE_PREVIEW}}：预览时是 true，正式发布时是 false。
{{PROJECT_ID}}、{{PROJECT_NAME}}：当前作品 ID 和名称。

预览机制

模板详情页的“打开完整预览”会用参数默认值渲染 HTML，不会创建真实作品，也不会创建真实数据集合。
预览时 {{PLAYPAGE_PREVIEW}} 会被替换成 true；用户真正创建作品后会替换成 false。
预览时 {{PLAYPAGE_API_BASE}} 和 {{PLAYPAGE_PUBLIC_KEY}} 会替换成演示值，不能当成真实数据接口使用。
互动模板必须自己判断预览模式：预览时使用浏览器内存里的假数据；正式发布时才调用互动 API。
如果模板预览直接请求真实 API，通常会失败；正确做法是像下方示例一样封装 api 和 previewApi。

互动请求最小写法

const API_BASE = "{{PLAYPAGE_API_BASE}}";
const PROJECT_KEY = "{{PLAYPAGE_PUBLIC_KEY}}";
const PREVIEW = "{{PLAYPAGE_PREVIEW}}" === "true";

async function api(path, options = {}) {
  if (PREVIEW) {
    return previewApi(path, options);
  }

  const response = await fetch(API_BASE + path, {
    ...options,
    headers: {
      "Content-Type": "application/json",
      "X-Project-Key": PROJECT_KEY,
      ...(options.headers || {})
    }
  });
  const data = await response.json().catch(() => ({}));
  if (!response.ok) throw new Error(data.error || "请求失败");
  return data;
}

const previewMessages = [
  { id: "preview-1", data: { nickname: "预览用户", content: "这是预览数据，不会保存。" }, createdAt: new Date().toISOString() }
];

async function previewApi(path, options = {}) {
  if (path === "/collections/messages/records" && (!options.method || options.method === "GET")) {
    return { items: previewMessages };
  }
  if (path === "/collections/messages/records" && options.method === "POST") {
    const body = JSON.parse(options.body || "{}");
    const item = { id: "preview-" + (previewMessages.length + 1), data: body.data || {}, createdAt: new Date().toISOString() };
    previewMessages.push(item);
    return item;
  }
  throw new Error("预览模式不支持这个操作");
}