---
title: "useSigmaLabelTiers"
description: "按相机比例分级显示标签，视野越广只留下越重要的那几档。"
canonical_url: "https://sigma.mhaibaraai.cn/docs/composables/use-sigma-label-tiers"
---
# useSigmaLabelTiers

> 按相机比例分级显示标签，视野越广只留下越重要的那几档。

## 用法

拉远之后节点变密，标签再全出就只剩噪声。档位先由 [`degreeToTier()`](https://sigma.mhaibaraai.cn/docs/utils/degree-to-tier) 写进属性，本 composable 只决定「当前该显示到哪一档」：

```vue [UseSigmaLabelTiersExample.vue]
<script setup lang="ts">
import Graph from 'graphology'
import type { StylesDeclaration } from 'sigma/types'

const props = defineProps<{ breakpoints: string }>()

const { data: dataset } = await useFetch('/api/wikipedia.json', { server: false })

const graph = computed(() => {
  if (!dataset.value) {
    return null
  }

  const instance = new Graph()
  instance.import(dataset.value.data)

  for (const [node, tier] of Object.entries(degreeToTier(instance))) {
    instance.setNodeAttribute(node, 'labelTier', tier)
  }

  return instance
})

const parsed = computed(() =>
  props.breakpoints.split('/').map((ratio, index) => [Number(ratio), index] as const)
)

const styles = computed<StylesDeclaration>(() => ({
  nodes: {
    color: { attribute: 'cluster', dict: dataset.value?.clusterColors ?? {}, defaultValue: '#94a3b8' },
    size: {
      attribute: 'score',
      min: 4,
      max: 18,
      minValue: dataset.value?.scoreExtent[0],
      maxValue: dataset.value?.scoreExtent[1]
    },
    labelSize: { attribute: 'labelTier', dict: { 0: 14, 1: 12, 2: 11 }, defaultValue: 12 },
    labelColor: { attribute: 'labelTier', dict: { 0: '#0f172a', 1: '#1e293b', 2: '#64748b' }, defaultValue: '#1e293b' }
  }
}))
</script>

<template>
  <SigmaGraph
    v-if="graph"
    :graph="graph"
    :styles="styles"
    :settings="{ itemSizesReference: 'screen', hideEdgesOnMove: true, renderEdgeLabels: false }"
  >
    <UseSigmaLabelTiersPanel :key="breakpoints" :breakpoints="parsed" />
  </SigmaGraph>
</template>
```

```ts
const { tier } = useSigmaLabelTiers({ breakpoints: [[2.6, 0], [1.3, 1]] })
```

### `breakpoints`

`[ratio, tier]` 的列表，按 `ratio` 降序，`ratio` 越大视野越广。上面那组读作：比例超过 2.6 只留 0 档，超过 1.3 留到 1 档，再近就不限制。自动 fit 之后比例通常落在 1 附近，默认值因此从 1.3 起跳。

### `attribute`

读取节点档位的属性名，需与 styles 里消费该档位的属性名一致。`degreeToTier()` 默认就写在 `labelTier` 上。

## API

### useSigmaLabelTiers()

`useSigmaLabelTiers(options?: UseSigmaLabelTiersOptions): UseSigmaLabelTiersReturn`

必须在 `SigmaGraph` 子树内调用。作用域销毁时自动解绑相机监听并把档位复位。

#### Options

**breakpoints** (`readonly SigmaLabelTierBreakpoint[]`): 默认 [[2.6, 0], [1.3, 1]] —— 相机比例断点 [ratio, tier]，按 ratio 降序排列。比例大于 ratio 时只显示不高于 tier 的档位。

**attribute** (`string`): 默认 'labelTier' —— 读取节点档位的属性名，需与 styles 里消费该档位的属性名一致。

#### Returns

**tier** (`Readonly<Ref<number>>`): 当前允许显示的最低档位。所有断点都未命中时为 Infinity，即不限制。

`SigmaLabelTierBreakpoint` 的形态是 `readonly [ratio: number, tier: number]`。类型从根出口取：

```ts
import type { SigmaLabelTierBreakpoint, UseSigmaLabelTiersOptions, UseSigmaLabelTiersReturn } from '@movk/sigma'
```


## Sitemap

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