Lzh on GitHub

queryCollection

queryCollection composable 提供了查询和获取你的集合的方法。

用法

使用自动导入的 queryCollection 来查找集合中的内容。这里我们假设你已经在 content.config.ts 中定义了 docs 集合。

如果你还没有定义任何集合，请查看 如何定义一个集合。

pages/[...slug].vue
<script>
const route = useRoute()
const { data: page } = await useAsyncData(route.path, () => {
  return queryCollection('docs').path(route.path).first()
})
</script>
queryCollection 实用程序在 Vue 和 Nitro 中都可用。查看 服务器端用法 以获取有关如何在服务器端使用它的更多详细信息。

API

类型

function queryCollection<T extends keyof Collections>(collection: T): CollectionQueryBuilder<Collections[T]>

interface CollectionQueryBuilder<T> {
  where(field: keyof T | string, operator: SQLOperator, value?: unknown): CollectionQueryBuilder<T>
  andWhere(groupFactory: QueryGroupFunction<T>): CollectionQueryBuilder<T>
  orWhere(groupFactory: QueryGroupFunction<T>): CollectionQueryBuilder<T>
  order(field: keyof T, direction: 'ASC' | 'DESC'): CollectionQueryBuilder<T>
  // ... other methods
}

queryCollection(collection: CollectionName)

创建一个查询构建器以在特定集合中搜索。

  • Parameters:
    • collection: 在 content.config.ts 中定义的集合的键

path(path: string)

搜索具有特定 path 的内容。（path 是 page 集合中的一个特殊字段，它基于文件系统路径生成，并且可以用作渲染内容的路由）

  • Parameter:
    • path: 要匹配的路径字符串。
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
  return queryCollection('docs').path(route.path).first()
})

select(...fields: keyof Collection)

从集合中选择特定的字段以在查询结果中返回。

  • Parameters:
    • ...fields: 要从集合中选择的字段名称列表。
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
  return queryCollection('docs')
    .select('path', 'title', 'description')
    .first()
})

where(field: keyof Collection | string, operator: SqlOperator, value?: unknown)

向查询添加条件，以根据特定字段过滤结果。

  • Parameters:
    • field: 要过滤的字段
    • operator: 用于比较的 SQL 运算符。可能的值包括：
      • '=': 等于
      • '>': 大于
      • '<': 小于
      • '<>': 不等于
      • 'IN': 在一个值列表中
      • 'BETWEEN': 在两个值之间
      • 'NOT BETWEEN': 不在两个值之间
      • 'IS NULL': 为空
      • 'IS NOT NULL': 不为空
      • 'LIKE': 匹配一个模式
      • 'NOT LIKE': 不匹配一个模式
    • value: 要比较的值。类型取决于所使用的运算符。
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
  return queryCollection('docs')
    .where('date', '<', '2024-04-04')
    .all()
})

andWhere(groupFactory: QueryGroupFunction<Collection>)

向查询添加一个 AND 条件组。这允许更复杂的查询条件。

  • Parameter:
    • groupFactory: 一个接收查询构建器的函数，可以添加多个将使用 AND 分组在一起的条件
const { data } = await useAsyncData('recent-docs', () => {
  return queryCollection('docs')
    .where('published', '=', true)
    .andWhere(query => query.where('date', '>', '2024-01.backface-visibility.md-01.backface-visibility.md').where('category', '=', 'news'))
    .all()
})

orWhere(groupFactory: QueryGroupFunction<Collection>)

向查询添加一个 OR 条件组。这允许替代条件。

  • Parameter:
    • groupFactory: 一个接收查询构建器的函数，可以添加多个将使用 OR 分组在一起的条件
const { data } = await useAsyncData('featured-docs', () => {
  return queryCollection('docs')
    .where('published', '=', true)
    .orWhere(query => query.where('featured', '=', true).where('priority', '>', 5))
    .all()
})

order(field: keyof Collection, direction: 'ASC' | DESC)

根据特定字段对查询结果进行排序。

  • Parameters:
    • field: 要排序的字段。
    • direction: 排序方向，'ASC' 表示升序，'DESC' 表示降序。
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
  return queryCollection('docs')
    .order('date', 'DESC')
    .all()
})

limit(limit: number)

限制查询返回的结果数量。

  • Parameter:
    • limit: 要返回的最大结果数。
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
  return queryCollection('docs')
    .limit(10)
    .all()
})

skip(skip: number)

在查询中跳过指定数量的结果。

  • Parameter:
    • skip: 要跳过的结果数。
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
  return queryCollection('docs')
    // Skip first 5 items
    .skip(5)
    .all()
})

all()

执行查询并返回所有匹配的结果。

  • Returns: 一个 Promise，解析为包含所有匹配文档的数组。
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
  return queryCollection('docs').all()
})

first()

执行查询并返回第一个匹配的结果。

  • Returns: 一个 Promise，解析为第一个匹配的文档，如果没有匹配的文档则解析为 null。
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
  return queryCollection('docs').first()
})

count()

计算基于查询匹配的集合条目的数量。

const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
  return queryCollection('docs')
    // Count matches
    .count()
})

// Returns
5 // number of matches

你还可以将 count() 与上面定义的其他方法（如 where()）一起使用，以便在集合查询中应用其他条件。

const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
  return queryCollection('docs')
    .where('date', '<', '2024-04-04')
    // Count matches
    .count()
})

// Returns
3 // number of matches for the provided query

示例

这是一个完整的示例，说明如何获取 docs 集合中的文档列表。

index.vue
<script setup lang="ts">
const { data: docs } = await useAsyncData('documents-list', () => {
  return queryCollection('docs')
    .order('date', 'DESC')
    .select('title', 'path', 'description')
    .all()
})
</script>

<template>
  <NuxtLink v-for="doc in docs" :key="doc.path" :to="doc.path">
    <h2>{{ doc.title }}</h2>
    <p>{{ doc.description }}</p>
  </NuxtLink>
</template>

服务器端用法

Nuxt Content 提供了一个类似的实用工具，用于在服务器端查询集合。唯一的区别是你需要将 event 作为第一个参数传递给 queryCollection 函数。

server/api/[slug].ts
export default eventHandler(async (event) => {
  const { slug } = getRouterParams(event)
  const page = await queryCollection(event, 'docs').path(slug).first()
  return page
})
请确保创建包含以下内容的 server/tsconfig.json 文件以避免类型错误。
{
  "extends": "../.nuxt/tsconfig.server.json"
}