ApostropheCMS & Astro

ApostropheCMS 是一个支持在 Astro 中进行页面内编辑的内容管理系统。

与 Astro 集成

在本节中，你将使用 Apostrophe 集成将 ApostropheCMS 连接到 Astro。

先决条件

要开始，你需要具备以下条件

1. 一个按需渲染的 Astro 项目，已安装 Node.js 适配器并配置了 output: 'server' - 如果你还没有 Astro 项目，我们的安装指南将帮助你快速启动并运行。

2. 一个配置了名为 APOS_EXTERNAL_FRONT_KEY 的环境变量的 ApostropheCMS 项目 - 这个环境变量可以设置为任何随机字符串。如果你还没有 ApostropheCMS 项目，安装指南可以帮助你快速设置一个。我们强烈建议使用 Apostrophe CLI 工具来简化此过程。

设置项目通信

你的 Astro 项目需要设置一个 APOS_EXTERNAL_FRONT_KEY 环境变量，其值与 ApostropheCMS 项目中的值相同，以允许两者之间的通信。这个共享密钥用作验证前端（Astro）和后端（ApostropheCMS）之间请求的方法。

在你的 Astro 项目的根目录中创建一个 .env 文件，并包含以下变量

.env

APOS_EXTERNAL_FRONT_KEY='RandomStrongString'

现在你的根目录应该包含这个新文件

• 目录src/

  • …
• .env
• astro.config.mjs
• package.json

安装依赖

要将 Astro 与你的 ApostropheCMS 项目连接，请使用下面适用于你首选包管理器的命令，在你的 Astro 项目中安装官方的 Apostrophe 集成。

npm

npm install @apostrophecms/apostrophe-astro vite @astro/node

pnpm

pnpm add @apostrophecms/apostrophe-astro vite @astro/node

Yarn

yarn add @apostrophecms/apostrophe-astro vite @astro/node

配置 Astro

在你的 astro.config.mjs 文件中配置 apostrophe-astro 集成和 vite。

以下示例提供了你的 Apostrophe 实例的基本 URL 和项目中文件夹的路径，用于在 ApostropheCMS 小部件和页面模板类型与你的 Astro 项目之间进行映射。它还配置了 Vite 的服务器端渲染。

astro.config.mjs

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import apostrophe from '@apostrophecms/apostrophe-astro';
import { loadEnv } from 'vite';

const env = loadEnv("", process.cwd(), 'APOS');

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone'
  }),
  integrations: [
    apostrophe({
      aposHost: 'https://:3000',
      widgetsMapping: './src/widgets',
      templatesMapping: './src/templates'
    })
  ],
  vite: {
    ssr: {
      // Do not externalize the @apostrophecms/apostrophe-astro plugin, we need
      // to be able to use virtual: URLs there
      noExternal: [ '@apostrophecms/apostrophe-astro' ],
    },
    define: {
      'process.env.APOS_EXTERNAL_FRONT_KEY': JSON.stringify(env.APOS_EXTERNAL_FRONT_KEY),
      'process.env.APOS_HOST': JSON.stringify(env.APOS_HOST)
    }
  }
});

有关完整的配置选项和说明，请参阅 apostrophe-astro 文档。

将 ApostropheCMS 小部件连接到 Astro 组件

ApostropheCMS 小部件是可添加到页面的结构化内容块，例如布局列、图像和文本块。你需要为 Apostrophe 项目中的每个小部件创建一个 Astro 组件，外加一个文件来将这些组件映射到相应的 Apostrophe 小部件。

在 `src/widgets/` 目录下为你的 Astro 组件和映射文件 index.js 创建一个新文件夹。

位于此文件夹中的映射组件通过 Astro.props 接收一个 widget 属性，其中包含小部件的 schema 字段和任何自定义 props。然后这些值可用于页面内编辑。

以下示例展示了一个 RichTextWidget.astro 组件，它访问其对应的 ApostropheCMS 小部件的内容以允许在上下文中进行编辑

src/widgets/RichTextWidget.astro

---
const { widget } = Astro.props;
const { content } = widget;
---
<Fragment set:html={ content }></Fragment>

一些标准的 Apostrophe 小部件，例如图片和视频，需要**占位符**，因为它们默认不包含可编辑的内容。以下示例创建了一个标准的 ImageWidget.astro 组件，它有条件地将 src 值设置为小部件传递的 aposPlaceholder 图像的值、Astro 项目中的备用图像，或内容管理员使用 Apostrophe attachment 辅助函数选择的图像

src/widgets/ImageWidget.astro

---
const { widget } = Astro.props;
const placeholder = widget?.aposPlaceholder;
const src = placeholder ?
  '/images/image-widget-placeholder.jpg' :
  widget?._image[0]?.attachment?._urls['full'];
---
<style>
  .img-widget {
    width: 100%;
  }
</style>
<img class="img-widget" {src} />

更多示例，请参阅 astro-frontend 入门项目的小部件示例。

每个 .astro 组件都必须在 src/widgets/index.js 中映射到相应的核心 Apostrophe 小部件。

下面的示例将前两个组件添加到此文件中

src/widgets/index.js

import RichTextWidget from './RichTextWidget.astro';
import ImageWidget from './ImageWidget.astro';

const widgetComponents = {
  '@apostrophecms/rich-text': RichTextWidget,
  '@apostrophecms/image': ImageWidget
};

export default widgetComponents;

有关标准、专业和自定义项目级小部件的命名约定，请参阅 ApostropheCMS 文档

项目目录现在应如下所示

• 目录src/

  • 目录widgets/

    • index.js
    • ImageWidget.astro
    • RichTextWidget.astro
• .env
• astro.config.mjs
• package.json

添加页面类型

与小部件非常相似，ApostropheCMS 项目中的任何页面类型模板都需要在 Astro 项目中有一个相应的模板组件。你还需要一个文件来将 Apostrophe 页面类型映射到各个组件。

在 `src/templates/` 目录下为你的 Astro 组件和映射文件 index.js 创建一个新文件夹。位于此文件夹中的映射组件通过 Astro.props 接收一个 page 属性，其中包含页面的 schema 字段和任何自定义 props。这些组件还可以访问一个 AposArea 组件来渲染 Apostrophe 区域。

以下示例展示了一个 HomePage.astro 组件，它从其对应的 `home-page` ApostropheCMS 页面类型渲染页面模板，包括一个名为 main 的区域 schema 字段

src/templates/HomePage.astro

---
import AposArea from '@apostrophecms/apostrophe-astro/components/AposArea.astro';
const { page, user, query } = Astro.props.aposData;
const { main } = page;
---

<section class="bp-content">
  <h1>{ page.title }</h1>
  <AposArea area={main} />
</section>

每个 .astro 组件都必须在 src/templates/index.js 中映射到相应的核心 Apostrophe 页面类型。

下面的示例将之前的 HomePage.astro 组件添加到此文件中

src/templates/index.js

import HomePage from './HomePage.astro';

const templateComponents = {
  '@apostrophecms/home-page': HomePage
};

export default templateComponents;

有关模板命名约定，包括特殊页面和 piece 页面类型，请参阅 ApostropheCMS 文档。

项目目录现在应如下所示

• 目录src/

  • 目录widgets/

    • index.js
    • ImageWidget.astro
    • RichTextWidget.astro
  • 目录templates/

    • HomePage.astro
    • index.js
• .env
• astro.config.mjs
• package.json

创建 […slug.astro] 组件并获取 Apostrophe 数据

由于 Apostrophe 负责将 URL 连接到内容，包括动态创建新内容和页面，因此你只需要一个顶级的 Astro 页面组件：[...slug].astro 路由。

以下示例展示了一个最小化的 [...slug].astro 组件

src/pages/[...slug].astro

---
import aposPageFetch from '@apostrophecms/apostrophe-astro/lib/aposPageFetch.js';
import AposLayout from '@apostrophecms/apostrophe-astro/components/layouts/AposLayout.astro';
import AposTemplate from '@apostrophecms/apostrophe-astro/components/AposTemplate.astro';

const aposData = await aposPageFetch(Astro.request);
const bodyClass = `myclass`;

if (aposData.redirect) {
  return Astro.redirect(aposData.url, aposData.status);
}
if (aposData.notFound) {
  Astro.response.status = 404;
}
---
<AposLayout title={aposData.page?.title} {aposData} {bodyClass}>
    <Fragment slot="standardHead">
      <meta name="description" content={aposData.page?.seoDescription} />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <meta charset="UTF-8" />
    </Fragment>
    <AposTemplate {aposData} slot="main"/>
</AposLayout>

有关其他模板选项，包括 AposTemplate 组件中可用的插槽，请参阅 ApostropheCMS 文档。

使用 Astro 和 ApostropheCMS 制作博客

集成设置完成后，你现在可以使用 Astro 和 ApostropheCMS 创建一个博客。你的博客将使用一个 Apostrophe piece（一种可以包含在任何页面上的独立内容类型）和一个 piece 页面类型（一种专门用于单独或集体显示这些 piece 的页面类型）。

先决条件

1. 一个已安装 Apostrophe CLI 工具的 ApostropheCMS 项目 - 你可以创建一个新项目或使用现有项目。然而，本教程将只展示如何创建一个博客 piece 和 piece 页面类型。你将需要独立地集成任何其他现有的项目代码。如果你没有安装 CLI 工具，请参阅 Apostrophe CLI 安装说明。
2. 一个与 ApostropheCMS 集成的 Astro 项目 - 要从头开始创建一个项目，请参阅与 Astro 集成部分以获取有关如何设置集成的说明，或使用 astro-frontend 入门项目。

创建博客 piece 和 piece 页面类型

要创建用于显示的博客 piece 和 piece 页面类型，请在终端中导航到你的 ApostropheCMS 项目的根目录。使用 ApostropheCMS CLI 工具通过以下命令创建新的 piece 和 piece 页面类型

apos add piece blog --page

这将在你的项目中创建两个新模块，一个用于博客 piece 类型，另一个用于相应的 piece 页面类型。接下来，在你的代码编辑器中打开 ApostropheCMS 项目根目录下的 app.js 文件，并添加你的新模块。

app.js

require('apostrophe')({
  // other configuration options
  modules: {
    // other project modules
    blog: {},
    'blog-page': {}
  }
});

blog-page 模块也需要添加到 @apostrophecms/page 模块的 types 选项数组中，以便可以在页面创建模态框中选择它。在你的 ApostropheCMS 项目中，打开 modules/@apostrophecms/page/index.js 文件并添加 blog-page。

modules/@apostrophecms/page/index.js

module.exports = {
  options: {
    types: [
      {
        name: '@apostrophecms/home-page',
        label: 'Home'
      },
      // Any other project pages
      {
        name: 'blog-page',
        label: 'Blog'
      }
    ]
  }
};

创建博客 schema

在 ApostropheCMS 项目中，编辑器会获得一组用于添加内容的输入字段。这里是一个简单博客文章的示例，它添加了三个输入字段：authorName、publicationDate 和一个 content 区域，内容管理员可以在其中添加多个小部件实例。在这种情况下，我们指定他们可以添加我们在集成设置期间创建的图像和富文本小部件。

modules/blog/index.js

module.exports = {
  extend: '@apostrophecms/piece-type',
  options: {
    label: 'Blog',
    // Additionally add a `pluralLabel` option if needed.
  },
  fields: {
    add: {
      authorName: {
        type: 'string',
        label: 'Author'
      },
      publicationDate: {
        type: 'date',
        label: 'Publication date'
      },
      content: {
        type: 'area',
        label: 'Content',
        options: {
          widgets: {
            '@apostrophecms/rich-text': {},
            '@apostrophecms/image': {}
          }
        }
      }
    },
    group: {
      basics: {
        label: 'Basic',
        fields: [ 'authorName', 'publicationDate', 'content' ]
      }
    }
  }
};

至此，所有来自 ApostropheCMS 项目的组件都已设置完毕。使用 npm run dev 从命令行启动本地站点，确保传入设置为你所选字符串的 APOS_EXTERNAL_FRONT_KEY 环境变量

APOS_EXTERNAL_FRONT_KEY='MyRandomString' npm run dev

显示博客文章

要显示一个包含所有博客文章的页面，请在你的 Astro 项目的 src/templates 目录中创建一个 BlogIndex.astro 组件文件，并添加以下代码

从 aposData prop 中获取页面和 piece 数据后，该组件会使用我们创建的博客 piece schema 中的字段以及 Apostrophe 添加到每个 piece 的 piece.title 和 piece._url 来创建标记。

src/templates/BlogIndex.astro

---
import dayjs from 'dayjs';

const { page, pieces } = Astro.props.aposData;
---

<section class="bp-content">
  <h1>{ page.title }</h1>

  <h2>Blog Posts</h2>

  {pieces.map(piece => (
    <h4>
      Released On { dayjs(piece.publicationDate).format('MMMM D, YYYY') }
    </h4>
    <h3>
      <a href={ piece._url }>{ piece.title }</a>
    </h3>
    <h4>{ piece.authorName }</h4>
  ))}
</section>

要显示单个博客文章，请在 Astro 项目的 src/templates 文件夹中创建一个 BlogShow.astro 文件，并包含以下代码

该组件使用 <AposArea> 组件来显示添加到 content 区域的任何小部件，以及在同名字段中输入的 authorName 和 publicationDate 内容。

src/templates/BlogShow.astro

---
import AposArea from '@apostrophecms/apostrophe-astro/components/AposArea.astro';
import dayjs from 'dayjs';

const { page, piece } = Astro.props.aposData;
const { main } = piece;
---

<section class="bp-content">
  <h1>{ piece.title }</h1>
  <h3>Created by: { piece.authorName }
  <h4>
    Released On { dayjs(piece.publicationDate).format('MMMM D, YYYY') }
  </h4>
  <AposArea area={content} />
</section>

最后，这些 Astro 组件必须映射到相应的 ApostropheCMS 页面类型。打开 Astro 项目的 src/templates/index.js 文件并将其修改为包含以下代码

src/templates/index.js

import HomePage from './HomePage.astro';
import BlogIndexPage from './BlogIndexPage.astro';
import BlogShowPage from './BlogShowPage.astro';

const templateComponents = {
  '@apostrophecms/home-page': HomePage,
  '@apostrophecms/blog-page:index': BlogIndexPage,
  '@apostrophecms/blog-page:show': BlogShowPage
};

export default templateComponents;

创建博客文章

向你的网站添加博客文章是通过使用 ApostropheCMS 的内容和管理工具来创建这些文章，并发布至少一个索引页面来显示它们来完成的。

在 Astro 开发服务器运行的情况下，在你的浏览器预览中导航到位于 https://:4321/login 的登录页面。使用创建 ApostropheCMS 项目期间添加的凭据以管理员身份登录。你的 ApostropheCMS 项目应仍在运行。

登录后，你的浏览器将被重定向到项目的主页，并在顶部显示一个管理栏，用于编辑内容和管理你的项目。

要添加你的第一篇博客文章，请单击管理栏中的 Blogs 按钮以打开博客 piece 创建模态框。单击右上角的 New Blog 按钮将打开一个编辑模态框，你可以在其中添加内容。content 区域字段将允许你根据需要添加任意数量的图像和富文本小部件。

你可以重复此步骤并根据需要添加任意数量的文章。每次想要添加新文章时，你都需要遵循这些步骤。

要发布一个用于显示所有文章的页面，请单击管理栏中的 Pages 按钮。在页面树模态框中，单击 New Page 按钮。在右侧列的 Type 下拉菜单中选择 Blog。为页面添加一个标题，然后单击 Publish and View。你只需要执行一次此操作。

任何新创建的博客文章都将自动显示在此页面上。可以通过单击索引页面上创建的链接来显示单个博客文章。

单个文章的 content 区域可以通过导航到该文章并单击管理栏中的 edit 来直接在页面上进行编辑。其他字段可以通过单击管理栏中的 Blogs 菜单项打开的编辑模态框进行编辑。

部署你的网站

要部署你的网站，你需要托管你的 Astro 和 ApostropheCMS 项目。

对于 Astro，请访问我们的部署指南，并按照你首选的托管提供商的说明进行操作。

对于 ApostropheCMS 项目，请按照我们的托管指南中适用于你的托管类型的说明进行操作。最后，你需要向 Astro 项目提供一个 APOS_HOST 环境变量，以反映你的 ApostropheCMS 站点已部署的正确 URL。

官方资源

• 用于 ApostropheCMS 的 Astro 集成 - ApostropheCMS Astro 插件、集成指南以及适用于 Apostrophe 和 Astro 的入门项目
• 与 ApostropheCMS 一起使用的 Astro 示例项目 - 一个简单的 Astro 项目，已创建多个页面和 Apostrophe 小部件。
• 与 Astro 一起使用的 ApostropheCMS 入门套件示例 - 一个 ApostropheCMS 项目，对核心页面进行了修改以与 Astro 一起使用。

社区资源

• Antonello Zaini 撰写的将 ApostropheCMS 与 Astro 集成，第 1 部分
• Antonello Zaini 撰写的将 ApostropheCMS 与 Astro 集成，第 2 部分
• 展示与分享直播 | Astro & Apostrophe

更多 CMS 指南

• 

  Apostrophe

• 

  Builder.io

• 

  ButterCMS

• 

  Caisy

• 

  CloudCannon

• 

  Contentful

• 

  Cosmic

• 

  Craft CMS

• 

  Crystallize

• 

  DatoCMS

• 

  Decap CMS

• 

  Directus

• 

  Drupal

• 

  Flotiq

• 

  Front Matter CMS

• 

  Ghost

• 

  GitCMS

• 

  Hashnode

• 

  Hygraph

• 

  Keystatic

• 

  KeystoneJS

• 

  Kontent.ai

• 

  microCMS

• 

  Optimizely CMS

• 

  Payload CMS

• 

  Prepr CMS

• 

  Prismic

• 

  Sanity

• 

  Sitecore XM

• 

  Sitepins

• 

  Spinal

• 

  Statamic

• 

  Storyblok

• 

  Strapi

• 

  StudioCMS

• 

  Tina CMS

• 

  Umbraco

• 

  WordPress