---
title: "useSigmaFilter"
description: "声明式过滤，落到 sigma 的 isHidden 状态上，不改动图数据本身。"
canonical_url: "https://sigma.mhaibaraai.cn/docs/composables/use-sigma-filter"
---
# useSigmaFilter

> 声明式过滤，落到 sigma 的 isHidden 状态上，不改动图数据本身。

## 用法

写一个谓词，返回 `true` 保留、`false` 隐藏：

```vue [UseSigmaFilterExample.vue]
<script setup lang="ts">
const { data } = await useFetch('/api/data.json')
</script>

<template>
  <SigmaGraph :data="data">
    <UseSigmaFilterPanel />
  </SigmaGraph>
</template>
```

```vue [UseSigmaFilterPanel.vue]
<script setup lang="ts">
const { nodeFilter, only, reset, hiddenCount } = useSigmaFilter()

nodeFilter.value = (key, attributes) => attributes.category === '核心'

only(neighborhood('11.0')) // 或者直接给一批 key
</script>
```

### `hideDanglingEdges`

任一端点被隐藏时一并隐藏该边——否则会看到一堆连向空白处的断线。这条规则只在 `nodeFilter` 非空时生效，边的隐藏先看显式的 `edgeFilter`，再看它。

```vue [UseSigmaFilterDanglingExample.vue]
<script setup lang="ts">
defineProps<{ hideDanglingEdges: boolean }>()

const { data } = await useFetch('/api/data.json')
</script>

<template>
  <SigmaGraph :data="data">
    <UseSigmaFilterDanglingPanel
      :key="String(hideDanglingEdges)"
      :hide-dangling-edges="hideDanglingEdges"
    />
  </SigmaGraph>
</template>
```

## 示例

### 换谓词才触发重绘

库监听的是 `nodeFilter` / `edgeFilter` 两个 ref 的**赋值**，在既有闭包里改状态不会触发重绘：

```ts
// 错：谓词只赋值一次，之后改 keyword 不会重绘
nodeFilter.value = (_key, attrs) => String(attrs.label).includes(keyword.value)

// 对：每次都重新赋值
watch(keyword, (value) => {
  nodeFilter.value = (_key, attrs) => String(attrs.label).includes(value)
})
```

`only(null)` 只清 `nodeFilter`，`edgeFilter` 保持不变；`reset()` 才是两个都清。

### hiddenCount 是 O(n)

每次图变更或谓词更换都会全量遍历一遍节点，`nodeFilter` 为 `null` 时直接返回 `0`，不遍历。万级图上频繁触发要留意。

## API

### useSigmaFilter()

`useSigmaFilter(options?: UseSigmaFilterOptions): UseSigmaFilterReturn`

#### Options

**hideDanglingEdges** (`boolean`): 默认 true —— 任一端点被隐藏时一并隐藏该边。仅在 nodeFilter 非空时生效。

#### Returns

**nodeFilter** (`Ref<SigmaNodePredicate | null>`): 节点谓词，可写。为 null 表示不过滤。重新赋值才触发重绘。

**edgeFilter** (`Ref<SigmaEdgePredicate | null>`): 边谓词，可写。为 null 表示不过滤。

**only()** (`(keys: Iterable<string> | null) => void`): 只保留给定的节点。传 null 清空节点谓词，不影响边谓词。

**reset()** (`() => void`): 清空所有过滤。

**hiddenCount** (`ComputedRef<number>`): 当前被隐藏的节点数。无节点谓词时为 0。

`SigmaNodePredicate` 与 `SigmaEdgePredicate` 的形态都是 `(key: string, attributes: Attributes) => boolean`，返回 `true` 表示保留。类型从根出口取：

```ts
import type { SigmaEdgePredicate, SigmaNodePredicate, UseSigmaFilterOptions, UseSigmaFilterReturn } from '@movk/sigma'
```


## Sitemap

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