# @cloudcannon/editable-regions 中文文档

规范地址：https://npmcn.com/package/%40cloudcannon/editable-regions/

版本：0\.0\.22
npm 元数据更新时间：2026-10-15T01:12:43.714Z
中文译文更新时间：2026-11-10T02:44:56.187Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cloudcannon/editable-regions
原文对照：https://npmcn.com/package/%40cloudcannon/editable-regions/?lang=original
项目主页：https://github.com/CloudCannon/editable-regions#readme
源码仓库：https://github.com/CloudCannon/editable-regions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：374 kB，104 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：1 个
- 首次发布：2025-10-07T00:46:28.489Z
- 最新版本发布：2026-10-15T01:12:43.273Z
- 近 30 天下载量：12538（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 19 个）

## 中文简介

CloudCannon CMS的视觉编辑.

## 安装

```sh
npm install @cloudcannon/editable-regions
```

也可以使用：`pnpm add @cloudcannon/editable-regions`、`yarn add @cloudcannon/editable-regions`、`bun add @cloudcannon/editable-regions`

## README

# 可编辑区域

图像编辑 [云冈](https://cloudcannon.com/) CMS (中文(简体) ).

[![version badge](https://img.shields.io/npm/v/@cloudcannon%2Feditable-regions?logo=npm)](https://www.npmjs.com/package/@cloudcannon%2Feditable-regions)

可编辑区域允许您标记带有属性(或网络组件)的 HTML 输出, 向 CloudCannon 的可视化编辑器精确显示可编辑的内容: 文本、 图像、 阵列、 组件和硬码源标记 。 编辑重新将预览直播,并将您的更改写回结构化的数据或源文件.

## 目录

-   [安装](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-installation)
-   [快速启动](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-quickstart)
    -   [天体](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-astro)
    -   [十一号](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-eleventy)
    -   [乌戈](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-hugo)
    -   [反应](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-react)
    -   [丝绒](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-svelte)
    -   [阴道](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-vue)
    -   [下一个.js](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-nextjs)
    -   [斯维尔特基特](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-sveltekit)
    -   [坚果](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-nuxt)
-   [可编辑区域如何工作](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-how-editable-regions-work)
    -   [定义可编辑区域](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-defining-editable-regions)
    -   [向可编辑区域传递值](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-passing-values-to-editable-regions)
-   [价值区域](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-value-regions)
    -   [文本](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-text)
    -   [图像](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-image)
-   [结构区域](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-structural-regions)
    -   [构成部分](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-components)
    -   [阵列和阵列项目](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-arrays-and-array-items)
    -   [道具选择者如何组成](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-how-prop-selectors-compose)
-   [页面大楼](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-page-building)
-   [参考外部数据](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-referencing-external-data)
-   [文学道具](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-literal-props)
-   [来源区域](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-source-regions)
    -   [他们如何工作](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-how-they-work)
    -   [限制](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-limitations)
    -   [什么时候用](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-when-to-use-them)
    -   [选项](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-options-4)

关于特定集成设置和选项检查,专用文件页:

-   [天体](https://npmcn.com/package/%40cloudcannon/editable-regions/docs/astro.md)
-   [十一号](https://npmcn.com/package/%40cloudcannon/editable-regions/docs/eleventy.md)。 。 。 .
-   [乌戈](https://npmcn.com/package/%40cloudcannon/editable-regions/docs/hugo.md)。 。 。 .

## 安装

从 npm 安装软件包 :

```sh
npm install @cloudcannon/editable-regions
```

对于雨果站点,在被固定的版本中安装模块:

```sh
hugo mod get github.com/CloudCannon/editable-regions@<version>
```

## 快速启动

### 天体

添加集成到 `astro.config.mjs`数字 :

```js
import { defineConfig } from "astro/config";
import editableRegions from "@cloudcannon/editable-regions/astro-integration";

export default defineConfig({
  integrations: [editableRegions()],
});
```

创建一个注册脚本,用于导入和注册您想要运行的每个组件 :

```js
// src/scripts/register-components.js
import { registerAstroComponent } from "@cloudcannon/editable-regions/astro";
import CTA from "../components/CTA.astro";

registerAstroComponent("cta", CTA);
```

从您的布局装入脚本 :

```html
<script>
  // Check that the page is loaded in CloudCannon before loading your Editable Components
  if (window.inEditorMode) {
    import("../scripts/register-components.js").catch((error) => {
      console.warn("Failed to load CloudCannon component registration:", error);
    });
  }
</script>
```

如果您的 Astro 组件包含 React, Svelte, 或 Vue 组件, 请将匹配的副作用渲染器导入到相同的注册文件中 :

```js
import "@cloudcannon/editable-regions/astro-react-renderer";
import "@cloudcannon/editable-regions/astro-svelte-renderer";
import "@cloudcannon/editable-regions/astro-vue-renderer";
```

然后标记您的模板 :

```astro
<h1 data-editable="text" data-prop="title">{title}</h1>
<editable-component data-component="cta" data-prop="cta">
  <CTA {...cta} />
</editable-component>
```

### 十一号

将插件添加到 `eleventy.config.mjs`数字 :

```js
import editableRegions from "@cloudcannon/editable-regions/eleventy";

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(editableRegions);

  return {
    dir: { input: "src", includes: "_includes", output: "_site" },
  };
}
```

在普通JS配置上,使用需要替换:

```js
const editableRegions = require("@cloudcannon/editable-regions/eleventy");

module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(editableRegions);

  return {
    dir: { input: "src", includes: "_includes", output: "_site" },
  };
};
```

每次构建后, 插件都会发出 `register-components.js` 输入输出目录、包含客户端液体引擎的捆绑、过滤器/短码/tag(自动从您真实的"十一"配置中取出)以及包含模板的捆绑。 装入您的布局 :

```html
<script>
  // Check that the page is loaded in CloudCannon before loading your Editable Components
  if (window.inEditorMode) {
    import("/register-components.js").catch((error) => {
      console.warn("Failed to load CloudCannon component registration:", error);
    });
  }
</script>
```

插件自动将您的液体登记为组件 .

```liquid
<div data-editable="component" data-component="author-card" data-prop-author-name="authorName">
  {% include "author-card", author-name: authorName %}
</div>
```

插件还注册一个 `includeWith` 用于将道具对象扩散到一个对象的标记包括:

```liquid
<div data-editable="component" data-component="post-meta" data-prop="postMeta">
  {% includeWith "post-meta", postMeta %}
</div>
```

### 乌戈

将软件包安装为雨果模块 :

```toml
# hugo.toml
[module]
  [[module.imports]]
    path = "github.com/CloudCannon/editable-regions"
```

将部分包含在您的网站上 `<head>`数字 :

```html
{{ partial "editable-regions" . }}
```

模块自动将雨果部分注册为组件 .

```html
<div data-editable="component" data-component="card" data-prop="card">
  {{- partial "card" .Params.card -}}
</div>
```

### 反应

对于独立的React SPA,请在客户端入口注册您的组件:

```js
// src/index.js
import { registerReactComponent } from "@cloudcannon/editable-regions/react";
import CTA from "./components/CTA.jsx";

registerReactComponent("cta", CTA);
```

然后标记您的模板 :

```jsx
<editable-component data-component="cta" data-prop="cta">
  <CTA {...props.cta} />
</editable-component>
```

### 丝绒

对于独立的Svelte SPA,请在客户端入口注册您的组件:

```js
// src/index.js
import { registerSvelteComponent } from "@cloudcannon/editable-regions/svelte";
import CTA from "./components/CTA.svelte";

registerSvelteComponent("cta", CTA);
```

然后标记您的模板 :

```svelte
<editable-component data-component="cta" data-prop="cta">
  <CTA {...cta} />
</editable-component>
```

### 阴道

对于独立的Vue SPA,请在客户端入口注册您的组件:

```js
// src/index.js
import { registerVueComponent } from "@cloudcannon/editable-regions/vue";
import CTA from "./components/CTA.vue";

registerVueComponent("cta", CTA);
```

然后标记您的模板 :

```vue
<editable-component data-component="cta" data-prop="cta">
  <CTA v-bind="cta" />
</editable-component>
```

### 下一个.js

在 Next.js app中,将页面内容包入 `EditableRegions` 根组件。 可编辑 内部区域只有在应用完成水分后才能连接:

```jsx
// app/layout.js
import { EditableRegions } from "@cloudcannon/editable-regions/react";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <EditableRegions tag="main">{children}</EditableRegions>
      </body>
    </html>
  );
}
```

然后标记您的模板——页面保留服务器组件,区域标记为平面 HTML :

```jsx
// app/page.js
export default function Page() {
  return (
    <h1>
      <editable-text data-prop="title">Hello from Next.js</editable-text>
    </h1>
  );
}
```

从一个客户端组件注册您的组件, 闸门打开 `window.inEditorMode` 所以代码 远离生产捆绑:

```jsx
// app/components/CloudCannon.js
"use client";

import { useEffect } from "react";
import { registerReactComponent } from "@cloudcannon/editable-regions/react";
import CTA from "./CTA.jsx";

export default function CloudCannon() {
  useEffect(() => {
    if (window.inEditorMode) {
      registerReactComponent("cta", CTA);
    }
  }, []);

  return null;
}
```

对于完全静态的站点,导出页面为平版 HTML ——该建筑将静态站点写入 `out/` 不需要服务器运行时间 :

```js
// next.config.js
const nextConfig = {
  output: "export",
};

export default nextConfig;
```

### 斯维尔特基特

在 SvelteKit 应用程序中,将路由页面包裹在 `EditableRegions` 根组件在根中 设置。 它内部的可编辑区域只有在应用程序完成水分后才能连接 :

```svelte
<!-- src/routes/+layout.svelte -->
<script>
  import { onMount } from "svelte";
  import {
    EditableRegions,
    registerSvelteComponent,
  } from "@cloudcannon/editable-regions/svelte";
  import CTA from "$lib/components/CTA.svelte";

  let { children } = $props();

  onMount(() => {
    if (window.inEditorMode) {
      registerSvelteComponent("cta", CTA);
    }
  });
</script>

<EditableRegions tag="main">
  {@render children()}
</EditableRegions>
```

然后标记您的模板 :

```svelte
<!-- src/routes/+page.svelte -->
<h1>
  <editable-text data-prop="title">Hello from SvelteKit</editable-text>
</h1>
```

对于一个完全静态的站点,使用静态适配器并提前回复每条路线——建筑写道: 静态站点到 `build/`数字 :

```js
// svelte.config.js
import adapter from "@sveltejs/adapter-static";

const config = {
  kit: {
    adapter: adapter(),
  },
};

export default config;
```

```js
// src/routes/+layout.js
export const prerender = true;
```

### 坚果

在 Nuxt 应用程序中, 将路由页面包入 `EditableRegions` 布局中的根组件. 它内部的可编辑区域只有在应用程序完成水分后才能连接 :

```vue
<!-- app/layouts/default.vue -->
<script setup>
import { EditableRegions } from "@cloudcannon/editable-regions/vue";
</script>

<template>
  <EditableRegions tag="main">
    <slot />
  </EditableRegions>
</template>
```

告诉Vue治疗 `editable-*` 元素作为原生元素而不是组件:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith("editable-"),
    },
  },
});
```

然后标记您的模板 :

```vue
<!-- app/pages/index.vue -->
<template>
  <h1>
    <editable-text data-prop="title">Hello from Nuxt</editable-text>
  </h1>
</template>
```

从一个客户端插件注册您的组件, 闸机已打开 `window.inEditorMode` 所以,代码保留 生产捆绑:

```ts
// app/plugins/cloudcannon.client.ts
import { registerVueComponent } from "@cloudcannon/editable-regions/vue";
import CTA from "../components/CTA.vue";

export default defineNuxtPlugin(() => {
  if (window.inEditorMode) {
    registerVueComponent("cta", CTA);
  }
});
```

对于一个完全静态的站点,配置硝基通过从索引页上爬行来预发站点, 然后用 `nuxt generate` ——建筑将静态站点写入 `.output/public`数字 :

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    prerender: {
      crawlLinks: true,
      routes: ["/"],
    },
  },
});
```

## 可编辑区域如何工作

一个可编辑区域是您页面中的一块,视觉编辑器可以就地编辑. 当您在视觉编辑器中加载页面时, CloudCannon 将您的元素水化为可编辑区域 。 在 CloudCannon 之外, 您的元素是纯 HTML ; 您的用户会看到您所写的标记 .

可编辑区域可以编辑您 CloudCannon 站点中配置的任何结构化数据, 包括您的页面前题和内容, 您的数据集以及您的收藏 .

### 定义可编辑区域

您通过在已有元素中添加 HTML 属性, 或通过在等同的 Web 组件中包裹内容来定义其中之一 :

| 属性 | 网络组件 |
| --- | --- |
| `data-editable="text"` | `<editable-text>` |
| `data-editable="image"` | `<editable-image>` |
| `data-editable="source"` | `<editable-source>` |
| `data-editable="array"` | `<editable-array>` |
| `data-editable="array-item"` | `<editable-array-item>` |
| `data-editable="component"` | `<editable-component>` |

两种形式是等同的。 数据属性在将可编辑区域附加到现有的标记上时是有用的,而当没有现有的标记来附加一个属性或者没有直接访问标记时,网页组件是有用的.

```astro
<h1 data-editable="text" data-prop="title">{title}</h1>

<editable-image data-prop-src="src">
    <MyFigureComponent src={src} />
</editable-image>
```

### 向可编辑区域传递值

每个可编辑区域通过一个区域获得编辑值 `data-prop` 选择器。 选择者指向您的数据, 相对于当前文件的根( 通常是其前题) 或 [最近的可编辑祖先](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-how-prop-selectors-compose)。区域会解决选择器和重交的值变化;编辑通过同一选择器回写.

```astro
<h4 data-editable="text" data-prop="name">{testimonial.name}</h4>
```

区域也可以通过 `data-prop-*` 属性。 属性后缀是值被传递到下方的名称,属性值是第二个选择器:

```astro
<img
  data-editable="image"
  data-prop-src="heroImage"
  data-prop-alt="heroImageAlt"
/>
```

在此图像区域得到两个值: `src` 从 `heroImage`,以及 `alt` 从 `heroImageAlt`。每个区域期望的值的名称和类型列于以下选项部分.

## 价值区域

值区域编辑一个值. 它们是你页面的叶子 不允许其他可编辑区域在其中筑巢.

### 文本

添加 `data-editable="text"` (单位:千美元) `data-prop` 命名要编辑的结构化数据密钥 :

```astro
<h4 data-editable="text" data-prop="name">{testimonial.name}</h4>
```

或者用那个 `editable-text` 网络组件 :

```astro
<h4><editable-text data-prop="name">{testimonial.name}</editable-text></h4>
```

#### 编辑文件内容

如果您想要编辑的元素是文件的正文内容( Markdown/HTML 内容而不是前题密钥), 您可以使用特殊 `@content` 语法( 见 [参考外部数据](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-referencing-external-data) 更多信息).

```astro
<div data-editable="text" data-prop="@content">
    <Content />
</div>
```

默认 `@content` 指的是当前页面的内容。 如果您想要引用另一页面的内容, 您可以将其与其它外部数据选择器合并, 如 `@file`。 。 。 .

```astro
<div data-editable="text" data-prop="@file[README.md].@content">
    <Content />
</div>
```

#### 选项

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `data-prop` | 选择器 | 对 | 要编辑的数据,所选值必须是字符串. |
| `data-type` | `"span"` | `"text"` | `"block"` | 没有 | 控制编辑表面 : `span` 编辑纯文本, `text` 编辑段落级别丰富的文本,以及 `block` 编辑多段丰富的文本. |
| `data-defer-mount` | 布尔 | 没有 | 设定时,编辑器只初始化了第一次被点击的区域,而不是在页面负载上. 默认为 `false`。 。 。 . |

这个 `data-type` 默认从编辑的值中计算: 区域编辑内容丰富的文本-源区域, `@content`,或配置了丰富文本输入的值——默认为 `block` 或者说 `text`默认值为 `span`如果该值没有配置输入, CloudCannon 将返回到主机元素的家族(例如 an) `h2` 表现为 `text`页:1 `div` 作为 `block`) (中文(简体) ).

### 图像

添加 `data-editable="image"` (或围绕) `<img>` 元素并绑定其属性 `data-prop-*`数字 :

```astro
<img
  data-editable="image"
  data-prop-src="heroImage"
  data-prop-alt="heroImageAlt"
  data-prop-title="heroImageTitle"
  src={heroImage}
  alt={heroImageAlt}
  title={heroImageTitle}
/>
```

或者用那个 `editable-image` 网络组件 :

```astro
<editable-image data-prop-src="heroImage" data-prop-alt="heroImageAlt">
  <img src={heroImage} alt={heroImageAlt} />
</editable-image>
```

该区域必须包含 `<img>` 要素,无论是作为儿童还是作为要素本身.

单击图像区域打开 _编辑图像_ visual Editor 中的面板: 从您的机器上传, 从仓库或 DAM 中选择一个已有的文件, 并编辑 alt/ title 细节 .

#### 编辑图片元素

图像区域也可以覆盖 `<picture>` 键。 将区域属性设置在 `<picture>`; 当图像改变时, CloudCannon 更新预览 URL `<source>` 要素以及 `<img>`数字 :

```astro
<picture data-editable="image" data-prop-src="heroImage" data-prop-alt="heroImageAlt">
  <source srcset={heroImageAvif} type="image/avif" />
  <img src={heroImage} alt={heroImageAlt} />
</picture>
```

#### 选项

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `data-prop` | 选择器 : 字符串, 备选案文 ? : 字符串, 标题 ? : 字符串 | 没有 | 选择一个持有图像细节的对象。 每个图像属性绑定在 `<selector>.src`, (中文(简体) ), `<selector>.alt`,以及 `<selector>.title`。 。 。 . |
| `data-prop-src` | 选择器 | 没有 | 为图像源选择数据. |
| `data-prop-alt` | 选择器 | 没有 | 为备选案文文本选择数据. |
| `data-prop-title` | 选择器 | 没有 | 为标题文本选择数据. |

需要至少一个选择器 。 当将对象绑定时 `data-prop`,其值只应包含 `src`, (中文(简体) ), `alt`,以及 `title` 密钥; 其它任何东西都会产生一个错误卡, 建议您删除额外的绑定值 .

## 结构区域

结构区域定义页面的形状,而不是单一的值。 与可编辑价值区域不同的是,可编辑结构区域可以让其他可编辑区域嵌入其中并相互作曲.

### 构成部分

一个组成区域将一块标记绑在 **登记** 组件,编辑器可以随着数据的变化而重新发送.

```astro
<editable-component data-component="cta" data-prop="cta">
  <CTA {...cta} />
</editable-component>
```

#### 选项

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `data-component` | 字符串 | 对 | 该组件的密钥登记在下(如在雨果,部分路径加扩展,如:. `card.html`) (中文(简体) ). |
| `data-prop` | 选择器 | 没有 | 数据作为道具传递给组件. |

在组件自身的文件中,为其文本,图像和嵌入式阵列添加更多可编辑区域. 当用户在Visual Editor中编辑组件数据时,已注册的渲染器会重新发送组件并更新结果到位.

### 阵列和阵列项目

一个阵列区域定义了从重复元素列表中构建的标记区域. 数组项目区域定义该数组中单个元素的边界。 阵列和阵列项区域总是作为一对进行工作,作为拇指规则,它们将被定位在您模板中循环的任意一面.

```astro
<ul data-editable="array" data-prop="testimonials">
  {testimonials.map((testimonial) => (
    <li data-editable="array-item">
      <h4 data-editable="text" data-prop="name">{testimonial.name}</h4>
      <p data-editable="text" data-prop="quote">{testimonial.quote}</p>
    </li>
  ))}
</ul>
```

#### 向数组添加项目

当用户在"视觉编辑器"中添加一个项目时,编辑器必须发明新项目的标记. 这取决于阵列的设置方式:

##### 具有组件的同源数组

如果数组将一个组件命名为 `data-component`,每个项目由该组件提供。 创建一个新项目作为光阵列项目,注册组件仅从项目数据中产生;不需要模板标记.

```astro
<ul data-editable="array" data-prop="testimonials" data-component="testimonial">
  {testimonials.map(() => (
    <li data-editable="array-item" data-component="testimonial">
      <Testimonial />
    </li>
  ))}
</ul>
```

##### 带有模板的同源数组

A 类 `<template>` 矩阵区域内的元素是新项目的蓝图。 没有模板 `data-id` 每个新项目的蓝图:

```html
<ul data-editable="array" data-prop="features">
  <template>
    <li>
      <h4 data-editable="text" data-prop="title"></h4>
      <p data-editable="text" data-prop="description"></p>
    </li>
  </template>
</ul>
```

多根模板自动被包裹在一个 `editable-array-item`。既无模板,也无组件,编辑器会复制一个已存在的项目的标记;如果阵列是空的,也没有,则会获得一个出错卡来命名要添加的内容.

##### 带有 id 密钥和组件密钥的异质数组

当项目有不同的形状时,每个项目都命名自己的组件. 数组的 `data-id-key` 财务报告和审定财务报表 `data-component-key` 告诉编辑器哪个项键持有 id 和组件名称;见 [页面结构](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-page-building) 下面是一个完整的设置。 创建一个新项目,作为光子阵列项目,其组件使其:

```html
<main data-editable="array" data-prop="contentBlocks" data-component-key="_name">
  <section data-editable="array-item" data-id="HeroBlock" data-component="HeroBlock">
    <h2 data-editable="text" data-prop="title"></h2>
  </section>
</main>
```

每个项目 `_name` 值既用作其代号,也用作其组成部分,因此一个新项目命名为 `HeroBlock` 由注册人提供 `HeroBlock` 组件.

##### 带有 id 密钥和模板的异质数组

一个按键 `<template data-id="…">` 是带有此标识的新项目的蓝图;每个新项目的形状从正确的模板中选择。 此项的ID来自数组 `data-id-key`; 平原 `<template>` (无) `data-id`)是无按键模板的id的倒置.

```html
<ul data-editable="array" data-prop="blocks" data-id-key="type">
  <template data-id="hero">
    <section class="hero">
      <h2 data-editable="text" data-prop="title"></h2>
    </section>
  </template>
  <template data-id="stats">
    <section class="stats"><!-- ... --></section>
  </template>
</ul>
```

#### 特殊道具

两个选择器由数组结构本身提供,而不是由您的数据提供:

-   `@length` ——由阵列区域提供;项目计数.
-   `@index` ——由每个阵列项提供;项目的位置.

和任何其他选择者一样参考 `data-prop="@length"` 或者说 `data-prop="@index"`。 。 。 .

#### 选项

阵列区域 :

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `data-prop` | 选择器 | 对 | 要编辑的阵列 . |
| `data-id-key` | 字符串 | 没有 | 持有每个项目唯一标识符的项目密钥 。 见 [页面结构](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-page-building)。 。 。 . |
| `data-component` | 字符串 | 没有 | 从组件键中生成无法解析组件的已注册组件 . |
| `data-component-key` | 字符串 | 没有 | 包含注册部件名称的项目密钥以制成每个项目. |
| `data-direction` | `"row"` | `"column"` | `"row-reverse"` | `"column-reverse"` | 没有 | 物品的行走方向,所以物品控制和拖放工作正确. 当元素是弹性容器时默认其弹性方向, 否则 `column`。 。 。 . |

矩阵项目区域 :

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `data-id` | 字符串 | 没有 | 用于匹配项目到 `<template>` 当项目移动时,设计并调节 DOM。 通常来自数组 `data-id-key`。 。 。 . |
| `data-component` | 字符串 | 没有 | 用于制作此项目的已登记部件。 通常来自数组 `data-component-key`。 。 。 . |

阵列区域指定每个项目 `data-prop` (物品的指数)在水合时;你没有自己设置. 阵列项区域必须是阵列元素的即时子——使对子尽可能相近.

在区域到位后,编辑器可以添加,复制,删除,重排,并拖动项目——同时进行预览更新直播.

### 道具选择者如何组成

每个 `data-prop` 选择器是相对于最近的可编辑祖先的值。 链从页上起下:

```astro
<main data-editable="array" data-prop="blocks">
  {blocks.map((block, i) => (
    <section data-editable="array-item">
      <h2 data-editable="text" data-prop="title">{block.title}</h2>
      <img data-editable="image" data-prop-src="image" src={block.image} />
    </section>
  ))}
</main>
```

阅读区域内部:

-   阵列区域 `blocks` 整个阵列.
-   每个阵列项都会递出一个条目: 数组给出其项选择器 `blocks.0`, (中文(简体) ), `blocks.1`,, , , , , , , ,
-   项目中的文本区域解析 `title` 与此值相对应: `blocks.0.title`。 。 。 .

写作逆行行同一行. 编辑 `<h2>` 发送更改事件 `title`; 每一个祖先会预先使用自己的部分,直到根区域执行 `blocks.0.title = "New value"` 与基础文件相对。 这也是为什么 [最佳做法是增加 " 家长优先 " 的区域](https://cloudcannon.com/documentation/developer-guides/set-up-visual-editing/an-overview-of-editable-regions/): 在一个阵列或组件内嵌入的区域,在祖先存在之前无法解决其选择器.

## 页面大楼

将不同的数组设置与已注册的组件合并,可以给您页面构建:数组中的每个项目都是内容块,编辑器可以添加,重排,并编辑块来构成页面.

```astro
<main
  data-editable="array"
  data-prop="contentBlocks"
  data-id-key="_name"
  data-component-key="_name"
>
  {contentBlocks.map((block) => {
    const Component = components[block._name];
    return (
      <section data-editable="array-item" data-id={block._name} data-component={block._name}>
        <Component {...block} />
      </section>
    );
  })}
</main>
```

前题有:

```yaml
contentBlocks:
  - _name: HeroBlock
    title: We're on a mission
    description: Lorem ipsum dolor sit amet…
  - _name: StatsBlock
    stats:
      - figure: $200m
        text: Venture capital raised
      - figure: 40+
        text: Amazing team members
  - _name: ContactBlock
    text: Want to get in contact with us?
    button: Click here
```

注册每个块组件,编辑器可以添加任何块类型,重新排序,并编辑每个块的内容. 保存中 `_name` 由于id和组件键都是常见的和方便的,但是它们可以是独立的键. 如果两个密钥相同, 您只需要指定 `data-component-key` 财务报告和审定财务报表 `data-id-key` 将默认为同一值.

## 参考外部数据

`data-prop` 选择器相对当前文件(或最近的可编辑祖先). 要指向生活在别处的数据,请用 `@` 参考文献 :

| 参考文献 | 决定 |
| --- | --- |
| `@collections[blog]` | 这个 `blog` 收藏——可直接用作数组区域值 |
| `@data[nav]` | 这个 `nav` 数据集(在页面外管理的数据文件) |
| `@file[about.md]` | 另一个文件的结构化数据 |
| `@file[about.md].@content` | 另一个文件的内容 |
| `@content` | 当前文件的内容 |

```astro
<ul data-editable="array" data-prop="@collections[blog]">
  <li data-editable="array-item">
    <h4 data-editable="text" data-prop="title" />
  </li>
</ul>
```

注释:

-   `@content` 在文本区域上,您可以在文件的Markdown/HTML正文上获得丰富的文本编辑器——见 [编辑文件内容](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-editing-file-content) 详情和实例.
-   在一个不合格的选择者之后 `@` 参考文献(例如:. `@file[about.md].seo.title`继续到已解决对象.

## 文学道具

对于根本不存在于任何文件中的值, `data-literal-prop-*` 属性将字面值传递给一个区域。 属性后缀是值在下方传递的名称(参见 [将数值移入可编辑区域](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-passing-values-to-editable-regions):

```html
<editable-component
  data-component="author-card"
  data-literal-prop-name="C. Kent"
  data-literal-prop-role="Support engineer"
/>
```

给 `author-card` 收到组件 `{ name: "C. Kent", role: "Support engineer" }`。 。 。 .

解析为 JSON 的值作为结构值传递 :

```html
<editable-component
  data-component="author-card"
  data-literal-prop-social='{"twitter": "@cloudcannon"}'
/>
```

在这里,组件收到 `{ social: { twitter: "@cloudcannon" } }`。不解析为 JSON 的值会作为普通字符串传递.

## 来源区域

全部编辑值和结构区域 **结构化数据**,而您的模板则重新提交。 源区域是例外:它们编辑 **模板文件本身的硬编码标记**。 。 。 .

### 他们如何工作

```astro
<p
  data-editable="source"
  data-path="src/pages/about.astro"
  data-key="about-intro"
>
  We've been building websites since 2014.
</p>
```

当编辑器中的文件更改时,运行时间会获取文件的原始来源,通过查找元素 `data-key` 属性,然后在源文件中直接编辑其内容.

### 限制

-   **只有静态标记.** 区域编辑文件中的字面HTML. 如果元素含有任何调试, 您必须配置匹配的片段, 否则编辑器无法安全解析 .
-   **`data-key` 文件内的值必须是独一无二的**,属性必须活入已建输出.
-   由于源可编辑区域直接编辑源,一个区域的编辑会更新文件被引用的所有其他地点. 任何未被配置为片段的动态内容都会被以静态内容覆盖.

### 什么时候用

当文本后面没有结构化的数据密钥时使用源区域 。 例如:登陆页和有硬码副本的独立模板,或呼叫到动作被烘烤成布局. 是逃生舱门使得硬码的HTML可以编辑,而无需围绕数据文件调整你的模板.

狦 _能够_ 将数值移动到前置物质或数据文件中, 选择文本区域: 数据驱动区域重新将您的内容保存在内容所属位置 .

### 选项

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `data-path` | 字符串 | 对 | 模板文件文本存在,相对于站点根. 领先 `/` 是可选的。 这是文件路径, 不是选择器 . |
| `data-key` | 字符串 | 对 | 在文件中识别此区域的名称 。 一定是独一无二的 `data-key` 在同一文件中的数值. |
| `data-type` | `"span"` | `"text"` | `"block"` | 没有 | 控制丰富的文本编辑表面,如同 [文本区域](https://npmcn.com/package/%40cloudcannon/editable-regions/#readme-text)。源内容作为 HTML 编辑. |
| `data-input-config` | JSON 对象 | 没有 | 编辑器的内置输入配置,作为JSON对象. 胜过 `data-input`。 。 。 . |
| `data-input` | 字符串 | 没有 | CloudCannon 输入配置中用于解决此区域的弹出, 当 `data-input-config` 没有设定. |

## 常见问题

### @cloudcannon/editable-regions 是什么？

CloudCannon CMS的视觉编辑\.

### 如何安装 @cloudcannon/editable-regions？

在项目目录运行 npm install @cloudcannon/editable-regions，或使用 pnpm add / yarn add / bun add。

### @cloudcannon/editable-regions 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cloudcannon/editable-regions 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cloudcannon/editable-regions 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cloudcannon/editable-regions 可以商用吗？

@cloudcannon/editable-regions 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudcannon/editable-regions 的下载量有多少？

根据 npm 官方下载统计，@cloudcannon/editable-regions 在 2026/10/10 – 2026/11/08 这 30 天内被下载 12,538 次，日均约 418 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cloudcannon/editable-regions 还在维护吗？

最新版本 0\.0\.22 发布于 2026/10/15（26 天前）；至今共发布 24 个版本，其中过去 12 个月发布了 19 个；首次发布于 2025/10/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。