Permitir que la gente configure tu widget

Las entradas son los ajustes que alguien rellena al añadir tu widget a su marco, como su ciudad, el símbolo de una acción o qué fuente de noticias mostrar. Permiten que un mismo widget funcione para todo el mundo, sin que nadie toque el código.

Añadir una entrada

1. En el Estudio de widgets, elige Archivo > Entradas.
2. En la pestaña Entradas públicas, elige Crear nueva entrada.
3. Rellena:
   • Nombre: el nombre que usas en tu código, como CITY. Solo admite letras, dígitos y guiones bajos, y no puede empezar por un dígito. Con mayúsculas, las entradas se distinguen fácilmente en tu código.
   • Descripción: lo que ve la gente al configurar tu widget, como Which city's weather would you like to see?
   • Tipo: la clase de campo que rellenan. Consulta Tipos de entrada.
   • Obligatorio: si tienen que rellenarla antes de poder añadir el widget. Las entradas nuevas son obligatorias.
4. Cierra el cuadro de diálogo para guardar tus entradas.

Leerla en tu código

Lee las entradas con useInputs:

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

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

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

Cada entrada llega con el tipo que le corresponde: el texto como string, un Número como number, una Selección múltiple como una lista de cadenas, etc. Una entrada que se deja vacía llega como undefined. El Estudio de widgets conoce tus entradas, así que autocompleta sus nombres y señala las que estén mal escritas.

Probarla en la vista previa

Dale a cada entrada un Valor de prueba para ver cómo queda tu widget cuando alguien la rellena. Los valores de prueba solo duran hasta que recargas el Estudio de widgets, y nadie más los ve.

Si una entrada marcada como Obligatorio no tiene valor, la vista previa muestra Inputs Required (Entradas obligatorias) en lugar de tu widget, con una lista de lo que falta. Los marcos nunca muestran este aviso, porque una entrada obligatoria tiene que rellenarse antes de poder añadir el widget.

Entradas opcionales

Una entrada opcional que se deja vacía llega como undefined, así que dale un valor por defecto o muestra en su lugar algo que ayude:

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

Hacer legibles las opciones de una selección

Escribe las opciones de una entrada de tipo Selección pensando en quienes las eligen y luego convierte la elección en lo que necesite tu código. Por ejemplo, si una API de fútbol pide un código de competición:

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

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

Al configurar tu widget, la gente ve Champions League en lugar de CL.

Secretos y cuentas

• Para tu propia clave de API, que no quieres que vea nadie, usa una entrada privada.
• Para pedir a cada persona su propia clave de API, usa una entrada Sensible, que oculta lo que escribe.
• Para que la gente inicie sesión en un servicio como Google o Spotify, usa una integración.

Cambiar las entradas más adelante

Cuando la gente ya usa tu widget, cambiar sus entradas puede alterar lo que ha configurado. Añadir una entrada opcional no supone ningún riesgo, pero eliminar o renombrar una, o añadir una obligatoria, convierte la siguiente versión publicada en una actualización mayor, y cada persona decide cuándo actualizar a ella. Consulta Números de versión.