下書きプレビュー

下書きプレビューは、保存済みの原稿を公開前に自分のサイトで確認する機能です。Next.js App Routerでは View にページの searchParams を渡します。プレビュー専用のページやRoute Handlerを追加する必要はありません。

一覧に下書きを混ぜる機能ではありません。リスト形式の単一記事とオブジェクト形式が対象です。未保存の編集内容は反映されないので、管理画面で保存してから開いてください。

1. SDKを導入する

クイックスタートのCLIで lib/schema.ts と lib/client.ts を生成します。APIキーはサイトのサーバー環境変数 GENKO_API_KEY に設定してください。

2. 普段の詳細ページでsearchParamsを渡す

import { client } from '@/lib/client';import { View, ViewItem, Error, Null } from '@genko-me/react/next';
type Props = {  params: Promise<{ id: string }>;  searchParams: Promise<Record<string, string | string[] | undefined>>;};
export default async function Page({ params, searchParams }: Props) {  const { id } = await params;  return <View api={client.blog} id={id} searchParams={searchParams}>    <h1><ViewItem id="title" /></h1>    <ViewItem id="body" />    <Error template />    <Null>記事が見つかりません。</Null>  </View>;}

オブジェクト形式は id を省略します。View はURLに draftKey がある場合だけ下書きを取得します。公開表示でキャッシュを指定していても、プレビューは毎回取得します。不正なキーを公開版への切り替えで隠すことはありません。

ページ側でメタデータや共有ボタンを用意している場合

Viewが扱うのは部品内の取得・表示です。ページ側のgenerateMetadataや共有ボタンは別に設定します。プレビューURLを共有リンクやcanonical URLへ流用しないでください。

メタデータを自作する場合は、searchParamsにdraftKeyがあるときに下書き本文やタイトルをOGPへ埋め込まず、プレビュー用のタイトルとrobots: { index: false, follow: false }、referrer: "no-referrer"を返す構成にできます。公開URLを組み立てる共有ボタンも、プレビュー中は非表示にする運用ができます。

3. 管理画面でURLを設定する

APIの「設定」（/w/your-workspace/apis/blog/settings）で、「プレビューURLテンプレート」を設定します。

https://your-site.example/blog/{id}?draftKey={key}

{id} と {key} は管理画面が置き換えます。すでにクエリがあるURLは &draftKey={key} を使ってください。ローカル確認ではホストを http://localhost:3000 などに置き換えます。

このURL設定を client.ts に重複して書く必要はありません。ポートや詳細ページのパスを変更した場合は管理画面の設定を更新してください。

4. 保存してプレビューを開く

管理画面で記事を保存し、「プレビュー」を押します。同じ詳細ページに保存済みの下書きが表示されます。SDKはプレビュー中の表示と終了ボタンを出し、ページに noindex, nofollow と no-referrer を設定します。

公開中の原稿で「下書きとして保存」した場合も、プレビューには保存済みの未公開の変更が表示されます。通常のサイト表示と配信APIには、公開中の内容が表示され続けます。まだ保存していない入力はプレビューに反映されません。

終了ボタンはURLの draftKey を取り除いて公開表示に戻ります。未公開の記事には公開版がないため、終了後は Null（notFound を指定した場合は404画面）になります。

表示は previewNotice={{ position: 'bottom', className: 'preview-bar' }} で調整できます。非表示にする場合は previewNotice={false} を指定します。親の unstyled に関係なく通知は標準デザインになります。通知の装飾を外す場合は previewNotice={{ unstyled: true }} を指定します。

表示されないとき

プレビューURLには下書きを読むキーが含まれるため、共有しないでください。公開後はプレビューキーを再生成してください。SDKを使わず取得する場合は、REST APIの X-Draft-Key ヘッダーを推奨します。

記事の「設定」でプレビューキーを再生成すると、以前のプレビューURLは無効になります。プレビューにも有効なAPIキーと対象APIへのアクセス範囲が必要です。参照先の記事は通常の公開条件に従うため、親記事をプレビューしても下書きの参照先は展開されません。

言語版をプレビューする

多言語のAPIでは、言語を選んで保存してからプレビューを開きます。API設定のURLテンプレートには{lang}も指定できます。

https://your-site.example/blog/{id}?lang={lang}&draftKey={key}

{lang}は選択中の言語、{key}はその言語版だけのプレビューキーに置き換わります。サイト側でlangを配信APIまたはSDKへ渡してください。たとえば英語版の下書きにはlang=en&draftKey=...を指定します。別の言語のキーやメイン言語のキーでは取得できません。言語版が未作成の場合は先に作成します。プレビュー中の参照先は、その言語で公開中の版だけが展開対象です。詳しい配信条件は多言語コンテンツを参照してください。