---
title: "useDocsFilterConfig"
description: "侧栏导航过滤框的配置、显示条件与过滤函数，对应 app.config 的 aside.filter。自定义侧栏顶部或侧栏主体组件时，用这些函数保持与默认过滤行为一致。"
canonical_url: "https://docs.mhaibaraai.cn/docs/reference/composables/use-docs-filter-config"
---
# useDocsFilterConfig

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

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

## 用法

开启过滤框：

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

在自定义的 `DocsAsideLeftTop` 中读取配置：

```vue [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>
```

## 签名

```ts
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()`：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `enabled` | `ComputedRef<boolean>` | `aside.filter.enabled`，默认 `false` |
| `placeholder` | `ComputedRef<string>` | `aside.filter.placeholder`，留空时使用内置翻译 `docs.filterPlaceholder` |
| `threshold` | `ComputedRef<number>` | `aside.filter.threshold`，默认 `10` |
| `shortcut` | `ComputedRef<string>` | `aside.filter.shortcut`，默认 `/`；空字符串表示不绑定快捷键 |

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

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

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

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

## 相关

- [app.config 参考](https://docs.mhaibaraai.cn/docs/reference/app-config)
- [useNavigation](https://docs.mhaibaraai.cn/docs/reference/composables/use-navigation)

## 更新日志

See commit history for [layer/app/composables/useDocsFilterConfig.ts](https://github.com/mhaibaraai/movk-nuxt-docs/commits/main/layer/app/composables/useDocsFilterConfig.ts).

---

- [GitHub](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/composables/useDocsFilterConfig.ts)


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
