Skip to main content

@lexical/html/BlockIdHTMLExtension

Interfaces​

BlockIdHTMLConfig​

Defined in: packages/lexical-html/src/BlockIdHTMLExtension.ts:64

Experimental

Properties​

export​

export: boolean

Defined in: packages/lexical-html/src/BlockIdHTMLExtension.ts:71

Experimental

Write BLOCK_ID_ATTRIBUTE on the exported element of every identified block ($generateHtmlFromNodes, copy as HTML, …).

Showing blocks to a model? Set BlockIdHTMLConfig.handles too.

handles?​

optional handles?: boolean

Defined in: packages/lexical-html/src/BlockIdHTMLExtension.ts:103

Experimental

With BlockIdHTMLConfig.export on, write each block's handle in BLOCK_HANDLE_ATTRIBUTE instead of its id in BLOCK_ID_ATTRIBUTE: a short opaque name derived from a hash of the id (see $getBlockHandle), for HTML shown to a model. Keep the handles of the export ($getBlockHandles(), in the same read), and resolve what the model answers with $resolveBlockHandle(handle, {read}), so that a handle names the block the model was shown, never a block added since. Import does not read handles, so a handle is never mistaken for an id. Default: false. Optional, so that a whole BlockIdHTMLConfig written for an earlier version still type-checks.

configExtension(BlockIdHTMLExtension, {handles: true});
// The HTML the model reads, and the handles it is shown, in one read.
const [html, shown] = editor.read(() => [
  $generateHtmlFromNodes(editor),
  $getBlockHandles(),
]);
// <p data-block-handle="gTtF">Revenue grew 4% in Q3.</p>
// The model answers {block: 'gTtF', text: 'Revenue grew 6% in Q3.'}
editor.update(() => {
  const result = $resolveBlockHandle(op.block, {read: shown});
  if (result.status === 'found') {
    // In place, only the characters that differ (the Block IDs page has
    // this `$setBlockText`), rather than re-creating the block.
    $setBlockText(result.node, op.text);
  }
});
import​

import: boolean

Defined in: packages/lexical-html/src/BlockIdHTMLExtension.ts:113

Experimental

Read BLOCK_ID_ATTRIBUTE back when HTML is imported through DOMImportExtension, onto the block that the element produced. Imported ids are never trusted: an invalid one is ignored, and a valid one goes through the uniqueness rule of BlockIdExtension, so pasting HTML that carries ids already in the document gives the pasted blocks fresh ids. An imported id is dropped from a block that is not identified once it is inserted (a table cell, a nested list).

Variables​

BLOCK_HANDLE_ATTRIBUTE​

const BLOCK_HANDLE_ATTRIBUTE: "data-block-handle" = 'data-block-handle'

Defined in: packages/lexical-html/src/BlockIdHTMLExtension.ts:61

Experimental

The attribute that carries a block handle (see $getBlockHandle in @lexical/extension) in HTML exported with handles: true. Import never reads it.

BLOCK_ID_ATTRIBUTE​

const BLOCK_ID_ATTRIBUTE: "data-block-id" = 'data-block-id'

Defined in: packages/lexical-html/src/BlockIdHTMLExtension.ts:52

Experimental

The attribute that carries a block id in HTML.

BlockIdHTMLExtension​

const BlockIdHTMLExtension: LexicalExtension<BlockIdHTMLConfig, "@lexical/html/BlockIdHTML", NamedSignalsOutput<{ export: boolean; handles: boolean; import: boolean; }>, unknown>

Defined in: packages/lexical-html/src/BlockIdHTMLExtension.ts:174

Experimental

Opt-in HTML support for BlockIdExtension: exported HTML carries each identified block's id in a data-block-id attribute, and HTML imported through DOMImportExtension reads it back (through the uniqueness rule, so ids in pasted HTML never clash with ids in the document).

For HTML shown to a model, handles: true writes short handles in data-block-handle instead (see BlockIdHTMLConfig.handles).

This lives in @lexical/html rather than in BlockIdExtension because @lexical/html depends on @lexical/extension. The legacy $generateNodesFromDOM path (importDOM) does not read the attribute.