---
title: "useSigmaExport"
description: "把当前画面导出为 PNG，可取 Blob 自行处理，也可直接触发浏览器下载。"
canonical_url: "https://sigma.mhaibaraai.cn/docs/composables/use-sigma-export"
---
# useSigmaExport

> 把当前画面导出为 PNG，可取 Blob 自行处理，也可直接触发浏览器下载。

## 用法

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

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

```vue [UseSigmaExportPanel.vue]
<script setup lang="ts">
const { download, toBlob, isExporting } = useSigmaExport()

await download('知识图谱.png', { backgroundColor: '#fff' })

// 或者拿到 Blob 自己处理：上传、放进剪贴板、塞进 PDF
const blob = await toBlob({ width: 1920, height: 1080 })
</script>
```

> [!WARNING]
> 
> 需要可选 peer 
> 
> @sigma/export-image
> 
> 。未安装时抛出的错误里带有安装命令，捕获后直接展示给用户即可。它与 sigma 本体一样在模块顶层读 WebGL 全局，所以库内是动态加载的——使用方也不要静态 import 它。

> [!NOTE]
> 
> isExporting
> 
>  在 
> 
> whenReady()
> 
>  与动态导入
> 
> 之后
> 
> 才置位。绑到按钮的 loading 态上通常没问题，但别指望它覆盖首次加载可选依赖的那段时间。

## 示例

### 省略的键整个不传

`SigmaExportOptions` 的每个键在 `undefined` 时都不会出现在传给上游的对象里，由上游决定默认行为：

```vue [UseSigmaExportOverridesExample.vue]
<script setup lang="ts">
defineProps<{ backgroundColor: string, sigmaOverrides: boolean }>()

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

<template>
  <SigmaGraph :data="data">
    <UseSigmaExportOverridesPanel
      :background-color="backgroundColor"
      :sigma-overrides="sigmaOverrides"
    />
  </SigmaGraph>
</template>
```

**width / height**: 省略则用当前视口尺寸。给更大的值可以导出比屏幕更清晰的图。

**backgroundColor**: 省略得到透明背景的 PNG。放进浅色文档里的图通常要显式给 '#fff'，否则透明背景在深色主题下会看不清。

**cameraState**: 省略则沿用当前视角。给一个相机态就能导出与屏幕不同的取景。

### 只对这次导出生效的外观

`sigmaOverrides` 里的 `primitives` / `styles` / `settings` 只作用于这一次导出，屏幕上的实例不受影响。用来导一套与交互态无关的图——去掉选中淡出、换成打印友好的配色、关掉标签：

```ts
await download('print.png', {
  backgroundColor: '#ffffff',
  sigmaOverrides: {
    settings: { renderLabels: false },
    styles: { nodes: { color: '#111827' } }
  }
})
```

`styles` 与 `primitives` 交给上游时同样是**整体替换**，写了就要把需要的规则补全，取舍见 [`composeStyles`](https://sigma.mhaibaraai.cn/docs/utils/compose-styles)。

### 文件名的 .png 可写可不写

上游会按格式自行追加扩展名，库先把调用方带上的 `.png` 剥掉，所以 `'graph'` 与 `'graph.png'` 得到的文件名一致，不会出现 `graph.png.png`。`filename` 默认 `'graph.png'`。

## API

### useSigmaExport()

`useSigmaExport(): UseSigmaExportReturn`

无选项。

#### Returns

**isExporting** (`Readonly<Ref<boolean>>`): 是否正在导出。

**toBlob()** (`(options?: SigmaExportOptions) => Promise<Blob>`): 导出为 PNG 的 Blob。

**download()** (`(filename?: string, options?: SigmaExportOptions) => Promise<void>`): 导出并触发浏览器下载。filename 默认 'graph.png'，.png 后缀可写可不写。

### SigmaExportOptions

**width** (`number`): 导出宽度，省略则用当前视口宽度。

**height** (`number`): 导出高度，省略则用当前视口高度。

**backgroundColor** (`string`): 默认 'transparent' —— 背景色。

**cameraState** (`CameraState`): 导出时的相机状态，省略则沿用当前视角。

**sigmaOverrides** (`{ primitives?, styles?, settings? }`): 只在这次导出生效的渲染覆盖，屏幕上的实例不受影响。三个字段的类型分别是 PrimitivesDeclaration、StylesDeclaration 与 Partial<Settings>。

`CameraState` 等来自 `sigma/types`，`Settings` 来自 `sigma/settings`。本库自己的类型从根出口取：

```ts
import type { SigmaExportOptions, UseSigmaExportReturn } from '@movk/sigma'
```


## Sitemap

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