---
title: "defineSigmaPrimitives"
description: "声明一份延迟加载的渲染原语，绕开 sigma 在模块顶层读取 WebGL 全局导致的 SSR 崩溃。"
canonical_url: "https://sigma.mhaibaraai.cn/docs/utils/define-sigma-primitives"
---
# defineSigmaPrimitives

> 声明一份延迟加载的渲染原语，绕开 sigma 在模块顶层读取 WebGL 全局导致的 SSR 崩溃。

## 用法

sigma v4 的**每个**子路径在模块顶层就读 `WebGL2RenderingContext`——`sigma`、`sigma/rendering`、`sigma/primitives`、`sigma/types` 无一例外。服务端没有这个全局，静态 import 会让 SSR 直接 ReferenceError。这个函数把原语声明包成一个加载函数，`SigmaGraph` 在客户端建实例前才解析它：

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

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

const primitives = defineSigmaPrimitives(async () => {
  const { sdfCircle, layerFill, pathLine, pathCurved, pathLoop, extremityArrow } = await import('sigma/rendering')

  return {
    nodes: {
      shapes: [sdfCircle(), sdfPolygon({ name: 'hexagon', sides: 6 })],
      layers: [layerFill()]
    },
    edges: {
      paths: [pathLine(), pathCurved(), pathLoop()],
      extremities: [extremityArrow()]
    }
  }
})

const styles: StylesDeclaration = {
  nodes: {
    shape: { attribute: 'category', dict: { 核心: 'hexagon', 次要: 'hexagon' }, defaultValue: 'circle' },
    color: { attribute: 'category', dict: { 核心: '#f43f5e', 次要: '#3b82f6', 边缘: '#22c55e' }, defaultValue: '#64748b' },
    size: { attribute: 'category', dict: { 核心: 16, 次要: 14, 边缘: 12 }, defaultValue: 12 }
  },
  edges: {
    parallelPath: 'curved',
    parallelSpread: 3,
    selfLoopPath: 'loop',
    head: 'arrow'
  }
}
</script>

<template>
  <SigmaGraph
    :data="data"
    :primitives="primitives"
    :styles="styles"
  />
</template>
```

```ts
const primitives = defineSigmaPrimitives(async () => {
  const { sdfCircle, layerFill, pathCurved, extremityArrow } = await import('sigma/rendering')

  return {
    nodes: { shapes: [sdfCircle(), sdfPolygon({ name: 'hexagon', sides: 6 })], layers: [layerFill()] },
    edges: { paths: [pathCurved()], extremities: [extremityArrow()] }
  }
})
```

> [!NOTE]
> 
> 本库的 
> 
> sdfPolygon()
> 
>  与 
> 
> sdfStar()
> 
>  返回纯数据、不引用 sigma 的任何值，可以直接写在外层。只有内置工厂函数需要延迟。

### 必须是函数，不能是 Promise

模块级的 `import()` 表达式在服务端同样会被求值，写成 `import('sigma/rendering').then(...)` 一样崩。必须是一个**函数**，组件在客户端才调用它。类型则不受影响——`import type` 编译期擦除，从 `sigma/primitives` 取 `PrimitivesDeclaration` 是安全的。

### 边的 path / head 也能按属性绑定切换

primitives 里注册的每个 path / extremity 只是一个名字，`styles.edges` 用与节点 `shape` 相同的 attribute-dict 绑定机制，按边的数据选取：

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

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

/**
 * path/head 与节点的 shape 走同一套 attribute-dict 绑定：primitives 注册可用的
 * path/extremity 名字，styles 按边的 kind 属性选取，数据决定每条边用哪种线型
 */
const primitives = defineSigmaPrimitives(async () => {
  const { pathLine, pathCurved, pathStep, pathLoop, extremityArrow, extremityCircle } = await import('sigma/rendering')

  return {
    edges: {
      paths: [pathLine(), pathCurved(), pathStep(), pathLoop()],
      extremities: [extremityArrow(), extremityCircle()]
    }
  }
})

const styles: StylesDeclaration = {
  nodes: {
    color: '#64748b',
    size: 14
  },
  edges: {
    path: { attribute: 'kind', dict: { assoc: 'line', flow: 'curved', dependency: 'step' }, defaultValue: 'line' },
    head: { attribute: 'kind', dict: { flow: 'arrow', dependency: 'circle' }, defaultValue: 'none' },
    // 平行边与自环由这三个字段接管，其余边才轮到 path 按 kind 选取
    parallelPath: 'curved',
    parallelSpread: 3,
    selfLoopPath: 'loop'
  }
}
</script>

<template>
  <SigmaGraph
    :data="data"
    :primitives="primitives"
    :styles="styles"
    :settings="{ renderEdgeLabels: true }"
  />
</template>
```

```ts
const styles = {
  edges: {
    path: { attribute: 'kind', dict: { assoc: 'line', flow: 'curved', dependency: 'step' }, defaultValue: 'line' },
    head: { attribute: 'kind', dict: { flow: 'arrow', dependency: 'circle' }, defaultValue: 'none' }
  }
}
```

sigma 默认只注册 `pathLine()` 与 `pathLoop()`，且不带端点。曲线、阶梯线、箭头、圆点端点都要在 `primitives.edges` 里显式注册才能被 styles 引用。

## API

### defineSigmaPrimitives()

`defineSigmaPrimitives(loader: () => PrimitivesDeclaration | Promise<PrimitivesDeclaration>): SigmaLazyPrimitives`

#### Parameters

**loader** (`() => PrimitivesDeclaration | Promise<PrimitivesDeclaration>`) *required*: 返回原语声明的函数，可同步可异步。SigmaGraph 在创建实例前调用一次。

#### Returns

`SigmaLazyPrimitives`，直接传给 `SigmaGraph` 的 `primitives`。该 prop 同时接受已解析的 `PrimitivesDeclaration`。

类型从根出口取：

```ts
import type { SigmaLazyPrimitives, SigmaPrimitivesSource } from '@movk/sigma'
```


## Sitemap

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