Skip to main content

@lexical/html/BlockIdHTMLExtension

Interfaces​

BlockIdHTMLConfig​

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

Experimental

Properties​

export​

export: boolean | "handle"

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

Experimental

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

Showing blocks to a model? Use 'handle': it writes BLOCK_HANDLE_ATTRIBUTE with the block's handle, the shortest unique prefix of its id (4 characters or more), instead of the id. 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 that took its prefix. Import does not read handles, so a handle is never mistaken for an id.

configExtension(BlockIdHTMLExtension, {export: 'handle'});
// 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="9xQe">Revenue grew 4% in Q3.</p>
// The model answers {block: '9xQe', 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:107

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 export: 'handle'. 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<BlockIdHTMLConfig>, unknown>

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

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, export: 'handle' writes short handles in data-block-handle instead (see BlockIdHTMLConfig.export).

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.