ThemeSwitch

Um controle segmentado de três estados (sistema / claro / escuro) ligado à API de temas do ranui. Clicar num segmento chama setTheme(), guarda a escolha na chave de localStorage ran-theme e mantém sincronizadas todas as instâncias da página (e de outras abas).

Use quando precisar de um controle segmentado sistema/claro/escuro já ligado à API de temas do ranui. O <r-theme-switch> cuida da persistência, do acompanhamento do sistema e da sincronização entre abas, então você não precisa montar um alternador na mão.

Início rápido

Uso básico

<r-theme-switch></r-theme-switch>

import 'ranui'; // ou a entrada independente:
import 'ranui/theme-switch';

💡 Neste site de documentação o tema é comandado pelo alternador global do cabeçalho, que reescreve data-ran-theme por conta própria, então o site pode reiniciar a demonstração acima. No seu aplicativo, o <r-theme-switch> é a fonte da verdade.

Chame initTheme() uma vez no carregamento da página para que a escolha salva seja restaurada antes de o controle ser desenhado:

import { initTheme } from 'ranui';
initTheme();

Referência da API

Propriedades

Propriedade	Tipo	Padrão	Descrição
`value`	`'system' \| 'light' \| 'dark'`	`'system'`	Seleção atual, lida da API de temas (`getTheme()`). Atribuí-la aplica e persiste o tema.
`sheet`	`string`	`''`	CSS injetado no shadow DOM do componente.

Atributos de localização

Os três botões são só ícone, então cada um carrega um aria-label. Sobrescreva-os para traduzir:

Atributo	Padrão	Descrição
`label`	`'Theme'`	`aria-label` do grupo de controle.
`label-system`	`'System theme'`	`aria-label` do botão de sistema.
`label-light`	`'Light theme'`	`aria-label` do botão claro.
`label-dark`	`'Dark theme'`	`aria-label` do botão escuro.

<r-theme-switch
  label="Tema"
  label-system="Tema do sistema"
  label-light="Tema claro"
  label-dark="Tema escuro"
></r-theme-switch>

Eventos

Evento	Detail	Descrição
`change`	`{ theme: 'system' \| 'light' \| 'dark' }`	Disparado quando o usuário escolhe um tema. Borbulha e cruza o shadow DOM.

const themeSwitch = document.createElement('r-theme-switch');
themeSwitch.addEventListener('change', (e) => {
  console.log('theme is now', e.detail.theme);
});
toolbar.append(themeSwitch);

Comportamento

Persistência: as seleções passam por setTheme(), então são salvas no localStorage (ran-theme) e restauradas por initTheme() na próxima visita.
Sincronização entre instâncias: coloque um controle no cabeçalho e outro no rodapé; escolher um tema em qualquer um atualiza os dois.
Sincronização entre abas: um tema trocado em outra aba atualiza este controle pelo evento storage.
Cromo do navegador: forçar claro ou escuro atualiza <meta name="theme-color"> para o fundo de página resolvido, de modo que o cromo do navegador ou do PWA combine; escolher system restaura o conteúdo original de cada meta (que pode ter condição de mídia).

Partes CSS

Parte	Descrição
`switch`	A pílula segmentada externa.
`button`	Cada botão de escolha (cada um expõe também seu nome de escolha como parte).
`system` / `light` / `dark`	Os botões de escolha individuais.

r-theme-switch::part(switch) {
  border-color: var(--line);
}
r-theme-switch::part(dark) {
  color: rebeccapurple;
}

Estas variáveis CSS podem ser sobrescritas: --ran-theme-switch-display, --ran-theme-switch-gap, --ran-theme-switch-padding, --ran-theme-switch-border-color, --ran-theme-switch-radius, --ran-theme-switch-background, --ran-theme-switch-button-size, --ran-theme-switch-icon-size, --ran-theme-switch-button-color, --ran-theme-switch-button-hover-color, --ran-theme-switch-button-active-background, --ran-theme-switch-button-active-color, --ran-theme-switch-button-focus-outline.

r-theme-switch {
  --ran-theme-switch-button-size: 32px;
  --ran-theme-switch-icon-size: 18px;
}

Boas práticas

Uma única fonte da verdade: use o <r-theme-switch> em vez de montar um alternador na mão; ele já cuida da persistência, do acompanhamento do sistema, da sincronização entre instâncias e das metas theme-color.
Restaure cedo: chame initTheme() o mais cedo possível (idealmente inline, antes da primeira pintura) para evitar um lampejo de claro para escuro.
Traduza: os botões são só ícone; defina label e label-* para interfaces que não estejam em inglês.