UI スニペット

Cloudflare AI Search UI snippet library ↗ を使うと、本番向けでカスタマイズ可能な Web コンポーネントで、Web サイトへ AI Search を簡単に追加できます。

ライブラリは github.com/cloudflare/ai-search-snippet ↗ でオープンソース公開されています。

利用できるコンポーネント

スニペットライブラリは 4 つの Web コンポーネントを提供します。各コンポーネントは api-url 属性で AI Search インスタンスに接続します。値には公開エンドポイント URL を指定します。

コンポーネント	説明
`<search-bar-snippet>`	インラインの検索バー。結果をドロップダウンで表示します
`<search-modal-snippet>`	`Cmd/Ctrl+K` のキーボードショートカットで開く検索モーダル
`<chat-bubble-snippet>`	ページ隅に表示するフローティングのチャットバブル
`<chat-page-snippet>`	会話履歴付きのフルページチャットインターフェース

高度なスタイルと設定は search.ai.cloudflare.com ↗ を参照してください。

前提条件

UI スニペットは、公開エンドポイント経由で AI Search インスタンスに接続します。スニペットを使う前に、このエンドポイントを有効にしてください。

Cloudflare ダッシュボードで、AI Search ページを開きます。
AI Search を開く ↗
AI Search インスタンスを選択します。
Settings > Public Endpoint を開きます。
Enable Public Endpoint をオンにします。
公開エンドポイント URL をコピーします。スニペットの api-url 属性に使います。

HTML で使う

HTML ファイル（例: index.html）に script タグを追加します。<PUBLIC_ENDPOINT_ID> は、AI Search インスタンスの Settings > Public Endpoint で確認できる公開エンドポイント ID に置き換えます。
```
<script
	type="module"
	src="https://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com/assets/v0.0.25/search-snippet.es.js"
></script>
```

api-url を付けてコンポーネントを追加します。

<search-bar-snippet
	api-url="https://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com/"
	placeholder="Search..."
></search-bar-snippet>

テストする前に、ローカルオリジンを許可する CORS を設定します。その後、HTML ファイルをブラウザーで開いて確認します。

完全な HTML の例

次の例は、検索バー付きの完全な HTML ページです。利用者が検索バーに入力すると、下のドロップダウンに結果が表示されます。

<!doctype html>
<html>
	<head>
		<script
			type="module"
			src="https://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com/assets/v0.0.25/search-snippet.es.js"
		></script>
	</head>
	<body>
		<search-bar-snippet
			api-url="https://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com/"
			placeholder="Search..."
			max-results="10"
		></search-bar-snippet>
	</body>
</html>

フレームワークで使う

React プロジェクトを開き、パッケージをインストールします。
```
npm install @cloudflare/ai-search-snippet
```
コンポーネントファイル（例: src/App.tsx）でパッケージをインポートします。
```
import "@cloudflare/ai-search-snippet";
```

JSX にコンポーネントを追加します。

export default function App() {
	return (
		<search-bar-snippet
			api-url="https://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com/"
			placeholder="Search..."
		/>
	);
}

テストする前に、ローカルオリジンを許可する CORS を設定します。その後、開発サーバーを起動します。
```
npm run dev
```

このパッケージには TypeScript の型が含まれ、React、Next.js、そのほかの React フレームワークで使えます。

Vue プロジェクトを開き、パッケージをインストールします。
```
npm install @cloudflare/ai-search-snippet
```

コンポーネントファイル（例: src/App.vue）でパッケージをインポートし、コンポーネントを追加します。

<template>
	<search-bar-snippet :api-url="apiUrl" placeholder="Search..." />
</template>

<script setup>
import "@cloudflare/ai-search-snippet";

const apiUrl = "https://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com/";
</script>

テストする前に、ローカルオリジンを許可する CORS を設定します。その後、開発サーバーを起動します。
```
npm run dev
```

コンポーネントを設定する

各コンポーネントは、動作を制御する属性を受け取ります。よく使う属性は次のとおりです。

属性	説明
`api-url`	必須。インスタンスの公開エンドポイント URL です。
`placeholder`	入力欄のプレースホルダーテキストです。
`max-results`	リクエストする結果の最大件数です。
`theme`	`light`、`dark`、またはシステムのテーマに従う `auto`（デフォルト）です。
`hide-branding`	Cloudflare のブランディングを非表示にします。
`translations`	利用者向け文字列を上書きし、コンポーネントをローカライズします。

チャットコンポーネント（<chat-bubble-snippet> と <chat-page-snippet>）は、フォローアップメッセージを独立したクエリへ書き換える chat-query-rewrite も受け取れます。

属性の完全な一覧と、HTML、React、Vue のコードを生成するライブエディターは、スニペットプレイグラウンド ↗ を使ってください。

見た目をカスタマイズする

コンポーネントは、すべて --search-snippet- で始まる CSS カスタムプロパティでスタイルできます。コンポーネント自身か、親要素に設定します。

search-bar-snippet {
	--search-snippet-primary-color: #f6821f;
	--search-snippet-border-radius: 12px;
}

プレイグラウンド ↗ には、使える変数の一覧と、変更のライブプレビューがあります。

ローカルテスト用に CORS を設定する

ローカル（例: http://localhost:3000）でテストするときは、公開エンドポイントの設定でローカルオリジンを許可する必要があります。

Cloudflare ダッシュボードで、AI Search ページを開きます。
AI Search を開く ↗
AI Search インスタンスを選択します。
Settings > Public Endpoint を開きます。
Authorized hosts に、ローカル URL（例: http://localhost:3000）を追加するか、テスト中はすべてのオリジンを許可する * を追加します。
Save を選択します。

デプロイするときは、* を本番オリジンに置き換え、ほかのサイトが検索コンポーネントを埋め込めないようにします。許可オリジンはブラウザー向けの制御であり、アクセス制御ではありません。そのため、curl やスクリプトからの直接リクエストは止まりません。エンドポイントをクエリできる相手を制限するには、Cloudflare Access を参照してください。