Texto enriquecido
Esta página es la referencia. Para declarar el campo, renderizarlo o migrar markdown, empieza por la guía del texto enriquecido.
Exportaciones
Sección titulada «Exportaciones»| 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/* |
RichText
Sección titulada «RichText»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
Sección titulada «renderToHtml»renderToHtml(value: unknown, options?: RenderOptions): stringDevuelve 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>'RenderOptions
Sección titulada «RenderOptions»| 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
Sección titulada «toPlainText»toPlainText(value: unknown): stringEl 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
Sección titulada «collectUploads»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 [].
El campo richText
Sección titulada «El campo richText»{ 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.
Validación
Sección titulada «Validación»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.
Forma del árbol
Sección titulada «Forma del árbol»| 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 |
Propiedades de bloque
Sección titulada «Propiedades de bloque»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 |
Encabezados, listas y código
Sección titulada «Encabezados, listas y código»| 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 |
Enlaces e imágenes
Sección titulada «Enlaces e imágenes»| 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 |
Contenedores
Sección titulada «Contenedores»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.
Tamaño y obligatorio
Sección titulada «Tamaño y obligatorio»| 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.
Errores de configuración
Sección titulada «Errores de configuración»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 |
Errores de validación
Sección titulada «Errores de validació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" } ]}pathes el nombre del campo.codeesCUSTOM. Es el código genérico de Zod para una regla propia del campo, yrichTextno tiene uno propio.messageempieza por el campo y después la ruta del nodo que falla, comoroot.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.
Markdown y el árbol
Sección titulada «Markdown y el árbol»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
Sección titulada «markdownToLexical»markdownToLexical(markdown: string, options?: RichTextConvertOptions): RichTextValueConvierte 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
Sección titulada «lexicalToMarkdown»lexicalToMarkdown(value: unknown, options?: RichTextConvertOptions): stringConvierte 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 ; 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.
Opciones y tipos
Sección titulada «Opciones y tipos»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.