Ir para o conteúdo principal

Conceitos fundamentais

O modelo de bloco

O coração de EditorData é o array blocks: objetos Block que preservam a ordem. Cada Block carrega seu tipo, dados específicos do tipo e metadados tunes opcionais.

CampoTipoDescrição
idstring | undefinedIdentificador único opcional, atribuído pelo editor na criação.
typeBlockToolTypeChave literal que vincula o bloco ao seu esquema, componente de entrada e renderizador.
dataobjectObjeto de dados específico do tipo: a forma difere por tipo de bloco.
tunesBlockTunes | undefinedDicionário opcional de metadados tune entre tipos. A chave é o nome do tune e o valor são dados de formato livre.
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." }
    }
  ]
}

Ferramentas de bloco vs ferramentas inline

Ferramentas de bloco criam slots de nível superior diretamente dentro de EditorData. Ferramentas inline decoram texto dentro do payload html que um bloco contém. As duas camadas são inteiramente separadas: não podem ser substituídas uma pela outra.

Saída JSON-first

O editor nunca persiste HTML. Ao chamar editor.data.extract(), você obtém JSON puro de EditorData: completo incluindo URLs de mídia. Esse JSON pode ser armazenado em um banco de dados, personalizado ou convertido para outros 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 o DOM do navegador para permitir que um usuário edite conteúdo (somente navegador). Renderer pega EditorData previamente salvo e o renderiza como HTML (pode rodar no navegador ou via SSR).

Ajustes de bloco

Tunes são um slot de metadados tipo-agnóstico para qualquer tipo de bloco. A chave é o nome do tune definido pelo sistema ou um plugin, e o valor é tipado para BlockTuneData: qualquer combinação de string, number, boolean ou null. Tunes podem adicionar semântica sem quebrar a forma dos dados principais.

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