LESSON 11 · 約35分

フォーム・Endpoint・Actionsを理解する

入力の送信先を作り、検証と失敗の扱いを学びます。

コードを試す前に

10で用意したadapter付きの構成で実行します。通常フォーム＋endpointが基本演習、Actionsの呼び出しは部分的な発展例です。

各コードは独立した学習用の例で、すべてを順に一つのプロジェクトへ上書きする形式ではありません。同じレッスン内の対応ファイルは組み合わせます。依存関係・入力ファイル・実行条件は各noteに記載します。

開発環境の準備を確認する →

このレッスンでわかること

フォームのname・method・actionを説明できる
静的endpointとリクエスト時のPOSTを区別できる
Actionsが検証を助けても認可は別だと説明できる

フォームは入力と送信先の約束

labelで入力欄の意味を示し、nameで送信データのキーを決めます。method="post"とactionで、どこへどう送るかを指定します。requiredなどのブラウザー検証は操作を助けますが、直接リクエストを送る人もいるため、サーバーでも形式・長さ・権限を確認します。

EndpointはHTML以外の応答も返す

src/pages/api/feedback.jsのPOST関数は、オンデマンドでフォームを受けてResponseを返せます。一方、静的GET endpointはビルド時にJSONなどのファイルを作る用途にも使えます。静的ファイルの生成機能だけでは訪問者のPOSTを処理できません。

Actionsはサーバー関数への橋渡し

Astro ActionsではdefineActionのinputにZodの検証ルール、handlerにサーバー処理を書きます。actionsから呼び出した結果はdataまたはerrorとして扱います。JSON送信やフォーム入力の検証をまとめやすい仕組みですが、実行できるサーバーとadapterが必要です。HTMLフォームのaction経由で呼ぶ場合は、フォームのページ自体もオンデマンドにします。

成功表示と、本当に行ったことを一致させる

以下の例は入力を検証して応答を返すだけです。DB保存もメール送信も行いません。本番の更新処理では認証・対象データへの認可・重複送信・送信中・エラーを考えます。Actionsも公開endpointとして呼べるため、ボタンを隠すだけで権限を守れません。

ラベルと送信先を持つフォーム

src/pages/feedback.astro

<form method="post" action="/api/feedback">
  <label for="feedback-message">感想（200文字以内）</label>
  <textarea id="feedback-message" name="message" required maxlength="200"></textarea>
  <button type="submit">入力を確認する</button>
</form>

次のendpointと10のadapter設定が必要です。送信後は応答テキストへ移動する最小例です。Astro Actions経由ではなく、通常のHTTP POSTです。

POSTを検証してResponseを返す

src/pages/api/feedback.js

export const prerender = false;

export async function POST({ request }) {
  let form;
  try {
    form = await request.formData();
  } catch {
    return new Response('フォームとして読み取れませんでした。', { status: 400 });
  }
  const value = form.get('message');
  const message = typeof value === 'string' ? value.trim() : '';
  if (!message || message.length > 200) {
    return new Response('1〜200文字で入力してください。', { status: 400 });
  }
  return new Response('入力を確認しました。この練習では保存していません。', {
    status: 200,
    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
  });
}

Nodeなどのadapterとサーバー実行が必要です。認証不要の入力検証だけの練習で、保存・メール配信・個人データ収集は実装していません。

Actionをブラウザーから呼ぶ形

src/pages/action-example.astro のscript部分

<script>
  import { actions } from 'astro:actions';

  // サーバー側にgetGreetingが定義されている場合の呼び出し方
  async function showGreeting(name) {
    const { data, error } = await actions.getGreeting({ name });
    if (error) return '入力や通信を確認してください。';
    return data;
  }
</script>

APIを読むための部分例です。単体では動きません。別途サーバー側のgetGreeting Action定義、adapter、呼び出すUIが必要です。関数を定義しただけでは自動実行されません。

TRY IT YOURSELF

入力と応答を確かめる

まず通常フォーム＋endpointの二つを作る
有効な文章のPOSTと、空のPOSTを比べる
開発者ツールで応答の200・400を確認する
保存処理を追加するなら何を検証すべきか書き出す

できたらOK：入力検証成功と永続保存成功を分けて説明できる

QUICK CHECK

理解を確かめよう

公式資料でもう少し詳しく

ここまで読めたら、ひとつ前進。