useDocsFilterConfig

侧栏导航过滤框的配置、显示条件与过滤函数,对应 app.config 的 aside.filter。自定义侧栏顶部或侧栏主体组件时,用这些函数保持与默认过滤行为一致。

侧栏过滤由 useDocsFilterConfig.ts 中的三个导出协作完成:useDocsFilterConfig 读取配置,useDocsFilterVisible 决定是否显示过滤框,filterNavigation 按输入过滤分组。过滤词由 docs 布局以 provide('docsFilterSearch', ref('')) 共享,切换路由时清空。

用法

开启过滤框:

app/app.config.ts
export default defineAppConfig({
  aside: {
    filter: {
      enabled: true,
      threshold: 10,
      shortcut: '/'
    }
  }
})

在自定义的 DocsAsideLeftTop 中读取配置:

app/components/DocsAsideLeftTop.vue
<script setup lang="ts">
const searchTerm = inject<Ref<string>>('docsFilterSearch', ref(''), false)
const { placeholder } = useDocsFilterConfig()
</script>

<template>
  <UInput v-model="searchTerm" :placeholder="placeholder" />
</template>

签名

function useDocsFilterConfig(): {
  enabled: ComputedRef<boolean>
  placeholder: ComputedRef<string>
  threshold: ComputedRef<number>
  shortcut: ComputedRef<string>
}

function useDocsFilterVisible(): ComputedRef<boolean>

function filterNavigation(
  groups: ContentNavigationItem[],
  term: string,
  scoreItem: (item: ContentNavigationItem, term: string, fields: string[]) => unknown
): ContentNavigationItem[]

返回值

useDocsFilterConfig():

名称类型说明
enabledComputedRef<boolean>aside.filter.enabled,默认 false
placeholderComputedRef<string>aside.filter.placeholder,留空时使用内置翻译 docs.filterPlaceholder
thresholdComputedRef<number>aside.filter.threshold,默认 10
shortcutComputedRef<string>aside.filter.shortcut,默认 /;空字符串表示不绑定快捷键

useDocsFilterVisible() 返回 ComputedRef<boolean>:过滤已启用,且当前栏目各分组的页面总数不少于 threshold 时为 true。

filterNavigation() 返回过滤后的分组:term 为空时原样返回;否则按 title、description 匹配页面,子项命中时保留其父级,没有命中项的分组被移除。scoreItem 通常取自 Nuxt UI 的 useFilter():

import { useFilter } from '@nuxt/ui/composables'

const { scoreItem } = useFilter()
const filtered = computed(() => filterNavigation(navigationByCategory.value, searchTerm.value, scoreItem))

相关

更新日志

No recent changes
Copyright © 2024 - 2026