メインコンテンツまでスキップ

ウィジェットを設定できるようにする

入力項目は、ウィジェットをフレームに追加するときに入力してもらう設定です。たとえば住んでいる都市、株式の銘柄コード、表示するニュースソースなどです。入力項目があれば、誰もコードに触れることなく、ひとつのウィジェットをみんなが使えます。

入力項目を追加する​

  1. ウィジェットスタジオで、ファイル > 入力項目を選びます。
  2. 公開入力項目タブで、新しい入力を作成を選びます。
  3. 次の項目を入力します。
    • 名前：コードの中で使う名前です（例：CITY）。使えるのは英字、数字、アンダースコアだけで、数字から始めることはできません。大文字にしておくと、コードの中で入力項目が見つけやすくなります。
    • 説明：ウィジェットを設定する人に表示される説明です（例：Which city's weather would you like to see?）。
    • タイプ：入力欄の種類です。入力項目のタイプを参照してください。
    • 必須：ウィジェットを追加する前に入力が必要かどうかです。新しく作った入力項目は、最初は必須になっています。
  4. ダイアログを閉じると、入力項目が保存されます。
「入力項目」ダイアログの「公開入力項目」タブ。入力項目の名前、説明、タイプ、オプション、必須かどうか、テスト用の値が並んでいる「入力項目」ダイアログの「公開入力項目」タブ。入力項目の名前、説明、タイプ、オプション、必須かどうか、テスト用の値が並んでいる

コードで読み取る​

入力項目はuseInputsで読み取ります。

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

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

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

入力項目は、それぞれに合った型で渡されます。テキストはstring、数値はnumber、複数選択は文字列の配列、といった具合です。空欄のままの入力項目はundefinedになります。ウィジェットスタジオは入力項目を把握しているので、名前を自動補完し、つづりの間違いも指摘してくれます。

プレビューで試す​

各入力項目にテスト用の値を設定すると、誰かが入力したときにウィジェットがどう見えるかを確認できます。テスト用の値はウィジェットスタジオを再読み込みするまでしか残らず、ほかの人には見えません。

入力項目にテスト用の値が入った状態のウィジェットのプレビュー。「Did you know?」と犬についての豆知識が表示されている入力項目にテスト用の値が入った状態のウィジェットのプレビュー。「Did you know?」と犬についての豆知識が表示されている

必須の入力項目に値がないと、プレビューにはウィジェットの代わりにInputs Required（入力項目が必要です）と表示され、足りない項目が一覧で示されます。必須の入力項目はウィジェットを追加する前に入力しなければならないので、フレームにこの表示が出ることはありません。

任意の入力項目​

任意の入力項目は、空欄のままだとundefinedになります。代わりの値を用意するか、代わりに役立つ案内を表示しましょう。

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

選択肢をわかりやすく書く​

選択の選択肢は選ぶ人が読んでわかるように書き、選ばれた値をコードの中で必要な形に変換します。たとえば、サッカーのAPIがリーグコードを求める場合は次のようにします。

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

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

こうすると、ウィジェットを設定する人にはCLではなくChampions Leagueと表示されます。

シークレットとアカウント​

  • 誰にも見せたくない自分のAPIキーには、非公開入力項目を使います。
  • 利用者それぞれに自分のAPIキーを入力してもらうには、機密タイプの入力項目を使います。入力した内容は伏せて表示されます。
  • GoogleやSpotifyなどのサービスにサインインしてもらうには、連携を使います。

あとから入力項目を変更する​

ウィジェットが使われ始めてから入力項目を変えると、利用者が設定した内容に影響することがあります。任意の入力項目を追加するのは問題ありません。しかし、入力項目を削除したり名前を変えたり、必須の入力項目を追加したりすると、次のリリースはメジャーバージョンになり、いつアップグレードするかは利用者が選ぶことになります。バージョン番号を参照してください。