---
title: "useSigmaState"
description: "读写 sigma 的交互状态，把悬停、高亮、隐藏这些纯展示态存在实例内部而不污染图数据。"
canonical_url: "https://sigma.mhaibaraai.cn/docs/composables/use-sigma-state"
---
# useSigmaState

> 读写 sigma 的交互状态，把悬停、高亮、隐藏这些纯展示态存在实例内部而不污染图数据。

## 用法

v4 把交互状态与图数据分开：`isHovered` / `isHighlighted` / `isHidden` / `isDragged` 这类纯展示态存在 sigma 内部，导出图数据时不会把 UI 状态一并带走。styles 里用 `whenState` 消费：

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

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

const customNodeState = { isPinned: false }

const styles: SigmaStyles<typeof customNodeState> = {
  nodes: [
    { whenState: 'isHighlighted', then: { labelVisibility: 'visible' } },
    { whenState: 'isPinned', then: { color: '#0f172b', labelVisibility: 'visible' } }
  ]
}
</script>

<template>
  <SigmaGraph :data="data" :styles="styles" :custom-node-state="customNodeState">
    <UseSigmaStatePanel />
  </SigmaGraph>
</template>
```

```ts
const { setNodeState, setNodesState } = useSigmaState()

setNodeState('a', { isHighlighted: true })
setNodesState(['b', 'c'], { isHidden: true }) // 批量比逐个调用少一次重绘
```

> [!NOTE]
> 
> 实例未就绪时写入静默跳过——服务端与挂载完成前都没有实例可写。读取则返回 
> 
> undefined
> 
> 。

## API

### useSigmaState()

`useSigmaState<NS, ES, GS>(): UseSigmaStateReturn<NS, ES, GS>`

三个泛型分别对应 `SigmaGraph` 的 `customNodeState` / `customEdgeState` / `customGraphState`，缺省时只有内置状态。

#### Returns

**setNodeState** (`(key: string, state: Partial<FullNodeState<NS>>) => void`): 设置单个节点的状态。

**setNodesState** (`(keys: string[], state: Partial<FullNodeState<NS>>) => void`): 批量设置节点状态，比逐个调用少一次重绘。

**setEdgeState** (`(key: string, state: Partial<FullEdgeState<ES>>) => void`): 设置单条边的状态。

**setEdgesState** (`(keys: string[], state: Partial<FullEdgeState<ES>>) => void`): 批量设置边状态。

**setGraphState** (`(state: Partial<FullGraphState<GS>>) => void`): 设置图级状态。

**getNodeState** (`(key: string) => FullNodeState<NS> | undefined`): 读取节点状态，实例未就绪时为 undefined。

**getEdgeState** (`(key: string) => FullEdgeState<ES> | undefined`): 读取边状态。

**getGraphState** (`() => FullGraphState<GS> | undefined`): 读取图级状态。

`FullNodeState` 等来自 `sigma/types`。本库自己的类型从根出口取：

```ts
import type { UseSigmaStateReturn } from '@movk/sigma'
```


## Sitemap

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