---
title: "useSigmaSelection"
description: "悬浮与选中的状态机，把焦点及其邻居写进 isHighlighted 状态，其余元素由库内规则淡出。"
canonical_url: "https://sigma.mhaibaraai.cn/docs/composables/use-sigma-selection"
---
# useSigmaSelection

> 悬浮与选中的状态机，把焦点及其邻居写进 isHighlighted 状态，其余元素由库内规则淡出。

## 用法

开箱即用——调用一次就接好了悬浮、点击、高亮、淡出四件事：

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

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

<template>
  <SigmaGraph :data="data">
    <UseSigmaSelectionPanel :key="String(dim)" :dim="dim" />
    <SigmaTooltip />
  </SigmaGraph>
</template>
```

```vue [UseSigmaSelectionPanel.vue]
<script setup lang="ts">
const { hovered, selected, focused, highlighted, select, clear } = useSigmaSelection()
</script>
```

### `hover` / `click`

两个开关只在 setup 时读一次，用来决定要不要绑定对应的事件，挂载后改它们没有效果。需要运行期开关，保持默认并在自己的逻辑里判断：

```ts
const { select } = useSigmaSelection({ click: false })

useSigmaEvents({
  clickNode: ({ node }) => {
    if (canSelect.value) {
      select(node)
    }
  }
})
```

内建行为是：点击已选中的节点取消选中，点击画布空白处清空。

### `dim`

打开时焦点及其一度邻居写 `isHighlighted: true`，其余节点与边染成 `dimColor`、隐藏标签、`zIndex: 0`；关掉则只写状态，外观完全交给自己的 styles（`whenState: 'isHighlighted'`）。

### `dimColor`

淡出后的颜色。库内规则的形状固定在构造期，`dimColor` 由闭包实时读取，改它不会重建实例。

> [!NOTE]
> 
> 库内规则排在用户 
> 
> styles
> 
>  之后，因而盖得住自定义配色。

## 示例

### 选中压过悬浮

`focused` 是 `selected ?? hovered`——选中之后鼠标扫过其他节点不会打断当前焦点。`hovered` 只读，由鼠标事件唯一决定；`selected` 可写，能从外部驱动：

```ts
watch(searchResult, (result) => {
  selected.value = result?.id ?? null
})
```

`highlighted` 暴露的就是「焦点 + 直接邻居」这个集合，只算一度邻居；要更深的范围用 [`useSigmaNeighborhood()`](https://sigma.mhaibaraai.cn/docs/composables/use-sigma-neighborhood)。

### 与 useSigmaFilter 的关系

被 [`useSigmaFilter()`](https://sigma.mhaibaraai.cn/docs/composables/use-sigma-filter) 过滤掉的元素落的是 `isHidden` 状态，`DEFAULT_STYLES` 把它绑到独占的 `visibility` 上，元素整体退出渲染与拾取。因此这里无需为它们做特殊处理——淡出规则只碰 `color` 一类的普通字段，悬浮与点击也命中不到已退出拾取缓冲的元素。

## API

### useSigmaSelection()

`useSigmaSelection(options?: UseSigmaSelectionOptions): UseSigmaSelectionReturn`

#### Options

**hover** (`boolean`): 默认 true —— 悬浮节点时进入高亮。仅在 setup 时读取一次。

**click** (`boolean`): 默认 true —— 点击节点选中，再次点击同一节点取消；点击空白处清空。仅在 setup 时读取一次。

**dim** (`boolean`): 默认 true —— 高亮时把无关的节点与边淡出。

**dimColor** (`string`): 默认 '#d1d5db' —— 淡出后的颜色。

#### Returns

**hovered** (`Readonly<Ref<string | null>>`): 当前悬浮的节点。

**selected** (`Ref<string | null>`): 当前选中的节点，可写。

**focused** (`ComputedRef<string | null>`): 当前焦点，等于 selected ?? hovered。

**highlighted** (`ComputedRef<Set<string>>`): 焦点节点及其直接邻居。无焦点或焦点已不在图上时为空集。

**select()** (`(key: string | null) => void`): 设置选中，传 null 清空。

**clear()** (`() => void`): 清空悬浮与选中。

类型从根出口取：

```ts
import type { UseSigmaSelectionOptions, UseSigmaSelectionReturn } from '@movk/sigma'
```


## Sitemap

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