Saltar al contenido principal

Conceptos fundamentales

El modelo de bloque

El corazón de EditorData es el array blocks: objetos Block que preservan el orden. Cada Block lleva su tipo, datos específicos del tipo y metadatos tunes opcionales.

CampoTipoDescripción
idstring | undefinedIdentificador único opcional, asignado por el editor al crearse.
typeBlockToolTypeClave literal que vincula el bloque con su esquema, componente de entrada y renderizador.
dataobjectObjeto de datos específico del tipo: la forma difiere por tipo de bloque.
tunesBlockTunes | undefinedDiccionario de metadatos tune opcional entre tipos. La clave es el nombre del tune y el valor son datos de formato libre.
JSON
{
  "time": 1745000000000,
  "version": "1.0.0",
  "blocks": [
    {
      "id": "abc123",
      "type": "header",
      "data": { "html": "Hello world", "level": "h1" }
    },
    {
      "id": "def456",
      "type": "paragraph",
      "data": { "html": "This is a <b>rich</b> paragraph." }
    }
  ]
}

Herramientas de bloque vs herramientas en línea

Las herramientas de bloque crean ranuras de nivel superior directamente dentro de EditorData. Las herramientas en línea decoran el texto dentro del payload html que contiene un bloque. Las dos capas son completamente independientes: no pueden sustituirse entre sí.

Salida JSON-first

El editor nunca persiste HTML. Cuando llamas a editor.data.extract(), obtienes JSON puro de EditorData: completo, incluyendo URLs de medios. Este JSON puede almacenarse en una base de datos, personalizarse o convertirse a otros formatos.

TypeScript
import { Editor } from '@clepit/core';

const editor = Editor.create({ containerId: 'editor' });

const data = editor.data.extract();
// data: EditorData
// {
//   time: 1745000000000,
//   version: '1.0.0',
//   blocks: [ ... ]
// }

Editor vs Renderer

Editor usa el DOM del navegador para que un usuario edite contenido (solo navegador). Renderer toma EditorData guardado previamente y lo renderiza como HTML (puede ejecutarse en el navegador o mediante SSR).

Ajustes de bloque

Los tunes son un slot de metadatos independiente del tipo para cualquier tipo de bloque. La clave es el nombre del tune establecido por el sistema o un plugin, y el valor está tipado como BlockTuneData: cualquier combinación de string, number, boolean o null. Los tunes pueden añadir semántica sin romper la forma de los datos principales.

JSON
{
  "id": "abc123",
  "type": "paragraph",
  "data": { "html": "Some text." },
  "tunes": {
    "textAlign": { "alignment": "center" },
    "visibility": { "hidden": false }
  }
}