Crear tu primer widget

En este tutorial vas a crear un widget que muestra un dato al azar sobre un tema que elige quien lo instala. Por el camino editarás código en el Estudio de widgets, verás la vista previa en distintos tamaños, añadirás un ajuste y obtendrás datos de una API. Al final lo publicarás y lo pondrás en tu marco.

Necesitarás un ordenador y un marco en tu cuenta. Un marco virtual sirve.

1. Crear el widget

1. En la Consola, elige Mi perfil en el menú de la izquierda.
2. Junto a tus widgets, haz clic en Crear.
3. En Nombre del widget, escribe Dato del día y haz clic en Crear.
4. Se abre la página de tu nuevo widget. Haz clic en Editar.

Se abre el Estudio de widgets. Abre la pestaña Código, a la izquierda. Verás el código inicial que recibe todo widget nuevo:

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 {"Dato del día"}!</span>
      </p>
      <p>{data.fact}</p>
    </div>
  );
};

A la derecha, la vista previa muestra el widget con un dato sobre gatos. Un widget es un componente de React llamado Widget. Este obtiene un dato con useFetch y lo muestra.

2. Usar la tipografía de la biblioteca

El texto de un marco se lee mejor en los tamaños que fijan los componentes de tipografía de la biblioteca Blotch. Sustituye el código por este:

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

La vista previa se actualiza un par de segundos después de que dejes de escribir. Fíjate en que no hay margen interior alrededor del borde ni un título con el nombre del widget: el marco añade ambos alrededor de cada widget, así que el widget no los incluye.

Pulsa Ctrl+S (⌘S en un Mac) para guardar.

3. Probar otros tamaños

En su página, cada persona puede dar a un widget el tamaño que quiera. Encima de la vista previa, recorre cada Tamaño de la vista previa, desde Cuadrado hasta Completo. En Banner, puede que un dato largo no quepa debajo del título.

Para solucionarlo, muestra menos en una caja baja. La clase short: se aplica cuando el widget es bajo y ancho, así que oculta ahí el título:

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

Vuelve a comprobar cada tamaño. Diseñar para todos los tamaños trata esto en profundidad.

4. Permitir que la gente elija un tema

Ahora deja que quien instale el widget elija entre gatos y perros.

1. Elige Archivo > Entradas.
2. En la pestaña Entradas públicas, haz clic en Crear nueva entrada.
3. Como Nombre, pon ANIMAL; como Descripción, ¿Sobre qué animal quieres datos?, y como Tipo, Selección.
4. Añade dos opciones, Cats y Dogs.
5. Pon Dogs como Valor de prueba, para que la vista previa tenga algo que mostrar, y cierra el cuadro de diálogo.

Lee la entrada con useInputs y obtén los datos de una API distinta para cada 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>
  );
};

Ahora la vista previa muestra un dato sobre perros. Cambia el Valor de prueba a Cats para comprobar el otro. Guarda.

5. Publicarlo

1. Elige Archivo > Configuración del widget. Añade una Descripción, como Cada día, un dato nuevo sobre animales, elige una Categoría y haz clic en Listo.
2. Haz clic en Publicar en la barra de herramientas.
3. En la visibilidad, elige Publicado para que cualquiera pueda usarlo, o Privado para quedártelo para ti si tienes Pro.
4. Haz clic en Publicar.

Has lanzado la versión 1.0.0.

6. Ponerlo en tu marco

1. Elige tu marco en el selector de marcos y luego Editor en el menú de la izquierda.
2. Haz clic en Añadir un widget y luego en la pestaña Tus creaciones.
3. Elige Dato del día y luego Añadir al marco.
4. Elige un animal y haz clic en Crear.

Tu widget ya está en tu página. Has creado y publicado tu primer widget.

Siguientes pasos

• Cómo se ejecutan los widgets explica qué le pasa a tu código entre el Estudio de widgets y el marco.
• Obtener datos de una API trata la caché, las claves de API y los errores.
• Explora la biblioteca Blotch para encontrar gráficos, calendarios, iconos y más.
• Publicar y lanzar versiones explica qué ocurre cuando cambias un widget que ya usa otra gente.