frappe-builder

Frappe Builder

Builder 站点由一组文档构成：Builder Page（块树存储在 blocks 中，表示线上版本；存储在 draft_blocks 中，表示草稿）、Builder Component（页面以实例形式嵌入的块树）、Builder Token（颜色和字体变量）、Builder Client Script（页面 JS/CSS 文件）以及 Builder Settings（主页、全站代码）。这里的每个步骤都是读取或写入文档，或调用白名单方法，因此无论使用站点助手、MCP 还是 frappectl，操作方式都相同。用户需要 Website Manager 角色；创建 DocType（用于表单）则需要 System Manager 角色。

如果使用 shell，请先阅读 reference/cli.md：此技能目录中的 scripts/builder.py 会登录、检查并推送树、构建组件实例，以及在站点之间复制页面。

1. 编辑流程

• 页面的树存储在 draft_blocks 中；如果草稿为空，则存储在 blocks 中。组件的树存储在 block 中。两者都以字符串形式存储为 JSON：将整棵树连同读取到的 modified 值一起写回 draft_blocks（或 block）。如果有人期间保存过内容，写入就会失败，而不会覆盖对方的修改；请重新读取并合并。
• 首次编辑页面前，调用其 create_manual_snapshot 方法并传入 label。若要回滚，请传入该 Builder Snapshot 的名称调用 restore_snapshot：它会将树恢复到草稿中。
• 写入前，请让用户关闭页面的编辑器标签页，写入后再重新加载：打开的标签页可能会在下一次编辑时，将旧树覆盖到你的草稿上。
• 对于已有页面的站点，请先读取一个页面，并复用其中的令牌、字体、宽度和组件。
• 使用页面上的块构建区块。只有当同一棵树在当前页面或多个页面上重复出现，且没有合适的现有组件时，才将其制作成组件。仅当编辑器无法在实例上编辑某项内容，或脚本会读取某项内容时，组件才需要 prop（参见 reference/components.md）。
• 新建页面：创建 Builder Page，并填写 page_title 和 route。
• 预览草稿：调用 builder.api.get_page_preview_html，使用线上数据脚本和脚本渲染页面。如果这里报错，访客也会遇到同样的错误。
• 使用页面的 publish 方法发布页面；该方法会返回路由。通过 REST 发布时，向 /api/resource/Builder Page/<name> 发送 POST 请求，并在 JSON 请求体中附上 {"run_method": "publish"}。

只有页面的块树具有草稿；发布后访客才能看到。其他内容保存后立即生效：页面的数据脚本和字段、客户端脚本、令牌、Builder Settings，以及组件保存（未锁定的实例会立即更改；随后 builder.api.sync_component 会重写所有嵌入该组件的页面中的线上块）。

当预览（或线上写入时的线上路由）显示了更改，并且用户清楚哪些内容已上线、哪些仍是草稿时，即可视为完成。

2. 注意事项

• 所有块文本、属性、组件脚本和样式、head_html 以及 canonical_url 都会通过 Jinja 渲染。 {{ }} 和 {% %} 会在线实时求值，并在编辑器中原样显示。除非位于 {% raw %} 中，否则 {# 会导致页面报错；即使位于其中，.__ 也会导致页面报错，因此请将此类代码移入客户端脚本文件。
• 数据脚本异常、缺少嵌套绑定，或在重复器需要列表时传入字典，都会导致页面返回 500 错误。 参见 reference/data-and-scripts.md。
• 路由会覆盖其他所有内容。 Builder 路由优先于其他所有网站路由；像 /:slug 这样的根级兜底路由会匹配 /login 和编辑器路由 /builder。
• 绑定值会作为原始 HTML 渲染。 请在数据脚本中清理或转义访客提交的文本。

参考资料

• reference/blocks.md：块 JSON、样式、断点、令牌、绑定、重复器、可见性。
• reference/data-and-scripts.md：两种执行器上的数据脚本、动态路由、客户端脚本及加载顺序、保存数据的表单。
• reference/components.md：构建组件、实例和覆盖项、编辑器沙盒、锁定与同步。examples/tabs/ 是一个可运行的组件示例。
• reference/live-and-cached.md：线上更改未显示时的处理方法。
• reference/cli.md：通过 shell 操作：登录、使用 scripts/builder.py、本地 bench 和隧道。