SignaturePad
Assinar o aceite
Desenhe a assinatura com o dedo, a caneta ou o mouse. Se preferir, use Digitar assinatura e escreva o nome.
Vale como aceite do contrato de locação.
Exportar SVG e PNG
Desenhe a assinatura com o dedo, a caneta ou o mouse. Se preferir, use Digitar assinatura e escreva o nome.
Digitar em vez de desenhar
Desenhe a assinatura com o dedo, a caneta ou o mouse. Se preferir, use Digitar assinatura e escreva o nome.
Estados
Desenhe a assinatura com o dedo, a caneta ou o mouse. Se preferir, use Digitar assinatura e escreva o nome.
Assine para continuar.
Desenhe a assinatura com o dedo, a caneta ou o mouse. Se preferir, use Digitar assinatura e escreva o nome.
Desenhe a assinatura com o dedo, a caneta ou o mouse. Se preferir, use Digitar assinatura e escreva o nome.
Desenhe a assinatura com o dedo, a caneta ou o mouse. Se preferir, use Digitar assinatura e escreva o nome.
import { SignaturePad } from '@rivocode/ui'Quando usar
A área de assinatura na tela: o aceite de um contrato de locação, o recebimento de uma entrega, o "de acordo" num laudo de vistoria. A pessoa assina com o dedo, com a caneta ou com o mouse, e quem não consegue desenhar digita o nome, que sai em letra cursiva.
const [assinatura, setAssinatura] = useState<SignatureValue | null>(null)
<Field>
<FieldLabel>Assinatura do locatário</FieldLabel>
<SignaturePad value={assinatura} onValueChange={setAssinatura} />
</Field>
O desenho sai por Pointer Events, então o mesmo código atende dedo, caneta e mouse. O traço é suave: os pontos são ligados por curvas, e a espessura varia com a velocidade, fina quando a mão corre e cheia quando ela desacelera, como tinta de verdade. Com caneta que mede pressão, a pressão entra na conta. O botão direito do mouse não desenha, e um segundo dedo que encosta no meio do traço (a palma da mão, quase sempre) é ignorado.
O valor
value é null sem assinatura, ou um de dois formatos:
{ kind: 'drawn', strokes, width, height }: os traços, cada um uma lista de pontos{ x, y, time, pressure? }em unidades de desenho. A área tem 600 unidades de largura em qualquer tamanho de tela, então a assinatura feita no celular sai igual no monitor.{ kind: 'typed', text, font, width, height }: o nome digitado e a família da letra.
onValueChange é chamado ao fim de cada traço, e não a cada ponto, a cada
letra digitada, ao desfazer e ao limpar. Quando a área esvazia, chega null,
que é o que o schema do formulário lê como "sem assinatura". Sem value, a
peça guarda a assinatura sozinha a partir de defaultValue.
ratio é a largura sobre a altura da área, com padrão 3. A altura sai daí, e
não de um número cravado: a área encolhe junto com a coluna.
Desfazer, limpar, e o que o leitor de tela ouve
Embaixo do papel ficam Desfazer o último traço e Limpar assinatura, os
dois IconButton com a dica ao pousar, e o botão que troca de modo. Vazia, a
área mostra a linha de base e o "Assine aqui", e os dois botões ficam inativos.
A peça é um group com o nome do rótulo do Field (ou aria-label, ou
"Assinatura" sem nenhum dos dois), descrito pela instrução de como assinar. O
papel é uma imagem cujo nome diz o estado: "Nenhuma assinatura", "Assinatura
desenhada, 3 traços" ou "Assinatura digitada: Maria Souza". Desfazer e limpar
se anunciam num status, e limpar pelo teclado leva o foco para o botão de
modo, que continua vivo, em vez de largar o foco no corpo da página.
Digitar em vez de desenhar
Desenhar pede mão firme e ponteiro fino, e muita gente não tem os dois: quem
usa só teclado, leitor de tela, acionador, ou tem tremor. Digitar assinatura
troca o papel pelo campo "Nome para a assinatura", e o nome aparece no papel em
letra cursiva. O valor vira kind: 'typed', e sai exportado do mesmo jeito que
o desenho. Não há prop que desligue esse modo: a alternativa é a peça.
<SignaturePad
value={assinatura}
onValueChange={setAssinatura}
font='"Great Vibes", cursive'
/>
font é a família cursiva, em CSS. Carregue a fonte na página: sem ela, o
navegador cai na cursiva do sistema, e o PNG também. Trocar de modo guarda o
rascunho do outro: quem desenhou, foi digitar e voltou, encontra os traços.
Quando o pai zera o value por fora (um reset do formulário), os dois
rascunhos vão junto: o campo do nome esvazia e voltar a desenhar não traz traço
antigo. Um caso escapa: se o valor já era null quando o pai zera, o React não
avisa a peça, e o rascunho do outro modo continua guardado. Isso acontece quando
a pessoa desenhou, trocou para "Digitar" sem escrever nada e o formulário foi
zerado. Para um reset que apaga tudo sem exceção, remonte a peça com key:
<SignaturePad key={tentativa} … />, trocando tentativa no reset.
Limpar não troca de modo: quem limpou o nome continua no campo do nome.
defaultMode="type" abre no nome digitado, para a tela em que a maioria assina
pelo teclado.
No formulário
Dentro de Field, o grupo pega o rótulo, a descrição e o erro; disabled e
invalid do Field chegam sozinhos. No React Hook Form, o forValue liga a
peça ao schema, e vazio é null:
const schema = z.object({
assinatura: z.custom<SignatureValue | null>().refine((valor) => valor !== null, {
message: 'Assine para continuar',
}),
})
<FormField name="assinatura" label="Assinatura do locatário">
{(field) => <SignaturePad {...forValue(field)} />}
</FormField>
No formulário do HTML, name põe o SVG da assinatura num campo escondido,
vazio quando não há assinatura.
Exportar
signatureToSvg(valor) devolve o SVG em texto, e signatureToPng(valor) a
imagem em data:image/png, desenhada num canvas com o dobro da resolução
(scale). Os dois devolvem '' sem assinatura.
const svg = signatureToSvg(assinatura)
const png = await signatureToPng(assinatura, { paper: true })
A tinta é escura nos dois temas. A assinatura feita no tema escuro não sai
clara no documento: a tinta, o papel e a guia são os --rc-signature-*, fixos
em scales.css como o par do código lido por máquina, e não papel de tema. O
check:contrast mede a tinta e o "Assine aqui" a 4,5:1 sobre o papel, a linha
de base a 3:1, e reprova a tinta mais clara que o papel. Sem paper, o fundo
sai transparente, para assentar sobre o documento; paper: true pinta o papel
branco, e ink troca a tinta de uma exportação só.
O nome digitado sai no SVG como texto com a font-family: quem abrir o arquivo
sem a fonte vê a cursiva do sistema. Para arquivo que precisa sair igual em
qualquer lugar, exporte o PNG.
Estados
- Desabilitada: nem desenho nem botões, a borda vira
border-disablede a guiasignature-disabled. A assinatura que já estava continua visível. - Só leitura (
readOnly): mostra a assinatura sem botões, sem desenho e sem o modo de digitar. É a forma de exibir a assinatura já colhida. - Inválida (
invalid, ou oFieldinválido): bordadangerearia-invalid. A mensagem é do formulário.
Partes
classNames alcança cada nó pelo nome: pad (o papel), placeholder (o
"Assine aqui"), baseline (a linha), actions (a fileira de botões) e input
(o campo do nome digitado). className veste a raiz.
Textos
labels troca cada texto: group, placeholder, instruction, undo,
clear, typeMode, drawMode, typedName, empty, undone, cleared, e
as funções drawn(traços) e typed(nome), que dizem o estado do papel ao
leitor de tela.
Quando não usar
- Aceite que não precisa de rubrica, como "li e concordo com os termos", é
Checkbox. A assinatura desenhada pesa mais na tela e na mão; peça só quando o documento pede o traço. - Assinatura que já existe em papel, digitalizada, é
FileUpload: a pessoa anexa a imagem, e não redesenha. - Só o nome, sem valor de assinatura, como "quem recebeu", é
Input. - Assinatura digital com validade jurídica, com certificado ICP-Brasil, não é esta peça: o traço na tela é evidência de aceite, e não assinatura qualificada. O certificado é do serviço que assina o documento.
No React Native
Traduz, no caminho @rivocode/ui-native/chart: o papel é desenhado com o react-native-svg, peer da raiz desde a 6.0, e mora com o gráfico pelo peso: quem só usa um Button não carrega o papel e o traço da assinatura.
O traço é o mesmo dos dois lados, linha por linha. A suavização por curvas, a espessura que varia com a velocidade e com a pressão, o nome digitado em cursiva e o SVG exportado moram em src/shared/ e atravessam por espelho: a assinatura feita no celular abre igual no web, com o mesmo value. O gesto é o PanResponder do core, que não cede o toque para a rolagem no meio do traço; onDrawingChange avisa quando o dedo começa e termina, para a ScrollView em volta desligar o scrollEnabled. A força do toque, quando o aparelho a mede, entra como pressão.
Exporta só o SVG. signatureToSvg sai daqui com a tinta do token, escura nos dois temas; o PNG não porta, porque o React Native não tem canvas. Quem precisa de imagem rasteriza o SVG no servidor, ou captura a área com uma biblioteca de captura de tela. O value é controlado, não há name (formulário escondido não existe no celular), e o modo de digitar o nome continua lá, na cursiva que o app declarar em fonts.script do RivoProvider (ou na prop font). Sem ela, o nome sai na cursiva de cada sistema (Snell Roundhand no iOS, cursive no Android), que é outra letra, com outra largura: declare a fonts.script para os dois saírem iguais.
import { SignaturePad } from '@rivocode/ui-native/chart'
<SignaturePad
value={assinatura}
onValueChange={setAssinatura}
onDrawingChange={(desenhando) => setRolagem(!desenhando)}
/>
O nome do grupo é label, no lugar do aria-label do web, e sem ele vale o labels.group. Dentro do FormField, o forValue já entrega o label.
As partes vestem pelo mesmo classNames do web: pad, placeholder, actions e input. baseline não porta como parte: a linha de base é um traço dentro do Svg, e o react-native-svg não recebe classe.
API
| Prop | Tipo | Padrão |
|---|---|---|
classNamesClasse por parte: `pad` (o papel), `placeholder`, `baseline`, `actions` e `input` (o campo do nome). | Partial<Record<"actions" | "baseline" | "input" | "pad" | "placeholder", string>> | sem padrão |
defaultModeEm que modo a area abre quando esta vazia. | "draw" | "type" | sem padrão |
defaultValueA assinatura ao montar, quando ninguem controla. | SignatureValue | null | null |
disabledTrava o desenho, a digitacao e os botoes. | boolean | false |
fontA familia cursiva do modo de digitar, em CSS (`'"Great Vibes", cursive'`). | string | sem padrão |
invalidPinta a moldura de perigo e anuncia `aria-invalid`. | boolean | false |
labelsOs textos da peca: rotulos dos botoes, instrucao, "Assine aqui" e o que o leitor de tela ouve. | Partial<SignaturePadLabels> | sem padrão |
nameNome do campo num `<form>`: vai num `input` escondido com o SVG da assinatura, e vazio quando nao ha assinatura. | string | sem padrão |
onValueChangeChamado ao fim de cada traco, a cada letra digitada, ao desfazer e ao limpar. | ((value: SignatureValue | null) => void) | sem padrão |
ratioLargura sobre altura da area. | number | sem padrão |
readOnlySo exibe a assinatura: sem desenho, sem botoes e sem o modo de digitar. | boolean | false |
ref | Ref<HTMLDivElement> | sem padrão |
valueA assinatura, controlada: os tracos desenhados (`kind: "drawn"`) ou o nome digitado (`kind: "typed"`). | SignatureValue | null | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.