Kirim formulir HTML tanpa reload halaman

Dengarkan event submit formulir, panggil preventDefault(), dan kirim new FormData(form) dengan fetch dan header Accept: application/json. Ikiform lalu menjawab dengan JSON alih-alih redirect: 201 saat sukses, atau error field yang Anda tampilkan di samping setiap input. Pertahankan action dan method sungguhan di formulir agar tetap terkirim dengan cara biasa jika script Anda tidak pernah berjalan.

Contoh di sini adalah kotak Was this page helpful? di bagian bawah halaman dokumentasi. Ini kasus klasik untuk tetap di halaman: pembaca sedang di tengah tugas, dan mengirimnya ke halaman terima kasih hanya untuk mencatat satu klik akan konyol. Pola yang sama bekerja untuk formulir apa pun.

Apa yang berubah saat Anda mengambil alih submit

Form post biasa memberi Anda banyak hal secara gratis: browser menampilkan indikator loading, membuat klik ganda tidak terlalu berpengaruh, menangani tombol back, dan menampilkan halaman apa pun yang kembali. Begitu Anda memanggil preventDefault(), semua itu menjadi tugas Anda. Panggilan fetch-nya sendiri hanya tiga baris; sisa halaman ini adalah pekerjaan yang dulu dilakukan browser.

Formulirnya

Tiga field: ya atau tidak yang wajib, komentar opsional, dan alamat halaman yang diisi script. Coba definisi di bawah; itulah yang ditegakkan Ikiform di server, jadi komentar lebih dari 2.000 karakter juga mendapat 422 di sini.

<form id="page-feedback" action="https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx" method="post">
  <fieldset>
    <legend>Was this page helpful?</legend>
    <label><input type="radio" name="helpful" value="yes" required /> Yes</label>
    <label><input type="radio" name="helpful" value="no" /> No</label>
  </fieldset>

  <label for="comment">What was missing?</label>
  <textarea id="comment" name="comment" rows="3" maxlength="2000" aria-describedby="comment-error"></textarea>
  <p id="comment-error" hidden></p>

  <input type="hidden" name="page" />
  <input type="hidden" name="_redirect" value="https://docs.example.com/feedback-sent" />
  <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden />
  <button>Send</button>
  <p id="feedback-status" role="status" tabindex="-1"></p>
</form>

<script type="module" src="/page-feedback.js"></script>

Formulir sudah lengkap tanpa script. Dengan JavaScript mati atau diblokir, formulir mengirim dengan cara biasa, Ikiform menjawab 303 dan pembaca mendarat di halaman _redirect. Script hanya menyempurnakannya.

Script-nya

const form = document.querySelector("#page-feedback");
const status = form.querySelector("#feedback-status");
const button = form.querySelector("button");
const pageInput = form.elements.namedItem("page");
const idempotencyKey = crypto.randomUUID();
let sending = false;

pageInput.value = location.href;

function showFieldErrors(fields) {
  for (const input of form.querySelectorAll("[aria-invalid]")) input.removeAttribute("aria-invalid");
  for (const hint of form.querySelectorAll("[id$='-error']")) hint.hidden = true;
  let first = null;
  for (const [name, messages] of Object.entries(fields)) {
    const control = form.elements.namedItem(name);
    const hint = form.querySelector(`#${name}-error`);
    if (control instanceof HTMLElement) control.setAttribute("aria-invalid", "true");
    if (hint) {
      hint.textContent = messages[0];
      hint.hidden = false;
    }
    first ??= control instanceof RadioNodeList ? control[0] : control;
  }
  first?.focus();
}

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  if (sending) return;
  const body = new FormData(form, event.submitter);
  body.set("_idempotency", idempotencyKey);
  sending = true;
  button.setAttribute("aria-disabled", "true");
  status.textContent = "Sending...";

  try {
    const response = await fetch(form.action, {
      method: "POST",
      headers: { Accept: "application/json" },
      body,
      signal: AbortSignal.timeout(15000),
    });
    const result = await response.json();

    if (result.ok) {
      form.replaceChildren(status);
      status.textContent = "Thanks, that helps.";
      status.focus();
      return;
    }
    if (result.error.code === "challenge_required") {
      form.submit();
      return;
    }
    if (result.error.fields) {
      status.textContent = "";
      showFieldErrors(result.error.fields);
    } else if (response.status === 429 && response.headers.has("Retry-After")) {
      const wait = response.headers.get("Retry-After");
      status.textContent = `Too many tries. Wait ${wait} seconds and send again.`;
    } else {
      status.textContent = result.error.message;
    }
  } catch {
    status.textContent = "Couldn't reach the server. Check your connection and send again.";
  } finally {
    sending = false;
    button.removeAttribute("aria-disabled");
  }
});

• new FormData(form, event.submitter) membaca setiap kontrol bernama, ditambah name dan value tombol yang diklik jika ada. Susun sebelum Anda mengubah apa pun di formulir.
• Tombol mendapat aria-disabled, bukan disabled. Flag sending yang benar-benar memblokir, dan tombol tetap bisa difokus agar pengguna pembaca layar tidak kehilangan posisinya.
• Tanpa header Content-Type. Dengan body FormData, browser mengatur multipart/form-data dengan boundary yang benar.
• Accept: application/json membuat Ikiform menjawab dalam JSON. Panggilan fetch mengirim Sec-Fetch-Mode: cors, yang toh akan memilih JSON, tetapi header ini memperjelas maksudnya.
• Satu idempotency key per pemuatan halaman, dikirim sebagai field _idempotency. Jika pembaca mengirim, jaringan menjatuhkan jawabannya, lalu ia mengirim lagi, Ikiform memutar ulang jawaban pertama alih-alih menyimpan kiriman kedua. Post yang ditolak tidak pernah mengklaim key, jadi kiriman ulang yang sudah diperbaiki tetap diproses. Header Idempotency-Key melakukan hal yang sama, tetapi header kustom membuat browser mengirim request preflight lebih dulu. JavaScript dan fetch berisi aturan persisnya.
• AbortSignal.timeout(15000) mengubah request yang macet menjadi cabang catch alih-alih Sending... tanpa akhir.
• Baris status punya role="status", jadi teksnya dibacakan tanpa memindahkan fokus. Saat sukses, fokus pindah ke sana karena field di sekitarnya sudah hilang.

Saat formulir punya pemeriksaan manusia

Jika Spam check formulir diatur ke Ikiform, post fetch tanpa token Turnstile mendapat 403 challenge_required. Script di atas menanganinya dengan memanggil form.submit(). Method itu melewati listener submit dan mengirim dengan cara biasa, dan untuk post biasa Ikiform menampilkan halaman pemeriksaan singkatnya sendiri, lalu lanjut ke halaman _redirect Anda. Pembaca hanya meninggalkan halaman saat pemeriksaan aktif.

Agar tetap di halaman bahkan saat itu, dapatkan token lebih dulu dengan challenge(formId) dari SDK dan berikan ke submit(). Dokumentasi spam menunjukkan alurnya.

Alternatif tanpa JavaScript

Sebelum ada fetch, triknya adalah menargetkan iframe tersembunyi, jadi respons dimuat di sana dan halaman tetap di tempat:

<iframe name="feedback-sink" hidden></iframe>
<form action="https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx" method="post" target="feedback-sink">
  ...
</form>

Trik ini masih berfungsi, tetapi iframe memuat halaman di ikiform.com, dan browser tidak mengizinkan script Anda membaca frame lintas origin. Anda tidak bisa membedakan sukses dari error validasi, jadi pembaca juga tidak mendapat umpan balik apa pun. Gunakan hanya jika script benar-benar tidak bisa berjalan.

Pastikan berfungsi

1. Di Allowed domains formulir, tambahkan domain situs Anda, ditambah localhost selama pengembangan. Biarkan kosong untuk menerima kiriman dari mana saja.
2. Kirim Yes tanpa komentar. Formulir berubah menjadi Thanks, that helps. dan panel Network menampilkan 201.
3. Tempel lebih dari 2.000 karakter ke komentar, hapus maxlength di developer tools, lalu kirim. Pesan muncul di bawah komentar dan fokus pindah ke sana.
4. Klik dua kali Send. Dashboard menampilkan satu kiriman, bukan dua.
5. Matikan JavaScript dan kirim. Anda mendarat di halaman _redirect.
6. Atur throttling ke Offline dan kirim. Baris status menyatakan tidak bisa menjangkau server, dan Send berfungsi lagi.

Hal yang sering menjebak

Pertanyaan