Lzh on GitHub

queryCollectionNavigation

queryCollectionNavigation composable 生成给定集合的导航树。

类型

function queryCollectionNavigation<T extends keyof PageCollections>(
  collection: T,
  fields?: Array<keyof PageCollections[T]>
): ChainablePromise<T, ContentNavigationItem[]>

interface ChainablePromise<T extends keyof PageCollections, R> extends Promise<R> {
  where(field: keyof PageCollections[T] | string, operator: SQLOperator, value?: unknown): ChainablePromise<T, R>
  andWhere(groupFactory: QueryGroupFunction<PageCollections[T]>): ChainablePromise<T, R>
  orWhere(groupFactory: QueryGroupFunction<PageCollections[T]>): ChainablePromise<T, R>
  order(field: keyof PageCollections[T], direction: 'ASC' | 'DESC'): ChainablePromise<T, R>
}

用法

使用自动导入的 queryCollectionNavigation 为特定集合生成导航树。这对于基于你的内容结构创建动态导航菜单或侧边栏特别有用。

该函数返回一个可链式调用的 Promise，允许你添加额外的查询条件：

pages/[...slug].vue
<script setup lang="ts">
const { data } = await useAsyncData('navigation', () => {
  return queryCollectionNavigation('docs')
    .where('published', '=', true)
    .order('date', 'DESC')
})
</script>
queryCollectionNavigation 实用工具在 Vue 和 Nitro 中都可用。查看 服务器端用法 以获取有关如何在服务器端使用它的更多详细信息。

使用 .navigation.yml 配置导航元数据

你可以使用 .navigation.yml 文件向目录添加元数据。

.navigation.yml
title: Getting Started
icon: i-lucide-square-play

API

queryCollectionNavigation(collection: CollectionName, extraField: keyof Collection)

为指定的集合生成导航树。

  • Parameters:
    • collection: 在 content.config.ts 中定义的集合的键。
    • extraFields: (可选) 要包含在导航项中的附加字段的数组。（默认情况下，导航项中包含 title 和 path。）
  • Returns: 一个可链式调用的 Promise，它解析为一个导航树结构。该 Promise 包含用于添加查询条件的方法：
    • where(field, operator, value): 添加 WHERE 条件
    • andWhere(groupFactory): 添加分组的 AND 条件
    • orWhere(groupFactory): 添加分组的 OR 条件
    • order(field, direction): 添加 ORDER BY 子句

导航树是基于目录结构生成的，排序是基于文件 排序 进行的。

示例

不带附加查询条件的基本用法：

pages/[...slug].vue
<script setup lang="ts">
const { data } = await useAsyncData('navigation', () => {
  return queryCollectionNavigation('docs')
})
</script>

<template>
  <nav>
    <ul v-if="data">
      <li v-for="item in data" :key="item.path">
        <NuxtLink :to="item.path">{{ item.title }}</NuxtLink>
      </li>
    </ul>
  </nav>
</template>

带有附加查询条件和额外字段的示例：

pages/[...slug].vue
<script setup lang="ts">
const { data } = await useAsyncData('navigation', () => {
  return queryCollectionNavigation('docs', ['description', 'badge'])
    .where('draft', '=', false)
    .where('partial', '=', false)
    .order('title', 'ASC')
})
</script>

<template>
  <nav>
    <ul v-if="data">
      <li v-for="item in data" :key="item.path">
        <NuxtLink :to="item.path">
          {{ item.title }}
          <span v-if="item.badge" class="badge">{{ item.badge }}</span>
        </NuxtLink>
        <p v-if="item.description">{{ item.description }}</p>
      </li>
    </ul>
  </nav>
</template>

服务器端用法

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

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

导航的额外工具

Content 模块提供了一些额外的实用工具，用于简化常见用例（如构建面包屑导航）。

findPageHeadline(navigation, path, options?)

返回导航树中指定路径的标题（父文件夹名称）。适用于显示章节标题或上下文导航头部。

  • navigation：导航树（ContentNavigationItem 数组）。
  • path：当前页面路径。
  • options（可选）：
    • indexAsChild：将索引页面视为子页面。

示例：

import { findPageHeadline } from '@nuxt/content/utils'

const headline = findPageHeadline(navigation, '/docs/guide/getting-started')
// headline is a string that contains the name of the parent folder

findPageBreadcrumb(navigation, path, options?)

返回导航树中指定路径的面包屑路径（导航项数组）。适用于构建面包屑导航组件。

  • navigation：导航树（ContentNavigationItem 数组）。
  • path：当前页面路径。
  • options（可选）：
    • current：在面包屑中包含当前页面。
    • indexAsChild：将索引页面视为子页面。

示例：

import { findPageBreadcrumb } from '@nuxt/content/utils'
const breadcrumb = findPageBreadcrumb(navigation, '/docs/guide/getting-started')
// breadcrumb 是导向当前页面的导航项数组

findPageChildren(navigation, path, options?)

查找并返回导航树中指定路径的直接子项。

  • navigation：导航树（ContentNavigationItem 数组）。
  • path：需查找子项的父路径。
  • options（可选）：
    • indexAsChild：将索引页面视为子页面。

示例：

import { findPageChildren } from '@nuxt/content/utils'

const children = findPageChildren(navigation, '/docs/guide')
// children is an array of navigation items under '/docs/guide'

findPageSiblings(navigation, path, options?)

返回指定路径的兄弟导航项（即同一父项下的其他项）。

  • navigation：导航树（ContentNavigationItem 数组）。
  • path：当前页面路径。
  • options（可选）：
    • indexAsChild：将索引页面视为子页面。

示例：

import { findPageSiblings } from '@nuxt/content/utils'

const siblings = findPageSiblings(navigation, '/docs/guide/getting-started')
// siblings is an array of navigation items that share the same parent as the current page