Créer votre premier widget

Dans ce tutoriel, vous allez créer un widget qui affiche une anecdote au hasard sur un thème choisi par la personne qui l’installe. En chemin, vous modifierez du code dans le Studio de widgets, afficherez son aperçu à différentes tailles, ajouterez un réglage, récupérerez des données depuis une API, puis publierez le widget et le placerez sur votre cadre.

Il vous faut un ordinateur et un cadre associé à votre compte. Un cadre virtuel convient très bien.

1. Créer le widget

1. Dans la Console, choisissez Mon profil dans le menu de gauche.
2. À côté de vos widgets, choisissez Créer.
3. Sous Nom du widget, saisissez Anecdote du jour, puis choisissez Créer.
4. La page de votre nouveau widget s’ouvre. Choisissez Modifier.

Le Studio de widgets s’ouvre. Choisissez l’onglet Code à gauche. Vous voyez le code de départ que reçoit chaque nouveau widget :

import { useFetch } from "~lib/use-fetch";

type Response = {
  readonly fact: string;
};

export const Widget = () => {
  const { data } = useFetch<Response>("https://catfact.ninja/fact");

  return (
    <div className="size-full flex flex-col items-center justify-center gap-4">
      <p>
        <span className="text-xl font-bold">
          Welcome to {"Anecdote du jour"}!
        </span>
      </p>
      <p>{data.fact}</p>
    </div>
  );
};

À droite, l’aperçu affiche le widget, avec une anecdote sur les chats. Un widget est un composant React appelé Widget. Celui-ci récupère une anecdote avec useFetch et l’affiche.

2. Utiliser la typographie de la bibliothèque

Sur un cadre, le texte se lit le mieux aux tailles que définissent les composants typographiques de la bibliothèque Blotch. Remplacez le code par celui-ci :

import { Heading, Paragraph } from "~lib/typography";
import { useFetch } from "~lib/use-fetch";

type Response = {
  readonly fact: string;
};

export const Widget = () => {
  const { data } = useFetch<Response>("https://catfact.ninja/fact");

  return (
    <div className="size-full flex flex-col justify-center gap-2">
      <Heading level={3}>Did you know?</Heading>
      <Paragraph>{data.fact}</Paragraph>
    </div>
  );
};

L’aperçu se met à jour quelques secondes après que vous avez arrêté de taper. Remarquez qu’il n’y a ni marge sur les bords, ni titre qui nomme le widget : le cadre ajoute l’une et l’autre autour de chaque widget, si bien qu’un widget s’en passe.

Appuyez sur Ctrl+S (⌘S sur Mac) pour enregistrer.

3. Essayer d’autres tailles

Sur leur page, les gens peuvent donner n’importe quelle taille à un widget. Au-dessus de l’aperçu, choisissez tour à tour chaque Taille d’aperçu, de Carré à Plein écran. En Bannière, une longue anecdote risque de ne pas tenir sous le titre.

Corrigez cela en affichant moins de choses dans une boîte peu haute. La classe short: s’applique quand le widget est bas et large. Masquez-y le titre :

<div className="short:hidden">
  <Heading level={3}>Did you know?</Heading>
</div>

Vérifiez de nouveau chaque taille. Concevoir pour toutes les tailles aborde ce sujet en détail.

4. Laisser les gens choisir un thème

Ensuite, laissez la personne qui installe le widget choisir entre les chats et les chiens.

1. Choisissez Fichier > Entrées.
2. Dans l’onglet Entrées publiques, choisissez Créer une entrée.
3. Définissez son Nom sur ANIMAL, sa Description sur Sur quel animal voulez-vous des anecdotes ? et son Type sur Sélection.
4. Ajoutez deux options, Cats et Dogs.
5. Définissez sa Valeur de test sur Dogs, pour que l’aperçu ait quelque chose à afficher, puis fermez la boîte de dialogue.

Lisez l’entrée avec useInputs, et récupérez les données depuis une API différente pour chaque animal :

import { Heading, Paragraph } from "~lib/typography";
import { useFetch } from "~lib/use-fetch";
import { useInputs } from "~lib/use-inputs";

type CatFact = {
  readonly fact: string;
};

type DogFacts = {
  readonly data: { readonly attributes: { readonly body: string } }[];
};

const CatFactText = () => {
  const { data } = useFetch<CatFact>("https://catfact.ninja/fact");
  return <Paragraph>{data.fact}</Paragraph>;
};

const DogFactText = () => {
  const { data } = useFetch<DogFacts>("https://dogapi.dog/api/v2/facts");
  return <Paragraph>{data.data[0].attributes.body}</Paragraph>;
};

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

  return (
    <div className="size-full flex flex-col justify-center gap-2">
      <div className="short:hidden">
        <Heading level={3}>Did you know?</Heading>
      </div>
      {ANIMAL === "Dogs" ? <DogFactText /> : <CatFactText />}
    </div>
  );
};

L’aperçu affiche maintenant une anecdote sur les chiens. Remplacez la Valeur de test par Cats pour vérifier l’autre. Enregistrez.

5. Publier le widget

1. Choisissez Fichier > Configuration du widget. Ajoutez une Description, comme Une nouvelle anecdote animalière chaque jour, choisissez une Catégorie, puis Terminé.
2. Choisissez Publier dans la barre d’outils.
3. Pour la visibilité, choisissez Publié pour que tout le monde puisse l’utiliser, ou Privé pour le garder pour vous si vous avez Pro.
4. Choisissez Publier.

Vous venez de publier la version 1.0.0.

6. Placer le widget sur votre cadre

1. Choisissez votre cadre dans le sélecteur de cadre, puis choisissez Éditeur dans le menu de gauche.
2. Choisissez Ajouter un widget, puis l’onglet Vos créations.
3. Choisissez Anecdote du jour, puis Ajouter au cadre.
4. Choisissez un animal, puis Créer.

Votre widget est sur votre page. Vous avez créé et publié votre premier widget.

Étapes suivantes

• Comment fonctionnent les widgets explique ce qui arrive à votre code entre le Studio de widgets et le cadre.
• Récupérer des données depuis une API traite de la mise en cache, des clés d’API et des erreurs.
• Parcourez la bibliothèque Blotch pour trouver des graphiques, des calendriers, des icônes et bien plus encore.
• Publier et diffuser des versions explique ce qui se passe quand vous modifiez un widget que des gens utilisent déjà.