RichTextEditor
Descrição do produto
Cafeteira italiana, 6 xícaras
Corpo em alumínio fundido e alça que não esquenta no fogão.
Rende 300 ml por preparo
Manual de uso em rivocode.com.br
Aparece na página do produto, abaixo das fotos.
Cafeteira italiana, 6 xícaras
Corpo em alumínio fundido e alça que não esquenta no fogão.
Rende 300 ml por preparo
Manual de uso em rivocode.com.br
No formulário, com erro
Só leitura e desabilitado
Cafeteira italiana, 6 xícaras
Corpo em alumínio fundido e alça que não esquenta no fogão.
Rende 300 ml por preparo
Manual de uso em rivocode.com.br
O produto está em revisão, e a descrição não muda até a aprovação.
import { RichTextEditor } from '@rivocode/ui/editor'Quando usar
O campo de texto com formatação: negrito, itálico, sublinhado, tachado,
código, dois níveis de título, listas, citação, bloco de código e link, com
desfazer, refazer e limpar formatação. Entrega o documento em HTML, e o
RichTextView exibe o que ele salvou com a mesma tipografia. Vive em
@rivocode/ui/editor, sobre o Tiptap 3.
npm install @tiptap/react @tiptap/pm @tiptap/core @tiptap/starter-kit @tiptap/extensions
Os cinco são peers opcionais: quem não importa @rivocode/ui/editor não
instala nenhum, e o resto da biblioteca não os alcança (check:chart guarda a
fronteira, como faz com a Recharts).
import { Field, FieldLabel, FieldDescription } from '@rivocode/ui'
import { RichTextEditor } from '@rivocode/ui/editor'
const [descricao, setDescricao] = useState('')
<Field>
<FieldLabel>Descrição do produto</FieldLabel>
<RichTextEditor
value={descricao}
onValueChange={setDescricao}
placeholder="O que é, e para quem serve"
maxLength={2000}
/>
<FieldDescription>Aparece na página do produto, abaixo das fotos.</FieldDescription>
</Field>
O valor
value e defaultValue são HTML, e onValueChange devolve o documento
inteiro em HTML a cada mudança. O editor em branco entrega string vazia, e
não <p></p>: é o que deixa z.string().min(1) recusar o campo vazio sem
regra especial.
Trocar o value por fora substitui o documento sem disparar
onValueChange, então o campo controlado não entra em laço.
onJsonChange entrega o mesmo documento no formato JSON do Tiptap. Guarde o
JSON quando o texto for exibido no celular ou precisar ser lido por máquina; o
RichTextView lê os dois formatos.
Com name, o HTML viaja num input escondido, e o campo entra no envio de um
<form> comum.
Escrever no cursor por fora
editorRef recebe um RichTextEditorHandle, para o botão "inserir variável",
a resposta pronta ou o texto que o assistente sugeriu:
const editor = useRef<RichTextEditorHandle>(null)
<RichTextEditor editorRef={editor} value={html} onValueChange={setHtml} />
<Button variant="secondary" onClick={() => editor.current?.insertText('{nome do cliente}')}>
Inserir nome do cliente
</Button>
insertText(texto)põe texto puro no cursor:<b>entra como os caracteres<b>, e cada quebra de linha vira quebra dentro do parágrafo.insertContent(conteúdo)aceita HTML ou o JSON doonJsonChange, e o que o editor não conhece cai fora, como na colagem.focus()devolve o foco ao texto.
Os dois de inserir trocam a seleção, se houver, devolvem o foco ao texto,
passam pelo maxLength e respondem false quando nada entrou: antes de o
editor montar, com readOnly ou disabled, ou barrado pelo teto. A mudança
chega pelo onValueChange, como a digitação.
O ref continua sendo o da moldura, um div: o handle mora numa prop própria
para não trocar o tipo de quem já passava ref.
Barra de ferramentas e atalhos
A barra é uma Toolbar: uma parada de Tab só, e as setas andam entre os
botões. Cada botão de estado é um Toggle com aria-pressed, agrupado num
ToggleGroup com nome ("Estilo do texto", "Títulos", "Listas", "Blocos"), e
cada um diz o próprio atalho em aria-keyshortcuts e na dica que abre ao
pousar ou focar.
Em tela estreita a barra quebra por grupo, e nunca no meio de um: desfazer, refazer e limpar formatação descem juntos, e o separador entre grupos some quando o grupo seguinte abre a linha.
| Ação | Atalho |
|---|---|
| Negrito, itálico, sublinhado | Ctrl+B, Ctrl+I, Ctrl+U |
| Tachado, código | Ctrl+Shift+S, Ctrl+E |
| Título, subtítulo | Ctrl+Alt+2, Ctrl+Alt+3 |
| Lista com marcadores, numerada | Ctrl+Shift+8, Ctrl+Shift+7 |
| Citação, bloco de código | Ctrl+Shift+B, Ctrl+Alt+C |
| Link | Ctrl+K |
| Desfazer, refazer | Ctrl+Z, Ctrl+Shift+Z |
| Limpar formatação | Ctrl+\ |
No Mac, Ctrl é ⌘. Título e subtítulo saem como h2 e h3: o h1 é da
página em volta, e um campo de formulário não disputa o esboço dela. HTML
colado com h1 ou h4 vira parágrafo.
Link
Ctrl+K ou o botão abre um painel com o endereço. O que se digita sem
protocolo ganha o que falta: rivocode.com.br vira https://rivocode.com.br,
e nf@rivocode.com.br vira mailto:. Só passam http, https, mailto,
tel e endereço relativo; javascript: é recusado com a explicação no
próprio campo. Com o cursor dentro de um link, o botão fica pressionado, com
aria-pressed="true", e o painel traz "Remover link".
O painel é um formulário próprio, e o envio dele não envia o formulário em volta do editor.
Colar
Colar do Word, do Google Docs ou de uma página não traz cor, fonte, tamanho, classe nem imagem: o documento só aceita o que a barra sabe fazer, e o resto cai no caminho. O negrito de verdade fica; o negrito falso que o Google Docs põe em volta de tudo, não.
Limite
maxLength conta caracteres de texto, e não o HTML: <strong>Frete</strong>
conta 5. O contador aparece no rodapé, é lido pelo leitor de tela como "120 de
2000 caracteres" ao entrar no campo, e passa ao tom de perigo no teto, com o
aviso "Limite de 2000 caracteres atingido." numa região educada. A digitação e
a colagem que passariam do teto são recusadas.
Conteúdo salvo maior que o teto abre inteiro, e só aceita apagar: cortar o texto de alguém ao abrir é perda de dado silenciosa.
No formulário
Dentro de Field, o FieldLabel nomeia o texto, o FieldDescription e o
FieldError o descrevem, e o invalid do Field pinta a moldura e anuncia
aria-invalid. Com o @rivocode/ui/form, o adaptador é o forValue, que já
leva o onBlur para o campo contar como tocado:
import { Form, FormField, forValue, useZodForm } from '@rivocode/ui/form'
import { RichTextEditor } from '@rivocode/ui/editor'
import { z } from 'zod'
const schema = z.object({
descricao: z.string().min(1, 'Descreva o produto.'),
})
function ServiceForm() {
const form = useZodForm(schema, { defaultValues: { descricao: '' } })
return (
<Form form={form} onSubmit={salvar}>
<FormField name="descricao" label="Descrição do produto">
{(field) => <RichTextEditor {...forValue(field)} maxLength={2000} />}
</FormField>
<Button type="submit">Salvar</Button>
</Form>
)
}
O defaultValues com string vazia não é detalhe: sem ele o value chega
undefined no primeiro desenho, e o editor começa não controlado.
Fora de Field, dê o nome com aria-label e pinte o erro com invalid.
Estados
readOnly: a barra some, o texto continua selecionável e copiável, e o campo anunciaaria-readonly.disabled: barra e texto travados, no tom apagado, comaria-disabled. Dentro de umFielddesabilitado, trava sozinho.invalid: moldura de perigo earia-invalid.- Carregando no servidor: o editor não monta no servidor
(
immediatelyRender: false), e no lugar dele sai o conteúdo já formatado, peloRichTextView. A página renderizada no servidor mostra o texto no primeiro desenho, e ele vira editável quando o JavaScript chega.
O que chega ao servidor
O HTML sai de um editor que só escreve o que a barra sabe fazer, e o
RichTextView só exibe isso. Mas o servidor recebe o que o navegador mandar,
e quem chama a sua API não é obrigado a usar o editor. Se o HTML salvo for
exibido por outro caminho (e-mail, PDF, dangerouslySetInnerHTML), passe-o
por um sanitizador no servidor, como o sanitize-html ou o DOMPurify, com a
mesma lista de tags. O RichTextView não precisa disso: ele não usa
innerHTML.
Nomes
Os nomes da barra, do painel e do contador saem em português, e labels troca
os que vierem, um por um:
<RichTextEditor
aria-label="Description"
labels={{
toolbar: 'Formatting',
bold: 'Bold',
count: (count, max) => `${count} of ${max} characters`,
}}
/>
Partes
classNames alcança toolbar, content (a área editável), footer e count.
A altura mínima é de três controles; para rolar por dentro, dê o teto pela
parte: classNames={{ content: 'max-h-96 overflow-y-auto' }}.
Quando não usar
- Observação, motivo, comentário curto é
Textarea. Texto sem negrito nem lista não precisa de barra de ferramentas, e oTextareaguarda texto puro, que qualquer sistema lê. ORichTextEditorguarda HTML. - Mensagem para um assistente é
PromptInput: Enter envia. NoRichTextEditor, Enter abre parágrafo novo. - Mostrar o que foi salvo é
RichTextView. UmRichTextEditorcomreadOnlycarrega o Tiptap inteiro para exibir texto parado.
No React Native
Não porta, por decisão, e não é fila: a pergunta que faltaria decidir não é de gesto, é de motor.
O editor do web não atravessa. Ele é o Tiptap sobre o ProseMirror, que vive do contenteditable do navegador, e o React Native não tem contenteditable. As duas saídas são outro produto: um WebView com o mesmo editor dentro, que traz o react-native-webview como peer de módulo nativo, teclado e seleção que não são os do sistema, e texto que o leitor de tela lê pelo caminho da página e não pelo do app; ou uma biblioteca de texto rico nativa, que não lê nem escreve o mesmo documento. Nenhuma das duas é a mesma peça com outra API.
E a barra é superfície de mesa. Ela é uma Toolbar, que também não porta: uma parada de tabulação com seta entre os botões, sobre uma seleção feita com o ponteiro. No toque, formatar um trecho é selecionar com o dedo que cobre o trecho, e quinze botões não cabem acima do teclado.
No celular, a resposta é dividir o trabalho. O que se escreve no telefone é texto curto, e o campo é o Textarea. O que foi escrito formatado no web se lê com o RichTextView, que porta sem peer e lê o mesmo HTML e o mesmo JSON.
API
| Prop | Tipo | Padrão |
|---|---|---|
classNamesClasse por parte: `toolbar`, `content`, `footer`, `count`. | Partial<Record<"content" | "count" | "footer" | "toolbar", string>> | sem padrão |
defaultValueO HTML do primeiro desenho, quando a peca guarda o proprio texto. | string | sem padrão |
disabledTrava o texto e a barra. | boolean | false |
editorRefRecebe um `RichTextEditorHandle`, para escrever no editor por fora: o botao "inserir variavel", a resposta pronta, o texto que o assistente sugeriu. | Ref<RichTextEditorHandle> | sem padrão |
invalidPinta a moldura de perigo e anuncia `aria-invalid`. | boolean | false |
labelsOs textos da barra, do painel de link e do contador, em portugues por padrao. | Partial<RichTextEditorLabels> | sem padrão |
maxLengthO teto de caracteres de texto, sem contar as marcas do HTML. | number | sem padrão |
nameO nome do campo no envio do formulario: o HTML sai num `input` escondido. | string | sem padrão |
onBlurChamado quando o texto perde foco; e o que marca o campo como tocado no formulario. | (() => void) | sem padrão |
onFocusChamado quando o texto ganha foco. | (() => void) | sem padrão |
onJsonChangeAvisado a cada mudanca com o documento em JSON, o formato do Tiptap. | ((value: RichTextJson) => void) | sem padrão |
onValueChangeAvisado a cada mudanca, com o documento inteiro em HTML. | ((value: string) => void) | sem padrão |
placeholderO texto que aparece no editor vazio. | string | sem padrão |
readOnlySo leitura: o texto pode ser selecionado e copiado, e a barra de ferramentas some. | boolean | false |
ref | Ref<HTMLDivElement> | sem padrão |
valueO conteudo, em HTML, quando quem usa guarda o texto. | string | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.