---
title: "useSigmaSettings"
description: "把响应式的配置同步到 sigma，源变化即调用 setSettings，整体透传不做键过滤。"
canonical_url: "https://sigma.mhaibaraai.cn/docs/composables/use-sigma-settings"
---
# useSigmaSettings

> 把响应式的配置同步到 sigma，源变化即调用 setSettings，整体透传不做键过滤。

## 用法

`SigmaGraph` 的 `settings` prop 已经是响应式的，这个 composable 解决的是**子组件里**要改配置的场景——不必把状态一路上传到根组件：

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

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

```vue [UseSigmaSettingsPanel.vue]
<script setup lang="ts">
const labels = shallowRef(true)
const density = shallowRef(1)

useSigmaSettings(computed(() => ({
  renderLabels: labels.value,
  labelDensity: density.value
})))
</script>
```

### `source`

接受普通对象、ref、`computed` 或 getter，整体交给 `sigma.setSettings()`，不逐字段枚举也不过滤未知键——sigma 新增的配置项无需本库升级即可使用。

监听是 `deep: true` 的，改嵌套字段也会重新应用。实例为 `null` 时（SSR、挂载完成前）是空操作，实例出现或被替换后自动重新应用：

```ts
const settings = reactive({ hideEdgesOnMove: true, zoomToSizeRatioFunction: fn })
useSigmaSettings(settings) // 改任何一层都会触发
```

## 示例

### 与 settings prop 的分工

两者最终都调 `setSettings()`，选哪个看状态住在哪里：

**settings prop**: 配置由页面持有，或需要与模块选项里的全局 settings 深度合并。合并后组件级优先。

**useSigmaSettings()**: 配置由子组件持有（控制面板、调试工具）。不参与与全局默认的合并，直接覆盖同名键。

## API

### useSigmaSettings()

`useSigmaSettings(source: MaybeRefOrGetter<Partial<Settings>>): void`

返回 `void`。停止同步靠作用域销毁。

#### Parameters

**source** (`MaybeRefOrGetter<Partial<Settings>>`) *required*: 配置源，接受普通对象、ref、computed 或 getter。深度监听，整体透传给 sigma.setSettings()。

`Settings` 来自 `sigma/settings`，需要时从原包直接 import：

```ts
import type { Settings } from 'sigma/settings'
```


## Sitemap

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