内容集合 API 参考

添加于： astro@2.0.0

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

从 `astro:content` 导入

import {
  z,
  defineCollection,
  getCollection,
  getEntry,
  getEntries,
  reference,
 } from 'astro:content';

`defineCollection()`

类型：(input: CollectionConfig) => CollectionConfig

添加于： astro@2.0.0

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

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`

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

添加于： astro@5.0.0

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

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

`schema`

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

添加于： astro@2.0.0

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

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

`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()`

类型： (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()`

Type: ( collection: string, id: string ) => CollectionEntry<collection> | ({ collection: string, id: string }) => CollectionEntry<collection>

添加于： 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()`

类型： (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()`

类型： () => Promise<RenderedEntry>

添加于： astro@5.0.0

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

<Content /> - 用于在 Astro 文件中渲染文档内容的组件。
headings - 生成的标题列表，与 Astro 的 getHeadings() 工具函数相同在 Markdown 和 MDX 导入中。
remarkPluginFrontmatter - 在应用 remark 或 rehype 插件后修改后的 frontmatter 对象。设置为类型 any。

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

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

`astro:content` 类型

import type {
  CollectionEntry,
  CollectionKey,
  ContentCollectionKey,
  DataCollectionKey,
  SchemaContext,
 } from 'astro:content';

`CollectionEntry`

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

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

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

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

`id`

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

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

`collection`

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

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

`data`

类型：CollectionSchema<TCollectionName>

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

`body`

类型：string

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

`CollectionKey`

添加于： astro@3.1.0

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

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

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

`SchemaContext`

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

它包括了以下属性：

image - image() schema 辅助工具允许你在内容集合中使用本地图片。

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

贡献社区赞助

内容集合 API 参考

从 astro:content 导入

defineCollection()

loader

schema

reference()

getCollection()

getEntry()

getEntries()

render()

astro:content 类型

CollectionEntry

id

collection

data

body

CollectionKey

SchemaContext

从 `astro:content` 导入

`defineCollection()`

`loader`

`schema`

`reference()`

`getCollection()`

`getEntry()`

`getEntries()`

`render()`

`astro:content` 类型

`CollectionEntry`

`id`

`collection`

`data`

`body`

`CollectionKey`

`SchemaContext`