BlockSuite API Documentation / @blocksuite/affine-block-frame

@blocksuite/affine-block-frame

Classes

Extension

EdgelessClipboardFrameConfig

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

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

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

Step 2: Create a service identifier

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

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

Step 3: Create implementations

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

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

Step 5: Create concrete extensions

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

Step 6: Use the extensions

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

• EdgelessClipboardConfig

Constructors

Properties

key

readonly static key: "affine:frame" = 'affine:frame'

Overrides

EdgelessClipboardConfig.key

Accessors

Methods

createBlock()

createBlock(frame, context): string | null

Parameters

frame

BlockSnapshot

context

ClipboardConfigCreationContext

Returns

string | null

Overrides

EdgelessClipboardConfig.createBlock

---

FrameHighlightManager

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

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

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

Step 2: Create a service identifier

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

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

Step 3: Create implementations

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

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

Step 5: Create concrete extensions

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

Step 6: Use the extensions

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

• InteractivityExtension

Constructors

Properties

key

static key: string = 'frame-highlight-manager'

Overrides

InteractivityExtension.key

Accessors

frameHighlightOverlay

Get Signature

get frameHighlightOverlay(): FrameOverlay

Returns

FrameOverlay

frameMgr

Get Signature

get frameMgr(): EdgelessFrameManager

Returns

EdgelessFrameManager

Methods

mounted()

mounted(): void

Returns

void

Overrides

InteractivityExtension.mounted

---

EdgelessFrameManager

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

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

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

Step 2: Create a service identifier

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

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

Step 3: Create implementations

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

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

Step 5: Create concrete extensions

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

Step 6: Use the extensions

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

• GfxExtension

Constructors

Constructor

new EdgelessFrameManager(gfx): EdgelessFrameManager

Parameters

gfx

GfxController

Returns

EdgelessFrameManager

Overrides

GfxExtension.constructor

Properties

key

static key: string = 'frame-manager'

Overrides

GfxExtension.key

Accessors

frames

Get Signature

get frames(): FrameBlockModel[]

Get all sorted frames by presentation orderer, the legacy frame that uses index as presentation order will be put at the beginning of the array.

Returns

FrameBlockModel[]

Methods

addElementsToFrame()

addElementsToFrame(frame, elements): void

Reset parent of elements to the frame

Parameters

frame

FrameBlockModel

elements

GfxModel[]

Returns

void

createFrameOnBound()

createFrameOnBound(bound): FrameBlockModel

Parameters

bound

Bound

Returns

FrameBlockModel

createFrameOnElements()

createFrameOnElements(elements): FrameBlockModel | undefined

Parameters

elements

GfxModel[]

Returns

FrameBlockModel | undefined

createFrameOnSelected()

createFrameOnSelected(): FrameBlockModel | undefined

Returns

FrameBlockModel | undefined

createFrameOnViewportCenter()

createFrameOnViewportCenter(wh): void

Parameters

wh

[number, number]

Returns

void

generatePresentationIndex()

generatePresentationIndex(): string

Returns

string

getChildElementsInFrame()

getChildElementsInFrame(frame): GfxModel[]

Get all elements in the frame, there are three cases:

1. The frame doesn't have childElements, return all elements in the frame bound but not owned by another frame.
2. Return all child elements of the frame if childElements exists.

Parameters

frame

FrameBlockModel

Returns

GfxModel[]

getElementsInFrameBound()

getElementsInFrameBound(frame, fullyContained?): GfxModel[]

Get all elements in the frame bound, whatever the element already has another parent frame or not.

Parameters

frame

FrameBlockModel

fullyContained?

boolean = true

Returns

GfxModel[]

getFrameFromPoint()

getFrameFromPoint(__namedParameters, ignoreFrames?): FrameBlockModel | null

Get most top frame from the point.

Parameters

__namedParameters

IVec

ignoreFrames?

FrameBlockModel[] = []

Returns

FrameBlockModel | null

getParentFrame()

getParentFrame(element): FrameBlockModel | null

Parameters

element

GfxModel

Returns

FrameBlockModel | null

refreshLegacyFrameOrder()

refreshLegacyFrameOrder(): void

This method will populate presentationIndex for all legacy frames, and keep the orderer of the legacy frames.

Returns

void

removeAllChildrenFromFrame()

removeAllChildrenFromFrame(frame): void

Parameters

frame

FrameBlockModel

Returns

void

removeFromParentFrame()

removeFromParentFrame(element): void

Parameters

element

GfxModel

Returns

void

unmounted()

unmounted(): void

Returns

void

Overrides

GfxExtension.unmounted

framePresentationComparator()

static framePresentationComparator<T>(a, b): -1 | 0 | 1

Type Parameters

T

T extends FrameBlockModel | { props: { index: string; presentationIndex?: string; }; }

Parameters

a

T

b

T

Returns

-1 | 0 | 1

---

FrameTool

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

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

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

Step 2: Create a service identifier

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

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

Step 3: Create implementations

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

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

Step 5: Create concrete extensions

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

Step 6: Use the extensions

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

• BaseTool

Constructors

Properties

toolName

static toolName: string = 'frame'

Overrides

BaseTool.toolName

Accessors

frameManager

Get Signature

get frameManager(): EdgelessFrameManager

Returns

EdgelessFrameManager

frameOverlay

Get Signature

get frameOverlay(): FrameOverlay

Returns

FrameOverlay

Methods

dragEnd()

dragEnd(): void

Returns

void

Overrides

BaseTool.dragEnd

dragMove()

dragMove(e): void

Parameters

e

PointerEventState

Returns

void

Overrides

BaseTool.dragMove

dragStart()

dragStart(e): void

Parameters

e

PointerEventState

Returns

void

Overrides

BaseTool.dragStart

---

PresentTool

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

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

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

Step 2: Create a service identifier

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

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

Step 3: Create implementations

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

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

Step 5: Create concrete extensions

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

Step 6: Use the extensions

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

• BaseTool<PresentToolOption>

Constructors

Properties

toolName

static toolName: string = 'frameNavigator'

Overrides

BaseTool.toolName

Accessors

Methods

Other

EdgelessFrameMenu

Extends

• LitElement<this> & EdgelessToolbarToolClass<this>

Constructors

Other

type

type: typeof FrameTool = FrameTool

Overrides

EdgelessToolbarToolMixin(LitElement).type

styles

static styles: CSSResult

Overrides

EdgelessToolbarToolMixin(LitElement).styles

frameManager

Get Signature

get frameManager(): EdgelessFrameManager

Returns

EdgelessFrameManager

attributes

controllers

dev-mode

lifecycle

properties

rendering

render()

render(): TemplateResult<1>

Invoked on each update to perform rendering tasks. This method may return any value renderable by lit-html's ChildPart - typically a TemplateResult. Setting properties inside this method will not trigger the element to update.

Returns

TemplateResult<1>

Overrides

EdgelessToolbarToolMixin(LitElement).render

styles

updates

---

EdgelessFrameToolButton

Extends

• LitElement<this> & QuickToolMixinClass<this>

Constructors

Other

type

type: typeof FrameTool = FrameTool

Overrides

QuickToolMixin(LitElement).type

styles

static styles: CSSResult

Overrides

QuickToolMixin(LitElement).styles

attributes

controllers

dev-mode

lifecycle

properties

rendering

render()

render(): TemplateResult<1>

Invoked on each update to perform rendering tasks. This method may return any value renderable by lit-html's ChildPart - typically a TemplateResult. Setting properties inside this method will not trigger the element to update.

Returns

TemplateResult<1>

Overrides

QuickToolMixin(LitElement).render

styles

updates

---

FrameBlockComponent

Extends

• GfxBlockComponent<FrameBlockModel>

Constructors

Other

showBorder

connectedCallback()

connectedCallback(): void

Returns

void

Overrides

GfxBlockComponent.connectedCallback

getCSSTransform()

getCSSTransform(): string

Due to potentially very large frame sizes, CSS scaling can cause iOS Safari to crash. To mitigate this issue, we combine size calculations within the rendering rect.

Returns

string

Overrides

GfxBlockComponent.getCSSTransform

getRenderingRect()

getRenderingRect(): object

Returns

object

h

h: number

rotate

rotate: number

w

w: number

x

x: number = scaledX

y

y: number = scaledY

zIndex

zIndex: string

Overrides

GfxBlockComponent.getRenderingRect

onBoxSelected()

onBoxSelected(context): boolean

When the element is selected by box selection, return false to prevent the default selection behavior.

Parameters

context

BoxSelectionContext

Returns

boolean

Overrides

GfxBlockComponent.onBoxSelected

renderGfxBlock()

renderGfxBlock(): TemplateResult<1>

Returns

TemplateResult<1>

Overrides

GfxBlockComponent.renderGfxBlock

attributes

controllers

dev-mode

lifecycle

properties

rendering

styles

updates

---

FrameOverlay

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

Extends

• Overlay

Constructors

Constructor

new FrameOverlay(gfx): FrameOverlay

Parameters

gfx

GfxController

Returns

FrameOverlay

Overrides

Overlay.constructor

Properties

overlayName

static overlayName: string = 'frame'

Overrides

Overlay.overlayName

Methods

clear()

clear(): void

Returns

void

Overrides

Overlay.clear

highlight()

highlight(frame, highlightElementsInBound?, highlightOutline?): void

Parameters

frame

FrameBlockModel

highlightElementsInBound?

boolean = false

highlightOutline?

boolean = true

Returns

void

render()

render(ctx): void

Parameters

ctx

CanvasRenderingContext2D

Returns

void

Overrides

Overlay.render

Type Aliases

NavigatorMode

NavigatorMode = "fill" | "fit"

---

PresentToolOption

PresentToolOption = object

Properties

mode?

optional mode?: NavigatorMode

restoredAfterPan?

optional restoredAfterPan?: boolean

Variables

buildFrameDenseMenu

const buildFrameDenseMenu: DenseMenuBuilder

---

EdgelessFrameManagerIdentifier

const EdgelessFrameManagerIdentifier: ServiceIdentifier<EdgelessFrameManager>

---

FrameBlockInteraction

const FrameBlockInteraction: ExtensionType

---

FrameBlockSpec

const FrameBlockSpec: ExtensionType[]

---

FrameConfig

const FrameConfig: object[]

Type Declaration

name

name: string

wh

wh: [number, number]

---

frameQuickTool

const frameQuickTool: ExtensionType

---

frameToolbarExtension

const frameToolbarExtension: ExtensionType

Functions

isFrameBlock()

isFrameBlock(element): element is FrameBlockModel

Parameters

element

unknown

Returns

element is FrameBlockModel