Storyblok 与 Astro
Storyblok 是一个基于组件的无头(headless)CMS,允许你使用可重用的组件(称为 Bloks)管理内容。
与 Astro 集成
段落标题 与 Astro 集成在本小节中,你将使用 Storyblok 集成 来将 Storyblok 连接到 Astro。
前期准备
段落标题 前期准备开始前,你需要具备以下条件:
- Astro 项目 - 如果你还没有 Astro 项目,我们的安装指南将帮助你快速启动;
- Storyblok 账号和空间 - 如果你还没有账号,可以免费注册并创建一个新的空间;
- Storyblok 预览令牌 - 这个令牌将用于获取你的草稿内容和已发布版本。你可以在 Storyblok 空间设置的访问令牌选项卡中找到并生成你的 API 令牌。
配置凭据
段落标题 配置凭据为了将你的 Storyblok 凭据添加到 Astro,你可以在项目的根目录中创建一个名为 .env
的文件,并添加以下的变量:
现在,你应该可以在项目中使用该环境变量了。
并且,你的根目录现在应该包含这一新文件:
文件夹src/
- …
- .env
- astro.config.mjs
- package.json
安装依赖
段落标题 安装依赖为了将 Astro 连接到你的 Storyblok 空间,使用以下命令安装官方的 Storyblok 集成,可以用你偏好的包管理器执行相应命令:
配置 Storyblok
段落标题 配置 Storyblok修改 Astro 配置文件以包含 Storyblok 集成:
Storyblok 集成需要一个包含以下属性的对象:
-
accessToken
- 这是引用你在上一步中添加的 Storyblok API 令牌;由于 Astro 配置文件通常不支持环境变量,可以使用 Vite 的
loadEnv
函数来加载它们。 -
components
- 一个将 Storyblok 组件名称映射到本地组件路径的对象。这是必需的,为了能在 Astro 中渲染你的 Storyblok Bloks;组件路径是相对于
src
目录的。例如,如果你的组件位于src/storyblok/MyComponent.astro
,路径将是storyblok/MyComponent
(不包括.astro
扩展名)。 -
apiOptions
- 一个包含 Storyblok API 选项 的对象。默认情况下,区域是
eu
。如果你的 Storyblok 空间创建在美国区域,你需要将区域设置为us
。
将 Bloks 连接到 Astro 组件
段落标题 将 Bloks 连接到 Astro 组件要将你的 Bloks 连接到 Astro,请在 src
目录下创建一个名为 storyblok
的新文件夹。该文件夹将包含与你的 Storyblok Blok 库中的 Bloks 所匹配的所有 Astro 组件。
在这个例子中,假设你的 Storyblok Blok 库中有一个名为 blogPost
的 Blok 内容类型,其具有以下字段:
title
- 一个文本字段description
- 一个文本字段content
- 一个富文本字段
我们的目标是创建一个同等的 Astro 组件,使用这些字段来渲染其内容。为此,在 src/storyblok
中创建一个名为 BlogPost.astro
的新文件,并添加以下内容:
blok
属性包含你从 Storyblok 中接收到的数据。它还包含在 Storyblok 的 blogPost
内容类型 Blok 中定义的字段。
为了渲染我们的内容,该集成提供了一些实用函数,例如:
storyblokEditable
- 它会为元素添加必要的属性,以便你可以在 Storyblok 中进行编辑;renderRichText
- 它将富文本字段转换为 HTML。
现在你的根目录应该包括这个新文件:
文件夹src/
文件夹storyblok/
- BlogPost.astro
- .env
- astro.config.mjs
- package.json
最后,要将 blogPost
Blok 连接到 BlogPost
组件,在你的 Astro 配置文件的组件对象中添加一个新属性。
- 键是 Storyblok 中的 Blok 名称。在这种情况下,它是
blogPost
。 - 值是组件的路径。在这里,它是
storyblok/BlogPost
。
key
必须与 Storyblok 中的 Blok 名称完全匹配,以便正确引用。如果它们不匹配,或者你尝试引用 Storyblok 中不存在的组件,将会出现错误提示。
获取数据
段落标题 获取数据为了测试设置,你可以在 Storyblok 中创建一个使用 blogPost
内容类型命名为 test-post
的新故事。
在 Astro 中,在 src/pages/
目录下创建一个名为 test-post.astro
的新页面,并使用以下内容:
要查询你的数据,使用 useStoryblokApi
钩子函数。这将使用你的集成配置初始化一个新的客户端实例。
为了渲染你的内容,请将 Story 的 content
属性作为 blok
属性传递给 StoryblokComponent
。该组件将渲染在 content
属性中定义的 Bloks。在这种情况下,它将会渲染 BlogPost
组件。
使用 Astro 和 Storyblok 创建博客
段落标题 使用 Astro 和 Storyblok 创建博客通过设置集成,你现在可以使用 Astro 和 Storyblok 创建博客。
前期准备
段落标题 前期准备-
Storyblok 空间 - 对于本教程,我们建议使用一个新的空间。如果你已经有一个包含 Blok 的空间,可以使用它们,但你需要修改代码以匹配 Blok 的名称和内容类型。
-
集成了 Storyblok 的 Astro 项目 - 参考与 Astro 集成中的说明来设置集成。
创建 Blok 库
段落标题 创建 Blok 库要创建 Blok,请转到 Storyblok 应用程序,然后点击 Block Library 选项卡。点击 + New blok 按钮,然后创建以下 Bloks:
-
blogPost
- 包含以下字段的内容类型 Blok:title
- 文本字段description
- 文本字段content
- 富文本字段
-
blogPostList
- 空的可嵌套 Blok -
page
- 包含以下字段的内容类型 Blok:body
- 可嵌套 Blok
创建内容
段落标题 创建内容要添加新的内容,请点击 Content 选项卡,进入内容部分。请使用在上一步中创建的 Blok 库创建以下故事:
-
home
- 使用page
Blok 的内容类型故事。在body
字段中添加一个blogPostList
Blok。 -
blog/no-javascript
- 位于博客文件夹中,使用blogPost
内容类型的故事。 -
blog/astro-is-amazing
- 位于博客文件夹中,使用blogPost
内容类型的故事。
现在准备好了你的内容,然后返回到 Astro 项目中,开始构建你的博客。
将 Bloks 连接到组件
段落标题 将 Bloks 连接到组件为了将你新创建的 Bloks 连接到 Astro 组件,创建一个名为 storyblok
的新文件夹,放置到你的 src
目录中,并添加以下文件:
Page.astro
是一个可嵌套的 Block 类型组件,它会递归地渲染 page
Blok 的 body
属性中的所有 Blok。它还会给父元素添加 storyblokEditable
属性,这样我们就可以在 Storyblok 中编辑页面。
BlogPost.astro
将渲染 blogPost
Blok 的 title
、description
和 content
属性。
要将 content
属性从富文本字段转换为 HTML,你可以使用 renderRichText
辅助函数。
BlogPostList.astro
是一个可嵌套的 Blok 类型组件,用于渲染博客文章预览列表。
它使用 useStoryblokApi
钩子函数来获取所有内容类型为 blogPost
的文章。在开发模式下,它使用 version
查询参数来获取文章的草稿版本,在生产环境构建时则获取已发布的版本。
Astro.props
用于在 Storyblok 中设置编辑器,还可以在此处根据需要传递其他属性给该组件。
最后,在 astro.config.mjs
的 storyblok
配置对象的 components
属性中,将你的组件添加进去。键是 Storyblok 中 Blok 的名称,值是相对于 src
的组件路径。
生成页面
段落标题 生成页面要为特定的 page
创建一个路由,你可以直接从 Storyblok API 获取它的内容,并将其传递给 StoryblokComponent
组件。请确保在你的 astro.config.mjs
中添加了 Page
组件。
现在在 src/pages/
目录下创建一个 index.astro
文件,用于渲染 home
页面:
为了给你的所有博客文章生成页面,你可以创建一个 .astro
页面来创建动态路由。不过取决于你的路由是预渲染(在 Astro 中默认)还是按需渲染 (EN),这种方法会有所不同。
静态站点生成
段落标题 静态站点生成如果你正在使用 Astro 的默认静态站点生成功能,你将使用动态路由和 getStaticPaths
函数来生成你的项目页面。
创建一个名为 src/pages/blog/
的新目录,并添加一个名为 [...slug].astro
的新文件,其中包含以下代码:
这个文件将为每个故事生成一个页面,页面的 slug 和内容都从 Storyblok API 中获取。
当在 Storyblok 中添加文件夹时,请在与 Storyblok API 交互时将它们包含在 slug 中。例如,在上面的 GET 请求例子中,我们可以使用 cdn/stories/blog,其中包含一个 blog 文件夹,而不是在根目录中使用它们。
按需渲染
段落标题 按需渲染如果你已经配置了适配器来按需渲染你的路由 (EN),你将使用动态路由从 Storyblok 获取页面数据。
在 src/pages/blog/
目录下创建一个名为 [...slug].astro
的新文件,并添加以下代码:
这个文件将从 Storyblok 获取并渲染与动态 slug
参数匹配的页面数据。
由于你要使用重定向到 /404
,请在 src/pages
目录下创建一个 404 页面:
如果找不到故事,请求将被重定向到 404 页面。
发布你的网站
段落标题 发布你的网站要部署你的网站,请访问我们的部署指南,并按照你所偏好的托管提供商的步骤说明进行操作。
当 Storyblok 发生更改时重新构建
段落标题 当 Storyblok 发生更改时重新构建如果你的项目使用 Astro 的默认静态模式,你需要设置一个 Webhook,在内容更改时触发新的构建。如果你的托管提供商是 Netlify 或 Vercel,则可以使用其 Webhook 功能来根据 Storyblok 事件触发新的构建。
Netlify
段落标题 Netlify在 Netlify 中设置 Webhook 的步骤如下:
-
进入你的站点仪表板,点击 Build & deploy;
-
在 Continuous Deployment 选项卡下,找到 Build hooks 部分,点击 Add build hook;
-
为你的 Webhook 提供一个名称,并选择要触发构建的分支。点击 Save 并复制生成的 URL。
Vercel
段落标题 Vercel在 Vercel 中设置 Webhook 的步骤如下:
-
进入你的项目仪表板,点击 Settings;
-
在 Git 选项卡下,找到 Deploy Hooks 部分;
-
为你的 Webhook 提供一个名称和要触发构建的分支。点击 Add 并复制生成的 URL。
将 Webhook 添加到 Storyblok
段落标题 将 Webhook 添加到 Storyblok在 Storyblok 空间的 Settings 中,点击 Webhooks 选项卡,将你复制的 Webhook URL 粘贴到 Story published & unpublished 字段中,然后点击 Save 创建 Webhook。
现在,每当你发布一个新的文章,都将触发一个新的构建,并更新你的博客。
官方资源
段落标题 官方资源- Storyblok 提供了一个 Astro 集成,可以将 Storyblok 添加到你的项目中。
社区资源
段落标题 社区资源- Sandra Rodgers 的文章:为 Storyblok + Astro 使用可视化编辑器
- Jonas Gierer 的文章:Astro + Storyblok:SSR 预览实现即时可视化编辑
- Sandra Rodgers 的文章:使用 Netlify 的分支部署功能预览带有 Astro-Storyblok 的站点