Nuxt Content 中的 queryCollection 查询工具详解

Nuxt Content 中的 queryCollection 查询工具详解

content The file-based CMS for your Nuxt application, powered by Markdown and Vue components. 项目地址: https://gitcode.com/gh_mirrors/con/content

前言

在 Nuxt Content 项目中，queryCollection 是一个强大的组合式函数，专门用于查询和获取内容集合中的数据。本文将全面解析这个工具的使用方法、API 接口以及实际应用场景，帮助开发者更好地利用 Nuxt Content 管理内容数据。

什么是 queryCollection

queryCollection 是 Nuxt Content 提供的一个查询构建器，它允许开发者以编程方式查询已定义的内容集合。通过链式调用各种方法，可以构建复杂的查询条件，精确获取所需的内容数据。

基本用法

要使用 queryCollection，首先需要确保已经在 content.config.ts 中定义了内容集合。假设我们有一个名为 docs 的集合，下面是基本查询示例：

<script>
const route = useRoute()
const { data: page } = await useAsyncData(route.path, () => {
  return queryCollection('docs').path(route.path).first()
})
</script>

这段代码会查询 docs 集合中路径与当前路由匹配的第一个文档。

核心 API 详解

1. 查询构建方法

queryCollection(collectionName)

• 功能：创建指定集合的查询构建器
• 参数：集合名称（在 content.config.ts 中定义）

const query = queryCollection('docs') // 创建对 docs 集合的查询

2. 查询条件方法

path(pathString)

• 功能：按路径查询内容
• 参数：要匹配的路径字符串

queryCollection('docs').path('/getting-started') // 查询路径为 /getting-started 的文档

where(field, operator, value)

• 功能：添加字段过滤条件
• 参数：
  • field: 字段名
  • operator: 比较运算符（=, >, <, IN, BETWEEN 等）
  • value: 比较值

queryCollection('docs')
  .where('date', '<', '2024-04-04') // 查询日期早于 2024-04-04 的文档

andWhere(groupFunction)

• 功能：添加 AND 条件组
• 参数：接收查询构建器的函数，用于构建复杂条件

queryCollection('docs')
  .andWhere(q => q.where('published', true).where('category', '=', 'news'))

orWhere(groupFunction)

• 功能：添加 OR 条件组
• 参数：接收查询构建器的函数

queryCollection('docs')
  .orWhere(q => q.where('featured', true).where('priority', '>', 5))

3. 结果处理方法

select(...fields)

• 功能：指定返回的字段
• 参数：要返回的字段名列表

queryCollection('docs')
  .select('title', 'description', 'author') // 只返回这三个字段

order(field, direction)

• 功能：排序结果
• 参数：
  • field: 排序字段
  • direction: 'ASC' 或 'DESC'

queryCollection('docs')
  .order('date', 'DESC') // 按日期降序排列

limit(number)

• 功能：限制返回结果数量
• 参数：最大返回数量

queryCollection('docs')
  .limit(10) // 最多返回10条记录

skip(number)

• 功能：跳过指定数量的结果
• 参数：要跳过的数量

queryCollection('docs')
  .skip(5) // 跳过前5条记录

4. 执行方法

all()

• 功能：执行查询并返回所有匹配结果
• 返回：Promise 解析为匹配文档数组

const allDocs = await queryCollection('docs').all()

first()

• 功能：执行查询并返回第一个匹配结果
• 返回：Promise 解析为第一个匹配文档或 null

const firstDoc = await queryCollection('docs').first()

count()

• 功能：返回匹配文档的数量
• 返回：Promise 解析为数字

const docCount = await queryCollection('docs').count()

实际应用示例

示例1：获取最新文档列表

<script setup lang="ts">
const { data: recentDocs } = await useAsyncData('recent-docs', () => {
  return queryCollection('docs')
    .where('published', '=', true)
    .order('date', 'DESC')
    .limit(5)
    .select('title', 'path', 'description', 'date')
    .all()
})
</script>

<template>
  <div v-for="doc in recentDocs" :key="doc.path">
    <h2>{{ doc.title }}</h2>
    <p>{{ doc.description }}</p>
    <time>{{ doc.date }}</time>
  </div>
</template>

示例2：复杂条件查询

const featuredDocs = await queryCollection('docs')
  .where('category', '=', 'featured')
  .andWhere(q => q
    .where('views', '>', 1000)
    .orWhere('rating', '>', 4.5)
  )
  .order('rating', 'DESC')
  .limit(3)
  .all()

服务端使用

在服务端 API 路由中使用 queryCollection 时，需要传递事件对象作为第一个参数：

// server/api/docs/[slug].ts
export default eventHandler(async (event) => {
  const { slug } = getRouterParams(event)
  const doc = await queryCollection(event, 'docs').path(slug).first()
  return doc
})

最佳实践

1. 合理使用缓存：结合 useAsyncData 或 useFetch 使用，避免重复查询
2. 按需选择字段：使用 select() 只获取需要的字段，提高性能
3. 分页处理：对于大量数据，使用 limit() 和 skip() 实现分页
4. 条件组合：利用 andWhere 和 orWhere 构建复杂查询条件

总结

queryCollection 是 Nuxt Content 中一个功能强大的查询工具，通过链式调用提供了灵活的数据查询能力。掌握它的使用方法可以极大地提高内容管理的效率和灵活性。无论是简单的单条件查询还是复杂的多条件组合，queryCollection 都能胜任，是 Nuxt Content 项目中不可或缺的工具。

content The file-based CMS for your Nuxt application, powered by Markdown and Vue components. 项目地址: https://gitcode.com/gh_mirrors/con/content