Permettre aux gens de configurer votre widget

Les entrées sont les réglages qu’une personne remplit lorsqu’elle ajoute votre widget à son cadre, comme sa ville, un symbole boursier ou la source d’actualités à afficher. Grâce à elles, un même widget fonctionne pour tout le monde, sans que personne ait à toucher au code.

Ajouter une entrée

1. Dans le Studio de widgets, choisissez Fichier > Entrées.
2. Dans l’onglet Entrées publiques, choisissez Créer une entrée.
3. Remplissez :
   • Nom : le nom que vous utilisez dans votre code, comme CITY. Uniquement des lettres, des chiffres et des tirets bas, sans chiffre au début. Les majuscules permettent de repérer facilement les entrées dans votre code.
   • Description : ce que voient les gens lorsqu’ils configurent votre widget, comme Which city's weather would you like to see?
   • Type : le genre de champ qu’ils remplissent. Consultez Types d’entrées.
   • Obligatoire : s’ils doivent la remplir avant de pouvoir ajouter le widget. Les nouvelles entrées sont obligatoires.
4. Fermez la boîte de dialogue pour enregistrer vos entrées.

La lire dans votre code

Lisez les entrées avec useInputs :

import { Heading } from "~lib/typography";
import { useInputs } from "~lib/use-inputs";

export const Widget = () => {
  const { CITY } = useInputs();

  return <Heading>{CITY}</Heading>;
};

Chaque entrée arrive avec le type qui lui convient : le texte sous forme de string, un Nombre sous forme de number, une Sélection multiple sous forme de liste de chaînes, et ainsi de suite. Une entrée laissée vide arrive sous la forme undefined. Le Studio de widgets connaît vos entrées : il complète automatiquement leurs noms et signale un nom mal orthographié.

L’essayer dans l’aperçu

Donnez à chaque entrée une Valeur de test pour voir à quoi ressemble votre widget lorsque quelqu’un la remplit. Les valeurs de test ne durent que jusqu’au prochain rechargement du Studio de widgets, et personne d’autre ne les voit.

Si une entrée Obligatoire n’a pas de valeur, l’aperçu affiche Inputs Required (Entrées obligatoires) à la place de votre widget, avec la liste de ce qui manque. Les cadres n’affichent jamais ce message, car une entrée obligatoire doit être remplie avant de pouvoir ajouter le widget.

Entrées facultatives

Une entrée facultative laissée vide arrive sous la forme undefined : prévoyez donc une valeur de repli, ou affichez quelque chose d’utile à sa place :

import { EmptyState } from "~lib/feedback/empty-state";

const { CITY } = useInputs();
const city = String(CITY ?? "").trim();

if (city === "") {
  return <EmptyState title="Choose a city in the Widget's settings" />;
}

Rendre les options d’une sélection lisibles

Rédigez les options d’une Sélection pour les personnes qui les choisissent, puis convertissez le choix en ce dont votre code a besoin. Par exemple, si une API de football attend un code de compétition :

const LEAGUE_CODES: Record<string, string> = {
  "Champions League": "CL",
  "European Championship": "EC",
  "World Cup": "WC",
};

const { LEAGUE } = useInputs();
const code = LEAGUE_CODES[LEAGUE];

Les gens voient Champions League plutôt que CL lorsqu’ils configurent votre widget.

Secrets et comptes

• Pour votre propre clé d’API, que vous ne voulez montrer à personne, utilisez une entrée privée.
• Pour demander à chaque personne sa propre clé d’API, utilisez une entrée Sensible, qui masque ce qu’elle saisit.
• Pour que les gens se connectent à un service comme Google ou Spotify, utilisez une intégration.

Modifier les entrées par la suite

Une fois que des gens utilisent votre widget, modifier ses entrées peut changer ce qu’ils ont configuré. Ajouter une entrée facultative ne pose aucun problème, mais en supprimer ou en renommer une, ou en ajouter une obligatoire, fait de la prochaine publication une version majeure, vers laquelle chacun choisit quand passer. Consultez Numéros de version.