---
title: "SigmaLegend"
description: "按节点属性聚合的图例，点击条目切换该组显隐，插槽同时给出数据与切换行为。"
canonical_url: "https://sigma.mhaibaraai.cn/docs/components/legend"
---
# SigmaLegend

> 按节点属性聚合的图例，点击条目切换该组显隐，插槽同时给出数据与切换行为。

## 用法

按某个节点属性聚合，每组显示代表色与节点数，点击切换显隐。

切换走的是 [`useSigmaFilter()`](https://sigma.mhaibaraai.cn/docs/composables/use-sigma-filter)，往 sigma 的 `isHidden` 状态上写——**图数据一个字节都没动**。被隐藏的节点仍然参与邻域计算与检索，取消隐藏时立刻回来，不需要重新加载数据。注意该 composable **要求 sigma 至少为 4.0.0-beta.3**，详见它的文档。

连带效果：`useSigmaFilter` 默认 `hideDanglingEdges: true`，端点被隐藏的边也会一并隐藏。

### `field`

用于分组的节点属性名。这份数据集把节点按度数排名分了三档，写在 `category` 上：

```vue [LegendFieldExample.vue]
<script setup lang="ts">
defineProps<{ field: string, colorField: string, fallback: string }>()

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

<template>
  <SigmaGraph :data="data">
    <SigmaControls position="top-right">
      <SigmaLegend :field="field" :color-field="colorField" :fallback="fallback" />
    </SigmaControls>
  </SigmaGraph>
</template>
```

> [!WARNING]
> 
> field
> 
>  默认取 
> 
> 'type'
> 
> ，但在 sigma 里 
> 
> type
> 
>  是
> 
> 渲染程序名
> 
> ，不是业务分类。领域分类几乎总要显式传自己的字段——上面切到 
> 
> type
> 
>  就能看到整张图坍缩成一组。

### `colorField`

取色所用的节点属性名。组色取该组**首个遇到的**节点的该属性，缺失时回落到字面量 `'currentColor'`（即跟随文字颜色）。同组节点颜色不一致时以第一个为准，图例不会去做平均或投票。

这正是上面选择条的用途：数据集的 `color` 是一条按度数排的红色渐变，同档内取值不一，三个色块因而挤在相近的红里；`categoryColor` 每档一色，图例才读得清。

### `fallback`

分组值缺失时归入的组名。`field` 选 `type` 时全图都没有这个属性，于是整张图落进 `fallback` 这一组。

### `toggleable`

点击条目是否切换该组显隐。`false` 时 `toggle()` 是空操作，默认外观下的按钮也会置为 `disabled`：

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

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

<template>
  <SigmaGraph :data="data">
    <SigmaControls position="top-right">
      <SigmaLegend field="category" color-field="categoryColor" :toggleable="toggleable" />
    </SigmaControls>
  </SigmaGraph>
</template>
```

> [!NOTE]
> 
> order
> 
>  默认 
> 
> 200
> 
> ，高于选中高亮的 
> 
> 100
> 
> ，且只在 setup 时读一次，挂载后改这个 prop 不会重新登记。
> 
> visibility
> 
>  是独占字段、不会被后执行的归约器覆盖，所以这个次序影响的是配色谁最终生效，不是显隐本身能否生效。

## 示例

### 默认插槽

作用域除了 `groups`，还给了 `toggle` 与 `reset`。只给数据的话，接管外观就等于丢掉显隐切换——这与「封装是加法」的前提相悖：

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

<template>
  <SigmaGraph :data="data">
    <SigmaControls position="top-right" direction="horizontal">
      <SigmaLegend field="category" color-field="categoryColor">
        <template #default="{ groups, toggle, reset }">
          <div class="flex items-center gap-1">
            <UButton
              v-for="group in groups"
              :key="group.value"
              size="xs"
              color="neutral"
              :variant="group.visible ? 'solid' : 'ghost'"
              @click="toggle(group.value)"
            >
              <span class="size-2 rounded-full" :style="{ background: group.color }" />
              {{ group.value }} · {{ group.count }}
            </UButton>
            <UButton size="xs" variant="outline" color="neutral" label="全部显示" @click="reset" />
          </div>
        </template>
      </SigmaLegend>
    </SigmaControls>
  </SigmaGraph>
</template>
```

**groups** (`SigmaLegendGroup[]`): 聚合结果，随图变化自动重算。分组值，取自节点的 field 属性；缺失时为 fallback。该组的代表色，取该组首个节点的 colorField 属性，缺失时为 'currentColor'。该组的节点数。当前是否可见。

**toggle()** (`(value: string) => void`): 切换某组的显隐。toggleable 为 false 时是空操作。

**reset()** (`() => void`): 全部恢复显示，并清空节点过滤器。

> [!NOTE]
> 
> SigmaLegendGroup
> 
>  声明在组件的 
> 
> <script setup>
> 
>  里，目前
> 
> 不在
> 
>  Movk Sigma 的根出口中。接管插槽时作用域类型由 Vue 自行推断，通常不必显式标注。

### `reset()`

组件实例上也暴露了同一个方法，供图例之外的按钮调用：

```vue [LegendResetExample.vue]
<script setup lang="ts">
const legend = useTemplateRef('legend')

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

<template>
  <SigmaGraph :data="data">
    <SigmaControls position="top-right">
      <SigmaLegend ref="legend" field="category" color-field="categoryColor" />
    </SigmaControls>

    <SigmaControls position="bottom-left">
      <UButton size="xs" color="neutral" label="reset()" @click="legend?.reset()" />
    </SigmaControls>
  </SigmaGraph>
</template>
```

## API

### Props

```ts
/**
 * Props for the SigmaLegend component
 */
interface SigmaLegendProps {
  /**
   * 用于分组的节点属性名
   * @default 'type'
   */
  field?: string | undefined;
  /**
   * 取色所用的节点属性名
   * @default 'color'
   */
  colorField?: string | undefined;
  /**
   * 分组值缺失时归入的组名
   * @default '未分类'
   */
  fallback?: string | undefined;
  /**
   * 点击条目切换该组显隐
   * @default true
   */
  toggleable?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the SigmaLegend component
 */
interface SigmaLegendSlots {
  default(): any;
}
```

### Expose

通过 [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref) 访问该组件实例。

| Name | Type |
| --- | --- |
| `reset()` | `() => void` <br> 全部恢复显示并清空节点过滤器，与插槽作用域里的同名方法一致。 |


## Sitemap

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