Skip to main content

@lexical/html/BlockIdHTMLExtension

Interfaces​

BlockIdHTMLConfig​

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

Experimental

Properties​

export​

export: boolean

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

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:119

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:129

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:63

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:54

Experimental

The attribute that carries a block id in HTML.

BLOCK_WRAPPER_ID_ATTRIBUTE​

const BLOCK_WRAPPER_ID_ATTRIBUTE: "data-block-wrapper-id" = 'data-block-wrapper-id'

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

Experimental

The attribute that carries the block id of a block whose own element its export removes, handing its children to another element: a list item that only wraps a nested list is exported as that nested list, inside the previous item's element. The id goes on the first element the block's element held (the nested list), and import puts it back on the block that ends up holding only what that element produced (the wrapper item), where the import of that element, its parent or its grandparent makes it (the list importer does, in the outer list); otherwise that block gets a new id.

BlockIdHTMLExtension​

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

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

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.