Permettere agli altri di configurare il widget

Gli input sono le impostazioni che una persona compila quando aggiunge il tuo widget alla sua cornice, come la sua città, il simbolo di un titolo azionario o la fonte di notizie da mostrare. Permettono a un solo widget di funzionare per tutti, senza che nessuno tocchi il codice.

Aggiungere un input

1. Nello Studio dei widget, scegli File > Input.
2. Nella scheda Input pubblici, scegli Crea nuovo input.
3. Compila:
   • Nome: il nome che usi nel codice, come CITY. Solo lettere, cifre e trattini bassi, e non può iniziare con una cifra. Con le maiuscole gli input si riconoscono facilmente nel codice.
   • Descrizione: ciò che le persone vedono quando configurano il tuo widget, come Which city's weather would you like to see?
   • Tipo: il tipo di campo da compilare. Consulta Tipi di input.
   • Obbligatorio: se va compilato prima di poter aggiungere il widget. I nuovi input sono obbligatori.
4. Chiudi la finestra di dialogo per salvare gli input.

Leggerlo nel codice

Leggi gli input con useInputs:

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

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

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

Ogni input arriva con il tipo adatto: il testo come string, un Numero come number, una Selezione multipla come elenco di stringhe, e così via. Un input lasciato vuoto arriva come undefined. Lo Studio dei widget conosce i tuoi input: ne completa automaticamente i nomi e segnala quelli scritti male.

Provarlo nell’anteprima

Assegna a ogni input un Valore di test per vedere come appare il tuo widget quando qualcuno lo compila. I valori di test durano solo finché non ricarichi lo Studio dei widget, e nessun altro li vede.

Se un input contrassegnato come Obbligatorio non ha un valore, l’anteprima mostra Inputs Required (Input obbligatori) al posto del tuo widget, con l’elenco di ciò che manca. Le cornici non mostrano mai questo avviso, perché un input obbligatorio deve essere compilato prima di poter aggiungere il widget.

Input facoltativi

Un input facoltativo lasciato vuoto arriva come undefined, quindi dagli un valore di riserva, oppure mostra al suo posto qualcosa di utile:

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" />;
}

Rendere leggibili le opzioni di una selezione

Scrivi le opzioni di un input Selezione pensando a chi le sceglie, poi trasforma la scelta in ciò che serve al tuo codice. Ad esempio, se un’API di calcio vuole il codice di una competizione:

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

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

Quando configurano il tuo widget, le persone vedono Champions League invece di CL.

Segreti e account

• Per la tua chiave API, che non vuoi far vedere a nessuno, usa un input privato.
• Per chiedere a ciascuno la propria chiave API, usa un input Sensibile, che nasconde ciò che viene digitato.
• Per far accedere le persone a un servizio come Google o Spotify, usa un’integrazione.

Modificare gli input in seguito

Quando le persone usano già il tuo widget, modificarne gli input può cambiare ciò che hanno configurato. Aggiungere un input facoltativo non comporta rischi, ma rimuoverne o rinominarne uno, oppure aggiungerne uno obbligatorio, fa della versione successiva un aggiornamento principale, e ciascuno sceglie quando aggiornare. Consulta Numeri di versione.