Flotiq 和 Astro

Flotiq 是一个无头 CMS，专为各种前端设计，例如静态站点、移动和 Web 应用。开发者和内容创建者通过 REST 和基于 GraphQL 的 API 管理和交付内容。

¥Flotiq is a headless CMS designed for various frontends, such as static sites, mobile, and web applications. Developers and content creators manage and deliver content through REST and GraphQL-based APIs.

与 Astro 集成

¥Integrating with Astro

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

¥This guide will use the Flotiq headless CMS API with an Astro project to display content on your website.

先决条件

¥Prerequisites

首先，你将需要：

¥To get started, you will need:

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

设置环境变量

¥Setting up the Environment variables

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

¥Add the read-only API key from your Flotiq account to the .env file in the root of your Astro project:

FLOTIQ_API_KEY=__YOUR_FLOTIQ_API_KEY__

在 Flotiq 中定义内容类型

¥Defining a Content Type in Flotiq

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

¥First, you need to define an example Content Type Definition in Flotiq to store data.

登录你的 Flotiq 账户并使用以下示例 Blog Post 配置创建自定义内容类型定义：

¥Log in to your Flotiq account and create a custom Content Type Definition with the following example Blog Post configuration:

标签：博客文章
API 名称：blogpost
字段：
- 标题：文本，必需
- 蛞蝓：文本，必需
- 内容：富文本，必需

然后，使用此 Blog Post 类型创建一个或多个示例内容对象。

¥Then, create one or more example Content Objects using this Blog Post type.

安装 Flotiq TypeScript SDK

¥Installing the Flotiq TypeScript SDK

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

¥To connect your project with Flotiq, install the Flotiq SDK using the package manager of your choice:

npm install flotiq-api-ts

pnpm add flotiq-api-ts

yarn add flotiq-api-ts

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

¥Next, configure the SDK using your credentials. Create a new file named flotiq.ts inside the src/lib directory of your project:

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

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

此配置现在可以在整个项目中使用。

¥This configuration can now be used throughout your project.

从 Flotiq 获取和显示数据

¥Fetching and Displaying Data from Flotiq

Fetch the Blog Post data on an Astro page using your content’s custom API BlogpostAPI:
src/pages/index.astro
```
---
import { flotiq } from "../lib/flotiq";

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

Display the content in your Astro template. You will have access to the title, slug, and content of your posts as well as other internal post data:

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

Start the dev server and visit your page preview at http://localhost:4321 to see the list of your blog posts. Each post will link to a page that does not yet exist. These will be created in the next step.

生成单个页面

¥Generating Individual Pages

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

¥Astro supports both prerendering all your pages ahead of time, or creating routes on demand when they are requested. Follow the instructions for either static site generation or on-demand rendering to build the page routes for your blog posts.

静态站点生成

¥Static Site Generation

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

¥In static site generation (SSG) mode, use the getStaticPaths() method to fetch all possible blog post paths from Flotiq.

Create a new file [slug].astro in the /src/pages/posts/ directory. Fetch all blog posts and return them within the getStaticPaths() method:

---
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
  })) || []
}
---

Add the templating to display an individual 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>

Visit http://localhost:4321 and click on a linked blog post in your list. You will now be able to navigate to the individual post’s page.

按需渲染

¥On-demand Rendering

如果你使用 SSR 模式，则需要根据其 slug 获取单个帖子。

¥If you are using SSR mode, you will need to fetch a single post based on its slug.

Create a new file [slug].astro in the /src/pages/posts/ directory. Fetch the post by its slug field, including logic to display a 404 page when the route is not found:

---
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');
}
---

Add the templating to display an individual post:

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

Visit http://localhost:4321 and click on a linked blog post in your list. You will now be able to navigate to the individual post’s page.

内容类型更改后刷新 SDK

¥Refreshing the SDK After Content Type Changes

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

¥When using the Flotiq TypeScript SDK (flotiq-api-ts), all your data types are accurately mapped into the Astro project.

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

¥If you make changes to the structure of your content types (such as adding a new field or modifying an existing one), you’ll need to refresh the SDK to ensure that your project reflects the latest model updates.

要执行此操作，请为你的包管理器运行重建命令：

¥To do this, run the rebuild command for your package manager:

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 方法与你当前的数据模型保持一致。

¥This will update the SDK, aligning object types, fields, and API methods with your current data model.

发布你的网站

¥Publishing Your Site

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

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

在 Flotiq 上重新部署更改

¥Redeploy on Flotiq Changes

要更新你发布的网站，请配置 Flotiq 以在你的内容发生更改时向你的托管提供商发送 webhook 以触发重建。

¥To update your published site, configure Flotiq to send a webhook your hosting provider to trigger a rebuild whenever your content changes.

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

¥In Flotiq, you can define which Content Type and events it should trigger on, and configure it accordingly. See the Flotiq Webhooks documentation for more details.