Creare il tuo primo widget

In questo tutorial creerai un widget che mostra una curiosità a caso su un argomento scelto da chi lo installa. Strada facendo modificherai il codice nello Studio dei widget, vedrai l’anteprima in diverse dimensioni, aggiungerai un’impostazione e recupererai dati da un’API. Alla fine lo pubblicherai e lo metterai sulla tua cornice.

Ti servono un computer e una cornice nel tuo account. Va bene anche una cornice virtuale.

1. Creare il widget

1. Nella Console, scegli Il mio profilo nel menu a sinistra.
2. Accanto ai tuoi widget, fai clic su Crea.
3. In Nome del widget, digita Curiosità del giorno, poi fai clic su Crea.
4. Si apre la pagina del tuo nuovo widget. Fai clic su Modifica.

Si apre lo Studio dei widget. Fai clic sulla scheda Codice a sinistra. Vedrai il codice iniziale che riceve ogni nuovo 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 {"Curiosità del giorno"}!
        </span>
      </p>
      <p>{data.fact}</p>
    </div>
  );
};

A destra, l’anteprima mostra il widget, con una curiosità sui gatti. Un widget è un componente React chiamato Widget. Questo recupera una curiosità con useFetch e la mostra.

2. Usare la tipografia della libreria

Il testo su una cornice si legge meglio nelle dimensioni stabilite dai componenti tipografici della libreria Blotch. Sostituisci il codice con questo:

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’anteprima si aggiorna un paio di secondi dopo che smetti di scrivere. Nota che non c’è margine interno lungo i bordi, né un titolo con il nome del widget: la cornice aggiunge entrambi intorno a ogni widget, quindi un widget non li include.

Premi Ctrl+S (⌘S su Mac) per salvare.

3. Provare altre dimensioni

Sulla propria pagina, le persone possono dare a un widget qualsiasi dimensione. Sopra l’anteprima, scegli una per una le voci di Dimensione anteprima, da Quadrato a Completo. In Banner, una curiosità lunga potrebbe non entrare sotto il titolo.

Risolvi mostrando meno contenuto in un riquadro basso. La classe short: si applica quando il widget è basso e largo, quindi nascondi lì il titolo:

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

Controlla di nuovo ogni dimensione. Progettare per ogni dimensione approfondisce l’argomento.

4. Far scegliere un argomento

Ora fai in modo che chi installa il widget possa scegliere tra gatti e cani.

1. Scegli File > Input.
2. Nella scheda Input pubblici, fai clic su Crea nuovo input.
3. Imposta il Nome su ANIMAL, la Descrizione su Su quale animale vuoi le curiosità? e il Tipo su Selezione.
4. Aggiungi due opzioni, Cats e Dogs.
5. Imposta il Valore di test su Dogs, così l’anteprima ha qualcosa da mostrare, poi chiudi la finestra di dialogo.

Leggi l’input con useInputs e recupera i dati da un’API diversa per ogni animale:

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>
  );
};

Ora l’anteprima mostra una curiosità sui cani. Cambia il Valore di test in Cats per controllare l’altra. Salva.

5. Pubblicarlo

1. Scegli File > Configurazione widget. Aggiungi una Descrizione, come Ogni giorno una nuova curiosità sugli animali, scegli una Categoria e fai clic su Fatto.
2. Fai clic su Pubblica nella barra degli strumenti.
3. Come visibilità, scegli Pubblicato per permettere a chiunque di usarlo, oppure Privato per tenerlo per te, se hai Pro.
4. Fai clic su Pubblica.

Hai rilasciato la versione 1.0.0.

6. Metterlo sulla tua cornice

1. Scegli la tua cornice nel selettore della cornice, poi scegli Editor nel menu a sinistra.
2. Fai clic su Aggiungi un widget, poi sulla scheda Le tue creazioni.
3. Scegli Curiosità del giorno, poi Aggiungi alla cornice.
4. Scegli un animale, poi fai clic su Crea.

Il tuo widget è sulla tua pagina. Hai creato e pubblicato il tuo primo widget.

Passaggi successivi

• Come vengono eseguiti i widget spiega cosa succede al tuo codice tra lo Studio dei widget e la cornice.
• Recuperare dati da un’API tratta la cache, le chiavi API e gli errori.
• Esplora la libreria Blotch per trovare grafici, calendari, icone e altro ancora.
• Pubblicare e rilasciare versioni spiega cosa succede quando modifichi un widget che altre persone usano già.