内容集合 API 参考

Added in: astro@2.0.0

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

¥Content collections offer APIs to configure and query your Markdown or MDX documents in src/content/. For features and usage examples, see our content collections guide.

从 `astro:content` 导入

¥Imports from astro:content

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

`defineCollection()`

类型：(input: CollectionConfig) => CollectionConfig

¥Type: (input: CollectionConfig) => CollectionConfig

Added in: astro@2.0.0

defineCollection() 是一个用于在 src/content.config.* 文件中配置集合的实用程序。

¥defineCollection() is a utility to configure a collection in a src/content.config.* file.

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

// Expose your defined collection to Astro
// with the `collections` export
export const collections = { blog };

该函数接受以下属性：

¥This function accepts the following properties:

`loader`

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

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

Added in: astro@5.0.0

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

¥A loader is either an object or a function that allows you to load data from any source, local or remote, into content collections.

请参阅 Content Collection 指南例如用法。

¥See the Content Collection guide for example usage.

`schema`

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

¥Type: ZodType | (context: SchemaContext) => ZodType

Added in: astro@2.0.0

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

¥schema is an optional Zod object to configure the type and shape of document frontmatter for a collection. Each value must use a Zod validator.

请参阅 Content Collection 指南例如用法。

¥See the Content Collection guide for example usage.

`reference()`

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

¥Type: (collection: string) => ZodEffects<ZodString, { collection, id: string }>

Added in: astro@2.5.0

reference() 函数在内容配置中用于定义关系，或 “参考，” 从一个集合到另一个集合。这接受集合名称并验证内容前言或数据文件中指定的条目标识符，然后将引用转换为包含集合名称和引用 ID 的对象。

¥The reference() function is used in the content config to define a relationship, or “reference,” from one collection to another. This accepts a collection name and validates the entry identifier(s) specified in your content frontmatter or data file before transforming the reference into an object containing the collection name and the reference id.

此示例定义了博客作者对 authors 集合的引用以及对同一 blog 集合的相关帖子数组：

¥This example defines references from a blog author to the authors collection and an array of related posts to the same blog collection:

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({
    // Reference a single author from the `authors` collection by `id`
    author: reference('authors'),
    // Reference an array of related posts from the `blog` collection by `slug`
    relatedPosts: z.array(reference('blog')),
  })
});

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

export const collections = { blog, authors };

请参阅 Content Collection 指南例如用法。

¥See the Content Collection guide for example usage.

`getCollection()`

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

¥Type: (collection: string, filter?: (entry: CollectionEntry<collection>) => boolean) => CollectionEntry<collection>[]

Added in: astro@2.0.0

getCollection() 是按集合名称检索内容集合条目列表的函数。

¥getCollection() is a function that retrieves a list of content collection entries by collection name.

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

¥It returns all items in the collection by default, and accepts an optional filter function to narrow by entry properties. This allows you to query for only some items in a collection based on id or frontmatter values via the data object.

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

// Get all `src/content/blog/` entries
const allBlogPosts = await getCollection('blog');

// Only return posts with `draft: true` in the frontmatter
const draftBlogPosts = await getCollection('blog', ({ data }) => {
  return data.draft === true;
});
---

请参阅 Content Collection 指南例如用法。

¥See the Content Collection guide for example usage.

`getEntry()`

类型：

¥Types:

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

Added in: astro@2.5.0

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

¥getEntry() is a function that retrieves a single collection entry by collection name and the entry id. getEntry() can also be used to get referenced entries to access the data or body properties:

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

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

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

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

有关查询集合条目的示例，请参阅 Content Collections 指南。

¥See the Content Collections guide for examples of querying collection entries.

`getEntries()`

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

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

Added in: astro@2.5.0

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

¥getEntries() is a function that retrieves multiple collection entries from the same collection. This is useful for returning an array of referenced entries to access their associated data and body properties.

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

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

// Get related posts referenced by `data.relatedPosts`
const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts);
---

`render()`

类型：(entry: CollectionEntry) => Promise<RenderedEntry>

¥Type: (entry: CollectionEntry) => Promise<RenderedEntry>

Added in: astro@5.0.0

用于编译给定条目以进行渲染的函数。这将返回以下属性：

¥A function to compile a given entry for rendering. This returns the following properties:

<Content /> - 用于在 Astro 文件中渲染文档内容的组件。
headings - 生成的标题列表，Markdown 上的镜像 Astro 的 getHeadings() 实用程序和 MDX 导入。
remarkPluginFrontmatter - 任何已应用评论或 rehype 插件之后修改后的 frontmatter 对象。设置为类型 any。

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

if (!entry) {
   // Handle Error, for example:
  throw new Error('Could not find blog post 1');
}
const { Content, headings, remarkPluginFrontmatter } = await render(entry);
---

请参阅 Content Collection 指南例如用法。

¥See the Content Collection guide for example usage.

`astro:content` 类型

¥astro:content types

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

`CollectionEntry`

包括 getCollection()、getEntry() 和 getEntries() 在内的查询函数均返回 CollectionEntry 类型的条目。该类型可作为 astro:content 中的实用程序使用：

¥Query functions including getCollection(), getEntry(), and getEntries() each return entries with the CollectionEntry type. This type is available as a utility from astro:content:

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

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

¥CollectionEntry is a generic type. Use it with the name of the collection you’re querying. For example, an entry in your blog collection would have the type CollectionEntry<'blog'>.

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

¥Each CollectionEntry is an object with the following values:

`id`

示例类型：'author-1' | 'author-2' | ...

¥Example Type: 'author-1' | 'author-2' | ...

唯一 ID。请注意，Astro 内置 glob() 加载器中的所有 ID 都已 slugified。

¥A unique ID. Note that all IDs from Astro’s built-in glob() loader are slugified.

`collection`

示例类型：'blog' | 'authors' | ...

¥Example Type: 'blog' | 'authors' | ...

条目所在的集合的名称。这是用于在架构和查询函数中引用集合的名称。

¥The name of a collection in which entries are located. This is the name used to reference the collection in your schema, and in querying functions.

`data`

类型：CollectionSchema<TCollectionName>

¥Type: CollectionSchema<TCollectionName>

从集合架构 (参见 defineCollection() 参考) 推断出的 frontmatter 属性的对象。如果未配置架构，则默认为 any。

¥An object of frontmatter properties inferred from your collection schema (see defineCollection() reference). Defaults to any if no schema is configured.

`body`

类型：string

¥Type: string

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

¥A string containing the raw, uncompiled body of the Markdown or MDX document.

`CollectionKey`

Added in: astro@3.1.0

src/content.config.* 文件中定义的所有集合名称的字符串并集。此类型在定义封装内置 getCollection() 的通用函数时很有用。

¥A string union of all collection names defined in your src/content.config.* file. This type can be useful when defining a generic function wrapping the built-in getCollection().

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

async function queryCollection(collection: CollectionKey) {
  return getCollection(collection, ({ data }) => {
    return data.draft !== true;
  });
}

`SchemaContext`

defineCollection 用于 schema 函数形状的 context 对象。在为多个集合构建可重用架构时，此类型非常有用。

¥The context object that defineCollection uses for the function shape of schema. This type can be useful when building reusable schemas for multiple collections.

这包括以下属性：

¥This includes the following property:

image - 允许你在资源库中使用本地图片的 image() 模式助手

import { defineCollection, z, 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 })
  }),
});

Astro v5.5 中文网 - 粤ICP备13048890号

Nodejs.cn 旗下网站

内容集合 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`