Torche

Autoriser la torche

La torche n’est accessible que si la case « Torche » est cochée dans la section « WebApp avancée » de la carte lien. Votre page le vérifie avec mairies.commands :

const m = window.mairies;
const torchAllowed = Boolean(m && m.commands.includes('torch'));

L’objet mairies.torch existe dès que le pont est présent, même si la case n’est pas cochée : dans ce cas, chaque appel est rejeté avec NOT_ALLOWED. Testez donc commands, pas seulement la présence de mairies.torch.

Aucune autorisation n’est demandée à l’utilisateur pour la torche.

Vérifier la disponibilité

mairies.torch.isAvailable() indique si la torche peut être utilisée maintenant :

const { available } = await window.mairies.torch.isAvailable();

Le résultat vaut false quand l’appareil n’a pas de lampe (certaines tablettes), mais aussi quand elle est momentanément indisponible : caméra utilisée par votre page ou par une autre application, appareil trop chaud sur iPhone. Appelez-la juste avant d’afficher votre bouton, et de nouveau après l’arrêt d’un flux caméra.

mairies.torch.getState() donne l’état actuel. Sur un appareil sans lampe, elle est rejetée avec UNAVAILABLE.

Allumer, éteindre, basculer

Méthode	Résultat
mairies.torch.isAvailable()	{ available: boolean }
mairies.torch.getState()	{ on: boolean }
mairies.torch.on()	{ on: true }
mairies.torch.off()	{ on: false }
mairies.torch.toggle()	{ on: boolean }, le nouvel état

Chaque méthode renvoie une Promise. Mettez à jour votre interface avec la valeur renvoyée plutôt qu’avec celle que vous attendiez :

const button = document.querySelector('#lampe');

function render(on) {
  button.setAttribute('aria-pressed', String(on));
  button.textContent = on ? 'Éteindre la lampe' : 'Allumer la lampe';
}

button.addEventListener('click', async () => {
  try {
    const { on } = await window.mairies.torch.toggle();
    render(on);
  } catch (error) {
    if (error.code === 'RATE_LIMITED') return; // clic trop rapproché : ignorer
    console.warn('Torche indisponible :', error.code);
  }
});

L’appel générique mairies.call('torch.on') est équivalent à mairies.torch.on(). Voir Appel générique.

Limites (anti-flash, arrière-plan)

Limitation anti-flash. L’application accepte au plus un changement d’état toutes les 500 ms. Au-delà, l’appel est rejeté avec RATE_LIMITED et la torche ne change pas. Cette limite protège les personnes photosensibles (critère WCAG 2.3.1 : pas plus de trois flashs par seconde) ; elle ne peut pas être désactivée.

Ne sont pas limités : getState(), isAvailable(), et une demande qui ne change rien (on() sur une torche déjà allumée, off() sur une torche éteinte). Un appel refusé ne repousse pas le délai.

Attention

N’utilisez pas la torche pour produire un clignotement ou un signal lumineux. En plus de la limite ci-dessus, un clignotement peut provoquer des crises chez les personnes photosensibles.

Extinction automatique. La torche allumée par votre page est éteinte quand l’utilisateur ferme l’écran du lien ou met l’application en arrière-plan. Une lampe allumée par l’utilisateur ailleurs (centre de contrôle, réglages rapides) n’est jamais éteinte par l’application.

Une navigation vers une autre page, à l’intérieur de l’écran du lien, n’éteint pas la torche. Si votre parcours l’exige, éteignez-la vous-même :

window.addEventListener('pagehide', () => {
  window.mairies?.torch.off().catch(() => {});
});

Caméra en cours d’utilisation. Si votre page filme avec getUserMedia, la torche se pilote différemment. Voir Torche pendant un flux caméra.