---
title: "useSigmaEvents"
description: "声明式绑定 sigma 事件，作用域销毁时自动解绑，接受根组件 emits 未覆盖的任意事件名。"
canonical_url: "https://sigma.mhaibaraai.cn/docs/composables/use-sigma-events"
---
# useSigmaEvents

> 声明式绑定 sigma 事件，作用域销毁时自动解绑，接受根组件 emits 未覆盖的任意事件名。

## 用法

`SigmaGraph` 的 `emits` 覆盖了 sigma 事件全集，但只有在**根组件那一层**才能监听。子组件里要接事件就用这个，payload 类型与上游完全一致，不做转换：

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

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

```vue [UseSigmaEventsPanel.vue]
<script setup lang="ts">
useSigmaEvents({
  clickNode: ({ node }) => select(node),
  wheelStage: () => closePanel(),
  afterRender: () => frames.value++
})
</script>
```

### `handlers`

绑定跟着 `sigma` 走：实例尚未创建时等就绪后再绑，实例被替换时先解绑旧的再绑新的，作用域销毁时解绑，都不需要使用方操心。

> [!NOTE]
> 
> handlers
> 
>  对象在绑定时枚举一次键，之后按引用持有。运行期往里加键不会生效——需要动态开关某个处理器，在处理器
> 
> 内部
> 
> 判断，或者走原生 
> 
> sigma.on()
> 
>  / 
> 
> off()
> 
> 。

## 示例

### 三条通道并存

绑定 sigma 事件有三种方式，语义上等价，按位置选：

```vue
<template>
  <!-- 根组件那一层：直接监听 emits -->
  <SigmaGraph :data="data" @click-node="onClickNode" />
</template>
```

```ts
// 子组件里：声明式，自动解绑
useSigmaEvents({ clickNode: onClickNode })

// 需要动态增删绑定时：原生 API 始终可用
const { sigma } = useSigma()
sigma.value?.on('clickNode', onClickNode)
```

### 生命周期事件只能走这条

`beforeRender`、`afterRender`、`resize`、`beforeClear`、`afterClear`、`beforeProcess`、`afterProcess`、`kill` 不是交互事件，但同样是 sigma 事件全集的一部分。覆盖层与缩略图跟随画布同步位置用的就是 `afterRender`——相机移动、图变更、容器缩放都会触发重绘，跟着重绘走即可覆盖全部情况：

```ts
useSigmaEvents({ afterRender: syncPosition })
```

## API

### useSigmaEvents()

`useSigmaEvents(handlers: SigmaEventHandlers): void`

返回 `void`。解绑由作用域负责，没有手动退订的手柄。

#### Parameters

**handlers** (`SigmaEventHandlers`) *required*: 事件名到处理函数的映射。键是任意 SigmaEventType，值的签名与 SigmaEvents[K] 一致，两者都来自 sigma/types。

`SigmaEventHandlers` 的形态是 `{ [K in SigmaEventType]?: SigmaEvents[K] }`。类型从根出口取：

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


## Sitemap

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