Comment fonctionnent les widgets
Un widget ressemble à un composant React ordinaire, mais il ne s’exécute jamais sur le cadre. Blotch l’exécute sur ses propres serveurs, en prend une image et envoie cette image au cadre. Comprendre ce fonctionnement explique la plupart des règles d’écriture des widgets.
Du code à l’encre électronique
Peu avant qu’une page doive s’afficher sur un cadre, Blotch la prépare :
- Chaque widget de la page est ouvert dans sa propre fenêtre de navigateur, aux dimensions exactes de sa zone sur la page.
- Le widget récupère ses données et se dessine.
- Une fois que tout est chargé, Blotch en fait une capture d’écran.
- La capture d’écran est convertie en noir et blanc, avec des motifs de points à la place des nuances de gris, puis envoyée au cadre.
Le cadre affiche ensuite l’image jusqu’à la prochaine actualisation. En Mode standard, il se met en veille entre deux actualisations.
Ce que cela implique pour votre code
Un widget est une image fixe. Personne ne peut le toucher, le faire défiler ni le voir s’animer. Les minuteurs, les transitions et les gestionnaires de clic ne servent à rien. Dessinez dès le premier rendu tout ce qui doit être vu.
Il n’y a pas d’état de chargement. Blotch attend que votre widget ait ses données avant de prendre l’image : le hook useFetch vous donne donc directement les données. Vous n’affichez jamais d’indicateur de chargement.
Les erreurs sont affichées pour vous. Si votre widget lève une erreur, par exemple parce qu’une API est en panne, le cadre affiche l’erreur à la place de votre widget. Vous n’avez pas besoin de votre propre périmètre d’erreur (error boundary). Pour afficher un message plus aimable lors d’une erreur prévisible, détectez-la vous-même et dessinez autre chose.
Les requêtes passent par Blotch. useFetch envoie chaque requête via les serveurs de Blotch. C’est pourquoi les API qui bloquent les requêtes venant des navigateurs fonctionnent quand même, et pourquoi les réponses peuvent être mises en cache et partagées entre les cadres. Cela signifie aussi qu’un widget ne peut pas joindre un serveur situé sur le réseau domestique de quelqu’un.
Les données sont récupérées un peu en avance. Les pages sont préparées quelques minutes avant de s’afficher, si bien que les données ont vieilli d’autant au moment où quelqu’un les voit. C’est rarement gênant, sauf autour de minuit. Consultez Afficher la bonne date et la bonne heure.
L’horloge est avancée. Pour qu’un widget affiche la bonne heure, new Date() vous donne le moment où la page s’affiche, et non celui où elle a été préparée. Dans l’aperçu du Studio de widgets, c’est simplement l’heure actuelle.
Le fuseau horaire doit être demandé. Le navigateur qui dessine votre widget ne se trouve pas dans le fuseau horaire du cadre. Obtenez le fuseau du cadre avec useTimeZone et transmettez-le chaque fois que vous formatez une heure. Sinon, votre widget peut paraître correct dans l’aperçu, qui utilise le fuseau de votre ordinateur, et pourtant être faux sur le cadre.
Les dates et les nombres suivent la langue du cadre. Les fonctions de formatage comme toLocaleDateString utilisent la langue choisie par le propriétaire du cadre, à moins que vous n’en indiquiez une. Consultez Afficher du texte dans la langue du cadre.
Tout passe par les hooks
Votre composant Widget ne reçoit aucune prop. Tout ce qu’il sait de l’endroit où il s’exécute lui vient des hooks de la bibliothèque Blotch :
| Hook | Ce qu’il vous donne |
|---|---|
useInputs | Les réglages choisis par la personne qui l’a installé |
useAssets | Les images que vous avez importées |
useLayoutShape | La taille et la forme de sa zone |
useTimeZone | Le fuseau horaire du cadre |
usePreferredLanguage | La langue du cadre |
useTheme | Si le cadre est dans son thème clair ou sombre |
useBatteryLevel | Le niveau de batterie du cadre |
Noir et blanc
L’écran affiche deux couleurs : le noir et le blanc. Les widgets sont stylés avec Tailwind CSS, configuré avec seulement deux couleurs, foreground et background, qui s’inversent quand le cadre utilise son thème sombre. Les autres classes de couleur n’ont aucun effet.
Les nuances proviennent de motifs de points, qui conviennent bien aux grandes surfaces comme une barre remplie, mais donnent un aspect moucheté aux traits fins et aux petits textes. Gardez le texte et les traits en text-foreground plein, et réservez les teintes aux arrière-plans.
Les composants de la bibliothèque Blotch respectent déjà ces règles : partir d’eux est donc le moyen le plus simple d’obtenir un bon rendu.
Tailles
L ’écran entier mesure 960 pixels sur 680, et un widget peut en occuper n’importe quelle partie, d’un petit carré à l’écran entier, en paysage comme en portrait. Le propriétaire du cadre ajoute aussi une bordure et une marge autour. Un widget doit être réussi à toutes les tailles. Consultez Concevoir pour toutes les tailles.
Les widgets masqués ne sont pas dessinés
Si un widget est entièrement recouvert par d’autres widgets sur la page, Blotch ne le dessine pas du tout.