跳转到内容

内容集合 API 参考

添加于： astro@2.0.0

内容集合提供了 API 来配置和查询 src/content/ 中的 Markdown 或 MDX 文档。有关功能和用法示例，请参考内容集合指南。

从 astro:content 导入

段落标题 从 astro:content 导入
import {
  z,
  defineCollection,
  getCollection,
  getEntry,
  getEntries,
  reference,
 } from 'astro:content';

defineCollection()

段落标题 defineCollection()

类型：(input: CollectionConfig) => CollectionConfig

添加于： astro@2.0.0

defineCollection() 是一个用于在 src/content.config.* 文件中配置集合的工具函数。

src/content/config.js
import { z, defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';


const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/data/blog' }),
  schema: z.object({
    title: z.string(),
    permalink: z.string().optional(),
  }),
});


// 将定义的集合公开给 Astro
// 通过 `collections` 导出
export const collections = { blog };

这个函数接受以下属性：

loader

段落标题 loader

Type: () => Promise<Array<{ id: string, [key: string]: any }> | Record<string, Record<string, any>>> | Loader

添加于： astro@5.0.0

loader 是一个对象或函数，允许你从任何源加载数据到内容集合中，无论是本地还是远程数据。

更多有关示例请 参考 内容集合指南。

schema

段落标题 schema

类型：ZodType | (context: SchemaContext) => ZodType

添加于： astro@2.0.0

schema 是一个可选的 Zod 对象，用于配置集合的文档 frontmatter 的类型和形状。每个值必须使用 Zod 验证器

更多有关示例请 参考 内容集合指南。

reference()

段落标题 reference()

类型：(collection: string) => ZodEffects<ZodString, { collection, id: string }>

添加于： astro@2.5.0

在内容配置中使用 reference() 函数来定义从一个集合到另一个集合的关系或 “引用”。该函数接受一个集合名称，并验证内容前置事项或数据文件中指定的条目标识符。

此示例定义了从博客作者到 “作者 “集合的引用，以及到同一 “博客 “集合的相关文章数组的引用：

import { defineCollection, reference, z } from 'astro:content';
import { glob, file } from 'astro/loaders';


const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/data/blog' }),
  schema: z.object({
    // 通过 "id "从 "作者 "集合中引用单个作者
    author: reference('authors'),
    // 按 "slug "从 "blog "集合中引用相关帖子数组
    relatedPosts: z.array(reference('blog')),
  })
});


const authors = defineCollection({
  loader: file("src/data/authors.json"),
  schema: z.object({ /* ... */ })
});


export const collections = { blog, authors };

更多有关示例请 参考 内容集合指南。

getCollection()

段落标题 getCollection()

类型： (collection: string, filter?: (entry: CollectionEntry<collection>) => boolean) => CollectionEntry<collection>[]

添加于： astro@2.0.0

getCollection() 是一个函数，用于通过集合名称检索内容集合条目列表。

默认情况下，它返回集合中的所有项目，并接受可选的 filter 函数来缩小条目属性。这允许你根据 id 或 frontmatter 值（通过 data 对象）查询集合中的某些项目。

---
import { getCollection } from 'astro:content';


// 获取 `src/content/blog/` 中的所有条目
const allBlogPosts = await getCollection('blog');


// 仅返回 frontmatter 中 `draft: true` 的条目
const draftBlogPosts = await getCollection('blog', ({ data }) => {
  return data.draft === true;
});
---

更多有关示例请 参考 内容集合指南。

getEntry()

段落标题 getEntry()

Type:

  • (collection: string, id: string) => Promise<CollectionEntry<collection> | undefined>
  • ({ collection: string, id: string }) => Promise<CollectionEntry<collection> | undefined>
添加于： astro@2.5.0

getEntry() 是一个函数，通过集合名称和条目 id 检索单个集合条目。getEntry() 也可以用于获取引用条目以访问 data 或 body 属性：

---
import { getEntry } from 'astro:content';


// 得到 `src/content/blog/enterprise.md`
const enterprisePost = await getEntry('blog', 'enterprise');


// 得到 `src/content/captains/picard.json`
const picardProfile = await getEntry('captains', 'picard');


// 得到 the profile referenced by `data.captain`
const enterpriseCaptainProfile = await getEntry(enterprisePost.data.captain);
---

更多有关内容集合的示例，请参考 查询集合条目。

getEntries()

段落标题 getEntries()

类型： (Array<{ collection: string, id: string }>) => Array<CollectionEntry<collection>>

添加于： astro@2.5.0

getEntries() 是一个从同一集合中检索多个集合条目的函数。这对于 返回引用条目的数组 访问其关联的data 和 body 属性非常有用。

---
import { getEntries } from 'astro:content';


const enterprisePost = await getEntry('blog', 'enterprise');


// 获取由 `data.relatedPosts` 引用的相关帖子
const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts);
---

render()

段落标题 render()

类型： () => Promise<RenderedEntry>

添加于： astro@5.0.0

一个用于编译给定的 Markdown 或 MDX 文档以进行渲染的函数。它返回以下属性：

---
import { getEntry, render } from 'astro:content';
const entry = await getEntry('blog', 'entry-1');


if (!entry) {
   // 处理错误，例如：
  throw new Error('Could not find blog post 1');
}
const { Content, headings, remarkPluginFrontmatter } = await render(entry);
---

更多有关示例请 参考内容集合指南 。

astro:content 类型

段落标题 astro:content 类型
import type {
  CollectionEntry,
  CollectionKey,
  ContentCollectionKey,
  DataCollectionKey,
  SchemaContext,
 } from 'astro:content';

CollectionEntry

段落标题 CollectionEntry

查询函数包括 getCollection()、getEntry() 和 getEntries()，每个函数都会返回 CollectionEntry 类型的条目。这种类型可以作为 astro:content 中的工具函数使用：

import type { CollectionEntry } from 'astro:content';

CollectionEntry 是一个泛型类型。将其与你正在查询的集合的名称一起使用。 例如，blog 集合中的条目的类型为 CollectionEntry<'blog'>。

每个 CollectionEntry 都是一个具有以下值的对象：

id

段落标题 id

适用于： type: 'content' 和 type: 'data' 集合
示例类型： 'author-1' | 'author-2' | ...

一个唯一的 ID。请注意，Astro 的内置 glob() 加载器中的所有 ID 都是 slug 化的。

collection

段落标题 collection

适用于： type: 'content' 和 type: 'data' 集合
示例类型： 'blog' | 'authors' | ...

条目所在的集合的名称。该名称用于在 schema 和查询函数中引用集合。

data

段落标题 data

类型：CollectionSchema<TCollectionName>

一个从集合模式推断出的 frontmatter 属性对象（参考 defineCollection()）。如果没有配置模式，则默认为 any。

body

段落标题 body

类型：string

一个包含 Markdown 或 MDX 文档原始未编译的 body 的字符串。

CollectionKey

段落标题 CollectionKey

添加于： astro@3.1.0

这是一个在 src/content.config.* 文件中定义的所有集合名称的字符串联合类型。当定义一个可以接受任何集合名称的通用函数时，这个类型很有用。

import { type CollectionKey, getCollection } from 'astro:content';


async function getCollection(collection: CollectionKey) {
  return getCollection(collection);
}

SchemaContext

段落标题 SchemaContext

即 defineCollection 在 schema 函数形状中所使用的 context 对象。当为多个集合构建可重用的模式时，这个类型很有用。

它包括了以下属性：

import type { SchemaContext } from 'astro:content';


export const imageSchema = ({ image }: SchemaContext) =>
    z.object({
        image: image(),
        description: z.string().optional(),
    });


const blog = defineCollection({
  loader: /* ... */
  schema: ({ image }) => z.object({
    title: z.string(),
    permalink: z.string().optional(),
    image: imageSchema({ image })
  }),
});
贡献 社区 赞助
京ICP备15031610号-99