BlockSuite

Appearance

BlockSuite API Documentation / @blocksuite/affine-block-embed-doc

@blocksuite/affine-block-embed-doc ​

Classes ​

Extension ​

EdgelessClipboardEmbedLinkedDocConfig ​

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 ​

readonly static key: "affine:embed-linked-doc" = 'affine:embed-linked-doc'

Overrides ​

EdgelessClipboardConfig.key

Accessors ​
Methods ​
createBlock() ​

createBlock(linkedDocEmbed): string | null

Parameters ​
linkedDocEmbed ​

BlockSnapshot

Returns ​

string | null

Overrides ​

EdgelessClipboardConfig.createBlock

EdgelessClipboardEmbedSyncedDocConfig ​

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 ​

readonly static key: "affine:embed-synced-doc" = 'affine:embed-synced-doc'

Overrides ​

EdgelessClipboardConfig.key

Accessors ​
Methods ​
createBlock() ​

createBlock(syncedDocEmbed): string | null

Parameters ​
syncedDocEmbed ​

BlockSnapshot

Returns ​

string | null

Overrides ​

EdgelessClipboardConfig.createBlock

Other ​

EmbedEdgelessLinkedDocBlockComponent ​

Extends ​
Constructors ​
Other ​
_handleClick() ​

protected _handleClick(evt): void

Parameters ​
evt ​

MouseEvent

Returns ​

void

Overrides ​

toEdgelessEmbedBlock( EmbedLinkedDocBlockComponent )._handleClick

convertToEmbed() ​

convertToEmbed(): void

Returns ​

void

Overrides ​

toEdgelessEmbedBlock( EmbedLinkedDocBlockComponent ).convertToEmbed

attributes ​
controllers ​
dev-mode ​
properties ​
rendering ​
styles ​
updates ​

EmbedLinkedDocBlockComponent ​

Extends ​
Constructors ​
Other ​
_cardStyle ​

_cardStyle: "list" | "citation" | "horizontal" | "horizontalThin" | "vertical" | "cube" = 'horizontal'

Overrides ​

EmbedBlockComponent._cardStyle

icon$ ​

icon$: ReadonlySignal<TemplateResult>

referenceInfo$ ​

referenceInfo$: ReadonlySignal<{ description?: string; pageId: string; params?: { blockIds?: string[]; commentId?: string; databaseId?: string; databaseRowId?: string; elementIds?: string[]; mode?: "edgeless" | "page"; xywh?: `[${number},${number},${number},${number}]`; }; title?: string; }>

title$ ​

title$: ReadonlySignal<ReadonlySignal<string>>

styles ​

static styles: CSSResult

Overrides ​

EmbedBlockComponent.styles

citationService ​
Get Signature ​

get citationService(): CitationViewService

Returns ​

CitationViewService

docTitle ​
Get Signature ​

get docTitle(): string

Returns ​

string

editorMode ​
Get Signature ​

get editorMode(): DocMode

Returns ​

DocMode

isBannerEmpty ​
isCitation ​
Get Signature ​

get isCitation(): boolean

Returns ​

boolean

isError ​
isNoteContentEmpty ​
linkedDoc ​
Get Signature ​

get linkedDoc(): Store | undefined

Returns ​

Store | undefined

noteContainer ​
readonly ​
Get Signature ​

get readonly(): boolean

Returns ​

boolean

_handleClick() ​

protected _handleClick(event): void

Parameters ​
event ​

MouseEvent

Returns ​

void

connectedCallback() ​

connectedCallback(): void

Returns ​

void

Overrides ​

EmbedBlockComponent.connectedCallback

convertToEmbed() ​

convertToEmbed(): void

Returns ​

void

convertToInline() ​

convertToInline(): void

Returns ​

void

getInitialState() ​

getInitialState(): object

Returns ​

object

isBannerEmpty? ​

optional isBannerEmpty: boolean

isError? ​

optional isError: boolean

isNoteContentEmpty? ​

optional isNoteContentEmpty: boolean

loading? ​

optional loading: boolean

open() ​

open(__namedParameters): void

Parameters ​
__namedParameters ​
event? ​

MouseEvent

openMode? ​

OpenDocMode

Returns ​

void

refreshData() ​

refreshData(): void

Returns ​

void

renderBlock() ​

renderBlock(): TemplateResult<1>

Returns ​

TemplateResult<1>

Overrides ​

EmbedBlockComponent.renderBlock

attributes ​
controllers ​
dev-mode ​
properties ​
rendering ​
styles ​
updates ​
updated() ​

updated(): void

Invoked whenever the element is updated. Implement to perform post-updating tasks via DOM APIs, for example, focusing an element.

Setting properties inside this method will trigger the element to update again after this update cycle completes.

Returns ​

void

Overrides ​

EmbedBlockComponent.updated

EmbedEdgelessSyncedDocBlockComponent ​

Extends ​
Constructors ​
Other ​
contentElement ​
headerWrapper ​
useCaptionEditor ​
Overrides ​

toEdgelessEmbedBlock( EmbedSyncedDocBlockComponent ).useCaptionEditor

_renderSyncedView() ​

protected _renderSyncedView(): TemplateResult<1>

Returns ​

TemplateResult<1>

Overrides ​

toEdgelessEmbedBlock( EmbedSyncedDocBlockComponent )._renderSyncedView

convertToCard() ​

convertToCard(aliasInfo?): void

Parameters ​
aliasInfo? ​
description? ​

string

title? ​

string

Returns ​

void

Overrides ​

toEdgelessEmbedBlock( EmbedSyncedDocBlockComponent ).convertToCard

renderGfxBlock() ​

renderGfxBlock(): unknown

Returns ​

unknown

Overrides ​

toEdgelessEmbedBlock( EmbedSyncedDocBlockComponent ).renderGfxBlock

attributes ​
controllers ​
dev-mode ​
properties ​
rendering ​
styles ​
updates ​

EmbedSyncedDocBlockComponent ​

Extends ​
Constructors ​
Other ​
cardStyleMap ​

protected cardStyleMap: DirectiveResult<typeof StyleMapDirective>

embedContainerStyle ​

protected embedContainerStyle: StyleInfo

The style of the embed card. You can use this to change the height and width of the card. By default, the height and width are set to _cardHeight and _cardWidth respectively.

Overrides ​

EmbedBlockComponent.embedContainerStyle

icon$ ​

icon$: ReadonlySignal<TemplateResult>

title$ ​

title$: ReadonlySignal<ReadonlySignal<string>>

styles ​

static styles: CSSResult = blockStyles

Overrides ​

EmbedBlockComponent.styles

_isEmptySyncedDoc ​
blockState ​
Get Signature ​

get blockState(): object

Returns ​

object

isCycle ​

isCycle: boolean

isDeleted ​

isDeleted: boolean

isError ​

isError: boolean

isLoading ​

isLoading: boolean

depth ​
docTitle ​
Get Signature ​

get docTitle(): string

Returns ​

string

docUpdatedAt ​
Get Signature ​

get docUpdatedAt(): Date

Returns ​

Date

editorMode ​
Get Signature ​

get editorMode(): DocMode

Returns ​

DocMode

isPageMode ​
Get Signature ​

get protected isPageMode(): boolean

Returns ​

boolean

linkedMode ​
Get Signature ​

get linkedMode(): "edgeless" | "page" | undefined

Returns ​

"edgeless" | "page" | undefined

referenceInfo ​
Get Signature ​

get referenceInfo(): object

Returns ​

object

description? ​

optional description: string

pageId ​

pageId: string

params? ​

optional params: object

params.blockIds? ​

optional params.blockIds: string[]

params.commentId? ​

optional params.commentId: string

params.databaseId? ​

optional params.databaseId: string

params.databaseRowId? ​

optional params.databaseRowId: string

params.elementIds? ​

optional params.elementIds: string[]

params.mode? ​

optional params.mode: "edgeless" | "page"

params.xywh? ​

optional params.xywh: `[${number},${number},${number},${number}]`

title? ​

optional title: string

syncedDoc ​
Get Signature ​

get syncedDoc(): Store | null

Returns ​

Store | null

syncedDocCard ​
syncedDocEditorHost ​
syncedDocMode ​
useCaptionEditor ​
Overrides ​

EmbedBlockComponent.useCaptionEditor

_buildPreviewSpec() ​

protected _buildPreviewSpec(name): ExtensionType[]

Parameters ​
name ​

"preview-page" | "preview-edgeless"

Returns ​

ExtensionType[]

_handleClick() ​

protected _handleClick(_event): void

Parameters ​
_event ​

MouseEvent

Returns ​

void

_renderSyncedView() ​

protected _renderSyncedView(): TemplateResult<1>

Returns ​

TemplateResult<1>

connectedCallback() ​

connectedCallback(): void

Returns ​

void

Overrides ​

EmbedBlockComponent.connectedCallback

convertToCard() ​

convertToCard(aliasInfo?): void

Parameters ​
aliasInfo? ​
description? ​

string

title? ​

string

Returns ​

void

convertToInline() ​

convertToInline(): void

Returns ​

void

open() ​

open(event?): void

Parameters ​
event? ​

Partial<DocLinkClickedEvent>

Returns ​

void

refreshData() ​

refreshData(): void

Returns ​

void

renderBlock() ​

renderBlock(): TemplateResult<1>

Returns ​

TemplateResult<1>

Overrides ​

EmbedBlockComponent.renderBlock

attributes ​
controllers ​
dev-mode ​
properties ​
rendering ​
styles ​
updates ​
firstUpdated() ​

firstUpdated(): void

Invoked when the element is first updated. Implement to perform one time work on the element after update.

ts
firstUpdated() {
  this.renderRoot.getElementById('my-text-area').focus();
}

Setting properties inside this method will trigger the element to update again after this update cycle completes.

Returns ​

void

Overrides ​

EmbedBlockComponent.firstUpdated

updated() ​

updated(changedProperties): void

Invoked whenever the element is updated. Implement to perform post-updating tasks via DOM APIs, for example, focusing an element.

Setting properties inside this method will trigger the element to update again after this update cycle completes.

Parameters ​
changedProperties ​

PropertyValueMap<any> | Map<PropertyKey, unknown>

Returns ​

void

Overrides ​

EmbedBlockComponent.updated

Type Aliases ​

EmbedSyncedDocConfig ​

EmbedSyncedDocConfig = object

Properties ​

edgelessHeader() ​

edgelessHeader: (context) => TemplateResult

Parameters ​
context ​
model ​

EmbedSyncedDocModel

std ​

BlockStdScope

Returns ​

TemplateResult

InsertedLinkType ​

InsertedLinkType = { flavour: LinkableFlavour; } | null

LinkableFlavour ​

LinkableFlavour = "affine:bookmark" | "affine:embed-linked-doc" | "affine:embed-synced-doc" | "affine:embed-iframe" | "affine:embed-figma" | "affine:embed-github" | "affine:embed-loom" | "affine:embed-youtube"

Variables ​

embedLinkedDocBlockHtmlAdapterMatcher ​

const embedLinkedDocBlockHtmlAdapterMatcher: BlockHtmlAdapterMatcher

embedLinkedDocBlockMarkdownAdapterMatcher ​

const embedLinkedDocBlockMarkdownAdapterMatcher: BlockMarkdownAdapterMatcher

EmbedLinkedDocBlockPlainTextAdapterExtension ​

const EmbedLinkedDocBlockPlainTextAdapterExtension: ExtensionType & object

Type Declaration ​

identifier ​

identifier: ServiceIdentifier<BlockPlainTextAdapterMatcher>

embedLinkedDocBlockPlainTextAdapterMatcher ​

const embedLinkedDocBlockPlainTextAdapterMatcher: BlockPlainTextAdapterMatcher

EmbedLinkedDocHtmlAdapterExtension ​

const EmbedLinkedDocHtmlAdapterExtension: ExtensionType & object

Type Declaration ​

identifier ​

identifier: ServiceIdentifier<BlockHtmlAdapterMatcher>

EmbedLinkedDocInteraction ​

const EmbedLinkedDocInteraction: ExtensionType

EmbedLinkedDocMarkdownAdapterExtension ​

const EmbedLinkedDocMarkdownAdapterExtension: ExtensionType & object

Type Declaration ​

identifier ​

identifier: ServiceIdentifier<BlockMarkdownAdapterMatcher>

EmbedLinkedDocViewExtensions ​

const EmbedLinkedDocViewExtensions: ExtensionType[]

EmbedSyncedDocBlockHtmlAdapterExtension ​

const EmbedSyncedDocBlockHtmlAdapterExtension: ExtensionType & object

Type Declaration ​

identifier ​

identifier: ServiceIdentifier<BlockHtmlAdapterMatcher>

embedSyncedDocBlockHtmlAdapterMatcher ​

const embedSyncedDocBlockHtmlAdapterMatcher: BlockHtmlAdapterMatcher

embedSyncedDocBlockMarkdownAdapterMatcher ​

const embedSyncedDocBlockMarkdownAdapterMatcher: BlockMarkdownAdapterMatcher

EmbedSyncedDocBlockPlainTextAdapterExtension ​

const EmbedSyncedDocBlockPlainTextAdapterExtension: ExtensionType & object

Type Declaration ​

identifier ​

identifier: ServiceIdentifier<BlockPlainTextAdapterMatcher>

embedSyncedDocBlockPlainTextAdapterMatcher ​

const embedSyncedDocBlockPlainTextAdapterMatcher: BlockPlainTextAdapterMatcher

EmbedSyncedDocConfigExtension ​

const EmbedSyncedDocConfigExtension: ConfigFactory<EmbedSyncedDocConfig>

EmbedSyncedDocMarkdownAdapterExtension ​

const EmbedSyncedDocMarkdownAdapterExtension: ExtensionType & object

Type Declaration ​

identifier ​

identifier: ServiceIdentifier<BlockMarkdownAdapterMatcher>

EmbedSyncedDocViewExtensions ​

const EmbedSyncedDocViewExtensions: ExtensionType[]

insertEmbedLinkedDocCommand ​

const insertEmbedLinkedDocCommand: Command<{ docId: string; params?: ReferenceParams; }, { blockId: string; }>

insertEmbedSyncedDocCommand ​

const insertEmbedSyncedDocCommand: Command<{ docId: string; params?: ReferenceParams; }, { blockId: string; }>

LinkedDocSlashMenuConfigIdentifier ​

const LinkedDocSlashMenuConfigIdentifier: ServiceIdentifier<SlashMenuConfig>

SYNCED_MIN_HEIGHT ​

const SYNCED_MIN_HEIGHT: 48 = 48

SYNCED_MIN_WIDTH ​

const SYNCED_MIN_WIDTH: 370 = 370

Functions ​

getEmbedLinkedDocIcons() ​

getEmbedLinkedDocIcons(theme, editorMode, style): EmbedCardImages

Parameters ​

theme ​

ColorScheme

editorMode ​

"edgeless" | "page"

style ​

"list" | "citation" | "horizontal" | "horizontalThin" | "vertical" | "cube"

Returns ​

EmbedCardImages

Copyright © 2022-present Toeverything