Docs›Componentes (Admin)›mad-signature-field
Componentes (Admin)

mad-signature-field

Assinatura draw/type/upload.

Campo de captura de assinatura com 3 modos: desenho, digitacao em fonte cursiva e upload de imagem. Fullscreen automatico em mobile. Usa SignaturePad.js.

Props

Prop Tipo Default Descricao
name string '' Nome do campo (obrigatorio)
label string '' Label do campo
value string '' Assinatura atual (URL path ou base64)
modes string 'draw,type,upload' Modos habilitados (qualquer combinacao)
pen-color string '#000000' Cor padrao da caneta
pen-colors array ['#000000','#1e40af','#dc2626'] Paleta de cores
pen-width number 2 Espessura padrao
pen-widths array [1, 2, 4] Opcoes de espessura
fonts array ['Dancing Script','Great Vibes','Courier Prime'] Fontes do modo type
width string '100%' Largura do componente
max-width string '' max-width CSS do wrapper
height string '200px' Altura do canvas
storage string '' disk (filesystem) ou db (BLOB base64 no banco)
folder string 'uploads' Diretorio destino (somente com storage="disk")
name-column string '' Coluna para nome original do arquivo
file-name string 'prefix' Modo do nome: prefix, unique, original, record
max_size string '5MB' Tamanho maximo (modo upload) — atencao ao underscore, ver nota abaixo
accept string 'image/png,image/jpeg' MIME types (modo upload)
camera bool false Habilita captura via camera no modo upload
hint string '' Texto de ajuda
error string '' Mensagem de erro
required bool false Campo obrigatorio
disabled bool false Campo desabilitado
attrs string '' Atributos HTML extras (aplicados no input hidden que carrega o valor)

Gotcha real — max_size e underscore, nao kebab. O MadBlade::parseParams() converte todo atributo kebab-case para camelCase (pen-color → $penColor, name-column → $nameColumn, file-name → $fileName). O blade do signature-field le a variavel $max_size (com underscore), entao max-size="10MB" viraria $maxSize e seria silenciosamente ignorado — o limite continuaria em 5MB. Escreva max_size="10MB":

{{-- ERRADO: nunca chega no componente --}}
<mad-signature-field name="assinatura" max-size="10MB" />

{{-- CERTO --}}
<mad-signature-field name="assinatura" max_size="10MB" />

Uso basico

<mad-signature-field name="assinatura" label="Assinatura" />

So desenho, com storage em disco

<mad-signature-field name="assinatura" label="Assine aqui"
    modes="draw" storage="disk" folder="uploads/assinaturas"
    name-column="assinatura_nome" />

Desenho + digitacao, BLOB no banco

<mad-signature-field name="assinatura" label="Assinatura do cliente"
    modes="draw,type" pen-color="#1e40af" storage="db" />

Com callback PHP

<mad-signature-field name="assinatura" label="Assinatura"
    mad:change="onAssinaturaChange" required />

public function onAssinaturaChange(string $tempPath): void
{
    $size = getimagesize($tempPath);
    $this->form->set('dimensoes', $size[0] . 'x' . $size[1]);
}

Dentro de formulario

<mad-form submit="onSave">
    <mad-signature-field name="assinatura" label="Assinatura do contrato"
        storage="disk" folder="uploads/contratos" required />
    <mad-btn type="submit" variant="primary" icon="save">Salvar</mad-btn>
</mad-form>

public function onSave(): MadResponse
{
    $data = $this->form->getData();
    $this->form->validate(Contrato::rules($this->registroId));

    $contrato = Contrato::findOrNew($this->registroId);
    $this->form->save($contrato); // salva assinatura automaticamente

    return (new MadResponse())
        ->toast('Contrato salvo!', 'success')
        ->closeDrawer();
}

Modos disponiveis

Modo Descricao
draw Desenho com dedo/mouse via SignaturePad.js
type Texto digitado em fonte cursiva (3 fontes)
upload Upload de imagem (drag-and-drop)

Fullscreen

  • Mobile (<768px): automatico ao entrar no modo draw
  • Desktop: botao expandir no canto do canvas
  • Fullscreen: overlay com canvas grande + toolbar flutuante

Storage automatico (disco)

<mad-signature-field name="assinatura" label="Assinatura"
    storage="disk" folder="uploads/assinaturas" name-column="assinatura_nome" />

// Controller — zero codigo de arquivo:
$this->form->save($record);
// 1. Salva em uploads/assinaturas/uniqid_assinatura.png
// 2. $record->assinatura = 'uploads/assinaturas/xxx.png'
// 3. $record->assinatura_nome = 'assinatura.png'

Storage automatico (BLOB no banco)

<mad-signature-field name="assinatura_blob" label="Assinatura"
    storage="db" name-column="assinatura_nome" />

// No onEdit, carregar o BLOB:
$this->form->loadBlob($record, 'assinatura_blob', 'assinatura_nome');
$this->form->fill($record);

// No onSave:
$this->form->save($record);  // BLOB salvo via prepared statement

NUNCA fazer

{{-- ERRADO: salvar o arquivo manualmente no controller --}}
$path = $request->file('assinatura')->store('uploads/assinaturas');
$contrato->assinatura = $path;
$contrato->save();

{{-- CERTO: storage="disk" + form->save() cuidam disso --}}
<mad-signature-field name="assinatura" label="Assinatura" storage="disk" />

{{-- ERRADO: montar canvas de assinatura manualmente --}}
<canvas id="sig-canvas"></canvas>
<script>var pad = new SignaturePad(document.getElementById('sig-canvas'));</script>

{{-- CERTO --}}
<mad-signature-field name="assinatura" label="Assinatura" />

{{-- ERRADO: upload de assinatura via input file nativo --}}
<input type="file" name="assinatura" accept="image/*">

{{-- CERTO --}}
<mad-signature-field name="assinatura" label="Assinatura" modes="upload" />