Ir al contenido

Texto enriquecido

Esta página es la referencia. Para declarar el campo, renderizarlo o migrar markdown, empieza por la guía del texto enriquecido.

Ruta Exporta Dónde corre
@kevolution-co/cms/rich-text renderToHtml, toPlainText, collectUploads y el tipo RenderOptions Donde quieras: sin DOM y sin Lexical
@kevolution-co/cms/rich-text/RichText.astro el componente RichText Astro, solo en el servidor
@kevolution-co/cms/rich-text/convert markdownToLexical, lexicalToMarkdown y los tipos RichTextConvertOptions y RichTextValue Servidor o scripts: usa @lexical/*
import RichText from '@kevolution-co/cms/rich-text/RichText.astro'
<RichText value={valor} class="prose" />
Prop Tipo Qué hace
value unknown El valor del campo. null y undefined no pintan nada
class string, opcional Clase del div que envuelve el resultado

No tiene directiva client: ni script: el componente no envía JavaScript. Si el resultado es una cadena vacía, no sale ningún div. Los upload se resuelven con Astro.locals.cms, en las colecciones que declaran upload; sin Astro.locals.cms (una página prerenderizada) no se resuelven y sus nodos no salen.

renderToHtml(value: unknown, options?: RenderOptions): string

Devuelve el HTML del árbol, con todo el texto y los atributos escapados. No lanza nunca: un valor que no es un árbol da ''.

renderToHtml(valor) // → '<p>Hola <strong>mundo</strong></p>'
Opción Tipo Qué hace
resolveUpload (node: { relationTo: string; value: string }) => { url: string; alt?: string } | null | undefined Dice la URL de un medio. Sin esta función, o si devuelve null o undefined, el nodo upload no sale. La URL solo se usa si es una ruta que empieza por / (sin // ni /\) o una URL https, y no lleva espacios ni caracteres de control. Si no cumple, el nodo no sale y no hay aviso: los ficheros de la biblioteca se sanean al subirlos (solo minúsculas, dígitos, ., _ y -), así que sus URL no llevan espacios. Si la función lanza, se avisa con warn y no sale
warn (message: string) => void Recibe un mensaje por cada nodo que se pinta como sus hijos o como nada, y por cada resolveUpload que falla. Si lanza, el render sigue

Los mensajes de warn son Unknown rich text node "<tipo>" y resolveUpload failed for "<slug>".

El HTML que sale de cada nodo:

Nodo HTML
paragraph <p>…</p>
heading (h1 a h6) <h1>…</h1>, <h2>…</h2>, <h3>…</h3>, <h4>…</h4>, <h5>…</h5>, <h6>…</h6>
list bullet <ul>…</ul>
list number <ol>…</ol>, con start="N" si el primer número no es 1
list check <ul class="contains-task-list">…</ul>
listitem <li>…</li>
listitem de una lista check <li class="task-list-item">…</li>, con una casilla <input type="checkbox" disabled> al principio (con checked si el elemento está marcado). Un elemento que solo envuelve una lista anidada sale como <li>…</li> sin casilla
link interno (/ruta, #ancla) <a href="…">…</a>
link https o http <a href="…" rel="noopener noreferrer">…</a>
link mailto o tel <a href="…">…</a>
link con una url que no cumple las reglas de validación Solo el texto, sin <a> y sin aviso
quote <blockquote>…</blockquote>
code <pre><code class="language-…">…</code></pre>; la clase solo si el lenguaje tiene letras, dígitos, +, # o -
horizontalrule <hr>
linebreak <br>
image (https) <img src="…" alt="…" loading="lazy" referrerpolicy="no-referrer">
upload <img src="…" alt="…" loading="lazy"> con la URL de resolveUpload
text El texto escapado, envuelto en <strong> (negrita), <em> (cursiva), <u> (subrayado), <s> (tachado) y <code> (código en línea), anidados así: la negrita por fuera y el código por dentro

Las casillas de una lista de tareas salen deshabilitadas: la página pública muestra el estado y no lo cambia. task-list-item y contains-task-list son las clases de GitHub, así que una hoja de estilos escrita para ellas sirve aquí.

Un image con src que no es https no produce nada: se descarta sin aviso. Las comillas, <, > y & del texto y de los atributos se escapan.

toPlainText(value: unknown): string

El texto del documento. Los bloques van separados por \n, y cada elemento de una lista va en su propia línea. Los image, upload y horizontalrule no aportan texto. Un valor que no es un árbol da ''.

toPlainText(valor) // → 'Primera línea\nSegunda, con negrita'
collectUploads(value: unknown): { relationTo: string; value: string }[]

Cada nodo upload del árbol, en orden de documento, sin repetir la pareja relationTo y value. Es lo que usa RichText para leer cada colección una sola vez. Un valor que no es un árbol da [].

{
name: 'content',
type: 'richText',
features: ['bold', 'italic', 'heading'],
uploadTo: 'ssd',
maxSize: 512 * 1024,
}
Opción Tipo Por defecto Qué hace
features RichTextFeature[] Todas menos upload e image Lo que puede escribir el editor, y lo que admite el servidor. Un array vacío solo admite párrafos y texto
uploadTo string 'ssd' Slug de la colección de la que salen las imágenes de la biblioteca. Si se indica, debe ser una colección que declare upload; si no, defineConfig falla con INVALID_UPLOAD_TARGET
maxSize number (bytes) 524288 (512 KB) Tamaño máximo del JSON: un entero entre 1 y 2 097 152, que es el límite de una fila de D1. Otro valor falla con INVALID_RICH_TEXT_MAX_SIZE. Un valor mayor que el máximo del campo se rechaza con 400; no se trunca

Además, aceptan las opciones comunes de todos los campos (name, label, required, admin, hooks…). La columna en D1 es text('name', { mode: 'json' }), igual que json, y el tipo en TypeScript es unknown.

RichTextFeature es la unión de estas trece cadenas. Un nombre que no esté aquí falla con INVALID_RICH_TEXT_FEATURE al resolver la configuración. Los dos tipos se importan desde la entrada del paquete, junto con RichTextField, que es el tipo del campo:

import type { RichTextField, RichTextFeature } from '@kevolution-co/cms'

En features se escriben las cadenas tal cual:

type RichTextFeature =
| 'bold' | 'italic' | 'strikethrough' | 'underline' | 'inlineCode'
| 'heading' | 'list' | 'link' | 'quote' | 'codeBlock' | 'hr'
| 'upload' | 'image'

RichTextField es la variante de Field con type: 'richText'.

Son los del formato de Lexical más dos nodos del paquete, upload e image. Todos llevan type y version numérica. Los que tienen hijos llevan children.

type Campos propios Feature que lo activa
root children, direction, format, indent Siempre. Solo puede ser la raíz del valor
paragraph children Siempre
text text, format (máscara de bits), mode, style, detail Siempre; cada bit de format exige su feature
linebreak — Siempre
heading tag (h1 a h6), children heading
list listType (bullet, number o check), tag (ul u ol), start, children list
listitem value, checked (solo en una lista check), children list. Admite texto, enlaces y bloques, menos upload, y un list anidado
link url, rel, target, title, children link. La url tiene que cumplir las reglas de abajo
quote children quote. Admite texto, enlaces y bloques, menos upload
code language (texto o null), children codeBlock. Hijos: text, linebreak y code-highlight
horizontalrule — hr
upload relationTo (slug de la colección, el de uploadTo), value (id del medio) upload
image src (https), alt (texto) image

code-highlight solo es válido dentro de un code, y se trata como texto.

Los bits de format de text:

Bit Marca Feature
1 Negrita bold
2 Cursiva italic
4 Tachado strikethrough
8 Subrayado underline
16 Código en línea inlineCode

Los bits 32 (subíndice) y 64 (superíndice) no se admiten en ningún campo.

El servidor aplica estas reglas en cada escritura, por la API local, la REST y el panel: las pone el propio tipo, así que ninguna ruta las salta. Un valor que incumple una sola regla se rechaza entero, con 400. Nada se corrige ni se trunca.

Cada tabla dice la regla, qué se rechaza y un fragmento del mensaje. El mensaje completo empieza por el campo y la ruta del nodo, como en Errores de validación.

Regla Qué se rechaza Mensaje incluye
root Un valor que no es un objeto, o cuyo root no es de tipo root con children de tipo lista debe tener "root" de tipo "root"
version Un nodo, la raíz incluida, sin version numérica no tiene "version" numérica
type Un nodo cuyo type no es una cadena o no está en la tabla de nodos, como table que no existe en el formato de nodos
feature Un nodo cuya feature no está activa en el campo: un upload sin upload, un heading sin heading y así con todos que requiere la feature "upload" y este campo no la tiene
root anidado Un nodo de tipo root que no es la raíz del valor solo puede ser la raíz del valor
profundidad Un nodo a más de 12 niveles de la raíz. La raíz es el nivel 0 y sus hijos el nivel 1 el máximo es 12
Regla Qué se rechaza Mensaje incluye
text Un nodo text sin text de cadena no tiene "text" de cadena
style Estilos en línea: un style distinto de vacío con estilos en línea
format Bits que no son 1, 2, 4, 8 ni 16 (subíndice y superíndice son 32 y 64), o un número que no es una máscara de 0 a 127 usa un formato no admitido
format con bit sin feature Negrita (1), cursiva (2), tachado (4), subrayado (8) o código en línea (16) sin la feature que les corresponde que requiere la feature "bold"
mode Un mode que no es normal, token ni segmented los válidos son normal, token y segmented
detail Un detail fuera de 0 a 15 debe ser un entero entre 0 y 15

Se comprueban en la raíz, en los bloques que tienen hijos (paragraph, heading, quote, list, listitem, code) y en link. Los nodos image, upload, horizontalrule y linebreak no se revisan en estas propiedades.

Regla Qué se rechaza Mensaje incluye
format del bloque Alineación: un format distinto de vacío la alineación no se admite
textStyle Estilos en línea: un textStyle distinto de vacío con estilos en línea
textFormat Un textFormat con bits distintos de 1, 2, 4, 8 y 16. No pide feature solo se admiten los bits 1, 2, 4, 8 y 16
indent Una sangría fuera de 0 a 12 entre 0 y 12
direction Una dirección distinta de ltr, rtl o null los válidos son ltr, rtl o null
Regla Qué se rechaza Mensaje incluye
tag de heading Un tag que no es h1, h2, h3, h4, h5 ni h6 los válidos son h1, h2, h3, h4, h5 y h6
listType Un listType distinto de bullet, number y check los válidos son bullet, number y check
tag de list Un tag que no es ul ni ol los válidos son ul y ol
listType con tag Un bullet o un check con ol, o un number con ul deben corresponder
start Un start que no es un entero mayor o igual que 0 debe ser un entero mayor o igual que 0
value de listitem Un value que no es un entero mayor o igual que 0 debe ser un entero mayor o igual que 0
checked fuera de una lista de tareas Un checked en un listitem cuya lista no es check que solo se admite en una lista de tareas
checked no booleano Un checked que no es true ni false debe ser true o false
listitem fuera de lista Un listitem cuyo padre no es un list usa "listitem" fuera de una lista
code-highlight Un code-highlight fuera de un bloque code fuera de un bloque de código
language Un language que no es cadena ni null que no es cadena ni null
Regla Qué se rechaza Mensaje incluye
url de link Cualquier dirección que no sea una ruta interna (/ruta o #ancla), mailto:, tel:, o http:// o https:// con host. Se rechazan //host, /\host, https:x.dev y javascript: tiene una url no permitida
url con espacios Un espacio en cualquier posición, también al principio o al final, y los caracteres de control: C0, DEL y U+0085 tiene una url no permitida
target Un target distinto de vacío o null solo se admite vacío o null
rel Valores que no son noopener, noreferrer o nofollow, separados por un único espacio solo se admiten noopener, noreferrer y nofollow
title Un title que no es cadena ni null que no es cadena ni null
src de image Una src que no es https:// con host que no es una URL https
alt de image Un alt que no es cadena no tiene "alt" de cadena
Regla Qué se rechaza Mensaje incluye
value de upload Un value que no es una cadena no vacía. El servidor no comprueba que el id exista no tiene "value" con el id del medio
relationTo Un relationTo distinto del destino del campo (uploadTo, ssd por defecto) solo admite medios de

Cada nodo solo admite los hijos de su fila. Un hijo que no está en la lista se rechaza con su ruta.

Nodo Hijos admitidos
root paragraph, heading, list, quote, code, horizontalrule, upload e image. Solo bloques
paragraph text, linebreak y link
heading text, linebreak y link
link text y linebreak
list listitem
listitem text, linebreak, link, paragraph, heading, list, quote, code, horizontalrule e image. No upload
quote text, linebreak, link, paragraph, heading, list, quote, code, horizontalrule e image. No upload
code text, code-highlight y linebreak. code-highlight solo es válido aquí

upload solo es válido como hijo de la raíz: listitem y quote admiten bloques, pero no upload.

Regla Qué se rechaza Mensaje incluye
maxSize El JSON serializado ocupa más de maxSize bytes en UTF-8. El mensaje dice el tamaño recibido y el límite el contenido no se trunca
required Con required: true, un árbol sin contenido. Cuentan el texto que no sea solo espacios ni caracteres de ancho cero (U+200B, U+200C, U+200D, U+2060, U+FEFF), y los nodos upload, image y horizontalrule. Un bloque de código cuenta si tiene texto. Un párrafo vacío no cuenta es obligatorio y no tiene contenido

El servidor no mira si el id de un upload existe en la biblioteca, porque la validación es síncrona y no consulta la base, ni si una image carga.

Estas comprobaciones se hacen al resolver la configuración (defineConfig). Un valor incorrecto falla con el código de la tabla, y el mensaje nombra la colección y el campo.

Código Cuándo falla Mensaje incluye
INVALID_RICH_TEXT_FEATURES features no es un array. Un array vacío sí vale: el campo solo admite párrafos y texto tiene que ser un array de features
INVALID_RICH_TEXT_FEATURE Una feature que no está en RichTextFeature. Si se parece a una real, el mensaje la sugiere pide la feature
INVALID_RICH_TEXT_MAX_SIZE maxSize que no es un entero de bytes entre 1 y 2 097 152 entre 1 y 2 097 152
INVALID_UPLOAD_TARGET uploadTo que no es una colección que declara upload: no existe, es un global o no tiene upload apunta a la colección

Un error de richText sale como cualquier otro error de validación, con status 400 y issues de la forma { path, code, message } de la API local:

{
"issues": [
{
"path": "content",
"code": "CUSTOM",
"message": "content: root.children[1] tiene tag \"h7\"; los válidos son h1, h2, h3, h4, h5 y h6"
}
]
}
  • path es el nombre del campo.
  • code es CUSTOM. Es el código genérico de Zod para una regla propia del campo, y richText no tiene uno propio.
  • message empieza por el campo y después la ruta del nodo que falla, como root.children[3].children[0], seguida de lo que está mal.

Otros mensajes del mismo tipo: content es obligatorio y no tiene contenido para required, y content: root ocupa 524289 bytes y el límite es 524288 bytes; el contenido no se trunca para maxSize.

Los dos convertidores viven en @kevolution-co/cms/rich-text/convert. Se usan en scripts, no desde la página pública. La guía tiene el ejemplo completo de migración desde markdown.

import { lexicalToMarkdown, markdownToLexical } from '@kevolution-co/cms/rich-text/convert'
markdownToLexical(markdown: string, options?: RichTextConvertOptions): RichTextValue

Convierte markdown en el árbol del campo, que pasa las reglas de validación para las features indicadas. Por defecto usa las features de contenido: todas menos upload e image. Un markdown vacío da un árbol vacío. No lanza nunca: si Lexical rechaza el texto, cada línea no vacía pasa a un párrafo.

Lo que no tiene equivalente se degrada a texto, incluidas las tablas y el HTML en línea. Los títulos conservan su nivel, de 1 a 6, y las listas de tareas (- [ ] y - [x]) pasan a listas check. Las listas se quedan en cinco niveles: una lista del sexto nivel o más se convierte en texto, una línea por elemento.

lexicalToMarkdown(value: unknown, options?: RichTextConvertOptions): string

Convierte el árbol en markdown, con los bloques separados por líneas en blanco. Por defecto usa las trece features, de modo que una imagen por URL sale como ![alt](src); sin la feature image, sale solo su texto alternativo. Una lista check sale como - [ ] y - [x] . El subrayado no tiene sintaxis en markdown, así que sale solo el texto. Un nodo upload no sale: el módulo no conoce la URL del medio. No lanza nunca; un valor que no es un árbol da ''.

Esta función no usa Lexical, así que funciona con nodos que Lexical no tiene registrados.

interface RichTextConvertOptions {
features?: RichTextFeature[]
}
type RichTextValue = { root: Record<string, unknown> }

RichTextValue es el valor que guarda un campo richText. El tipo no tiene más campos que root.