Einstellungen für Ihr Widget anbieten

Eingaben sind die Einstellungen, die jemand ausfüllt, wenn er Ihr Widget zu seinem Rahmen hinzufügt, etwa die eigene Stadt, ein Börsenkürzel oder die Nachrichtenquelle, die angezeigt werden soll. So funktioniert ein Widget für alle, ohne dass jemand den Code anfassen muss.

Eine Eingabe hinzufügen

1. Wählen Sie im Widget-Studio Datei > Eingaben.
2. Klicken Sie auf dem Tab Öffentliche Eingaben auf Neue Eingabe erstellen.
3. Füllen Sie Folgendes aus:
   • Name: der Name, den Sie in Ihrem Code verwenden, etwa CITY. Erlaubt sind nur Buchstaben, Ziffern und Unterstriche, und am Anfang darf keine Ziffer stehen. In Großbuchstaben fallen Eingaben in Ihrem Code leicht auf.
   • Beschreibung: was andere sehen, wenn sie Ihr Widget einrichten, etwa Which city's weather would you like to see?
   • Typ: die Art des Feldes, das sie ausfüllen. Siehe Eingabetypen.
   • Erforderlich: ob sie das Feld ausfüllen müssen, bevor das Widget hinzugefügt werden kann. Neue Eingaben sind erforderlich.
4. Schließen Sie den Dialog, um Ihre Eingaben zu speichern.

Im Code lesen

Lesen Sie Eingaben mit useInputs:

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

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

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

Jede Eingabe kommt in dem Typ an, der zu ihr passt: Text als string, eine Zahl als number, eine Mehrfachauswahl als Liste von Strings und so weiter. Eine leer gelassene Eingabe kommt als undefined an. Das Widget-Studio kennt Ihre Eingaben. Es vervollständigt deshalb ihre Namen und markiert einen falsch geschriebenen Namen.

In der Vorschau ausprobieren

Geben Sie jeder Eingabe einen Testwert, um zu sehen, wie Ihr Widget aussieht, wenn jemand sie ausfüllt. Testwerte bleiben nur erhalten, bis Sie das Widget-Studio neu laden, und niemand sonst sieht sie.

Hat eine als Erforderlich markierte Eingabe keinen Wert, zeigt die Vorschau statt Ihres Widgets Inputs Required (Eingaben erforderlich) und listet auf, was fehlt. Rahmen zeigen das nie, denn eine erforderliche Eingabe muss ausgefüllt sein, bevor das Widget hinzugefügt werden kann.

Optionale Eingaben

Eine leer gelassene optionale Eingabe kommt als undefined an. Geben Sie ihr deshalb einen Ersatzwert, oder zeigen Sie an ihrer Stelle etwas Hilfreiches:

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

Optionen einer Auswahl lesbar machen

Formulieren Sie die Optionen einer Eingabe vom Typ Auswahl für die Menschen, die daraus wählen, und wandeln Sie die Wahl dann in das um, was Ihr Code braucht. Ein Beispiel für eine Fußball-API, die einen Wettbewerbscode erwartet:

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

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

Beim Einrichten Ihres Widgets sehen die Leute Champions League statt CL.

Geheimnisse und Konten

• Für Ihren eigenen API-Schlüssel, den niemand sehen soll, verwenden Sie eine Private Eingabe.
• Um jede Person nach ihrem eigenen API-Schlüssel zu fragen, verwenden Sie eine Eingabe vom Typ Vertraulich. Sie verbirgt, was eingetippt wird.
• Damit sich andere bei einem Dienst wie Google oder Spotify anmelden, verwenden Sie eine Integration.

Eingaben später ändern

Sobald andere Ihr Widget nutzen, kann eine Änderung an seinen Eingaben verändern, was sie eingerichtet haben. Eine optionale Eingabe hinzuzufügen ist unbedenklich. Wenn Sie aber eine Eingabe entfernen oder umbenennen oder eine erforderliche hinzufügen, wird die nächste Veröffentlichung ein Major-Update. Bei einem solchen Update entscheidet jeder selbst, wann er aktualisiert. Siehe Versionsnummern.