---
title: "对齐线 Snapline"
description: "对齐线 Snapline"
language: "zh"
canonical: "https://g6.antv.antgroup.com/zh/manual/plugin/Snapline/"
version: "5.1.1"
---

## 概述

对齐线插件为画布提供智能对齐参考线，在移动节点时自动显示辅助线并支持自动吸附，帮助用户实现精确对齐，是图形编辑中提升效率和精确度的重要工具。

## 使用场景

对齐线插件主要适用于以下场景：

- 手动调整节点位置时,需要与其他节点精确对齐
- 拖拽移动多个节点时,保持它们之间的对齐关系
- 制作规范的图形布局时,确保节点间距和位置的一致性
- 通过自动吸附功能提高节点排版效率

## 基本用法

以下是一个简单的 Snapline 插件初始化示例：

```js
const graph = new Graph({
  plugins: [
    {
      type: 'snapline',
      key: 'my-snapline', // 指定唯一标识符
      tolerance: 5, // 对齐吸附阈值
      offset: 20, // 对齐线延伸距离
      autoSnap: true, // 启用自动吸附
    },
  ],
});
```

## 在线体验



```ts
import { createGraph } from '/demo-runtime.ts';

createGraph(
  {
    data: {
      nodes: [
        { id: 'node-0' },
        { id: 'node-1' },
        { id: 'node-2' },
        { id: 'node-3' },
        { id: 'node-4' },
        { id: 'node-5' },
      ],
      edges: [
        { source: 'node-0', target: 'node-1' },
        { source: 'node-0', target: 'node-2' },
        { source: 'node-0', target: 'node-3' },
        { source: 'node-0', target: 'node-4' },
        { source: 'node-1', target: 'node-0' },
        { source: 'node-2', target: 'node-0' },
        { source: 'node-3', target: 'node-0' },
        { source: 'node-4', target: 'node-0' },
        { source: 'node-5', target: 'node-0' },
      ],
    },
    layout: { type: 'grid' },
    behaviors: ['drag-canvas', 'drag-element'],
    plugins: [
      { type: 'grid-line', key: 'grid-line', size: 30 },
      {
        type: 'snapline',
        key: 'snapline',
        tolerance: 5,
        offset: 20,
        verticalLineStyle: { stroke: '#F08F56', lineWidth: 2 },
        horizontalLineStyle: { stroke: '#17C76F', lineWidth: 2 },
      },
    ],
  },
  { width: 600, height: 300 },
  (gui, graph) => {
    const options = {
      type: 'snapline',
      tolerance: 5,
      offset: 20,
      autoSnap: true,
    };
    const optionFolder = gui.addFolder('Snapline Options');
    optionFolder.add(options, 'type').disable(true);
    optionFolder.add(options, 'tolerance', 1, 20, 1);
    optionFolder.add(options, 'offset', 1, 50, 1);
    optionFolder.add(options, 'autoSnap');

    optionFolder.onChange(({ property, value }) => {
      graph.updatePlugin({
        key: 'snapline',
        [property]: value,
      });
      graph.render();
    });
  },
);
```



## 配置项

| 属性                | 描述                                                                                                                    | 类型                                                                                                                            | 默认值                  | 必选 |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---- |
| type                | 插件类型                                                                                                                | string                                                                                                                          | `'snapline'`            | ✓    |
| key                 | 插件唯一标识符                                                                                                          | string                                                                                                                          | -                       |      |
| tolerance           | 对齐精度，即触发对齐的距离阈值                                                                                          | number                                                                                                                          | 5                       |      |
| offset              | 对齐线头尾的延伸距离                                                                                                    | number                                                                                                                          | 20                      |      |
| autoSnap            | 是否启用自动吸附                                                                                                        | boolean                                                                                                                         | true                    |      |
| shape               | 指定元素的参照图形：<br/>- `'key'`: 使用元素的主图形作为参照图形<br/>- `Function`: 传入函数时接收元素对象，返回一个图形 | string \| ((node: Node) => DisplayObject)                                                                                       | `'key'`                 |      |
| verticalLineStyle   | 垂直对齐线样式                                                                                                          | 支持[BaseStyleProps](/zh/manual/element/shape/properties/#baseshapestyle) 下的部分配置，详见[「对齐线样式配置项」](#对齐线样式配置) | `{ stroke: '#1783FF' }` |      |
| horizontalLineStyle | 水平对齐线样式                                                                                                          | 支持[BaseStyleProps](/zh/manual/element/shape/properties/#baseshapestyle) 下的部分配置，详见[「对齐线样式配置项」](#对齐线样式配置) | `{ stroke: '#1783FF' }` |      |
| filter              | 过滤不需要参与对齐的节点                                                                                                | (node: Node) => boolean                                                                                                         | `() => true`            |      |

### shape

`shape` 属性用于指定元素的参照图形，支持以下配置方式：

```js
// 使用主图形作为参照
{
  type: 'snapline',
  shape: 'key'
}

// 使用自定义函数返回参照图形
{
  type: 'snapline',
  shape: (node) => {
    return node.getShape('custom-shape');
  }
}
```

### 对齐线样式配置

| 配置项         | 说明            | 类型                                     | 默认值      |
| -------------- | --------------- | ---------------------------------------- | ----------- |
| stroke         | 线条颜色        | string \| Pattern \| null                | `'#1783FF'` |
| opacity        | 整体透明度      | number \| string                         | 1           |
| strokeOpacity  | 描边透明度      | number \| string                         | 1           |
| lineWidth      | 线宽度          | number \| string                         | 1           |
| lineCap        | 线段端点样式    | `'butt'` \| `'round'` \| `'square'`      | `'butt'`    |
| lineJoin       | 线段连接处样式  | `'miter'` \| `'round'` \| `'bevel'`      | `'miter'`   |
| lineDash       | 虚线配置        | number \| string \| (string \| number)[] | -           |
| lineDashOffset | 虚线偏移量      | number                                   | 0           |
| shadowBlur     | 阴影模糊程度    | number                                   | 0           |
| shadowColor    | 阴影颜色        | string                                   | -           |
| shadowOffsetX  | 阴影 X 方向偏移 | number                                   | 0           |
| shadowOffsetY  | 阴影 Y 方向偏移 | number                                   | 0           |
| cursor         | 鼠标样式        | string                                   | `'default'` |
| zIndex         | 渲染层级        | number                                   | 0           |

示例配置

```js
{
  type: 'snapline',
  horizontalLineStyle: {
    stroke: '#F08F56',
    strokeOpacity: 0.8,
    lineWidth: 2,
    lineDash: [4, 4],
    lineDashOffset: 0,
    opacity: 1,
    cursor: 'move',
  },
  verticalLineStyle: {
    stroke: '#17C76F',
    strokeOpacity: 0.8,
    lineWidth: 2,
    lineDash: [4, 4],
    lineDashOffset: 0,
    opacity: 1,
    cursor: 'move',
  },
}
```

## 代码示例

### 基础对齐线

最简单的使用方式：

```js
const graph = new Graph({
  plugins: ['snapline'],
});
```

### 自定义配置

可以根据需要自定义对齐线的行为：

```js
const graph = new Graph({
  plugins: [
    {
      type: 'snapline',
      tolerance: 8, // 更大的吸附范围
      offset: 30, // 更长的延伸线
      horizontalLineStyle: {
        stroke: '#1890ff',
        lineWidth: 2,
      },
      filter: (node) => node.id !== 'node-0', // 根据id过滤节点，不参与对齐
    },
  ],
});
```

## 实际案例



```ts

import { Graph } from '@antv/g6';

const data = {
  nodes: [{ id: 'node-0' }, { id: 'node-1' }, { id: 'node-2' }, { id: 'node-3' }, { id: 'node-4' }, { id: 'node-5' }],
  edges: [
    { source: 'node-0', target: 'node-1' },
    { source: 'node-0', target: 'node-2' },
    { source: 'node-0', target: 'node-3' },
    { source: 'node-0', target: 'node-4' },
    { source: 'node-1', target: 'node-0' },
    { source: 'node-2', target: 'node-0' },
    { source: 'node-3', target: 'node-0' },
    { source: 'node-4', target: 'node-0' },
    { source: 'node-5', target: 'node-0' },
  ],
};

const graph = new Graph({
  container: 'container',
  data,
  layout: { type: 'grid' },
  behaviors: ['drag-canvas', 'drag-element'],
  plugins: [
    {
      type: 'snapline',
      key: 'snapline',
      verticalLineStyle: { stroke: '#F08F56', lineWidth: 2 },
      horizontalLineStyle: { stroke: '#17C76F', lineWidth: 2 },
      autoSnap: false,
    },
  ],
});

graph.render();
```
### demo-runtime.ts

```ts
import { Graph } from '@antv/g6';
import GUI from 'lil-gui';

export function addPanel(renderPanel: (gui: GUI) => void) {
  const gui = new GUI({ container: document.body });
  gui.title('Control');
  Object.assign(gui.domElement.style, { position: 'absolute', top: '0', right: '0', zIndex: '10' });
  renderPanel(gui);
  addEventListener('pagehide', () => gui.destroy(), { once: true });
}

export async function createGraph(
  options: ConstructorParameters<typeof Graph>[0],
  size: { width?: number; height?: number } = {},
  renderPanel?: (gui: GUI, graph: Graph) => void,
) {
  const container = document.createElement('div');
  Object.assign(container.style, {
    width: '100%',
    maxWidth: `${size.width || 600}px`,
    height: `${size.height || 400}px`,
  });
  document.getElementById('container')!.append(container);
  const graph = new Graph({ ...size, ...options, width: container.clientWidth, container, autoResize: true });
  addEventListener('pagehide', () => graph.destroy(), { once: true });
  await graph.render();
  if (renderPanel) addPanel((gui) => renderPanel(gui, graph));
  return container;
}
```