Dengan peristiwa baru dan API elemen kustom, berpartisipasi dalam formulir menjadi jauh lebih mudah.
Banyak developer membuat kontrol formulir kustom, baik untuk memberikan kontrol yang tidak ada di browser, atau untuk menyesuaikan tampilan dan nuansa yang lebih mungkin dengan kontrol formulir bawaan.
Namun, mungkin sulit untuk mereplikasi fitur kontrol formulir HTML bawaan. Pertimbangkan beberapa fitur yang didapatkan oleh elemen <input>
secara otomatis saat Anda menambahkannya ke formulir:
- Input akan otomatis ditambahkan ke daftar kontrol formulir.
- Nilai input akan otomatis dikirim bersama formulir.
- Input berpartisipasi dalam validasi formulir. Anda dapat menata gaya input menggunakan pseudoclass
:valid
dan:invalid
. - Input akan diberi tahu saat formulir direset, saat formulir dimuat ulang, atau saat browser mencoba mengisi otomatis entri formulir.
Kontrol formulir kustom biasanya memiliki beberapa fitur ini. Developer dapat mengatasi beberapa batasan pada JavaScript, seperti menambahkan <input>
tersembunyi ke formulir untuk berpartisipasi dalam pengiriman formulir. Tetapi fitur lain tidak dapat direplikasi dalam JavaScript saja.
Dua fitur web baru mempermudah pembuatan kontrol formulir kustom, dan menghapus batasan kontrol kustom saat ini:
- Peristiwa
formdata
memungkinkan objek JavaScript arbitrer berpartisipasi dalam pengiriman formulir sehingga Anda dapat menambahkan data formulir tanpa menggunakan<input>
tersembunyi. - API elemen kustom yang terkait dengan Formulir memungkinkan elemen kustom bertindak lebih seperti kontrol formulir bawaan.
Kedua fitur ini dapat digunakan untuk membuat jenis kontrol baru yang berfungsi lebih baik.
API berbasis peristiwa
Peristiwa formdata
adalah API level rendah yang memungkinkan kode JavaScript berpartisipasi dalam pengiriman formulir. Mekanismenya seperti ini:
- Anda menambahkan pemroses peristiwa
formdata
ke formulir yang ingin Anda gunakan. - Saat pengguna mengklik tombol kirim, formulir akan mengaktifkan peristiwa
formdata
, yang menyertakan objekFormData
yang menyimpan semua data yang dikirim. - Setiap pemroses
formdata
mendapatkan kesempatan untuk menambahkan atau mengubah data sebelum formulir dikirim.
Berikut adalah contoh pengiriman satu nilai dalam pemroses peristiwa formdata
:
const form = document.querySelector('form');
// FormData event is sent on <form> submission, before transmission.
// The event has a formData property
form.addEventListener('formdata', ({formData}) => {
// https://developer.mozilla.org/docs/Web/API/FormData
formData.append('my-input', myInputValue);
});
Coba ini menggunakan contoh kami di Glitch. Pastikan untuk menjalankannya di Chrome 77 atau yang lebih baru untuk melihat cara kerja API.
Kompatibilitas browser
Elemen kustom yang terkait dengan formulir
Anda dapat menggunakan API berbasis peristiwa dengan jenis komponen apa pun, tetapi API ini hanya memungkinkan Anda berinteraksi dengan proses pengiriman.
Selain pengiriman, kontrol formulir standar digunakan di banyak bagian siklus proses formulir. Elemen kustom yang terkait dengan formulir bertujuan untuk menjembatani kesenjangan antara widget kustom dan kontrol bawaan. Elemen kustom yang terkait dengan formulir cocok dengan banyak fitur elemen formulir standar:
- Saat Anda menempatkan elemen kustom terkait formulir di dalam
<form>
, elemen tersebut akan otomatis dikaitkan dengan formulir, seperti kontrol yang disediakan oleh browser. - Elemen ini dapat diberi label menggunakan elemen
<label>
. - Elemen dapat menetapkan nilai yang otomatis dikirimkan bersama formulir.
- Elemen dapat menyetel flag yang menunjukkan apakah elemen tersebut memiliki input yang valid atau tidak. Jika salah satu kontrol formulir memiliki input yang tidak valid, formulir tidak dapat dikirim.
- Elemen dapat memberikan callback untuk berbagai bagian siklus proses formulir—seperti saat formulir dinonaktifkan atau direset ke status default.
- Elemen ini mendukung pseudoclass CSS standar untuk kontrol formulir, seperti
:disabled
dan:invalid
.
Banyak sekali fiturnya. Artikel ini tidak akan membahas semuanya, tetapi akan menjelaskan dasar-dasar yang diperlukan untuk mengintegrasikan elemen kustom Anda dengan formulir.
Menentukan elemen kustom yang terkait dengan formulir
Untuk mengubah elemen kustom menjadi elemen kustom yang terkait dengan formulir, diperlukan beberapa langkah tambahan:
- Tambahkan properti
formAssociated
statis ke class elemen kustom Anda. Kode ini akan memberi tahu browser untuk memperlakukan elemen tersebut seperti kontrol formulir. - Panggil metode
attachInternals()
pada elemen untuk mendapatkan akses ke metode dan properti tambahan untuk kontrol formulir, sepertisetFormValue()
dansetValidity()
. - Tambahkan properti dan metode umum yang didukung oleh kontrol formulir, seperti
name
,value
, danvalidity
.
Berikut ini cara item tersebut sesuai dengan definisi elemen kustom dasar:
// Form-associated custom elements must be autonomous custom elements--
// meaning they must extend HTMLElement, not one of its subclasses.
class MyCounter extends HTMLElement {
// Identify the element as a form-associated custom element
static formAssociated = true;
constructor() {
super();
// Get access to the internal form control APIs
this.internals_ = this.attachInternals();
// internal value for this control
this.value_ = 0;
}
// Form controls usually expose a "value" property
get value() { return this.value_; }
set value(v) { this.value_ = v; }
// The following properties and methods aren't strictly required,
// but browser-level form controls provide them. Providing them helps
// ensure consistency with browser-provided controls.
get form() { return this.internals_.form; }
get name() { return this.getAttribute('name'); }
get type() { return this.localName; }
get validity() {return this.internals_.validity; }
get validationMessage() {return this.internals_.validationMessage; }
get willValidate() {return this.internals_.willValidate; }
checkValidity() { return this.internals_.checkValidity(); }
reportValidity() {return this.internals_.reportValidity(); }
…
}
customElements.define('my-counter', MyCounter);
Setelah terdaftar, Anda dapat menggunakan elemen ini di mana pun Anda menggunakan kontrol formulir yang disediakan browser:
<form>
<label>Number of bunnies: <my-counter></my-counter></label>
<button type="submit">Submit</button>
</form>
Menetapkan nilai
Metode attachInternals()
menampilkan objek ElementInternals
yang memberikan akses ke API kontrol formulir. Yang paling dasar adalah metode setFormValue()
, yang menetapkan nilai kontrol saat ini.
Metode setFormValue()
dapat menggunakan salah satu dari tiga jenis nilai:
- Nilai string.
- Objek
File
. - Objek
FormData
. Anda dapat menggunakan objekFormData
untuk meneruskan beberapa nilai (misalnya, kontrol input kartu kredit dapat meneruskan nomor kartu, tanggal habis masa berlaku, dan kode verifikasi).
Untuk menetapkan nilai sederhana:
this.internals_.setFormValue(this.value_);
Untuk menetapkan beberapa nilai, Anda dapat melakukan hal seperti ini:
// Use the control's name as the base name for submitted data
const n = this.getAttribute('name');
const entries = new FormData();
entries.append(n + '-first-name', this.firstName_);
entries.append(n + '-last-name', this.lastName_);
this.internals_.setFormValue(entries);
Validasi masukan
Kontrol Anda juga dapat berpartisipasi dalam validasi formulir dengan memanggil metode setValidity()
pada objek internal.
// Assume this is called whenever the internal value is updated
onUpdateValue() {
if (!this.matches(':disabled') && this.hasAttribute('required') &&
this.value_ < 0) {
this.internals_.setValidity({customError: true}, 'Value cannot be negative.');
}
else {
this.internals_.setValidity({});
}
this.internals.setFormValue(this.value_);
}
Anda dapat menata gaya elemen kustom terkait formulir dengan pseudoclass :valid
dan :invalid
, seperti kontrol formulir bawaan.
Callback siklus proses
API elemen kustom terkait formulir menyertakan sekumpulan callback siklus proses tambahan untuk dikaitkan dengan siklus proses formulir. Callback bersifat opsional: hanya terapkan callback jika elemen Anda perlu melakukan sesuatu pada titik tersebut di siklus proses.
void formAssociatedCallback(form)
Dipanggil saat browser mengaitkan elemen dengan elemen formulir, atau memisahkan elemen dari elemen formulir.
void formDisabledCallback(disabled)
Dipanggil setelah status disabled
elemen berubah, baik karena atribut disabled
elemen ini telah ditambahkan atau dihapus; atau karena status disabled
berubah pada <fieldset>
yang merupakan ancestor elemen ini. Parameter disabled
mewakili status dinonaktifkan yang baru untuk elemen. Misalnya, elemen dapat menonaktifkan elemen dalam shadow DOM-nya saat dinonaktifkan.
void formResetCallback()
Dipanggil setelah formulir direset. Elemen harus mereset dirinya sendiri ke jenis status default. Untuk elemen <input>
, hal ini biasanya melibatkan penetapan properti value
agar cocok dengan atribut value
yang disetel di markup (atau dalam kasus kotak centang, menyetel properti checked
agar cocok dengan atribut checked
.
void formStateRestoreCallback(state, mode)
Dipanggil dalam salah satu dari dua situasi:
- Saat browser memulihkan status elemen (misalnya, setelah navigasi atau saat browser dimulai ulang). Dalam kasus ini, argumen
mode
adalah"restore"
. - Saat fitur bantuan input browser seperti isi otomatis formulir menetapkan nilai. Dalam kasus ini, argumen
mode
adalah"autocomplete"
.
Jenis argumen pertama bergantung pada cara metode setFormValue()
dipanggil. Untuk detail selengkapnya, lihat Memulihkan status formulir.
Memulihkan status formulir
Dalam situasi tertentu—seperti saat membuka kembali halaman, atau memulai ulang browser, browser mungkin mencoba memulihkan formulir ke status saat pengguna meninggalkannya.
Untuk elemen kustom terkait formulir, status yang dipulihkan berasal dari nilai yang Anda teruskan ke metode setFormValue()
. Anda dapat memanggil metode dengan parameter nilai tunggal, seperti yang ditunjukkan pada contoh sebelumnya, atau dengan dua parameter:
this.internals_.setFormValue(value, state);
value
merepresentasikan nilai kontrol yang dapat dikirim. Parameter state
opsional adalah representasi internal dari status kontrol, yang dapat menyertakan data yang tidak dikirim ke server. Parameter state
menggunakan jenis yang sama dengan parameter value
. Parameter ini dapat berupa objek string, File
, atau FormData
.
Parameter state
berguna jika Anda tidak dapat memulihkan status kontrol berdasarkan nilai saja. Misalnya, Anda membuat pemilih warna dengan beberapa mode: palet atau roda warna RGB. Nilai tabel pengiriman akan berupa warna yang dipilih dalam bentuk kanonis, seperti "#7fff00"
. Namun, untuk memulihkan kontrol ke status tertentu, Anda juga perlu mengetahui dalam mode mana kontrol berada, sehingga state mungkin terlihat seperti "palette/#7fff00"
.
this.internals_.setFormValue(this.value_,
this.mode_ + '/' + this.value_);
Kode Anda harus memulihkan statusnya berdasarkan nilai status yang disimpan.
formStateRestoreCallback(state, mode) {
if (mode == 'restore') {
// expects a state parameter in the form 'controlMode/value'
[controlMode, value] = state.split('/');
this.mode_ = controlMode;
this.value_ = value;
}
// Chrome currently doesn't handle autofill for form-associated
// custom elements. In the autofill case, you might need to handle
// a raw value.
}
Dalam kasus kontrol yang lebih sederhana (misalnya input angka), nilainya mungkin cukup untuk memulihkan kontrol ke status sebelumnya. Jika Anda menghilangkan state
saat memanggil setFormValue()
, nilai akan diteruskan ke formStateRestoreCallback()
.
formStateRestoreCallback(state, mode) {
// Simple case, restore the saved value
this.value_ = state;
}
Contoh penerapannya
Contoh berikut menyatukan banyak fitur elemen kustom yang terkait dengan bentuk. Pastikan untuk menjalankannya di Chrome 77 atau yang lebih baru untuk melihat cara kerja API.
Deteksi fitur
Anda dapat menggunakan deteksi fitur untuk menentukan apakah peristiwa formdata
dan elemen kustom terkait formulir tersedia. Saat ini tidak ada polyfill yang dirilis untuk kedua fitur. Pada kedua kasus tersebut, Anda dapat kembali ke penambahan elemen formulir tersembunyi untuk menyebarkan nilai kontrol ke formulir. Banyak fitur lanjutan dari elemen khusus yang terkait formulir kemungkinan akan sulit atau tidak mungkin untuk di-polyfill.
if ('FormDataEvent' in window) {
// formdata event is supported
}
if ('ElementInternals' in window &&
'setFormValue' in window.ElementInternals.prototype) {
// Form-associated custom elements are supported
}
Kesimpulan
Peristiwa formdata
dan elemen kustom terkait formulir menyediakan alat baru untuk membuat kontrol formulir kustom.
Peristiwa formdata
tidak memberi Anda kemampuan baru, tetapi memberi Anda antarmuka untuk menambahkan data formulir ke proses pengiriman, tanpa harus membuat elemen <input>
tersembunyi.
API elemen kustom terkait formulir memberikan serangkaian kemampuan baru untuk membuat kontrol formulir kustom yang berfungsi seperti kontrol formulir bawaan.
Banner besar oleh Oudom Pravat di Unsplash.