はじめに

みなさんはRaycast利用していますか?ランチャーとしてアプリケーションを即座に開けることはもちろんですが、Raycast上のコマンドからアプリケーションの操作を実行できることも魅力だと思います。

そんなRaycastのExtensionをReactで開発できると知り、勤怠打刻用のExtensionを作成してみました。

弊社では勤怠打刻のツールにHRMOS勤怠を利用しているため、HRMOS勤怠のAPIを利用します。

開発したコマンド

打刻履歴コマンド

打刻履歴コマンドでは、直近の打刻履歴をAPIから取得し、Listを使って表示させています。日付の部分はList.Sectionというコンポーネントを利用しています。

打刻コマンド

打刻コマンドでは、プルダウンから「出勤」、「退勤」、「休憩開始」、「休憩終了」を選択し、cmd + Enterを入力することで該当した打刻を行うことができます。

Extensionの開発におけるポイント

package.jsonについて

作成したExtensionのメタ情報はpackage.jsonで管理します。参考

commands

commandsというプロパティでは、作成したそれぞれのコマンドに関する情報を管理します。その中のnameプロパティはファイル名と一致させる必要があります。例えば、nameプロパティをstampにした場合は、stamp.tsxやstamp.jsxというファイルをsrc配下に置く必要があります。フォルダ構成に関してはこちらに記載されています。コマンドのtitleなどをcreate extensionで作成した後にファイル名やnameを一致させないとエラーになりますので、注意してください。

"commands": [
    {
      "name": "stamp",
      "title": "stamp",
      "description": "HRMOSの打刻をします。",
      "mode": "view"
    },
    {
      "name": "stamp_logs",
      "title": "stamp logs",
      "description": "打刻の履歴を確認することができます。",
      "mode": "view"
    }
],

preferences

package.json内のpreferencesプロパティではAPIキーのような環境に依存した情報を管理することができます。requiredプロパティをtrue
にすれば、指定のpreferenceがない場合にユーザーに対して画像のような画面から情報の入力をさせることができます。

"preferences": [
    {
      "name": "apiKey",
      "description": "HRMOSのAPI keyを入力してください。https://ieyasu.co/docs/api.html?_ga=2.219204185.1903119651.1667613637-717436112.1661213988#section/APIURL",
      "type": "password",
      "required": true,
      "title": "HRMOS API key",
      "placeholder": "HRMOSのAPI key"
    }
]

ちなみに、preferenceを再入力したい場合にはRaycastを起動し、検索バーからExtensionsを検索して、作成しているExtensionのところから削除することができます。

useFetch

Raycastが提供するHooksにuseFetchが存在します。useFetchはswrと似たような書き方で、リソースをfetchしたり状態の管理を行うことができます。下記のコードは1つ目のuseFetchでauthenticationTokenを取得しています。2つ目のuseFetchのようにexecuteプロパティがtrueになったタイミングで発火させるようなことも可能です。他にもonDataやonErrorのようなプロパティもあるので是非公式のドキュメントをご覧になってください。

  const { data: authenticationToken } = useFetch<AuthenticationToken>(
    API_ENDPOINT + "authentication/token",
    {
      headers: {
        Authorization: `Basic ${apiKey}`,
      },
    }
  );

  const { data: stamps } = useFetch<Array<StampItemProps>>(
    `${API_ENDPOINT}stamp_logs/user/${USER_ID}?limit=${STAMPS_LIMIT}`,
    {
      headers: {
        Authorization: `Token ${authenticationToken?.token}`,
      },
      execute: !!authenticationToken,
    }
  );

Toast

APIとの通信が成功した時や例外処理が発生した時に、ユーザーへその内容を伝えたいときは、Toastが使えます。

if (response.status === 200) {
  await showToast({ title: "打刻に成功しました" });
} else {
  await showToast({
    style: Toast.Style.Failure,
    title: "打刻に失敗しました",
    message: data.message,
  });
}

最後に

RaycastのExtensionの開発では、Reactで得た知識を活かすことができました。今後も、何か作成したいExtensionがあれば開発していきたいと思います！