---
title: "Vue + Vite"
description: "在纯 Vue 3 + Vite 项目中经 @movk/sigma/vite、@movk/sigma/vue 与 vue-plugin 使用同一套组件与 composables。"
canonical_url: "https://sigma.mhaibaraai.cn/docs/getting-started/vue"
---
# Vue + Vite

> 在纯 Vue 3 + Vite 项目中经 @movk/sigma/vite、@movk/sigma/vue 与 vue-plugin 使用同一套组件与 composables。

## 安装

`sigma` 与 `graphology` 同样由你自己安装：

```bash [pnpm]
pnpm add @movk/sigma sigma graphology
```

```bash [npm]
npm install @movk/sigma sigma graphology
```

```bash [yarn]
yarn add @movk/sigma sigma graphology
```

要走 `@movk/sigma/vite` 自动导入，再补装 unplugin 三件套。它们是可选 peer，只在这条路径下需要，缺装时插件会抛出带包名的安装指引：

```bash
pnpm add -D unplugin unplugin-vue-components unplugin-auto-import
```

> [!TIP]
> 
> 只用
> 
> 具名导入
> 
> 的项目不需要三件套，装好 
> 
> @movk/sigma sigma graphology
> 
>  即可。

## Vite 插件

在 `vite.config.ts` 中加入插件，负责 `Sigma*` 组件与 composables / utils 的自动导入，并把 sigma 及已安装的可选 peer 声明进 Vite 预构建：

```ts [vite.config.ts]
import vue from '@vitejs/plugin-vue'
import Sigma from '@movk/sigma/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [vue(), Sigma()]
})
```

**prefix** (`string`): 默认 'Sigma' —— 组件名前缀，与 Nuxt 模块的 prefix 选项对应。

**dts** (`boolean`): 默认 true —— 生成 components.d.ts 与 auto-imports.d.ts，把两份文件纳入 tsconfig.json 的 include 后类型检查即可识别自动导入。

**optimizeDeps** (`boolean`): 默认 true —— 探测项目里已安装的 sigma 相关依赖并合并进 optimizeDeps.include。关掉后可用 sigmaOptimizeDepsInclude() 拿到同一份列表自行声明。

> [!NOTE]
> 
> Sigma()
> 
>  返回 
> 
> Promise<Plugin[]>
> 
> ，Vite 的 
> 
> plugins
> 
>  直接接受，不必 
> 
> await
> 
> 。

## 复用已有 unplugin 实例

部分库（如 `@nuxt/ui`）的 Vite 插件内置了唯一的 `unplugin-vue-components` / `unplugin-auto-import` 实例，检测到第二个实例会直接抛错。这时不要再叠加 `Sigma()`，改用 `@movk/sigma/unplugin` 导出的 `sigmaComponentResolver` 与 `sigmaAutoImportDirs` 注入宿主插件：

```ts [vite.config.ts]
import ui from '@nuxt/ui/vite'
import { sigmaAutoImportDirs, sigmaComponentResolver } from '@movk/sigma/unplugin'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      components: { resolvers: [sigmaComponentResolver()] },
      autoImport: { dirs: sigmaAutoImportDirs() }
    })
  ]
})
```

这两个函数只读文件系统、不触碰三件套，注入宿主时用的是宿主自带的 unplugin，因此这条路径同样不需要安装三件套。`sigmaComponentResolver({ prefix: 'Sg' })` 可自定义前缀。

## 具名导入

不想接任何 unplugin 时，从 `@movk/sigma/vue` 显式导入。组件按 Nuxt 侧的注册名导出，`controls/` 子目录不进名字：

```vue [App.vue]
<script setup lang="ts">
import { SigmaControls, SigmaGraph, SigmaZoomControl, useSigmaGraph } from '@movk/sigma/vue'

const { graph } = useSigmaGraph()
</script>

<template>
  <SigmaGraph :data="data" style="height: 480px">
    <SigmaControls position="top-right">
      <SigmaZoomControl />
    </SigmaControls>
  </SigmaGraph>
</template>
```

自动导入与具名导入指向同一份源码，可以混用。

## 注册 Vue 插件

`@movk/sigma/vue-plugin` 对应 Nuxt 模块的 `settings` 选项：注入全局默认的 sigma 行为配置，与组件级 `settings` 深度合并。它不做全局组件注册，组件仍按需 tree-shaking。运行时样式需要自行引入：

```ts [main.ts]
import { createApp } from 'vue'
import SigmaPlugin from '@movk/sigma/vue-plugin'
import '@movk/sigma/index.css'
import App from './App.vue'

createApp(App)
  .use(SigmaPlugin, {
    settings: { hideEdgesOnMove: true }
  })
  .mount('#app')
```

没有全局默认要注入时可以不注册插件，`index.css` 仍需引入才有控件样式。

## 用法一致

组件、composables 与 utils 的 API 与 Nuxt 完全相同，[组件](https://sigma.mhaibaraai.cn/docs/components/graph)、[Composables](https://sigma.mhaibaraai.cn/docs/composables/use-sigma) 与[工具函数](https://sigma.mhaibaraai.cn/docs/utils/apply-graph-diff) 各页的示例可直接照搬：

```vue [App.vue]
<script setup lang="ts">
import type { SerializedGraph } from 'graphology-types'

const data: SerializedGraph = {
  attributes: {},
  options: { type: 'undirected', multi: false, allowSelfLoops: false },
  nodes: [
    { key: 'a', attributes: { label: 'A', x: 0, y: 0, size: 20 } },
    { key: 'b', attributes: { label: 'B', x: 200, y: 100, size: 12 } }
  ],
  edges: [{ source: 'a', target: 'b' }]
}

const { start, stop, isRunning } = useSigmaLayout('forceatlas2')
</script>

<template>
  <SigmaGraph :data="data" style="height: 480px">
    <SigmaControls position="top-right">
      <button @click="isRunning ? stop() : start()">
        {{ isRunning ? '停止' : '布局' }}
      </button>
    </SigmaControls>
  </SigmaGraph>
</template>
```

## 与 Nuxt 的差异

- **无 SSR**：Vite 侧只有客户端，不存在 [SSR 与 WebGL](https://sigma.mhaibaraai.cn/docs/getting-started/installation#ssr-%E4%B8%8E-webgl) 一节的顶层 import 限制；但库内仍走动态导入，`defineSigmaPrimitives()` 的写法保持不变
- **无 useFetch**：文档示例里的 `useFetch('/api/xxx.json')` 是 Nuxt API，换成 `fetch` 或你自己的数据层
- **样式变量**：没有 Nuxt UI 令牌时 `--sigma-color-*` 回落到字面量兜底，覆盖方式与[样式](https://sigma.mhaibaraai.cn/docs/getting-started/installation#%E6%A0%B7%E5%BC%8F)一节相同


## Sitemap

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