可编辑区域

图像编辑 云冈 CMS (中文(简体) ).

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

目录

• 安装
• 快速启动
  • 天体
  • 十一号
  • 乌戈
  • 反应
  • 丝绒
  • 阴道
  • 下一个.js
  • 斯维尔特基特
  • 坚果
• 可编辑区域如何工作
  • 定义可编辑区域
  • 向可编辑区域传递值
• 价值区域
  • 文本
  • 图像
• 结构区域
  • 构成部分
  • 阵列和阵列项目
  • 道具选择者如何组成
• 页面大楼
• 参考外部数据
• 文学道具
• 来源区域
  • 他们如何工作
  • 限制
  • 什么时候用
  • 选项

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

• 天体
• 十一号。 。 。 .
• 乌戈。 。 。 .

安装

从 npm 安装软件包 :

npm install @cloudcannon/editable-regions

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

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

快速启动

天体

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

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

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

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

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

registerAstroComponent("cta", CTA);

从您的布局装入脚本 :

<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 组件, 请将匹配的副作用渲染器导入到相同的注册文件中 :

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

然后标记您的模板 :

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

十一号

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

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

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

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

在普通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(自动从您真实的"十一"配置中取出)以及包含模板的捆绑。 装入您的布局 :

<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>

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

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

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

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

乌戈

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

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

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

{{ partial "editable-regions" . }}

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

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

反应

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

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

registerReactComponent("cta", CTA);

然后标记您的模板 :

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

丝绒

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

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

registerSvelteComponent("cta", CTA);

然后标记您的模板 :

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

阴道

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

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

registerVueComponent("cta", CTA);

然后标记您的模板 :

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

下一个.js

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

// 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 :

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

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

// 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/ 不需要服务器运行时间 :

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

export default nextConfig;

斯维尔特基特

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

<!-- 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>

然后标记您的模板 :

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

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

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

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

export default config;

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

坚果

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

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

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

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

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

然后标记您的模板 :

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

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

// 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数字 :

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

可编辑区域如何工作

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

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

定义可编辑区域

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

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

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

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

向可编辑区域传递值

每个可编辑区域通过一个区域获得编辑值 data-prop 选择器。 选择者指向您的数据, 相对于当前文件的根( 通常是其前题) 或 最近的可编辑祖先。区域会解决选择器和重交的值变化;编辑通过同一选择器回写.

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

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

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

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

价值区域

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

文本

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

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

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

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

编辑文件内容

如果您想要编辑的元素是文件的正文内容( Markdown/HTML 内容而不是前题密钥), 您可以使用特殊 @content 语法( 见 参考外部数据 更多信息).

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

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

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

选项

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

图像

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

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

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

<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>数字 :

<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,其值只应包含 src, (中文(简体) ), alt,以及 title 密钥; 其它任何东西都会产生一个错误卡, 建议您删除额外的绑定值 .

结构区域

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

构成部分

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

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

选项

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

阵列和阵列项目

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

<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,每个项目由该组件提供。 创建一个新项目作为光阵列项目,注册组件仅从项目数据中产生;不需要模板标记.

<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 每个新项目的蓝图:

<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 和组件名称;见 页面结构 下面是一个完整的设置。 创建一个新项目,作为光子阵列项目,其组件使其:

<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的倒置.

<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-prop 选择器是相对于最近的可编辑祖先的值。 链从页上起下:

<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" 与基础文件相对。 这也是为什么 最佳做法是增加 " 家长优先 " 的区域: 在一个阵列或组件内嵌入的区域,在祖先存在之前无法解决其选择器.

页面大楼

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

<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>

前题有:

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

<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正文上获得丰富的文本编辑器——见 编辑文件内容 详情和实例.
• 在一个不合格的选择者之后 @ 参考文献(例如:. @file[about.md].seo.title继续到已解决对象.

文学道具

对于根本不存在于任何文件中的值, data-literal-prop-* 属性将字面值传递给一个区域。 属性后缀是值在下方传递的名称(参见 将数值移入可编辑区域:

<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 的值作为结构值传递 :

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

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

来源区域

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

他们如何工作

<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可以编辑,而无需围绕数据文件调整你的模板.

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

选项