---
title: "useSigmaNeighborhood"
description: "以某节点为中心逐层扩散的 BFS 邻域计算，以及「点击展开」的远端增量合入。"
canonical_url: "https://sigma.mhaibaraai.cn/docs/composables/use-sigma-neighborhood"
---
# useSigmaNeighborhood

> 以某节点为中心逐层扩散的 BFS 邻域计算，以及「点击展开」的远端增量合入。

## 用法

`neighborhood()` 是纯计算，返回节点集合，怎么用由你决定——高亮、过滤、统计都行：

```vue [UseSigmaNeighborhoodExample.vue]
<script setup lang="ts">
import type { SigmaStyles } from '@movk/sigma'

defineProps<{ depth: number }>()

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

interface NodeState { reach: string }

const customNodeState: NodeState = { reach: 'out' }

const styles: SigmaStyles<NodeState> = {
  nodes: [{
    matchState: 'reach',
    cases: {
      center: { color: '#f43f5e', zIndex: 2 },
      hit: { color: '#3b82f6', zIndex: 1 },
      out: { color: '#d1d5db', labelVisibility: 'hidden' }
    }
  }]
}
</script>

<template>
  <SigmaGraph :data="data" :styles="styles" :custom-node-state="customNodeState">
    <UseSigmaNeighborhoodPanel :key="depth" :depth="Number(depth)" />
  </SigmaGraph>
</template>
```

```ts
const { neighborhood } = useSigmaNeighborhood({ depth: 2 })
const { only } = useSigmaFilter()

only(neighborhood('11.0')) // 只显示某节点的二度邻域
```

### `depth`

默认邻域深度，`neighborhood()` 与 `neighborhoodEdges()` 的 `depth` 参数省略时取此值；逐次调用时也可以在参数里覆盖。

## 示例

### 结果含节点自身

`neighborhood('a')` 返回的集合里**包含 'a'**，可以直接喂给过滤器或高亮逻辑。节点不在图上时返回**空集**，而不是只含该 key 的单元素集合。

`neighborhoodEdges()` 返回的是两端都落在邻域内的边——只有一端在里面的边不算，否则会带出邻域之外的节点。

> [!NOTE]
> 
> BFS 走 graphology 的 
> 
> neighbors()
> 
> ，它在有向图上
> 
> 同时返回出入两侧
> 
> 的邻居。这是图谱浏览需要的可达性语义：看某份文件的关联时，引用它的和它引用的都该出现。需要区分方向请自己用 
> 
> graph.outNeighbors()
> 
>  / 
> 
> inNeighbors()
> 
>  写遍历。

### 点击展开

万级图不可能一次性下发。`expand()` 拉取远端邻域并增量合入当前图，内部走 `applyGraphDiff(graph, incoming, { prune: false })`——只添不删，已有节点的坐标沿用，所以布局不会跳、相机不会乱：

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

<template>
  <SigmaGraph :data="data">
    <UseSigmaNeighborhoodExpandPanel />
    <SigmaTooltip />
  </SigmaGraph>
</template>
```

```ts
const { expand, expanded, isExpanding } = useSigmaNeighborhood()

useSigmaEvents({
  clickNode: ({ node }) => {
    if (!expanded.value.has(node)) {
      expand(node, id => $fetch(`/api/graph/nodes/${id}/neighbors`))
    }
  }
})
```

> [!WARNING]
> 
> loader
> 
>  抛出的错误会原样向上传播，
> 
> isExpanding
> 
>  仍会正确复位，但该节点
> 
> 不会
> 
> 进入 
> 
> expanded
> 
> 。请自己 
> 
> catch
> 
>  并给用户反馈，否则失败的展开会静默重试。

### reset 只清记录

`reset()` 清空 `expanded` 集合，**不会**把已经合入图里的节点删掉——它的用途是「让这些节点可以被重新展开一次」。真要回退，重新设置 `SigmaGraph` 的 `data`（`prune` 默认为 `true`，多余的节点会被移除）。

## API

### useSigmaNeighborhood()

`useSigmaNeighborhood(options?: UseSigmaNeighborhoodOptions): UseSigmaNeighborhoodReturn`

#### Options

**depth** (`number`): 默认 1 —— 默认邻域深度。neighborhood() 与 neighborhoodEdges() 的 depth 参数省略时取此值。

#### Returns

**expanded** (`ComputedRef<ReadonlySet<string>>`): 已成功展开过的节点。加载失败的不计入。

**isExpanding** (`Readonly<Ref<boolean>>`): 是否正在拉取远端邻域。

**neighborhood()** (`(key: string, depth?: number) => Set<string>`): 求某节点的 N 度邻域节点集合，含节点自身。节点不存在时返回空集。

**neighborhoodEdges()** (`(key: string, depth?: number) => Set<string>`): 求某节点 N 度邻域内的边集合，只含两端都在邻域内的边。

**expand()** (`(key: string, loader: (key: string) => Promise<SerializedGraph>) => Promise<void>`): 拉取远端邻域并增量合入当前图，已有节点的坐标不受影响。loader 的错误向上传播。

**reset()** (`() => void`): 清空展开记录。不会移除已合入的节点。

`SerializedGraph` 来自 `graphology-types`。本库自己的类型从根出口取：

```ts
import type { UseSigmaNeighborhoodOptions, UseSigmaNeighborhoodReturn } from '@movk/sigma'
```


## Sitemap

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