Vuetify 3：v-data-table自定义键过滤功能失效问题排查

你遇到的核心问题是误解了custom-key-filter的作用，以及没处理空搜索的边界情况，导致过滤逻辑异常。

为什么原有代码失效？ #

1. custom-key-filter的定位错误：它是用来给单个字段提供自定义过滤逻辑的组件属性，会被应用到所有表头字段上。你的函数只检查嵌套字段，当处理id、title这类非嵌套字段时，会返回false；即便嵌套字段返回true，若搜索文本为空时函数没返回true，所有行都会被过滤。
2. 空搜索的边界处理缺失：当搜索框为空时，自定义过滤函数必须返回true，否则所有数据会被默认隐藏。

两种正确实现方式 #

方式一：全局行级过滤（推荐，适合全字段搜索）

直接给v-data-table绑定:filter属性，编写整行的过滤逻辑，覆盖默认的搜索行为：

<template>
  <v-data-table
    :items="items"
    :headers="headers"
    :search="searchQuery"
    :filter="rowFilter"
  />
</template>

<script setup>
import { ref } from 'vue'

const searchQuery = ref('')
const items = ref([
  { id: 1, title: 'Vue入门指南', author: { name: '张三', email: 'zhangsan@example.com' } },
  { id: 2, title: 'Vuetify实战', author: { name: '李四', email: 'lisi@example.com' } },
])

const headers = ref([
  { title: 'ID', key: 'id' },
  { title: '文章标题', key: 'title' },
  { title: '作者姓名', key: 'author.name' },
  { title: '作者邮箱', key: 'author.email' },
])

const rowFilter = (item, search) => {
  if (!search) return true // 空搜索时返回true，显示所有数据
  const lowerSearch = search.toLowerCase()
  // 检查所有需要匹配的字段，包括嵌套对象
  return (
    item.id.toString().includes(lowerSearch) ||
    item.title.toLowerCase().includes(lowerSearch) ||
    item.author.name.toLowerCase().includes(lowerSearch) ||
    item.author.email.toLowerCase().includes(lowerSearch)
  )
}
</script>

方式二：针对单个嵌套字段配置过滤

如果只需要对特定嵌套字段做自定义搜索，其他字段用默认逻辑，在表头配置中给对应字段添加customFilter：

<template>
  <v-data-table
    :items="items"
    :headers="headers"
    :search="searchQuery"
  />
</template>

<script setup>
import { ref } from 'vue'

const searchQuery = ref('')
const items = ref([
  { id: 1, title: 'Vue入门指南', author: { name: '张三', email: 'zhangsan@example.com' } },
  { id: 2, title: 'Vuetify实战', author: { name: '李四', email: 'lisi@example.com' } },
])

const headers = ref([
  { title: 'ID', key: 'id' },
  { title: '文章标题', key: 'title' },
  {
    title: '作者信息',
    key: 'author',
    // 针对author嵌套字段的自定义过滤逻辑
    customFilter: (author, search) => {
      if (!search) return true
      const lowerSearch = search.toLowerCase()
      return author.name.toLowerCase().includes(lowerSearch) || author.email.toLowerCase().includes(lowerSearch)
    },
    // 自定义单元格显示内容
    render: (item) => `${item.author.name} (${item.author.email})`
  },
])
</script>

关键注意点 #

• 所有自定义过滤函数都必须处理空搜索的情况，返回true，否则空搜索时数据会被全部隐藏。
• 若要实现全字段的嵌套搜索，优先使用全局filter属性，而非custom-key-filter，后者更适合统一修改所有字段的默认过滤规则（比如忽略大小写、模糊匹配逻辑）。

内容的提问来源于stack exchange，提问作者Steve Janke