λ沢
はじめに
microCMS では拡張フィールド機能を提供しています。
これは microCMS に iframe の postMessage でデータを渡すサイトを用意して、そのサイトの URL を microCMS のフィールドに設定することで、任意のデータを microCMS に登録できる機能です。
現時点ではサードパーティのものも含めて、以下のような拡張フィールドが開発 & 公開されています。
- 地図フィールド (by @himara2 さん)
- テーブルを入力する (by @sinhala さん)
- Amazon PA API を用いた Amazon の商品と連携 (by @shibe97 さん)
- Shopify 連携 (by @Pentaprogram さん)
- Stripe 連携 (by @Pentaprogram さん)
- 郵便番号を用いた住所の入稿 (by @hanetsuki_dev さん)
このように様々なことが行えます。
JSON にシリアライズ可能なデータであれば、どんなものでも連携可能です。
今まではこれらを実現するために postMessage を用いたプロトコル を把握する必要がありました。
しかし本日公開した microcms-field-extension パッケージ (GitHub) を使うと、プロトコルの詳細を把握せずとも簡単に外部データ連携の仕組みを作ることができます。
この記事では microcms-field-extension の利用方法を紹介します。
環境構築
Next.js の環境構築
ブラウザですぐに開発して Vercel にデプロイできる CodeSandbox を用意しました。create-next-app で使えるテンプレートも用意されています。
$ npx create-next-app my-app --example https://github.com/microcmsio/microcms-field-extension/tree/main/examples/nextjs
$ cd my-app
$ export NEXT_PUBLIC_MICROCMS_ORIGIN='https://example.microcms.io'
$ yarn devReact の環境構築
Next.js を使わずに素の React を使うこともできます。
こちらもブラウザですぐに開発して Vercel にデプロイできる CodeSandbox を用意しました。create-react-app で使えるテンプレートリポジトリも用意されています。
$ npx create-react-app my-app --template microcms-field-extension-app
$ cd my-app
$ export REACT_APP_MICROCMS_ORIGIN='https://example.microcms.io'
$ npm startcreate-react-app を使わない場合は以下のコマンドでパッケージをインストールできます。
$ npm i microcms-field-extension-reactフレームワーク無しの環境構築
microcms-field-extension-api パッケージを使うことによって、 Vue.js など React 以外のフレームワークでも簡単にフィールドを拡張できます。
こちらもブラウザですぐに開発して Vercel にデプロイできる CodeSandbox を用意しました。
以下のコマンドでパッケージをインストールできます。
詳しい使用方法は README を参照してください。
$ npm i microcms-field-extension-api使用方法
Next.js を使う場合でも React を使う場合でもフレームワーク無しでも基本的な使い方は同じです。
最初に SetupOption を指定して、データを更新する際に Message を指定するだけです。SetupOption は以下のようなオブジェクトです。
{
/**
* この iframe はこのオリジンからのみメッセージを受け取ります。
* "*" を指定すると全てのオリジンからメッセージを受け取ることができますが、意図しないオリジンからメッセージが注入されるリスクがあるため "*" の指定は推奨しません。
* 必須。
*/
origin: "https://example.microcms.io",
/**
* microCMS 上で表示される iframe フィールドの高さ。数値 or 文字列。
* オプショナル。
*/
height: 200,
/**
* microCMS 上で表示される iframe フィールドの幅。数値 or 文字列。
* オプショナル。
*/
width: "100%",
/**
* iframe フィールドに保存済みの初期値を取得した際のコールバック。
* オプショナル。
*/
onDefaultData: (message) => console.log(message),
/**
* set の呼び出しが成功した際のコールバック。
* オプショナル。
*/
onPostSuccess: (message) => console.log(message),
/**
* set の呼び出しが失敗した際のコールバック
* オプショナル。
*/
onPostError: (message) => console.log(message),
}Message は以下のようなオブジェクトです。
{
id: "item_123456",
/**
* 管理画面で表示されるテキスト。
* オプショナル。
*/
title: "foo",
/**
* 管理画面で表示されるテキスト。
* オプショナル。
*/
description: "foo\nbar\n",
/**
* 管理画面で表示される画像のURL。
* オプショナル。
*/
imageUrl: "http://placehold.jp/150x150.png",
/**
* 管理画面で表示される更新日時。
* オプショナル。
*/
updatedAt: "2022-04-26T00:27:13.176Z",
/**
* JSON にシリアライズ可能な任意のオブジェクト。
* この値がコンテンツ API で返されます。
* 必須。
*/
message: {},
}
React (Next.js) を使う場合は以下のようなコードが動作します。
import { useFieldExtension } from "microcms-field-extension-react";
import { ChangeEvent } from "react";
// CHANGEME
const origin =
process.env.REACT_APP_MICROCMS_ORIGIN || "https://example.microcms.io";
export default function App() {
const { data, sendMessage } = useFieldExtension("#00ff00", { origin });
const onChangeColor = (e: ChangeEvent<HTMLInputElement>) => {
sendMessage({ id: "color", data: e.target.value });
};
return (
<input type="color" value={String(color)} onChange={onChangeColor} />
);
}
ここで color の型は any です。プロダクションでは例えば zod などでバリデーションをすることが望ましいです。
また、 useFieldExtension の第2引数には width, height, onPostSuccess, onPostError などのフィールドを指定することができます。
アプリケーションの要件に応じて拡張フィールドの高さを変えたり、 データをセットした後のコールバックで通信の成否をトーストでユーザに伝える仕組みを追加するとより親切です。
その他の仕様例を examples ディレクトリから探すこともできます。
おわりに
拡張フィールド機能はとてもパワフルで遊びがいのある仕組みですが、今までは敷居が高い仕組みでもありました。
今後は新たな連携を作るのがより簡単になり、 様々な連携が公開され、 microCMS はよりパワフルなプラットフォームになると思います。
ぜひこの SDK を使って素敵な連携を開発してみてもらえると嬉しいです。
