BlockSuite

Appearance

BlockSuite API Documentation / @blocksuite/affine-gfx-connector

@blocksuite/affine-gfx-connector ​

Classes ​

Extension ​

ConnectorTool ​

Understanding Extensions ​

Extensions provide a way to extend the functionality of a system using dependency injection. They allow you to register services, implementations, and factories in the DI container, which can then be retrieved and used by different parts of the application.

Extensions are particularly useful for:

  • Registering different implementations for different types
  • Creating pluggable architecture where components can be added or removed
  • Managing dependencies between different parts of the application

Usage Example: Fruit Processing System ​

Let's consider a fruit processing system where different types of fruits need different processing methods. We'll show how to implement this using extensions.

Step 1: Define the interfaces ​

ts
interface FruitProcessor {
  process(fruit: Fruit): void;
}

interface Fruit {
  type: string;
  // other properties
}

Step 2: Create a service identifier ​

ts
import { createIdentifier } from '@blocksuite/global/di';

const FruitProcessorProvider = createIdentifier<FruitProcessor>('fruit-processor-provider');

Step 3: Create implementations ​

ts
class AppleProcessor implements FruitProcessor {
  process(fruit: Fruit): void {
    console.log('Slicing apple');
    // Apple-specific processing
  }
}

class BananaProcessor implements FruitProcessor {
  process(fruit: Fruit): void {
    console.log('Peeling banana');
    // Banana-specific processing
  }
}

Step 4: Create an extension factory ​

ts
const FruitProcessorExtension = (
  fruitType: string,
  implementation: new () => FruitProcessor
): ExtensionType => {
  return {
    setup: di => {
      di.addImpl(FruitProcessorProvider(fruitType), implementation);
    }
  };
};

Step 5: Create concrete extensions ​

ts
export const AppleProcessorExtension = FruitProcessorExtension('apple', AppleProcessor);
export const BananaProcessorExtension = FruitProcessorExtension('banana', BananaProcessor);

Step 6: Use the extensions ​

ts
import { Container } from '@blocksuite/global/di';

class FruitProcessingSystem {
  provider: ServiceProvider;

  constructor(extensions: ExtensionType[]) {
    const container = new Container();

    // Set up all extensions
    extensions.forEach(ext => ext.setup(container));

    // Create a provider from the container
    this.provider = container.provider();
  }

  processFruit(fruit: Fruit) {
    // Get the appropriate processor based on fruit type
    const processor = this.provider.get(FruitProcessorProvider(fruit.type));

    // Process the fruit
    processor.process(fruit);
  }
}

// Initialize the system with extensions
const system = new FruitProcessingSystem([
  AppleProcessorExtension,
  BananaProcessorExtension
]);

// Use the system
system.processFruit({ type: 'apple' });  // Output: Slicing apple
system.processFruit({ type: 'banana' }); // Output: Peeling banana

Note: We deliberately used a non-block specific example here. In BlockSuite, the extension pattern can be applied to any entity that can be configured by third parties, not just blocks. This includes different tools in the whiteboard, different column types in database blocks, and many other extensible components. The pattern remains the same regardless of what you're extending.

Extends ​
Constructors ​
Properties ​
toolName ​

static toolName: string = 'connector'

Overrides ​

BaseTool.toolName

Accessors ​
Methods ​
click() ​

click(): void

Returns ​

void

Overrides ​

BaseTool.click

deactivate() ​

deactivate(): void

Called when the tool is deactivated.

Returns ​

void

Overrides ​

BaseTool.deactivate

dragEnd() ​

dragEnd(): void

Returns ​

void

Overrides ​

BaseTool.dragEnd

dragMove() ​

dragMove(e): void

Parameters ​
e ​

PointerEventState

Returns ​

void

Overrides ​

BaseTool.dragMove

dragStart() ​

dragStart(): void

Returns ​

void

Overrides ​

BaseTool.dragStart

findTargetByPoint() ​

findTargetByPoint(point): void

Parameters ​
point ​

IVec

Returns ​

void

getNextMode() ​

getNextMode(): ConnectorMode

Returns ​

ConnectorMode

pointerDown() ​

pointerDown(e): void

Parameters ​
e ​

PointerEventState

Returns ​

void

Overrides ​

BaseTool.pointerDown

pointerMove() ​

pointerMove(e): void

Parameters ​
e ​

PointerEventState

Returns ​

void

Overrides ​

BaseTool.pointerMove

pointerUp() ​

pointerUp(_): void

Parameters ​
_ ​

PointerEventState

Returns ​

void

Overrides ​

BaseTool.pointerUp

quickConnect() ​

quickConnect(point, element): void

Parameters ​
point ​

IVec

element ​

GfxModel

Returns ​

void

ConnectorFilter ​

Understanding Extensions ​

Extensions provide a way to extend the functionality of a system using dependency injection. They allow you to register services, implementations, and factories in the DI container, which can then be retrieved and used by different parts of the application.

Extensions are particularly useful for:

  • Registering different implementations for different types
  • Creating pluggable architecture where components can be added or removed
  • Managing dependencies between different parts of the application

Usage Example: Fruit Processing System ​

Let's consider a fruit processing system where different types of fruits need different processing methods. We'll show how to implement this using extensions.

Step 1: Define the interfaces ​

ts
interface FruitProcessor {
  process(fruit: Fruit): void;
}

interface Fruit {
  type: string;
  // other properties
}

Step 2: Create a service identifier ​

ts
import { createIdentifier } from '@blocksuite/global/di';

const FruitProcessorProvider = createIdentifier<FruitProcessor>('fruit-processor-provider');

Step 3: Create implementations ​

ts
class AppleProcessor implements FruitProcessor {
  process(fruit: Fruit): void {
    console.log('Slicing apple');
    // Apple-specific processing
  }
}

class BananaProcessor implements FruitProcessor {
  process(fruit: Fruit): void {
    console.log('Peeling banana');
    // Banana-specific processing
  }
}

Step 4: Create an extension factory ​

ts
const FruitProcessorExtension = (
  fruitType: string,
  implementation: new () => FruitProcessor
): ExtensionType => {
  return {
    setup: di => {
      di.addImpl(FruitProcessorProvider(fruitType), implementation);
    }
  };
};

Step 5: Create concrete extensions ​

ts
export const AppleProcessorExtension = FruitProcessorExtension('apple', AppleProcessor);
export const BananaProcessorExtension = FruitProcessorExtension('banana', BananaProcessor);

Step 6: Use the extensions ​

ts
import { Container } from '@blocksuite/global/di';

class FruitProcessingSystem {
  provider: ServiceProvider;

  constructor(extensions: ExtensionType[]) {
    const container = new Container();

    // Set up all extensions
    extensions.forEach(ext => ext.setup(container));

    // Create a provider from the container
    this.provider = container.provider();
  }

  processFruit(fruit: Fruit) {
    // Get the appropriate processor based on fruit type
    const processor = this.provider.get(FruitProcessorProvider(fruit.type));

    // Process the fruit
    processor.process(fruit);
  }
}

// Initialize the system with extensions
const system = new FruitProcessingSystem([
  AppleProcessorExtension,
  BananaProcessorExtension
]);

// Use the system
system.processFruit({ type: 'apple' });  // Output: Slicing apple
system.processFruit({ type: 'banana' }); // Output: Peeling banana

Note: We deliberately used a non-block specific example here. In BlockSuite, the extension pattern can be applied to any entity that can be configured by third parties, not just blocks. This includes different tools in the whiteboard, different column types in database blocks, and many other extensible components. The pattern remains the same regardless of what you're extending.

Extends ​
Constructors ​
Properties ​
key ​

static key: string = 'connector-filter'

Overrides ​

InteractivityExtension.key

Accessors ​
Methods ​
mounted() ​

mounted(): void

Returns ​

void

Overrides ​

InteractivityExtension.mounted

Other ​

ConnectionOverlay ​

An overlay is a layer covered on top of elements, can be used for rendering non-CRDT state indicators.

Extends ​
Constructors ​
Constructor ​

new ConnectionOverlay(gfx): ConnectionOverlay

Parameters ​
gfx ​

GfxController

Returns ​

ConnectionOverlay

Overrides ​

Overlay.constructor

Properties ​
highlightPoint ​

highlightPoint: IVec | null = null

points ​

points: IVec[] = []

sourceBounds ​

sourceBounds: IBound | null = null

targetBounds ​

targetBounds: IBound | null = null

overlayName ​

static overlayName: string = 'connection'

Overrides ​

Overlay.overlayName

Methods ​
_clearRect() ​

_clearRect(): void

Returns ​

void

clear() ​

clear(): void

Returns ​

void

Overrides ​

Overlay.clear

dispose() ​

dispose(): void

Returns ​

void

Overrides ​

Overlay.dispose

render() ​

render(ctx): void

Parameters ​
ctx ​

CanvasRenderingContext2D

Returns ​

void

Overrides ​

Overlay.render

renderConnector() ​

renderConnector(point, excludedIds?): Connection

Render the connector at the given point. It will try to find the closest connectable element and render the connector. If the point is not close to any connectable element, it will just render the connector at the given point.

Parameters ​
point ​

IVec

the point to render the connector

excludedIds? ​

string[] = []

the ids of the elements that should be excluded

Returns ​

Connection

the connection result

ConnectorPathGenerator ​

Extends ​
Constructors ​
Constructor ​

new ConnectorPathGenerator(options): ConnectorPathGenerator

Parameters ​
options ​
getElementById ​

(id) => GfxModel | null

Returns ​

ConnectorPathGenerator

Overrides ​

PathGenerator.constructor

Properties ​
Methods ​
hasRelatedElement() ​

hasRelatedElement(connecter): boolean

Parameters ​
connecter ​

ConnectorElementModel | LocalConnectorElementModel

Returns ​

boolean

updatePath() ​

static updatePath(connector, path, elementGetter?): void

Parameters ​
connector ​

ConnectorElementModel | LocalConnectorElementModel

path ​

PointLocation[] | null

elementGetter? ​

(id) => GfxModel | null

Returns ​

void

PathGenerator ​

Extended by ​
Constructors ​
Constructor ​

new PathGenerator(): PathGenerator

Returns ​

PathGenerator

Properties ​
_aStarRunner ​

protected _aStarRunner: AStarRunner | null = null

Methods ​
_prepareOrthogonalConnectorInfo() ​

protected _prepareOrthogonalConnectorInfo(connectorInfo): [IVec, IVec, IVec, IVec, Bound | null, Bound | null, Bound | null, Bound | null]

Parameters ​
connectorInfo ​

OrthogonalConnectorInput

Returns ​

[IVec, IVec, IVec, IVec, Bound | null, Bound | null, Bound | null, Bound | null]

generateOrthogonalConnectorPath() ​

generateOrthogonalConnectorPath(input): IVec[]

Parameters ​
input ​

OrthogonalConnectorInput

Returns ​

IVec[]

ConnectorElementView ​

The methods that a graphic element should implement. It is already included in the GfxCompatibleInterface interface.

Extends ​
Constructors ​
Properties ​
type ​

static type: string = 'connector'

Overrides ​

GfxElementModelView.type

Accessors ​
Methods ​
onCreated() ​

onCreated(): void

Returns ​

void

Overrides ​

GfxElementModelView.onCreated

onDragEnd() ​

onDragEnd(context): void

Parameters ​
context ​

DragMoveContext

Returns ​

void

Overrides ​

GfxElementModelView.onDragEnd

onDragMove() ​

onDragMove(context): void

Parameters ​
context ​

DragMoveContext

Returns ​

void

Overrides ​

GfxElementModelView.onDragMove

onDragStart() ​

onDragStart(context): void

Parameters ​
context ​

DragStartContext

Returns ​

void

Overrides ​

GfxElementModelView.onDragStart

Type Aliases ​

Connectable ​

Connectable = Exclude<GfxModel, ConnectorElementModel | BrushElementModel | GroupElementModel>

ConnectorToolOptions ​

ConnectorToolOptions = object

Properties ​

mode ​

mode: ConnectorMode

OrthogonalConnectorInput ​

OrthogonalConnectorInput = object

Properties ​

endBound ​

endBound: Bound | null

endPoint ​

endPoint: PointLocation

startBound ​

startBound: Bound | null

startPoint ​

startPoint: PointLocation

Variables ​

connector ​

const connector: ElementRenderer<ConnectorElementModel | LocalConnectorElementModel>

ConnectorDomRendererExtension ​

const ConnectorDomRendererExtension: ExtensionType

Extension to register the DOM-based renderer for 'connector' elements.

ConnectorElementRendererExtension ​

const ConnectorElementRendererExtension: ExtensionType & object

Type Declaration ​

identifier ​

identifier: ServiceIdentifier<ElementRenderer<ConnectorElementModel | LocalConnectorElementModel>>

ConnectorEndpointLocations ​

const ConnectorEndpointLocations: IVec[]

ConnectorEndpointLocationsOnTriangle ​

const ConnectorEndpointLocationsOnTriangle: IVec[]

ConnectorInteraction ​

const ConnectorInteraction: ExtensionType

connectorQuickTool ​

const connectorQuickTool: ExtensionType

connectorToMarkdownAdapterMatcher ​

const connectorToMarkdownAdapterMatcher: ExtensionType & object

Type Declaration ​

identifier ​

identifier: ServiceIdentifier<ElementToMarkdownAdapterMatcher>

connectorToolbarConfig ​

const connectorToolbarConfig: object

Type Declaration ​

actions ​

readonly actions: [{ id: "a.stroke-color"; content: TemplateResult<1> | null; }, { id: "b.style"; when: (ctx) => boolean; content: TemplateResult<1> | null; }, { actions: [{ id: "a.start-point-style"; content: TemplateResult<1> | null; }, { icon: TemplateResult<1>; id: "b.flip-direction"; tooltip: "Flip direction"; run: void; }, { id: "c.end-point-style"; content: TemplateResult<1> | null; }, { id: "d.connector-shape"; content: TemplateResult<1> | null; }]; id: "c.endpoint-style"; }, { icon: TemplateResult<1>; id: "g.text"; tooltip: "Add text"; run: void; when: boolean; }, ...ToolbarGenericAction[]]

when ​

readonly when: (ctx) => boolean

Parameters ​
ctx ​

ToolbarContext

Returns ​

boolean

connectorToolbarExtension ​

const connectorToolbarExtension: ExtensionType

connectorToPlainTextAdapterMatcher ​

const connectorToPlainTextAdapterMatcher: ExtensionType & object

Type Declaration ​

identifier ​

identifier: ServiceIdentifier<ElementToPlainTextAdapterMatcher>

Functions ​

calculateNearestLocation() ​

calculateNearestLocation(point, bounds, locations?, shortestDistance?): IVec

Parameters ​

point ​

IVec

bounds ​

IBound

locations? ​

IVec[] = ConnectorEndpointLocations

shortestDistance? ​

number = Number.POSITIVE_INFINITY

Returns ​

IVec

connectorBaseDomRenderer() ​

connectorBaseDomRenderer(model, element, renderer): void

Renders a ConnectorElementModel to a given HTMLElement using DOM/SVG. This function is intended to be registered via the DomElementRendererExtension.

Parameters ​

model ​

ConnectorElementModel | LocalConnectorElementModel

The connector element model containing rendering properties.

element ​

HTMLElement

The HTMLElement to apply the connector's styles to.

renderer ​

DomRenderer

The main DOMRenderer instance, providing access to viewport and color utilities.

Returns ​

void

connectorDomRenderer() ​

connectorDomRenderer(model, element, renderer): void

Parameters ​

model ​

ConnectorElementModel

element ​

HTMLElement

renderer ​

DomRenderer

Returns ​

void

getAnchors() ​

getAnchors(ele): object[]

Parameters ​

ele ​

GfxModel

Returns ​

object[]

getNearestConnectableAnchor() ​

getNearestConnectableAnchor(ele, point): PointLocation | null

Parameters ​

ele ​

Connectable

point ​

IVec

Returns ​

PointLocation | null

isConnectorAndBindingsAllSelected() ​

isConnectorAndBindingsAllSelected(connector, selected): boolean

Parameters ​

connector ​

ConnectorElementModel | LocalConnectorElementModel

selected ​

GfxModel[]

Returns ​

boolean

isConnectorWithLabel() ​

isConnectorWithLabel(model): boolean

Parameters ​

model ​

GfxModel | GfxLocalElementModel

Returns ​

boolean

mountConnectorLabelEditor() ​

mountConnectorLabelEditor(connector, edgeless, point?): void

Parameters ​

connector ​

ConnectorElementModel

edgeless ​

BlockComponent

point? ​

IVec

Returns ​

void

Copyright © 2022-present Toeverything