Umbraco 和 Astro

Umbraco CMS 是一个开源 ASP.NET Core CMS。默认情况下，Umbraco 使用 Razor 页面作为其前端，但可以用作无头 CMS。

¥Umbraco CMS is an open-source ASP.NET Core CMS. By default, Umbraco uses Razor pages for its front-end, but can be used as a headless CMS.

与 Astro 集成

¥Integrating with Astro

在本节中，你将使用 Umbraco 的原生内容交付 API 为你的 Astro 项目提供内容。

¥In this section you will use Umbraco’s native Content Delivery API to provide content to your Astro project.

先决条件

¥Prerequisites

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

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

Astro 项目 - 如果你还没有 Astro 项目，我们的安装指南将立即帮助你启动并运行。
Umbraco (v12+) 项目 - 如果你还没有 Umbraco 项目，请参阅此安装指南。

设置内容交付 API

¥Setting up the Content Delivery API

要启用内容交付 API，请更新 Umbraco 项目的 appsettings.json 文件：

¥To enable the Content Delivery API, update your Umbraco project’s appsettings.json file:

{
  "Umbraco": {
    "CMS": {
      "DeliveryApi": {
        "Enabled": true,
        "PublicAccess": true
      }
    }
  }
}

你可以根据需要配置其他选项，例如公共访问、API 密钥、允许的内容类型、成员资格授权等。请参阅 Umbraco 内容交付 API 文档了解更多信息。

¥You can configure additional options as needed such as public access, API keys, allowed content types, membership authorisation, and more. See the Umbraco Content Delivery API documentation for more information.

获取数据

¥Fetching Data

使用 fetch() 调用内容交付 API 来访问你的内容并使其可用于你的 Astro 组件。

¥Use a fetch() call to the Content Delivery API to access your content and make it available to your Astro components.

以下示例显示获取的文章列表，包括文章日期和内容等属性。

¥The following example displays a list of fetched articles, including properties such as the article date and content.

---
const res = await fetch('http://localhost/umbraco/delivery/api/v2/content?filter=contentType:article');
const articles = await res.json();
---
<h1>Astro + Umbraco 🚀</h1>
{
  articles.items.map((article) => (
      <h1>{article.name}</h1>
      <p>{article.properties.articleDate}</p>
      <div set:html={article.properties.content?.markup}></div>
  ))
}

使用 Umbraco 和 Astro 构建博客

¥Building a blog with Umbraco and Astro

先决条件

¥Prerequisites

Astro 项目 - 如果你还没有 Astro 项目，我们的安装指南将立即帮助你启动并运行。
一个启用了内容交付 API 的 Umbraco 项目 (v12+) - 按照此安装指南创建一个新项目。

在 Umbraco 中创建博客文章

¥Creating blog posts in Umbraco

从 Umbraco 后台中，为名为 ‘文章’ 的简单博客文章创建文档类型。

¥From the Umbraco backoffice, create a Document Type for a simple blog article called ‘Article’.

Configure your ‘Article’ Document Type with the following properties:
- Title (DataType: Textstring)
- Article Date (DataType: Date Picker)
- Content (DataType: Richtext Editor)
Toggle “Allow as root” to true on the ‘Article’ document type.
From the “Content” section in the Umbraco backoffice, create and publish your first blog post. Repeat the process as many times as you like.

有关更多信息，请观看创建文档类型的视频指南。

¥For more information, watch a video guide on creating Document Types.

在 Astro 中显示博客文章列表

¥Displaying a list of blog posts in Astro

创建一个 src/layouts/ 文件夹，然后使用以下代码添加一个新文件 Layout.astro：

¥Create a src/layouts/ folder, then add a new file Layout.astro with the following code:

---
---
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>My Blog with Astro and Umbraco</title>
</head>
<body>
    <main>
        <slot />
    </main>
</body>
</html>

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

¥Your project should now contain the following files:

Directorysrc/
- Directorylayouts/
  - Layout.astro
- Directorypages/
  - index.astro

要创建博客文章列表，首先 fetch 调用内容交付 API content 端点并按 ‘article’ 的 contentType 进行过滤。文章对象将包括 CMS 中设置的属性和内容。然后，你可以循环遍历文章并显示每个标题及其文章的链接。

¥To create a list of blog posts, first fetch to call the Content Delivery API content endpoint and filter by contentType of ‘article’. The article objects will include the properties and content set in the CMS. You can then loop through the articles and display a each title with a link to its article.

将 index.astro 的默认内容替换为以下代码：

¥Replace the default contents of index.astro with the following code:

---
import Layout from '../layouts/Layout.astro';
const res = await fetch('http://localhost/umbraco/delivery/api/v2/content?filter=contentType:article');
const articles = await res.json();
---
<Layout>
  <h2>Blog Articles</h2>
  {
        articles.items.map((article: any) => (
            <div>
                <h3>{article.properties.title}</h3>
                <p>{article.properties.articleDate}</p>
                <a href={article.route.path}>Read more</a>
            </div>
        ))
    }
</Layout>

生成个人博客文章

¥Generating individual blog posts

在 /pages/ 目录的根目录中创建文件 [...slug].astro。此文件将用于动态生成单个博客页面。

¥Create the file [...slug].astro at the root of the /pages/ directory. This file will be used to generate the individual blog pages dynamically.

请注意，生成页面 URL 路径的 params 属性包含来自 API 获取的 article.route.path。同样，props 属性必须包含整个 article 本身，以便你可以访问 CMS 条目中的所有信息。

¥Note that the params property, which generates the URL path of the page, contains article.route.path from the API fetch. Similarly, the props property must include the entire article itself so that you can access all the information in your CMS entry.

将以下代码添加到 [...slug].astro，这将创建你的个人博客文章页面：

¥Add the following code to [...slug].astro which will create your individual blog post pages:

---
import Layout from '../layouts/Layout.astro';

export async function getStaticPaths() {
    let data = await fetch("http://localhost/umbraco/delivery/api/v2/content?filter=contentType:article");
    let articles = await data.json();

    return articles.items.map((article: any) => ({
        params: { slug: article.route.path },
        props: { article: article },
    }));
}

const { article } = Astro.props;
---

<Layout>
  <h1>{article.properties.title}</h1>
  <p>{article.properties.articleDate}</p>
  <div set:html={article.properties.content?.markup}></div>
</Layout>

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

¥Your project should now contain the following files:

Directorysrc/
- Directorylayouts/
  - Layout.astro
- Directorypages/
  - index.astro
  - […slug].astro

在开发服务器运行时，你现在应该能够在 Astro 项目的浏览器预览中查看 Umbraco 创建的内容。恭喜！🚀

¥With the dev server running, you should now be able to view your Umbraco-created content in your browser preview of your Astro project. Congratulations! 🚀

发布你的网站

¥Publishing your site

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

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

本地开发、HTTPS 和自签名 SSL 证书

¥Local dev, HTTPS and self-signed SSL certificates

如果你在本地使用 Umbraco HTTPS 端点，则任何 fetch 查询都将导致代码为 DEPTH_ZERO_SELF_SIGNED_CERT 的 fetch failed。这是因为 Node（Astro 建立在其上）默认不接受自签名证书。为避免这种情况，请对本地开发使用 Umbraco HTTP 端点。

¥If you are using the Umbraco HTTPS endpoint locally, any fetch queries will result in fetch failed with code DEPTH_ZERO_SELF_SIGNED_CERT. This is because Node (upon which Astro is built) won’t accept self-signed certificates by default. To avoid this, use the Umbraco HTTP endpoint for local dev.

或者，你可以在 env.development 文件中设置 NODE_TLS_REJECT_UNAUTHORIZED=0 并更新 astro.config.js，如下所示：

¥Alternatively, you can set NODE_TLS_REJECT_UNAUTHORIZED=0 in an env.development file and update astro.config.js as shown:

NODE_TLS_REJECT_UNAUTHORIZED=0

import { defineConfig } from 'astro/config';
import { loadEnv } from "vite";

const { NODE_TLS_REJECT_UNAUTHORIZED } = loadEnv(process.env.NODE_ENV, process.cwd(), "");
process.env.NODE_TLS_REJECT_UNAUTHORIZED = NODE_TLS_REJECT_UNAUTHORIZED;
// https://astro.build/config
export default defineConfig({});