背景 Background

概述

支持为图画布设置一个背景图片，让画布更有层次感、叙事性。

使用场景

这一插件主要用于：

为图表设置统一的品牌背景色或图片
通过背景区分不同的功能区域
增强图表的视觉层次感和美观度

基本用法

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

const graph = new Graph({
  plugins: [
    {
      type: 'background',
      key: 'my-background', // 为插件指定标识符，方便动态更新
      backgroundColor: '#f0f2f5', // 设置背景色
      backgroundImage: 'url(https://example.com/bg.png)', // 设置背景图
    },
  ],
});

配置项

Background 插件的配置项继承了所有 CSS 样式属性（CSSStyleDeclaration），因此你可以使用任何合法的 CSS 属性来配置背景。以下是一些常用配置：

属性	描述	类型	默认值	必选
type	插件类型	string	`background`	✓
key	插件唯一标识符，用于后续更新	string	-
width	背景宽度	string	`100%`
height	背景高度	string	`100%`
backgroundColor	背景颜色	string	-
backgroundImage	背景图片	string	-
backgroundSize	背景尺寸	string	`cover`
backgroundPosition	背景位置	string	-
backgroundRepeat	背景重复方式	string	-
opacity	背景透明度	string	-
transition	过渡动画	string	`background 0.5s`
zIndex	层叠顺序	string	-1

注意：zIndex 默认为 -1，这是为了避免背景覆盖其他插件的 DOM 元素，如网格线。

代码示例

基础背景色


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

const graph = new Graph({
  container: 'container',
  width: 300,
  height: 200,
  plugins: [
    {
      type: 'background',
      width: '300px',
      height: '200px',
      backgroundColor: '#f0f2f5',
    },
  ],
});

graph.render();

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;
}

使用背景图片


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

const graph = new Graph({
  container: 'container',
  width: 300,
  height: 200,
  plugins: [
    {
      type: 'background',
      width: '300px',
      height: '200px',
      backgroundImage:
        'url(https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*0Qq0ToQm1rEAAAAAAAAAAAAADmJ7AQ/original)',
      backgroundRepeat: 'no-repeat',
      backgroundSize: 'cover',
      opacity: 0.2,
    },
  ],
});

graph.render();

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;
}

渐变背景


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

const graph = new Graph({
  container: 'container',
  width: 300,
  height: 200,
  plugins: [
    {
      type: 'background',
      width: '300px',
      height: '200px',
      background: 'linear-gradient(45deg, #1890ff, #722ed1)',
      opacity: '0.8',
    },
  ],
});

graph.render();

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;
}

动态更新背景

// 初始化时配置
const graph = new Graph({
  // 其他配置...
  plugins: [
    {
      type: 'background',
      key: 'my-background',
      backgroundColor: '#f0f2f5',
    },
  ],
});

// 后续更新
graph.updatePlugin({
  key: 'my-background',
  backgroundColor: '#e6f7ff',
  transition: 'background 1s ease',
});

常见问题

1. 背景与其他插件冲突？

默认情况下，背景插件的 zIndex 设为 -1，以确保它位于其他元素之下。如果仍有冲突，可以调整 zIndex 值：

const graph = new Graph({
  plugins: [
    {
      type: 'background',
      zIndex: '-2', // 降低 z-index 避免冲突
    },
  ],
});