Flotiq & Astro

Flotiq 是一个为静态站点、移动和 Web 应用程序等各种前端设计的无头（headless）CMS。开发人员和内容创作者通过基于 REST 和 GraphQL 的 API 来管理和交付内容。

与 Astro 集成

本指南将使用 Flotiq headless CMS API 和一个 Astro 项目来在你的网站上显示内容。

先决条件

在开始之前，你需要准备好：

一个 Astro 项目 - 你可以使用 npm create astro@latest 命令创建一个新项目。
一个 Flotiq 帐户 - 如果你还没有帐户，可以免费注册。
Flotiq 只读 API 密钥 - 了解如何获取你的密钥。

设置环境变量

将你的 Flotiq 帐户中的只读 API 密钥添加到你的 Astro 项目根目录下的 .env 文件中

FLOTIQ_API_KEY=__YOUR_FLOTIQ_API_KEY__

在 Flotiq 中定义内容类型

首先，你需要在 Flotiq 中定义一个示例内容类型定义（Content Type Definition）来存储数据。

登录到你的 Flotiq 帐户，并使用以下示例 Blog Post 配置创建一个自定义内容类型定义

标签：Blog Post
API 名称：blogpost
字段:
- Title：text，必填
- Slug：text，必填
- Content：rich text，必填

然后，使用这个 Blog Post 类型创建一个或多个示例内容对象（Content Objects）。

安装 Flotiq TypeScript SDK

要将你的项目与 Flotiq 连接，请使用你选择的包管理器安装 Flotiq SDK

npm install flotiq-api-ts

pnpm add flotiq-api-ts

yarn add flotiq-api-ts

接下来，使用你的凭据配置 SDK。在你的项目的 src/lib 目录下创建一个名为 flotiq.ts 的新文件

import { FlotiqApi } from "flotiq-api-ts";

export const flotiq = new FlotiqApi(import.meta.env.FLOTIQ_API_KEY);

现在这个配置可以在你的整个项目中使用。

从 Flotiq 获取和显示数据

在 Astro 页面上，使用你内容的自定义 API BlogpostAPI 来获取 Blog Post 数据
src/pages/index.astro
```
---
import { flotiq } from "../lib/flotiq";

const posts = await flotiq.BlogpostAPI.list();
---
```

在你的 Astro 模板中显示内容。你将可以访问你文章的 title、slug 和 content，以及其他 internal 文章数据

---
import { flotiq } from "../lib/flotiq";

const posts = await flotiq.BlogpostAPI.list();
---
<html lang="en">
  <head>
    <title>Astro</title>
  </head>
  <body>
    {posts.data?.map((post) => (
      <section>
        <a href={`/posts/${post.slug}`}>
          <h2>{post.title}</h2>
        </a>
        <div>{post.internal?.createdAt}</div>
        <div set:html={post.content}/>
      </section>
    ))}
  </body>
</html>

启动开发服务器并访问 https://:4321 预览你的页面，以查看你的博客文章列表。每篇文章将链接到一个尚不存在的页面。这些页面将在下一步中创建。

生成独立页面

Astro 支持提前预渲染所有页面，也支持在请求时按需创建路由。请按照静态站点生成或按需渲染的说明为你的博客文章构建页面路由。

静态站点生成

在静态站点生成（SSG）模式下，使用 getStaticPaths() 方法从 Flotiq 获取所有可能的博客文章路径。

在 /src/pages/posts/ 目录下创建一个新文件 [slug].astro。获取所有博客文章并在 getStaticPaths() 方法中返回它们

---
import type { Blogpost } from "flotiq-api-ts";
import { flotiq } from "../../lib/flotiq";

export async function getStaticPaths() {
  const posts = await flotiq.BlogpostAPI.list();
  return posts.data?.map((post) => ({
    params: { slug: post.slug },
    props: post
  })) || []
}
---

添加模板以显示单篇文章

---
import type { Blogpost } from "flotiq-api-ts";
import { flotiq } from "../../lib/flotiq";

export async function getStaticPaths() {
  const posts = await flotiq.BlogpostAPI.list();
  return posts.data?.map((post) => ({
    params: { slug: post.slug },
    props: post
  })) || []
}
const post: Blogpost = Astro.props;
---
<html lang="en">
  <title>{post.title}</title>
  <body>
    <h1>{post.title}</h1>
    <div set:html={post.content}/>
  </body>
</html>

访问 https://:4321 并点击列表中的一篇链接的博客文章。你现在应该能够导航到单篇文章的页面了。

按需渲染

如果你正在使用 SSR 模式，你需要根据文章的 slug 获取单篇文章。

在 /src/pages/posts/ 目录下创建一个新文件 [slug].astro。根据其 slug 字段获取文章，并包含在找不到路由时显示 404 页面的逻辑

---
import type { Blogpost } from "flotiq-api-ts";
import { flotiq } from "../../lib/flotiq";

const { slug } = Astro.params;
let post: Blogpost;

const blogpostList = await flotiq.BlogpostAPI.list({
  filters: JSON.stringify({
    slug: {
      type: 'equals',
      filter: slug,
    }
  }),
  limit: 1
});

if (blogpostList.data?.[0]) {
  post = blogpostList.data[0]
} else {
  return Astro.redirect('/404');
}
---

添加模板以显示单篇文章

---
import type { Blogpost } from "flotiq-api-ts";
import { flotiq } from "../../lib/flotiq";

const { slug } = Astro.params;
let post: Blogpost;

const blogpostList = await flotiq.BlogpostAPI.list({
  filters: JSON.stringify({
    slug: {
      type: 'equals',
      filter: slug,
    }
  }),
  limit: 1
});

if (blogpostList.data?.[0]) {
  post = blogpostList.data[0]
} else {
  return Astro.redirect('/404');
}
---
<html lang="en">
  <title>{post.title}</title>
  <body>
    <h1>{post.title}</h1>
    <div set:html={post.content}/>
  </body>
</html>

访问 https://:4321 并点击列表中的一篇链接的博客文章。你现在应该能够导航到单篇文章的页面了。

内容类型变更后刷新 SDK

使用 Flotiq TypeScript SDK（flotiq-api-ts）时，你所有的数据类型都会被精确地映射到 Astro 项目中。

如果你对内容类型的结构进行了更改（例如添加新字段或修改现有字段），你需要刷新 SDK 以确保你的项目反映最新的模型更新。

为此，请为你的包管理器运行重建命令

npm rebuild flotiq-api-ts

pnpm rebuild flotiq-api-ts

yarn rebuild flotiq-api-ts
// for yarn v1 (Classic):
// yarn add flotiq-api-ts

这将更新 SDK，使对象类型、字段和 API 方法与你当前的数据模型保持一致。

发布你的站点

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

Flotiq 内容变更时重新部署

要更新你已发布的站点，请配置 Flotiq，使其在你的内容发生变化时向你的托管提供商发送 webhook 以触发重新构建。

在 Flotiq 中，你可以定义它应该在哪种内容类型和事件上触发，并相应地进行配置。有关更多详细信息，请参阅 Flotiq Webhooks 文档。

官方资源

Flotiq 文档

社区资源

Maciek Palmowski 撰写的 Flotiq x Astro