---
title: "Stencil"
description: "Stencil"
language: "zh"
canonical: "https://x6.antv.antgroup.com/zh/tutorial/plugins/stencil/"
version: "3.x"
---

[资料索引](/llms.txt)

> **在本章节中主要介绍 Stencil 插件相关的知识，通过阅读，你可以了解到**

- 如何通过 Stencil 提升 Dnd 能力
- 如何配置分组、折叠与搜索


## 使用

Stencil 是在 Dnd 基础上的进一步封装，提供了一个类似侧边栏的 UI 组件，并支持分组、折叠、搜索等能力。你可以通过插件 `Stencil` 启用该侧边栏模板功能，示例：

```ts
import { Graph, Stencil } from '@antv/x6'

const graph = new Graph({
  background: {
    color: '#F2F7FA',
  },
})

const stencil = new Stencil({
  target: graph,
  groups: [
    {
      name: 'group1',
    },
    {
      name: 'group2',
    },
  ],
})

const rect1 = graph.createNode({
  shape: 'rect',
  width: 100,
  height: 40,
})
const rect2 = rect1.clone()

// 需要一个容纳 stencil 的 Dom 容器 stencilContainer
stencilContainer.appendChild(stencil.container)
stencil.load([rect1, rect2], 'group1')
```

## 演示



```ts
import './index.less'
import { createRoot } from 'react-dom/client'
import React from 'react'
import { Graph, Stencil, Snapline } from '@antv/x6'

const commonAttrs = {
  body: {
    fill: '#fff',
    stroke: '#8f8f8f',
    strokeWidth: 1,
  },
}

export default class Example extends React.Component {
  private container: HTMLDivElement
  private stencilContainer: HTMLDivElement

  componentDidMount() {
    const graph = new Graph({
      container: this.container,
      background: {
        color: '#F2F7FA',
      },
    })
    graph.use(
      new Snapline({
        enabled: true,
        sharp: true,
      }),
    )

    const source = graph.addNode({
      x: 130,
      y: 30,
      width: 100,
      height: 40,
      label: 'Hello',
      attrs: {
        body: {
          stroke: '#8f8f8f',
          strokeWidth: 1,
          fill: '#fff',
          rx: 6,
          ry: 6,
        },
      },
    })

    const target = graph.addNode({
      x: 320,
      y: 240,
      width: 100,
      height: 40,
      label: 'World',
      attrs: {
        body: {
          stroke: '#8f8f8f',
          strokeWidth: 1,
          fill: '#fff',
          rx: 6,
          ry: 6,
        },
      },
    })

    graph.addEdge({
      source,
      target,
      attrs: {
        line: {
          stroke: '#8f8f8f',
          strokeWidth: 1,
        },
      },
    })

    graph.centerContent()

    const stencil = new Stencil({
      title: 'Stencil',
      target: graph,
      search(cell, keyword) {
        return cell.shape.indexOf(keyword) !== -1
      },
      placeholder: 'Search by shape name',
      notFoundText: 'Not Found',
      collapsable: true,
      stencilGraphHeight: 0,
      groups: [
        {
          name: 'group1',
          title: 'Group(Collapsable)',
        },
        {
          name: 'group2',
          title: 'Group',
          collapsable: false,
        },
      ],
    })

    this.stencilContainer.appendChild(stencil.container)

    const n1 = graph.createNode({
      shape: 'rect',
      x: 40,
      y: 40,
      width: 80,
      height: 40,
      label: 'rect',
      attrs: commonAttrs,
    })

    const n2 = graph.createNode({
      shape: 'circle',
      x: 180,
      y: 40,
      width: 40,
      height: 40,
      label: 'circle',
      attrs: commonAttrs,
    })

    const n3 = graph.createNode({
      shape: 'ellipse',
      x: 280,
      y: 40,
      width: 80,
      height: 40,
      label: 'ellipse',
      attrs: commonAttrs,
    })

    const n4 = graph.createNode({
      shape: 'path',
      x: 420,
      y: 40,
      width: 40,
      height: 40,
      // https://www.svgrepo.com/svg/13653/like
      path: 'M24.85,10.126c2.018-4.783,6.628-8.125,11.99-8.125c7.223,0,12.425,6.179,13.079,13.543c0,0,0.353,1.828-0.424,5.119c-1.058,4.482-3.545,8.464-6.898,11.503L24.85,48L7.402,32.165c-3.353-3.038-5.84-7.021-6.898-11.503c-0.777-3.291-0.424-5.119-0.424-5.119C0.734,8.179,5.936,2,13.159,2C18.522,2,22.832,5.343,24.85,10.126z',
      attrs: commonAttrs,
      label: 'path',
    })

    stencil.load([n1, n2], 'group1')
    stencil.load([n3, n4], 'group2')
  }

  refContainer = (container: HTMLDivElement) => {
    this.container = container
  }

  refStencil = (container: HTMLDivElement) => {
    this.stencilContainer = container
  }

  render() {
    return (
      <div className="stencil-app">
        <div className="app-stencil" ref={this.refStencil} />
        <div className="app-content" ref={this.refContainer} />
      </div>
    )
  }
}

const root = createRoot(document.getElementById('container')!)
root.render(<Example />)
window.addEventListener('pagehide', () => root.unmount(), { once: true })
```



## 配置

| 选项                | 类型                                                        | 必选 | 默认值               | 说明                                  |
|---------------------|-------------------------------------------------------------|:----:|----------------------|-------------------------------------|
| title               | string                                                      |      | `'Stencil'`          | 标题。                                 |
| groups              | Group[]                                                     |  ✓️   | -                    | 分组信息。                             |
| search              | Filter                                                      |      | `false`              | 搜索选项。                             |
| placeholder         | string                                                      |      | `'Search'`           | 搜索文本框的 placeholder 文本。        |
| notFoundText        | string                                                      |      | `'No matches found'` | 未匹配到搜索结果时的提示文本。         |
| collapsable         | boolean                                                     |      | `false`              | 是否显示全局折叠/展开按钮。            |
| layout              | (this: Stencil, model: Model, group?: Group \| null) => any |      | 网格布局             | 模板画布中节点的布局方法。             |
| layoutOptions       | any                                                         |      | -                    | 布局选项。                             |
| stencilGraphWidth   | number                                                      |      | `200`                | 模板画布宽度。                         |
| stencilGraphHeight  | number                                                      |      | `800`                | 模板画布高度。设置为 0 时高度会自适应。 |
| stencilGraphPadding | number                                                      |      | `10`                 | 模板画布边距。                         |
| stencilGraphOptions | Graph.Options                                               |      | -                    | 模板画布选项。                         |

> **提示**

除了上面的配置，Stencil 还继承了 Dnd 的所有配置。

### 分组

初始化时，按照 `groups` 提供的分组，在每个分组中会渲染一个模板画布。分组的类型定义如下：

```ts
export interface Group {
  name: string // 分组名称
  title?: string // 分组标题，缺省时使用 `name`
  collapsable?: boolean // 分组是否可折叠，默认为 true
  collapsed?: boolean // 初始状态是否为折叠状态
  nodeMovable?: boolean // 模板画布中的节点能否拖动
  graphWidth?: number // 模板画布宽度
  graphHeight?: number // 模板画布高度
  graphPadding?: number // 模板画布边距
  graphOptions?: Graph.Options // 模板画布选项
  layout?: (this: Stencil, model: Model, group?: Group | null) => any
  layoutOptions?: any // 布局选项
}
```

可以看到分组内的一些配置和外层的配置有重合，比如 `graphWidth`/`stencilGraphWidth` 与 `graphHeight`/`stencilGraphHeight`，分组内的配置优先级更高。

### 布局

添加节点时，使用分组或全局的 `layout` 和 `layoutOptions` 来对节点进行自动布局，默认使用网格布局方法来布局模板节点，支持的布局选项有：

| 选项        | 类型                          | 默认值   | 说明                                                                               |
|-------------|-------------------------------|----------|----------------------------------------------------------------------------------|
| columns     | number                        | `2`      | 网格布局的列数，默认为 `2`。行数根据节点数自动计算。                                  |
| columnWidth | number \| 'auto' \| 'compact' | `'auto'` | 列宽。auto: 所有节点中最宽节点的宽度作为列宽，compact: 该列中最宽节点的宽度作为列宽。 |
| rowHeight   | number \| 'auto' \| 'compact' | `'auto'` | 行高。auto: 所有节点中最高节点的高度作为行高，compact: 该行中最高节点的高度作为行高。 |
| dx          | number                        | `10`     | 单元格在 X 轴的偏移量，默认为 `10`。                                                 |
| dy          | number                        | `10`     | 单元格在 Y 轴的偏移量，默认为 `10`。                                                 |
| marginX     | number                        | `0`      | 单元格在 X 轴的边距，默认为 `0`。                                                    |
| marginY     | number                        | `0`      | 单元格在 Y 轴的边距，默认为 `0`。                                                    |
| center      | boolean                       | `true`   | 节点是否与网格居中对齐，默认为 `true`。                                              |
| resizeToFit | boolean                       | `false`  | 是否自动调整节点的大小来适应网格大小，默认为 `false`。                               |

也可以按照 `(this: Stencil, model: Model, group?: Group | null) => any` 签名进行自定义布局。

### 搜索

Stencil 还提供了搜索能力。

```ts
// 只搜索 rect 节点
const stencil = new Stencil({
  search: (cell, keyword, groupName, stencil) => {
    if (keyword) {
      return cell.shape === 'rect'
    }
    return true
  },
})

// 搜索 text 包含关键字的 rect 节点
const stencil = new Stencil({
  search: (cell, keyword, groupName, stencil) => {
    if (keyword) {
      return cell.shape === 'rect' && cell.attr('text/text').includes(keyword)
    }
    return true
  },
})
```

## API

### stencil.load(...)

```ts
load(nodes: (Node | Node.Metadata)[], groupName?: string): this
```

加载节点。参数如下：

| 名称      | 类型                        | 必选 | 默认值 | 描述                |
|-----------|-----------------------------|:----:|--------|-------------------|
| nodes     | `(Node \| Node.Metadata)[]` |  ✓️   | -      | 加载的节点。         |
| groupName | string                      |      | -      | 加载节点的分组名称。 |

### stencil.unload(...)

```ts
unload(nodes: (Node | Node.Metadata)[], groupName?: string): this
```

卸载节点。参数如下：

| 名称      | 类型                        | 必选 | 默认值 | 描述                |
|-----------|-----------------------------|:----:|--------|-------------------|
| nodes     | `(Node \| Node.Metadata)[]` |  ✓️   | -      | 卸载的节点。         |
| groupName | string                      |      | -      | 卸载节点的分组名称。 |

### stencil.addGroup(...)

```ts
addGroup(group: Stencil.Group | Stencil.Group[])
```

新增分组。

```ts
stencil.addGroup({
  name: 'group1',
  graphHeight: 100,
})
```

### stencil.removeGroup(...)

```ts
removeGroup(groupName: string | string[])
```

删除分组。

### stencil.resizeGroup(...)

```typescript
resizeGroup(groupName: string, size: { width: number; height: number })
```

修改分组的尺寸。
### docs/demos/tutorial/plugins/stencil/index.less

```less
.stencil-app {
  display: flex;
  border: 1px solid #f0f0f0;
  padding: 16px 8px;
  font-family: sans-serif;

  .app-stencil {
    position: relative;
    width: 200px;
    border: 1px solid #f0f0f0;
  }

  .app-content {
    flex: 1;
    height: 380px;
    margin-right: 8px;
    margin-left: 8px;
    box-shadow: 0 0 10px 1px #e9e9e9;
  }

  .x6-widget-stencil-group-title {
    // 避免 dumi 的样式影响
    margin-top: 0 !important;
  }
}
```