Builder.io 和 Astro

Builder.io 是一款可视化 CMS，支持拖放内容编辑来构建网站。

¥Builder.io is a visual CMS that supports drag-and-drop content editing for building websites.

本节将向你展示如何使用零客户端 JavaScript 将 Builder 空间连接到 Astro。

¥This recipe will show you how to connect your Builder space to Astro with zero client-side JavaScript.

先决条件

¥Prerequisites

首先，你需要具备以下条件：

¥To get started, you will need to have the following:

Builder 账户和空间 - 如果你还没有账户，免费注册并创建一个新空间。如果你已经有 Builder 的空间，请随意使用它，但你需要修改代码以匹配模型名称 (blogpost) 和自定义数据字段。
生成器 API 密钥 - 此公钥将用于从 Builder 获取你的内容。阅读架构商指南，了解如何找到密钥。

设置凭据

¥Setting up credentials

要将 Builder API 密钥和 Builder 模型名称添加到 Astro，请在项目的根目录中创建一个 .env 文件（如果尚不存在）并添加以下变量：

¥To add your Builder API key and your Builder model name to Astro, create a .env file in the root of your project (if one does not already exist) and add the following variables:

BUILDER_API_PUBLIC_KEY=YOUR_API_KEY
BUILDER_BLOGPOST_MODEL='blogpost'

现在，你应该能够在你的项目中使用此 API 密钥。

¥Now, you should be able to use this API key in your project.

如果你希望环境变量具有 IntelliSense，你可以在 src/ 目录中创建一个 env.d.ts 文件并配置 ImportMetaEnv，如下所示：

¥If you would like to have IntelliSense for your environment variables, you can create a env.d.ts file in the src/ directory and configure ImportMetaEnv like this:

interface ImportMetaEnv {
  readonly BUILDER_API_PUBLIC_KEY: string;
}

你的项目现在应该包含以下文件：

¥Your project should now include these files:

Directorysrc/
- env.d.ts
.env
astro.config.mjs
package.json

使用 Astro 和 Builder 制作博客

¥Making a blog with Astro and Builder

为博客文章创建模型

¥Creating a model for a blog post

下面的说明使用名为 blogpost 的构建器模型（类型：“部分”）创建一个 Astro 博客，其中包含两个必需的文本字段：title 和 slug。

¥The instructions below create an Astro blog using a Builder model (Type: “Section”) called blogpost that contains two required text fields: title and slug.

在 Builder 应用中创建代表博客文章的模型：转到“模型”选项卡并单击 + 创建模型按钮以创建具有以下字段和值的模型：

¥In the Builder app create the model that will represent a blog post: go to the Models tab and click the + Create Model button to create model with the following fields and values:

类型：部分
名称：“blogpost”
描述：“该模型适用于博客文章”

在你的新模型中使用 + 新建自定义字段按钮创建 2 个新字段：

¥In your new model use the + New Custom Field button to create 2 new fields:

文本域
- 名称：“title”
- 必需的：是的
- 默认值 “我忘了给这个标题”
（其他参数保留默认值）
文本域
- 名称：“slug”
- 必需的：是的
- 默认值 “some-slugs-take-their-time”
（其他参数保留默认值）

然后单击右上角的“保存”按钮。

¥Then click the Save button in the upper right.

设置预览

¥Setting up the preview

要使用 Builder 的可视化编辑器，请创建将渲染特殊 <builder-component> 的页面 src/pages/builder-preview.astro：

¥To use Builder’s visual editor, create the page src/pages/builder-preview.astro that will render the special <builder-component>:

Directorysrc/
- Directorypages/
  - builder-preview.astro
- env.d.ts
.env
astro.config.mjs
package.json

然后添加以下内容：

¥Then add the following content:

---
const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;
---

<html lang="en">
  <head>
    <title>Preview for builder.io</title>
  </head>
  <body>
    <header>This is your header</header>

    <builder-component model={builderModel} api-key={builderAPIpublicKey}
    ></builder-component>
    <script async src="https://cdn.builder.io/js/webcomponents"></script>

    <footer>This is your footer</footer>
  </body>
</html>

在上面的示例中，<builder-component> 告诉 Builder 将其 CMS 中的内容插入到何处。

¥In the above example, <builder-component> tells Builder where to insert the content from its CMS.

将新路由设置为预览 URL

¥Setting the new route as the preview URL

Copy the full URL of your preview, including the protocol, to your clipboard (e.g. https://{your host}/builder-preview).
Go to the Models tab in your Builder space, pick the model you’ve created and paste the URL from step 1 into the Preview URL field. Make sure the URL is complete and includes the protocol, for example https://.
Click the Save button in the upper right.

测试预览 URL 设置

¥Testing the preview URL setup

Make sure your site is live (e.g. your dev server is running) and the /builder-preview route is working.
In your Builder space under the Content tab, click on New to create a new content entry for your blogpost model.
In the Builder editor that just opened, you should be able to see the builder-preview.astro page with a big Add Block in the middle.

创建博客文章

¥Creating a blog post

In Builder’s visual editor, create a new content entry with the following values:
- title: ‘First post, woohoo!‘
- slug: ‘first-post-woohoo’
Complete your post using the Add Block button and add a text field with some post content.
In the text field above the editor, give your entry a name. This is how it will be listed in the Builder app.
When you’re ready click the Publish button in the upper right corner.
Create as many posts as you like, ensuring that all content entries contain a title and a slug as well as some post content.

显示博客文章列表

¥Displaying a list of blog posts

将以下内容添加到 src/pages/index.astro 以获取并显示所有帖子标题的列表，每个帖子标题都链接到自己的页面：

¥Add the following content to src/pages/index.astro in order to fetch and display a list of all post titles, each linking to its own page:

---

const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;

const { results: posts } = await fetch(
  `https://cdn.builder.io/api/v3/content/${builderModel}?${new URLSearchParams({
    apiKey: builderAPIpublicKey,
    fields: ["data.slug", "data.title"].join(","),
    cachebust: "true",
  }).toString()}`
)
  .then((res) => res.json())
  .catch();
---

<html lang="en">
  <head>
    <title>Blog Index</title>
  </head>
  <body>
    <ul>
      {
        posts.flatMap(({ data: { slug, title } }) => (
          <li>
            <a href={`/posts/${slug}`}>{title}</a>
          </li>
        ))
      }
    </ul>
  </body>
</html>

通过内容 API 获取会返回包含每个帖子数据的对象数组。fields 查询参数告诉 Builder 包含哪些数据（请参阅高亮的代码）。slug 和 title 应与你添加到构建器模型中的自定义数据字段的名称匹配。

¥Fetching via the content API returns an array of objects containing data for each post. The fields query parameter tells Builder which data is included (see highlighted code). slug and title should match the names of the custom data fields you’ve added to your Builder model.

从获取返回的 posts 数组显示主页上的博客文章标题列表。各个页面路由将在下一步中创建。

¥The posts array returned from the fetch displays a list of blog post titles on the home page. The individual page routes will be created in the next step.

转到你的索引路由，你应该能够看到一个链接列表，每个链接都带有博客文章的标题！

¥Go to your index route and you should be able to see a list of links each with the title of a blog post!

显示单个博客文章

¥Displaying a single blog post

为每个帖子创建 src/pages/posts/[slug].astro 页面和动态生成页面页面。

¥Create the page src/pages/posts/[slug].astro that will dynamically generate a page for each post.

Directorysrc/
- Directorypages/
  - index.astro
  - Directoryposts/
    [slug].astro
- env.d.ts
.env
astro.config.mjs
package.json

该文件必须包含：

¥This file must contain:

一个 getStaticPaths() 函数，用于从 Builder 获取 slug 信息并为每个博客文章创建静态路由。
fetch() 到 Builder API，使用 slug 标识符返回帖子内容和元数据（例如 title）。
模板中的 <Fragment /> 将帖子内容渲染为 HTML。

下面的代码片段中高亮了其中的每一个。

¥Each of these is highlighted in the following code snippet.

---
export async function getStaticPaths() {
  const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;
  const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
  const { results: posts } = await fetch(
    `https://cdn.builder.io/api/v3/content/${builderModel}?${new URLSearchParams(
      {
        apiKey: builderAPIpublicKey,
        fields: ["data.slug", "data.title"].join(","),
        cachebust: "true",
      }
    ).toString()}`
  )
    .then((res) => res.json())
    .catch
    // ...catch some errors...);
    ();
  return posts.map(({ data: { slug, title } }) => ({
    params: { slug },
    props: { title },
  }))
}
const { slug } = Astro.params;
const { title } = Astro.props;
const builderModel = import.meta.env.BUILDER_BLOGPOST_MODEL;
const builderAPIpublicKey = import.meta.env.BUILDER_API_PUBLIC_KEY;
// Builder's API requires this field but for this use case the url doesn't seem to matter - the API returns the same HTML
const encodedUrl = encodeURIComponent("moot");
const { html: postHTML } = await fetch(
  `https://cdn.builder.io/api/v1/qwik/${builderModel}?${new URLSearchParams({
    apiKey: builderAPIpublicKey,
    url: encodedUrl,
    "query.data.slug": slug,
    cachebust: "true",
  }).toString()}`
)
  .then((res) => res.json())
  .catch();
---
<html lang="en">
  <head>
    <title>{title}</title>
  </head>
  <body>
    <header>This is your header</header>
    <article>
      <Fragment set:html={postHTML} />
    </article>
    <footer>This is your footer</footer>
  </body>
</html>

现在，当你单击索引路径上的链接时，你将被带到单独的博客文章页面。

¥Now when you click on a link on your index route, you will be taken to the individual blog post page.

发布你的网站

¥Publishing your site

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

¥To deploy your website, visit our deployment guides and follow the instructions for your preferred hosting provider.

根据生成器更改进行重建

¥Rebuild on Builder changes

如果你的项目使用 Astro 的默认静态模式，则需要设置一个 Webhook 以在内容更改时触发新的构建。如果你使用 Netlify 或 Vercel 作为托管服务提供商，则可以使用其 webhook 功能在单击 Builder 编辑器中的“发布”时触发新构建。

¥If your project is using Astro’s default static mode, you will need to set up a webhook to trigger a new build when your content changes. If you are using Netlify or Vercel as your hosting provider, you can use its webhook feature to trigger a new build whenever you click Publish in the Builder editor.

Netlify

Go to your site dashboard, then Site Settings and click on Build & deploy.
Under the Continuous Deployment tab, find the Build hooks section and click on Add build hook.
Provide a name for your webhook and select the branch you want to trigger the build on. Click on Save and copy the generated URL.

Vercel

Go to your project dashboard and click on Settings.
Under the Git tab, find the Deploy Hooks section.
Provide a name for your webhook and the branch you want to trigger the build on. Click Add and copy the generated URL.

将 webhook 添加到 Builder

¥Adding a webhook to Builder

In your Builder dashboard, go into your blogpost model. Under Show More Options, select Edit Webhooks at the bottom.
Add a new webhook by clicking on Webhook. Paste the URL generated by your hosting provider into the Url field.
Click on Show Advanced under the URL field and toggle the option to select Disable Payload. With the payload disabled, Builder sends a simpler POST request to your hosting provider, which can be helpful as your site grows. Click Done to save this selection.

使用此 webhook，每当你单击 Builder 编辑器中的“发布”按钮时，你的托管服务提供商都会重建你的网站 - Astro 会为你获取新发布的数据。无事可做，只能向后靠并泵出甜蜜的内容！

¥With this webhook in place, whenever you click the Publish button in the Builder editor, your hosting provider rebuilds your site - and Astro fetches the newly published data for you. Nothing to do but lean back and pump out that sweet sweet content!