BaseSwitch

Liga ou desliga uma opção com efeito imediato, como um aviso ou um modo de trabalho. Para escolher algo que só vale ao salvar o formulário, use uma caixa de seleção.

Avisar vencimento da garantia

Mostrar só obras atrasadas

A lista esconde as obras dentro do prazo enquanto estiver ligado.

Resumo semanal por e-mailDesligado

Uso

• O rótulo diz o que fica ligado: "Avisar vencimento da garantia", não "Avisos: sim/não". Ele não muda com o estado.
• A mudança vale na hora. Se a opção só tem efeito ao salvar, ou se o usuário precisa confirmar, use caixa de seleção.
• Use on-text e off-text quando o estado precisa ficar escrito na tela, por exemplo em configurações revisadas por outra pessoa. Passe os dois juntos: com só um, nenhum texto aparece.
• Use helper-text para explicar o que muda quando está ligado.
• O BaseSwitch já traz rótulo e ajuda. Não coloque dentro de um BaseField.
• Um interruptor desabilitado não recebe foco, então quem navega por teclado ou leitor de tela não ouve a ajuda dele. Quando o motivo do bloqueio importa ("Só o fiscal do contrato pode mudar"), escreva esse motivo em texto visível fora do controle.
• Em tabela, use hide-label para esconder o rótulo da tela sem tirá-lo do leitor de tela. O rótulo continua dizendo o que liga, por exemplo "Avisar vencimento da garantia da obra 12".

Estados

Desligado

Ligado

Desabilitado e desligado

Desabilitado e ligado

Tamanhos

Pequeno · 28 × 16 px

Pequeno com estado escritoDesligado

Médio · 32 × 18 px

Use sm em tabelas e filtros densos.

Estilo

Propriedade	Token
Trilho desligado	--tj-field-01, borda --tj-border-strong-02; hover --tj-layer-hover-01; pressionado --tj-layer-accent-01
Trilho ligado	--tj-interactive, hover --tj-interactive-hover, pressionado --tj-interactive-active
Botão desligado / ligado	--tj-border-strong-02 / --tj-text-on-color
Desabilitado	desligado: trilho --tj-field-disabled, borda --tj-border-subtle-02, botão --tj-icon-secondary; ligado: trilho --tj-icon-secondary, botão --tj-field-01; texto --tj-text-helper
Texto do estado	--tj-text-helper, semibold
Foco	em todos os estados: contorno sólido de 2 px --tj-border-interactive, afastado 2 px do trilho; borda --tj-border-interactive
Área de clique	pelo menos 24 px de altura, termina no fim do texto
Movimento	--tj-duration-fast-02, --tj-easing-standard; sem animação com prefers-reduced-motion
Tamanho	32 × 18 px (md), 28 × 16 px (sm)

Todas as cores são tokens de papel e trocam com o botão Tema: no escuro, o trilho desligado usa o --tj-field-01 escuro e o botão, o --tj-border-strong-02 claro. Hover e pressionado aparecem com o ponteiro em qualquer parte do rótulo, porque o rótulo inteiro alterna.

Código

<BaseSwitch v-model="avisarVencimento" label="Avisar vencimento da garantia" />
<BaseSwitch v-model="resumo" label="Resumo semanal por e-mail" on-text="Ligado" off-text="Desligado" size="sm" />

Propriedade	Tipo	Padrão	Descrição
v-model	boolean	false	Ligado ou desligado
label	string	—	Rótulo (obrigatório); não muda com o estado
size	'sm' | 'md'	'md'	Tamanho do trilho e do texto
disabled	boolean	false	Desabilita a troca
onText / offText	string	—	Estado escrito ao lado do rótulo; só aparece com os dois
helperText	string	—	Ajuda abaixo do rótulo
hideLabel	boolean	false	Esconde o rótulo da tela e mantém para o leitor de tela; para tabelas

Evento: update:modelValue, com o novo valor. Se o pai não aceitar a troca (por exemplo, uma confirmação recusada), o interruptor volta ao valor que o pai manteve.

Outros atributos, como id, name, form e aria-controls, vão para o <input>; class e style ficam no contêiner. Um aria-describedby passado pelo pai é mantido, e a ajuda entra depois dele.

Acessibilidade

• É um <input type="checkbox"> nativo com role="switch": o leitor de tela anuncia "interruptor, ligado" ou "desligado". Segue o padrão Switch do WAI-ARIA APG.
• Tab leva ao interruptor e Espaço alterna (comportamento nativo do <input>). O rótulo inteiro é clicável, numa área de pelo menos 24 px de altura.
• Use aria-controls quando o interruptor mostra ou esconde outra parte da tela.
• O rótulo nomeia o interruptor e não muda com o estado. O texto de on-text e off-text fica escondido do leitor de tela (aria-hidden), que já anuncia o estado.
• A cor nunca é o único sinal: o botão muda de lado no trilho, e o estado pode ficar escrito.
• A ajuda fica em aria-describedby.
• O foco aparece só na navegação por teclado: um contorno sólido --tj-border-interactive de 2 px, afastado 2 px do trilho, ligado ou desligado. O anel translúcido --tj-ring sozinho ficaria fraco demais num trilho tão pequeno.
• No modo de alto contraste do Windows, o interruptor usa as cores do sistema: trilho Highlight quando ligado, contorno CanvasText quando desligado (também com foco), GrayText quando desabilitado e foco em Highlight. O botão continua mudando de lado.
• Testado com axe nos estados desligado, ligado, desabilitado, pequeno, com texto de estado, com ajuda, com aria-controls e com rótulo escondido, inclusive combinados. O nome acessível é conferido no teste: continua sendo o rótulo com texto de estado e com hide-label. A troca por Espaço e o alto contraste dependem do navegador e não entram no teste automático.