# 元数据与筛选

URL: https://caijiao.org/pagefind/tutorial-06-metadata-filters
Source: docs/pagefind/tutorial-06-metadata-filters.md
Description: 介绍 data-pagefind-meta、data-pagefind-filter、默认元数据、属性捕获和筛选查询设计，让搜索结果更有结构。

正文搜索只能告诉用户“哪一页匹配”。如果要展示更好的结果卡片，或按分类、作者、语言筛选，就需要给 Pagefind 提供元数据和筛选字段。

## 元数据

Pagefind 会自动读取一些元数据：

| 字段 | 默认来源 |
| --- | --- |
| `title` | 页面第一个 `h1` |
| `image` | 第一个跟随 `h1` 的图片 |
| `image_alt` | 该图片的 `alt` |

可以用 `data-pagefind-meta` 覆盖或新增字段：

```html
<h1 data-pagefind-meta="title">Pagefind 教程</h1>
<p data-pagefind-meta="description">静态网站搜索入门。</p>
```

也可以从属性中提取：

```html
<img
  src="/images/search-cover.png"
  alt="搜索教程封面"
  data-pagefind-meta="image[src], image_alt[alt]"
>
```

如果页面上没有现成元素，可以直接写内联元数据：

```html
<main data-pagefind-body data-pagefind-meta="section:前端开发">
  ...
</main>
```

## 筛选字段

筛选字段使用 `data-pagefind-filter`：

```html
<main data-pagefind-body data-pagefind-filter="category:教程">
  <h1>Pagefind 教程</h1>
</main>
```

也可以从元素内容或属性里捕获：

```html
<span data-pagefind-filter="author">菜鸟教程</span>
<meta data-pagefind-filter="section[content]" content="前端开发">
```

同一个筛选键可以有多个值，适合标签系统：

```html
<span data-pagefind-filter="tag">搜索</span>
<span data-pagefind-filter="tag">静态站点</span>
```

## API 中使用筛选

```js
const search = await pagefind.search("部署", {
  filters: {
    category: "教程",
    tag: "静态站点"
  }
});
```

保留字 `any`、`all`、`none`、`not` 不应作为筛选键。设计筛选字段时，优先选择稳定、数量有限的维度，例如 `section`、`category`、`language`、`version`。