nuxt-swiftsearch

使用方法

@atoms-studio/nuxt-swiftsearch を使用して Nuxt 3 アプリで Algolia 経由の検索 UI を構築する場合にこのスキルを使用します。

使用する場合

• Nuxt 3 アプリに Algolia を使った検索機能を追加する
• フィルター、ページネーション、無限スクロール機能を備えた検索ページを構築する
• SSR 互換の検索体験を実装する
• vue-instantsearch から Nuxt ネイティブなアプローチへ移行する

インストール

npx nuxi@latest module add swiftsearch

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@atoms-studio/nuxt-swiftsearch"],
});

コアパターン: デュアルレジストレーション

すべてのウィジェットには、composable（<script setup> 内）AND コンポーネント（<template> 内）の両方**が必要です。composable は InstantSearch インスタンスにウィジェットを登録し、コンポーネントがそれをレンダリングします。

<template>
  <AisInstantSearch :widgets :configuration>
    <AisSearchBox />
    <AisHits />
    <AisRefinementList attribute="brand" />
  </AisInstantSearch>
</template>

<script setup lang="ts">
import { algoliasearch } from "algoliasearch";

const client = algoliasearch("APP_ID", "API_KEY");

const widgets = computed(() => [
  useAisSearchBox({}),
  useAisHits({ escapeHTML: true }),
  useAisRefinementList({ attribute: "brand" }),
]);

const configuration = ref({
  indexName: "my_index",
  searchClient: client,
});
</script>

重要なルール

1. widgets は computed である必要があります — プレーンな配列ではなく。SSR ハイドレーション用にリアクティビティが必須です。
2. configuration は ref である必要があります — 設定オブジェクトを ref() でラップします。
3. 属性プロパティは一致する必要があります — AisRefinementList、AisMenu などを使用する場合、コンポーネントの attribute プロップは composable の attribute と一致する必要があります。
4. すべての composable とコンポーネントは自動インポートされます — useAis* composable または Ais* コンポーネント の手動インポートは不要です。

利用可能なコンポーネント & Composable

すべてのウィジェットの完全なプロップ、スロット、composable パラメーター、および例：widgets-reference.md

コンポーネント	Composable	用途
<AisInstantSearch>	—	ルートラッパー、:widgets と :configuration を受け取ります
<AisIndex>	useAisIndex()	マルチインデックススコープ
<AisSearchBox>	useAisSearchBox()	検索入力
<AisHits>	useAisHits()	ページネーション付き検索結果
<AisInfiniteHits>	useAisInfiniteHits()	無限スクロール結果
<AisRefinementList>	useAisRefinementList()	ファセットフィルタリング
<AisMenu>	useAisMenu()	単一選択ファセットメニュー
<AisMenuSelect>	—	ドロップダウンファセットメニュー
<AisHierarchicalMenu>	useAisHierarchicalMenu()	ネストされたカテゴリーナビゲーション
<AisNumericMenu>	useAisNumericMenu()	数値範囲フィルタリング
<AisRangeInput>	useAisRangeInput()	最小/最大範囲入力
<AisRatingMenu>	useAisRatingMenu()	スター評価フィルター
<AisToggleRefinement>	useAisToggleRefinement()	ブール値トグルフィルター
<AisClearRefinements>	useAisClearRefinements()	すべてのアクティブなフィルターをクリア
<AisCurrentRefinements>	useAisCurrentRefinements()	アクティブなフィルターを表示
<AisSortBy>	useAisSortBy()	並び替え順序セレクター
<AisStats>	useAisStats()	検索結果数とタイミング
<AisPagination>	useAisPagination()	ページナビゲーション
<AisConfigure>	useAisConfigure()	隠された検索パラメーター
<AisHighlight>	—	マッチしたテキストをハイライト
<AisAutocomplete>	useAisAutocomplete()	オートコンプリート候補
<AisPanel>	—	折りたたみ可能なパネルラッパー
<AisQueryRuleCustomData>	useAisQueryRuleCustomData()	クエリルールデータ
<AisStateResults>	—	汎用状態レンダラー

ウィジェットカテゴリー（クイックルックアップ）

検索入力: AisSearchBox、AisAutocomplete 検索結果: AisHits、AisInfiniteHits、AisStateResults リファインメント: AisRefinementList、AisMenu、AisMenuSelect、AisHierarchicalMenu、AisNumericMenu、AisRangeInput、AisRatingMenu、AisToggleRefinement アクティブなフィルター: AisClearRefinements、AisCurrentRefinements 並び替えとページネーション: AisSortBy、AisPagination 表示: AisStats、AisHighlight、AisPanel 設定: AisConfigure、AisQueryRuleCustomData 構造: AisInstantSearch、AisIndex

URL ルーティング

検索状態を URL と同期させるには：

1. クエリ文字列パースを設定します：

// app/router.options.ts
import type { RouterConfig } from "@nuxt/schema";
import qs from "qs";

export default <RouterConfig>{
  parseQuery: qs.parse,
  stringifyQuery: qs.stringify,
};

2. ルーターを設定に追加します：

<script setup lang="ts">
const algoliaRouter = useAisRouter();

const configuration = ref({
  indexName: "my_index",
  routing: algoliaRouter.value,
  searchClient: client,
});
</script>

スロットのカスタマイズ

すべてのコンポーネントは型付けされたレンダー状態を持つスロットを公開します：

<AisHits>
  <template #item="{ item }">
    <div>{{ item.name }}</div>
  </template>
</AisHits>

<AisInfiniteHits>
  <template #item="{ item }">
    <div>{{ item.title }}</div>
  </template>
  <template #loadMore="{ refineNext, isLastPage }">
    <button :disabled="isLastPage" @click="refineNext">さらに読み込む</button>
  </template>
</AisInfiniteHits>

キャッシング（無限ヒット）

ページナビゲーション全体でステートフルなキャッシングを行うには：

const cache = useAisStatefulCache();
const infiniteCache = useAisInfiniteHitsStatefulCache();

const widgets = computed(() => [useAisInfiniteHits({ cache: infiniteCache })]);

インスタンスへのアクセス

<script setup lang="ts">
const { getInstance } = useAisInstantSearch();
// 高度なユースケース用に生の InstantSearch インスタンスにアクセスします
</script>

マルチインデックス検索

<AisInstantSearch :widgets :configuration>
  <AisIndex index="products">
    <AisHits />
  </AisIndex>
  <AisIndex index="articles">
    <AisHits />
  </AisIndex>
</AisInstantSearch>

CSS クラス

コンポーネントは BEM 規約を使用します：ais-WidgetName-element--modifier。useSuit("WidgetName") を使用してプログラムでクラス名を生成します。

よくある間違い

• composable を widgets 配列に追加し忘れる（コンポーネントはレンダリングされますが機能しません）
• widgets に対してプレーンな配列を使用する代わりに computed() を使用しない
• コンポーネントプロップと composable パラメーターの attribute が一致しない
• composable を手動でインポートする（これらは自動インポートされます）

依存関係

• Nuxt >= 3.10
• algoliasearch v5+
• qs（ルーティングを使用する場合のみ）