amp-form

<script async custom-element="amp-form" src="https://cdn.ampproject.org/v0/amp-form-0.1.js"></script>

動作

amp-form 拡張機能を使用すると、AMP ドキュメントの入力フィールドを送信するためのフォーム（<form>）を作成できます。また、amp-form 拡張機能には、ブラウザに実装されていない動作を補うためのポリフィルが用意されています。

<form> を作成する前に、<amp-form> 拡張機能に必要なスクリプトを追加する必要があります。そうしないと、ドキュメントが無効になります。値を送信する以外の目的で input タグを使用する場合（<form> の外部での入力など）、amp-form 拡張機能を読み込む必要はありません。

以下に、基本的なフォームの例を示します。

<form method="post"
    action-xhr="https://example.com/subscribe"  
    target="_top">
    <fieldset>
      <label>
        <span>Name:</span>
        <input type="text"
          name="name"
          required>
      </label>
      <br>
      <label>
        <span>Email:</span>
        <input type="email"
          name="email"
          required>
      </label>
      <br>
      <input type="submit"
        value="Subscribe">
    </fieldset>
    <div submit-success>
      <template type="amp-mustache">
        Subscription successful!
      </template>
    </div>
    <div submit-error>
      <template type="amp-mustache">
        Subscription failed!
      </template>
    </div>
  </form>

属性

target

フォームの送信後にフォームの回答を表示する場所を指定します。値には _blank または _top を指定する必要があります。

action

フォームの入力を処理するサーバー エンドポイントを指定します。値には https URL（絶対または相対）を指定する必要があります。CDN へのリンクは指定できません。

• method=GET の場合: この属性または action-xhr を使用します。
• method=POST の場合: action-xhr 属性を使用します。

action-xhr

フォームの入力を処理し、XMLHttpRequest（XHR）でフォームを送信するサーバー エンドポイントを指定します。XHR リクエスト（AJAX リクエストと呼ばれることもあります）では、ブラウザでページを完全に読み込んだり新しいページを開いたりしなくてもリクエストを作成できます。ブラウザは、Fetch API を使用（可能な場合）してバックグラウンドでリクエストを送信します。また、古いブラウザの場合は、代わりに XMLHttpRequest API を使用します。

この属性は、method=POST の場合は必須、method=GET の場合はオプションです。

action-xhr の値には、action と同じまたは別のエンドポイントを指定できます。また、上記と同様の action に関する要件があります。

フォームの送信に成功した後にユーザーをリダイレクトする方法については、以下の送信後のリダイレクトをご覧ください。

その他のフォーム属性

その他のフォーム属性はすべてオプションです。

custom-validation-reporting

これは、カスタム検証レポート戦略を有効にして選択するためのオプションの属性です。show-first-on-submit、show-all-on-submit、as-you-go のいずれかを指定できます。

詳しくは、カスタム検証をご覧ください。

入力とフィールド

使用可:

• フォーム関連のその他の要素: <textarea>、<select>、<option>、<fieldset>、<label>、<input type=text>、<input type=submit> など
• <input type=password>、<input type=file>（<form method=POST action-xhr> 内）
• amp-selector

使用不可:

• <input type=button>、<input type=image>
• 入力のフォーム関連の属性の大部分: form、formaction、formtarget、formmethod など

（今後、これらのルールの緩和が再検討される可能性があります。これらの属性が必要な場合はお知らせください。また、ユースケースをご提示ください）

有効な入力とフィールドについて詳しくは、AMP 検証ツールの仕様で amp-form のルールをご覧ください。

アクション

amp-form 要素では以下のアクションを使用できます。

イベント

amp-form では以下のイベントを使用できます。

これらのイベントは on 属性を介して使用できます。

以下の例では、submit-success と submit-error の両方のイベントをリッスンし、イベントに応じて各種のライトボックスを表示します。

<form ...="" on="submit-success:success-lightbox;submit-error:error-lightbox">
</form>

この例のコード全体をご覧ください。

入力イベント

AMP では、子の <input> 要素で change イベントと input-debounced イベントを使用できます。このため、on 属性を使用して、入力値が変更されたときに任意の要素のアクションを実行できます。

一般的な使用例として、入力の変更時にフォームを送信することができます（ラジオボタンを選択してアンケートに回答する、select 入力から言語を選択してページを翻訳するなど）。

<form id="myform"
    method="post"
    action-xhr="https://example.com/myform"  
    target="_blank">
    <fieldset>
      <label>
        <input name="answer1"
          value="Value 1"
          type="radio"
          on="change:myform.submit">Value 1
      </label>
      <label>
        <input name="answer1"
          value="Value 2"
          type="radio"
          on="change:myform.submit">Value 2
      </label>
    </fieldset>
  </form>

この例のコード全体をご覧ください。

アナリティクス トリガー

amp-form 拡張機能は、amp-analytics の設定でトラッキング可能な以下のイベントをトリガーします。

次の例のように、これらのイベントを送信するようにアナリティクスを設定できます。

<amp-analytics>
  <script type="application/json">
    {
      "requests": {
        "event": "https://www.example.com/analytics/event?eid=${eventId}",
        "searchEvent": "https://www.example.com/analytics/search?formId=${formId}&query=${formFields[query]}"
      },
      "triggers": {
        "formSubmit": {
          "on": "amp-form-submit",
          "request": "searchEvent"
        },
        "formSubmitSuccess": {
          "on": "amp-form-submit-success",
          "request": "event",
          "vars": {
            "eventId": "form-submit-success"
          }
        },
        "formSubmitError": {
          "on": "amp-form-submit-error",
          "request": "event",
          "vars": {
            "eventId": "form-submit-error"
          }
        }
      }
    }
  </script>
</amp-analytics>

これらの 3 つのイベントでは、特定のフォームおよびフォーム内のフィールドに対応する一連の変数が生成されます。これらの変数はアナリティクスに使用できます。

たとえば、次のフォームには 1 つのフィールドがあります。

<form id="submit_form" action-xhr="/comment" method="POST">
  <input type="text" name="comment">
    <input type="submit" value="説明">
    </form>

amp-form-submit、amp-form-submit-success、amp-form-submit-error のいずれかのイベントが発生すると、フォームで指定された値を含む以下の変数が生成されます。

• formId
• formFields[comment]

成功 / エラー レスポンスのレンダリング

amp-mustache などの拡張テンプレートを使用することで、成功またはエラー レスポンスをフォームにレンダリングできます。また、amp-bind によるデータ バインディングと以下のレスポンス属性を使用して成功レスポンスをレンダリングすることもできます。

テンプレートを使用したレスポンスのレンダリング方法:

• <form> 要素の直接の子にレスポンス属性を適用します。
• 子要素の内部で <template></template> タグまたは <script type="text/plain"></script> タグを使用してテンプレートを含めるか、template="id_of_other_template" 属性でテンプレートを参照することにより、子要素でレスポンスをレンダリングします。
• レスポンスの有効な JSON オブジェクトを submit-success と submit-error に指定します。成功とエラーのどちらのレスポンスにも Content-Type: application/json ヘッダーを含める必要があります。

例: フォームに成功、エラー、送信中のメッセージを表示する

次の例では、フォーム内のインライン テンプレートにレスポンスがレンダリングされます。

<form ...="">
  <fieldset>
    <input type="text" name="firstName">
      ...
    </fieldset>
    <div verify-error="">
      <template type="amp-mustache">
        There is a mistake in the form!
        {{#verifyErrors}}{{message}}{{/verifyErrors}}
    </template>
  </div>
  <div submitting="">
    <template type="amp-mustache">
      Form submitting... Thank you for waiting {{name}}.
    </template>
  </div>
  <div submit-success="">
    <template type="amp-mustache">
      Success! Thanks {{name}} for subscribing! Please make sure to check your email {{email}}
    to confirm! After that we'll start sending you weekly articles on {{#interests}}<b>{{name}}</b> {{/interests}}.
  </template>
</div>
<div submit-error="">
  <template type="amp-mustache">
    Oops! {{name}}, {{message}}.
  </template>
</div>
</form>

サイト運営者の action-xhr エンドポイントから以下の JSON レスポンスが返されます。

成功:

{
  "name": "Jane Miller",
  "interests": [{"name": "Basketball"}, {"name": "Swimming"}, {"name": "Reading"}],
  "email": "email@example.com"
}

エラー:

{
  "name": "Jane Miller",
  "message": "The email (email@example.com) you used is already subscribed."
}

submit-success 属性と submit-error 属性が指定された要素に設定されたテンプレートの ID を template 属性の値として使用することで、ドキュメント内で以前に定義した参照テンプレートにレスポンスをレンダリングできます。

<template id="submit_success_template" type="amp-mustache">
  Success! Thanks {{name}} for subscribing! Please make sure to check your email {{email}}
to confirm! After that we'll start sending you weekly articles on {{#interests}}<b>{{name}}</b> {{/interests}}.
</template>
<template id="submit_error_template" type="amp-mustache">
  Oops! {{name}}, {{message}}.
</template></p>

<form ...="">
  <fieldset>
    ...
  </fieldset>
  <div submit-success="" template="submit_success_template"></div>
  <div submit-error="" template="submit_error_template"></div>
</form>

この例のコード全体をご覧ください。

データ バインディングを使用して成功レスポンスをレンダリングするには

• on 属性を使用して、フォームの submit-success** 属性を AMP.setState() にバインドします。
• event プロパティを使用して、レスポンス データを収集します。
• 状態の属性を目的の要素に追加して、フォーム レスポンスをバインドします。

以下に、amp-bind を使用してフォームの submit-success レスポンスをレンダリングする例を示します。

<p [text]="'Thanks, ' + subscribe +'! You have successfully subscribed.'">Subscribe to our newsletter</p>
<form method="post"
      action-xhr="/components/amp-form/submit-form-input-text-xhr"
      target="_ top"
      on="submit-success: AMP.setState({'subscribe': event.response.name})">
  <div>
    <input type="text"
        name="name"
        placeholder="Name..."
        required>
    <input type="email"
      name="email"
      placeholder="Email..."
      required>
  </div>
  <input type="submit" value="Subscribe">
</form>

フォームの送信が成功すると、次のような JSON レスポンスが返されます。

{
  "name": "Jane Miller",
  "email": "email@example.com"
}

その後、amp-bind により、<p> 要素のテキストが subscibe の状態と一致するように更新されます。

...
<p [text]="'Thanks, ' + subscribe +'! You have successfully subscribed.'">Thanks Jane Miller! You have successfully subscribed.</p>
...

送信後のリダイレクト

AMP-Redirect-To レスポンス ヘッダーを設定し、リダイレクト URL を指定することにより、フォームの送信が成功した後にユーザーを新しいページにリダイレクトできます。リダイレクト URL には HTTPS URL を指定する必要があります。そうしないと、AMP によってエラーがスローされ、リダイレクトが行われなくなります。HTTP レスポンス ヘッダーはサーバーで設定されます。

Access-Control-Expose-Headers レスポンス ヘッダーを更新し、許可されるヘッダーのリストに AMP-Redirect-To を追加してください。これらのヘッダーについて詳しくは、AMP の CORS セキュリティをご覧ください。

レスポンス ヘッダーの例:

AMP-Redirect-To: https://example.com/forms/thank-you
Access-Control-Expose-Headers: AMP-Access-Control-Allow-Source-Origin, AMP-Redirect-To

カスタム検証

amp-form 拡張機能では、custom-validation-reporting 属性をレポート戦略（show-first-on-submit、show-all-on-submit、as-you-go のいずれか）と組み合わせて使用することで、独自のカスタム検証 UI を作成できます。

フォームでカスタム検証を指定する方法は次のとおりです。

1. form の custom-validation-reporting 属性を検証レポート戦略のいずれかに設定します。
2. 特別な属性でマークアップされた独自の検証 UI を指定します。AMP は特別な属性を検出すると、指定したレポート戦略に応じて適切なタイミングでその属性をレポートします。

以下に例を示します。

<form method="post"
    action-xhr="https://example.com/subscribe"
    custom-validation-reporting="show-all-on-submit"  
    target="_blank">
    <fieldset>
      <label>
        <span>Name:</span>
        <input type="text"
          name="name"
          id="name5"
          required
          pattern="\w+\s\w+">
        <span visible-when-invalid="valueMissing"
          validation-for="name5"></span>
        <span visible-when-invalid="patternMismatch"
          validation-for="name5">
          Please enter your first and last name separated by a space (e.g. Jane Miller)
        </span>
      </label>
      <br>
      <label>
        <span>Email:</span>
        <input type="email"
          name="email"
          id="email5"
          required>
        <span visible-when-invalid="valueMissing"
          validation-for="email5"></span>
        <span visible-when-invalid="typeMismatch"
          validation-for="email5"></span>
      </label>
      <br>
      <input type="submit"
        value="Subscribe">
    </fieldset>
  </form>

その他の例については、examples/forms.amp.html をご覧ください。

検証メッセージに関しては、要素にテキスト コンテンツが含まれていない場合、ブラウザのデフォルトの検証メッセージが AMP によって入力されます。上の例では、name5 の入力が空の状態で検証が開始されたとき（ユーザーがフォームを送信しようとしたとき）に、AMP によってブラウザの検証メッセージが <span visible-when-invalid="valueMissing" validation-for="name5"></span> に指定され、この span がユーザーに表示されます。

レポート戦略

custom-validation-reporting 属性の以下のレポート オプションのいずれかを指定します。

show-first-on-submit

show-first-on-submit レポート オプションは、デフォルトの検証が開始されたときのブラウザのデフォルトの動作によく似ています。検出された最初の検証エラーが表示され、そこで停止します。

show-all-on-submit

show-all-on-submit レポート オプションでは、フォームの送信時にすべての無効な入力に対する検証エラーがすべて表示されます。このオプションは、検証の概要を表示する場合に便利です。

as-you-go

as-you-go レポート オプションを使用すると、入力の操作中に検証メッセージを確認できます。たとえば、ユーザーが無効なメールアドレスを入力すると、エラーがすぐに表示されます。値を修正すると、エラーが表示されなくなります。

interact-and-submit

interact-and-submit レポート オプションは、show-all-on-submit と as-you-go の動作を組み合わせたものです。操作後に個々のフィールドにエラーが即座に表示され、フォームの送信時にすべての無効なフィールドに関するエラーが表示されます。

検証

HTML5 の検証で提供されるフィードバックは、ページで利用できる情報のみに基づくものです（値が特定のパターンと一致するかどうかなど）。amp-form 検証では、HTML5 の検証だけでは得られないユーザー フィードバックを得ることができます。たとえば、フォームで検証を使用すると、メールアドレスが登録済みかどうか、市区町村名フィールドと郵便番号フィールドが対応しているかどうかなどを確認できます。

以下に例を示します。

<h4>検証の例</h4>
<form method="post" action-xhr="/form/verify-json/post" verify-xhr="/form/verify-json/post"{% if not format=='email'%}   target="_blank"{% endif %}>
  <fieldset>
    <label>
      <span>Email</span>
      <input type="text" name="email" required="">
      </label>
      <label>
        <span>Zip Code</span>
        <input type="tel" name="zip" required="" pattern="[0-9]{5}(-[0-9]{4})?">
        </label>
        <label>
          <span>City</span>
          <input type="text" name="city" required="">
          </label>
          <label>
            <span>Document</span>
            <input type="file" name="document" no-verify="">
            </label>
            <div class="spinner"></div>
            <input type="submit" value="送信">
            </fieldset>
            <div submit-success="">
              <template type="amp-mustache">
                <p>Congratulations! You are registered with {{email}}</p>
              </template>
            </div>
            <div submit-error="">
              <template type="amp-mustache">
                {{#verifyErrors}}
              <p>{{message}}</p>
              {{/verifyErrors}}
            {{^verifyErrors}}
          <p>Something went wrong. Try again later?</p>
          {{/verifyErrors}}
      </template>
    </div>
  </form>

フォームは、リクエストが検証リクエストであり、正式な送信ではないことをサーバーに伝えるために、フォームデータの一部として __amp_form_verify フィールドを送信します。これにより、検証と送信用に同じエンドポイントが使用されている場合には検証リクエストが保存されないことをサーバーが認識できます。

以下に、検証のエラー レスポンスの例を示します。

  {
    "verifyErrors": [
      {"name": "email", "message": "That email is already taken."},
    {"name": "zip", "message": "The city and zip do not match."}
  ]
}

verify-xhr リクエストからフィールドを削除するには、no-verify 属性を入力要素に追加します。

その他の例については、examples/forms.amp.html をご覧ください。

変数の置換

amp-form 拡張機能では、非表示の入力と data-amp-replace 属性が指定されている入力に対して、プラットフォーム変数の置換を行うことができます。各フォームの送信時に、amp-form がフォーム内の input[type=hidden][data-amp-replace] をすべて検出し、その value 属性に対して変数置換を適用して、置換の結果で値を置き換えます。

使用する変数のスペース区切りの文字列を data-amp-replace で指定することにより、各入力の置換に使用する変数を指定する必要があります（以下の例を参照）。AMP は、明示的に指定されていない変数の置換を行いません。

以下に、置換の前後の入力の例を示します（アナリティクスではなく変数置換のプラットフォーム構文を使用する必要があることに注意してください）。

<!-- Initial Load -->
<form ...>
  <input name="canonicalUrl" type="hidden"
        value="The canonical URL is: CANONICAL_URL - RANDOM - CANONICAL_HOSTNAME"
        data-amp-replace="CANONICAL_URL RANDOM">
  <input name="clientId" type="hidden"
        value="CLIENT_ID(myid)"
        data-amp-replace="CLIENT_ID">
  ...
</form>

ユーザーがフォームを送信しようとすると、AMP が変数の解決を試み、すべてのフィールドの value 属性を適切に置換して更新します。XHR の送信ではたいてい、すべての変数の置換と解決が行われます。ただし、XHR 以外の GET 送信では、非同期で解決する必要がある値は、あらかじめ解決されていないことが原因で利用できない可能性があります。たとえば CLIENT_ID は、あらかじめ解決およびキャッシュされていない場合は解決されません。

<!-- User submits the form, variables values are resolved into fields' value -->
<form ...>
  <input name="canonicalUrl" type="hidden"
        value="The canonical URL is: https://example.com/hello - 0.242513759125 - CANONICAL_HOSTNAME"
        data-amp-replace="CANONICAL_URL RANDOM">
  <input name="clientId" type="hidden"
        value="amp:asqar893yfaiufhbas9g879ab9cha0cja0sga87scgas9ocnas0ch"
        data-amp-replace="CLIENT_ID">
    ...
</form>

上の CANONICAL_HOSTNAME は、最初のフィールドの data-amp-replace 属性でホワイトリストに登録されていないため、置換されていません。

その後は送信のたびに置換が行われます。詳しくは、AMP での変数の置換をご覧ください。

ポリフィル

amp-form 拡張機能には、一部のブラウザに実装されていない動作や機能、または次のバージョンの CSS で実装される動作や機能を補うためのポリフィルが用意されています。

無効な送信のブロックと検証メッセージのバブル

現在（2016 年 8 月）、WebKit ベースのエンジンを使用しているブラウザは、無効なフォームの送信をサポートしていません。これには、すべてのプラットフォームの Safari と、すべての iOS ブラウザが含まれます。amp-form 拡張機能は、無効な送信をすべてブロックする動作をサポートしており、無効な入力に対して検証メッセージのバブルを表示します。

ユーザー操作の疑似クラス

:user-invalid および :user-valid 疑似クラスは、将来の CSS セレクタ 4 の仕様に含まれています。フックを改良し、フィールドが有効か無効かに関係なく、いくつかの条件に基づいてそのスタイルを設定できるようにするために導入されたものです。

:invalid と :user-invalid の主な違いの 1 つは、要素に適用されるタイミングです。:user-invalid クラスは、ユーザーがフィールドに対して重要な操作を行った後に適用されます（フィールドへの入力、フィールドのぼかしなど）。

amp-form 拡張機能には、これらの疑似クラスのポリフィルを提供するクラスが用意されています。amp-form 拡張機能は、これらのクラスを祖先の fieldset 要素や form にも伝播します。

<textarea> の検証

正規表現マッチングは、<textarea> を除くほとんどの入力要素でネイティブにサポートされている一般的な検証機能です。この機能にはポリフィルが用意されており、<textarea> 要素に pattern 属性を指定できます。

amp-form では、<textarea> 要素に autoexpand 属性を指定できます。この属性を使用すると、テキスト領域を拡大および縮小させることができ、ユーザーがフィールドの最大サイズまで入力できるようになります。ユーザーがフィールドのサイズを手動で変更すると、autoexpand が動作しなくなります。

<textarea autoexpand></textarea>

スタイル設定

クラスと CSS フック

amp-form 拡張機能には、サイト運営者がフォームと入力のスタイルを設定するためのクラスと CSS フックが用意されています。

以下のクラスを使用すると、フォームの送信状態を指定できます。

• .amp-form-initial
• .amp-form-verify
• .amp-form-verify-error
• .amp-form-submitting
• .amp-form-submit-success
• .amp-form-submit-error

以下のクラスは、ユーザー操作の疑似クラス用のポリフィルです。

• .user-valid
• .user-invalid

サイト運営者はこれらのクラスを使用して入力とフィールドセットのスタイルを設定し、ユーザー アクションに対応することができます（ユーザーが無効な入力をぼかした後に赤枠で強調するなど）。

これらのクラスの使用例をご覧ください。

セキュリティ上の考慮事項

XSRF に対する保護

AMP CORS 仕様を遵守するだけでなく、状態の変化に関するリクエストの処理#processing-state-changing-requests)のセクションに特に注意して、XSRF 攻撃から保護してください。この攻撃では、攻撃者が現在のユーザー セッションを利用して、ユーザーが気付かないうちに不正なコマンドを実行できます。

一般に、ユーザーからの入力を受け付ける場合は以下の点に注意してください。

• 状態の変化に関するリクエストには POST のみを使用します。
• XHR 以外の GET リクエストは、ナビゲーション（検索など）用にのみ使用します。
  • XHR 以外の GET リクエストは正確なオリジンやヘッダーを受け取らないため、バックエンドは上記のメカニズムでは XSRF から保護することができません。
  • 一般に、XHR GET リクエストまたは XHR 以外の GET リクエストは、ナビゲーションまたは情報取得用にのみ使用します。
• XHR 以外の POST リクエストは、AMP ドキュメントでは使用できません。これは、このリクエストでの Origin ヘッダーの設定方法がブラウザ間で統一されていないためです。また、XSRF からの保護では、このヘッダーのサポートに関する問題が生じます。このヘッダーは見直しが行われ、導入が遅れる可能性があります。このヘッダーが必要だとお考えの場合は、問題を報告してください。