はじめてのウィジェットを作る

このチュートリアルでは、ウィジェットをインストールする人が選んだテーマについて、ランダムな豆知識を表示するウィジェットを作ります。その過程で、ウィジェットスタジオでコードを編集し、さまざまなサイズでプレビューし、設定を追加し、APIからデータを取得し、公開してフレームに表示します。

パソコンと、アカウントに登録されたフレームが必要です。フレームは仮想フレームでもかまいません。

コンソールで、左のメニューからマイプロフィールを選びます。
ウィジェットの一覧の横にある作成を選びます。
ウィジェット名に今日の豆知識と入力し、作成を選びます。
新しいウィジェットのページが開きます。編集を選びます。

新しいウィジェットのダイアログ。「ウィジェット名」に「今日の豆知識」と入力されています

ウィジェットスタジオが開きます。左側のコードタブを選ぶと、新しいウィジェットに最初から入っているコードが表示されます。

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 {"今日の豆知識"}!</span>
      </p>
      <p>{data.fact}</p>
    </div>
  );
};

右側のプレビューに、猫の豆知識が入ったウィジェットが表示されます。ウィジェットはWidgetという名前のReactコンポーネントです。このウィジェットは、useFetchで豆知識を取得して表示しています。

ウィジェットスタジオ。左に「コード」タブとウィジェットのコード、その下に「出力」パネル、右にプレビューがあります

2. ライブラリのタイポグラフィを使う

フレーム上のテキストは、Blotchライブラリのタイポグラフィコンポーネントが設定するサイズにすると最も読みやすくなります。コードを次のように置き換えます。

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

入力をやめて数秒たつと、プレビューが更新されます。端の余白も、ウィジェット名の見出しもないことに注目してください。フレームがすべてのウィジェットの周りにその両方を付けるので、ウィジェットには入れません。

Ctrl+S（Macでは⌘S）を押して保存します。

3. ほかのサイズを試す

ウィジェットは、ページ上で好きなサイズにできます。プレビューの上で、正方形からフルまで、それぞれのプレビューサイズを選んでみてください。バナーでは、長い豆知識が見出しの下に収まらないことがあります。

プレビューの上にあるプレビューサイズのタブ：正方形、レンガ、ワイド、バナー、トール、カラム、フル

背の低い枠では表示する内容を減らして解決しましょう。short:クラスはウィジェットが低く横長のときに適用されるので、そのときは見出しを隠します。

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

もう一度それぞれのサイズを確認します。詳しくはどのサイズにも合うデザインにするで説明しています。

4. テーマを選べるようにする

次に、ウィジェットをインストールする人が猫か犬かを選べるようにします。

ファイル > 入力項目を選びます。
公開入力項目タブで新しい入力を作成を選びます。
名前をANIMAL、説明をどの動物の豆知識を表示しますか？、タイプを選択にします。
CatsとDogsの2つの選択肢を追加します。
プレビューに表示するものがあるようにテスト用の値をDogsにして、ダイアログを閉じます。

「入力項目」ダイアログの「公開入力項目」タブ。ANIMAL入力項目の説明、「選択」タイプ、選択肢のCatsとDogs、テスト用の値のDogsが表示されています

useInputsで入力項目を読み取り、動物ごとに別のAPIからデータを取得します。

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

プレビューに犬の豆知識が表示されるようになりました。テスト用の値をCatsに変えて、もう一方も確認しましょう。確認できたら保存します。

5. 公開する

ファイル > ウィジェット設定を選びます。毎日ひとつ、動物の豆知識をお届けしますのような説明を追加し、カテゴリを選んで、完了を選びます。
ツールバーの公開を選びます。
公開範囲で、誰でも使えるようにするなら公開済みを選びます。Proプランをご利用中なら、非公開を選んで自分だけで使うこともできます。
公開を選びます。