cloudcannon-visual-editing

CloudCannon 可视化编辑

@cloudcannon/editable-regions 可让页面元素在 CloudCannon 的 Visual Editor 中进行交互。本指南介绍可编辑区域 API、集成设置，以及针对 SSG 的模式，说明如何连接文本、图像、数组和组件可编辑项。

适用场景

• 为新的或现有的 CloudCannon 网站添加 Visual Editor 支持
• 使页面区块可编辑（文本、图像、数组、组件）
• 设置组件重新渲染，以实现实时预览
• 调试未显示或未更新的可编辑区域
• 为由数据文件支持的共享局部模板添加可编辑区域

不适用场景

• 字段没有 _inputs 条目，或集合尚未配置 — 请先使用 cloudcannon-configuration 进行配置。没有匹配 Input 的可编辑区域会在编辑器中报错。
• 编辑者需要在富文本中插入新的标记 — 这属于 cloudcannon-snippets。可编辑区域用于编辑已渲染的内容。
• 网站使用 Bookshop（*.bookshop.yml 文件、@bookshop/* 包、_bookshop_name 键）— 请从 cloudcannon-bookshop 开始。该指南会引导你回到这里了解可编辑区域。
• 页面完全无法在 Visual Editor 中打开 — 通常是集合的 url 错误，而不是区域的问题。请参阅 cloudcannon-configuration/collection-urls.md。

目录

文档	阅读时机
editable-regions.md	从这里开始。区域类型、属性参考、自定义元素对应形式
visual-editing.md	区块清点、完整性检查清单、交接前检查 — 适用于所有 SSG
visual-editing-reference.md	按需阅读。数据属性路径、数组、页面构建器、组件、源文件可编辑项
react/visual-editing-reference.md	React 组件，适用于任何 SSG — 注册、EditableRegions 导出、JSX 标记、富文本宿主、蓝图
vue/visual-editing-reference.md	Vue 组件，适用于任何 SSG — 注册、EditableRegions 导出
svelte/visual-editing-reference.md	Svelte 组件，适用于任何 SSG — 注册、EditableRegions 导出
editable-regions-internals.md	Visual Editor JavaScript API；用于调试的生命周期跟踪和行为细节
troubleshooting.md	症状 → 修复方案，适用于区域未显示、未更新或未写入预期位置的情况

针对 SSG：

从 SSG 的 overview.md 开始阅读；其中列出了该 SSG 各文件的阅读顺序。若网站渲染 React、Vue 或 Svelte 组件，还应阅读上方对应框架的 visual-editing-reference.md；SSG 的阅读顺序中会列出该文档。

SSG	文档	用途
Astro	astro/overview.md	从 Astro 开始 — 阅读顺序及各文件的内容
Astro	astro/visual-editing.md	设置工作流、基础设施检查清单、Astro 检查清单项
Astro	astro/visual-editing-reference.md	Astro 与通用模式参考的差异（按需阅读）
Astro	astro/troubleshooting.md	Astro 特有问题症状 → 修复方案
Hugo	hugo/overview.md	从 Hugo 开始 — 阅读顺序及各文件的内容
Hugo	hugo/visual-editing.md	模块设置、基础设施检查清单、Hugo 检查清单项、本地检查
Hugo	hugo/visual-editing-reference.md	Hugo 的差异：仅重新渲染 partial、ENV_CLIENT、编辑器中的 Hugo 内容
Hugo	hugo/troubleshooting.md	Hugo 特有问题症状 → 修复方案
Eleventy	eleventy/overview.md	从 Eleventy 开始 — Liquid 或 Nunjucks 路径、阅读顺序
Eleventy	eleventy/visual-editing.md	各路径的插件设置、基础设施检查清单、Eleventy 检查清单项、本地检查
Eleventy	eleventy/visual-editing-reference.md	Eleventy 的差异：将 include 作为组件、浏览器中的配置、Nunjucks 站点
Eleventy	eleventy/troubleshooting.md	Eleventy 特有问题症状 → 修复方案
Next.js	nextjs/overview.md	从 Next.js 开始 — EditableRegions 根节点、阅读顺序
Next.js	nextjs/visual-editing.md	Layout 根节点、受限的编辑器加载器、组件映射、基础设施检查清单、Next.js 检查清单项
Next.js	nextjs/visual-editing-reference.md	Next.js 的差异：客户端安全的注册组件、路由器钩子、MDX 正文
Next.js	nextjs/troubleshooting.md	Next.js 特有问题症状 → 修复方案

脚本：

脚本	用途
scripts/setup-editable-regions-astro.sh	仅限 Astro。 安装软件包、接入 Astro 集成，并创建 registerComponents.ts 存根文件。Hugo、Eleventy 和 Next.js 无需脚本——请参阅各自的 visual-editing.md

其他技能：

技能	何时阅读
make-site-multilingual	网站为多语言网站。翻译键（data-rosey）必须放在区域容器上，而非区域内部；组件区域需要显式传递键
cloudcannon-dev-server	区域编写完成后，用户需要试用时阅读。启动本地 CloudCannon，并在用户编辑时重新构建

快速参考

区域类型	用途	关键属性
text	行内富文本	data-editable="text" data-prop data-type
image	图片选择器	data-editable="image" data-prop（或 data-prop-src/data-prop-alt）
array	列表增删改查	容器上的 data-editable="array" data-prop
array-item	每个列表项	每个子项上的 data-editable="array-item"
component	重新渲染的版块	data-editable="component" data-component data-prop
source	模板中的硬编码文本	data-editable="source" data-path data-key

经验法则： 当版块包含条件元素、样式绑定或派生内容时，使用 component。在组件内部嵌套基本类型（text、image、array），以支持行内编辑。

工作流

1. 设置 — 按照对应 SSG 的 visual-editing.md 安装并接入集成（Astro：设置脚本 + 条件导入 registerComponents；Hugo：导入模块 + editable-regions 部分模板；Eleventy：插件 + 在 Liquid 站点中条件导入 register-components.js，Nunjucks 站点无需操作；Next.js：在 app/layout.tsx 或 pages/_app 中添加根级 EditableRegions + 条件导入 registerComponents）
2. 盘点 — 记录每个关键页面上所有可见版块的处理方式（visual-editing.md § 版块盘点）
3. 实现 — 按版块逐一处理，根据盘点结果添加可编辑属性
4. 验证 — 按照 visual-editing.md 中的完整性检查清单检查，然后完成对应 SSG 的额外检查项

清单强化

SSG 专用工作流文档包含详细的完整性清单。这些清单不是可选项。

• 开始前先阅读清单，以明确目标
• 只有在核实所有清单项后，工作才算完成
• 普查中的每个部分都必须包含可编辑区域，或附有 sidebar-only 说明，并给出具体的技术原因
• 不要在数组中的各项尚无嵌套可编辑区域时就将数组标记为已完成——仅有 CRUD 控件并不足够

常见错误

借口	实际情况
“这页有可编辑文本就够了”	图片、数组和组件也要检查。只处理文本就等于工作只完成了一半。
“这个组件太复杂，不适合设置可编辑区域”	如果它会从内容集合中渲染数据，就应该可编辑。简化组件，或将其包装在 editable-component 中，以便在侧边栏中重新渲染。
“页脚/导航不需要可编辑区域”	共享局部模板需要由数据文件支持的可编辑区域。每个可见部分都需要相应处理。
“数组项只需要添加/删除控件”	如果数组项没有嵌套的文本/图片可编辑区域，编辑者就无法直接编辑字段值。
“我之后再注册组件”	集成无法解析的组件就无法重新渲染。开发时就把它们接好（Astro：注册；Hugo：将其设为局部模板；Eleventy：将其设为 Liquid include；Next.js：将其添加到 componentMap.ts）。
“不需要源代码可编辑区域——这段文本很少变化”	如果内容可见，就应该可编辑——但具体_机制_取决于页面。共享 UI 使用数据文件；页面文本请参阅 visual-editing-reference.md § 何时使用源代码可编辑区域。
“我会为页面上的所有硬编码字符串添加源代码可编辑区域”	页面构建器是默认方式；源代码可编辑区域是例外，适用于结构由开发者维护的一次性页面。如果编辑者需要添加、删除或重新排列页面区块，请使用页面构建器。请参阅 visual-editing-reference.md § 何时使用源代码可编辑区域。