이 페이지는 Cloud Translation API를 통해 번역되었습니다.

더 강력한 양식 제어 기능

Arthur Evans

게시일: 2019년 8월 8일

많은 개발자가 브라우저에 내장되지 않은 컨트롤을 제공하거나 내장된 양식 컨트롤로 가능한 것 이상으로 디자인을 맞춤설정하기 위해 맞춤 양식 컨트롤을 빌드합니다.

하지만 기본 제공 HTML 양식 컨트롤의 기능을 복제하기는 어려울 수 있습니다. 양식에 <input> 요소를 추가하면 자동으로 제공되는 몇 가지 기능을 고려해 보세요.

입력이 폼의 컨트롤 목록에 자동으로 추가됩니다.
입력의 값은 양식과 함께 자동으로 제출됩니다.
입력이 양식 유효성 검사에 참여합니다. :valid 및 :invalid 의사 클래스를 사용하여 입력을 스타일 지정할 수 있습니다.
입력은 양식이 재설정되거나, 양식이 새로고침되거나, 브라우저가 양식 항목을 자동 완성하려고 할 때 알림을 받습니다.

맞춤 양식 컨트롤에는 일반적으로 이러한 기능이 거의 없습니다. 개발자는 양식 제출에 참여하기 위해 양식에 숨겨진 <input>를 추가하는 등 JavaScript의 일부 제한사항을 해결할 수 있습니다. 하지만 다른 기능은 JavaScript만으로는 복제할 수 없습니다.

두 가지 웹 기능을 사용하면 맞춤 양식 컨트롤을 더 쉽게 빌드하고 맞춤 컨트롤의 제한사항을 삭제할 수 있습니다.

formdata 이벤트를 사용하면 임의의 JavaScript 객체가 양식 제출에 참여할 수 있으므로 숨겨진 <input>를 사용하지 않고도 양식 데이터를 추가할 수 있습니다.
양식 연결 맞춤 요소 API를 사용하면 맞춤 요소가 내장 양식 컨트롤처럼 작동할 수 있습니다.

이 두 기능을 사용하면 더 효과적인 새로운 종류의 컨트롤을 만들 수 있습니다.

이벤트 기반 API

Browser Support

Source

formdata 이벤트는 모든 JavaScript 코드가 양식 제출에 참여할 수 있도록 하는 저수준 API입니다.

상호 작용하려는 양식에 formdata 이벤트 리스너를 추가합니다.
사용자가 제출을 클릭하면 양식에서 제출되는 모든 데이터를 보유하는 FormData 객체를 포함하는 formdata 이벤트를 실행합니다.
각 formdata 리스너는 양식이 제출되기 전에 데이터를 추가하거나 수정할 수 있는 기회를 얻습니다.

다음은 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);
});

양식 관련 사용자 정의 요소

이벤트 기반 API는 모든 종류의 구성 요소와 함께 사용할 수 있지만, 제출 프로세스와만 상호 작용할 수 있습니다.

표준화된 양식 컨트롤은 양식 수명 주기의 많은 부분에 참여합니다. 양식 관련 사용자 정의 요소는 사용자 정의 위젯과 기본 제공 컨트롤 간의 격차를 메우는 것을 목표로 합니다. 양식 관련 사용자 정의 요소는 표준화된 양식 요소의 많은 기능과 일치합니다.

<form> 내부에 양식 관련 사용자 지정 요소를 배치하면 브라우저에서 제공하는 컨트롤처럼 자동으로 양식과 연결됩니다.
<label> 요소를 사용하여 요소에 라벨을 지정할 수 있습니다.
해당 요소는 양식과 함께 자동으로 제출되는 값을 설정할 수 있습니다.
해당 요소는 유효한 입력이 있는지 여부를 나타내는 플래그를 설정할 수 있습니다. 양식 컨트롤 중 하나에 잘못된 입력이 있는 경우 양식을 제출할 수 없습니다.
이 요소는 양식이 사용 중지되거나 기본 상태로 재설정되는 경우와 같은 양식 수명 주기의 다양한 부분에 콜백을 제공할 수 있습니다.
이 요소는 :disabled 및 :invalid와 같은 양식 컨트롤에 대한 표준 CSS 의사 클래스를 지원합니다.

이 문서에서는 모든 내용을 다루지는 않지만 사용자 정의 요소를 양식과 통합하는 데 필요한 기본 사항을 설명합니다.

양식 관련 사용자 정의 요소 정의

사용자 정의 요소를 양식 관련 사용자 정의 요소로 바꾸려면 몇 가지 추가 단계가 필요합니다.

사용자 정의 요소 클래스에 정적 formAssociated 속성을 추가합니다. 이렇게 하면 브라우저는 해당 요소를 양식 컨트롤처럼 처리하게 됩니다.
setFormValue() 및 setValidity()와 같은 양식 컨트롤의 추가 메서드 및 속성에 액세스하려면 요소에서 attachInternals() 메서드를 호출합니다.
name, value, validity와 같이 폼 컨트롤에서 지원하는 일반적인 속성과 메서드를 추가합니다.

이러한 항목이 기본 사용자 정의 요소 정의에 어떻게 적용되는지는 다음과 같습니다.

// Form-associated custom elements must be autonomous custom elements.
// 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);

등록이 완료되면 브라우저에서 제공하는 양식 컨트롤을 사용하는 곳 어디에서나 이 요소를 사용할 수 있습니다.

<form>
  <label>Number of bunnies: <my-counter></my-counter></label>
  <button type="submit">Submit</button>
</form>

값을 설정하세요

attachInternals() 메서드는 폼 컨트롤 API에 대한 액세스를 제공하는 ElementInternals 객체를 반환합니다. 가장 기본적인 것은 컨트롤의 현재 값을 설정하는 setFormValue() 메서드입니다.

setFormValue() 메서드는 다음 세 가지 유형의 값 중 하나를 사용할 수 있습니다.

문자열 값입니다.
File 객체.
FormData 객체. FormData 객체를 사용하면 여러 값을 전달할 수 있습니다. 예를 들어, 신용카드 입력 컨트롤은 카드 번호, 만료일, 확인 코드를 전달할 수 있습니다.

값을 설정하려면:

this.internals_.setFormValue(this.value_);

여러 값을 설정하려면 다음과 같이 하면 됩니다.

// 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);

입력 검증

내부 객체에서 setValidity() 메서드를 호출하여 컨트롤이 양식 유효성 검사에 참여할 수도 있습니다.

// 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_);
}

:valid 및 :invalid 의사 클래스를 사용하면 기본 제공 양식 컨트롤과 마찬가지로 양식 관련 사용자 지정 요소의 스타일을 지정할 수 있습니다.

수명 주기 콜백

양식 연결 맞춤 요소 API에는 양식 수명 주기에 연결하기 위한 추가 수명 주기 콜백이 포함되어 있습니다. 콜백은 선택사항입니다. 요소가 수명 주기의 해당 시점에서 작업을 실행해야 하는 경우에만 콜백을 구현하세요.

`void formAssociatedCallback(form)`

브라우저가 요소를 폼 요소와 연결하거나, 요소와 폼 요소의 연결을 해제할 때 호출됩니다.

`void formDisabledCallback(disabled)`

요소의 disabled 상태가 변경된 후 호출됩니다. 이는 이 요소의 disabled 속성이 추가되거나 제거되었거나, 이 요소의 상위 요소인 <fieldset>에서 disabled 상태가 변경되었기 때문입니다.

예를 들어, 해당 요소는 비활성화된 경우 Shadow DOM의 요소를 비활성화할 수 있습니다.

`void formResetCallback()`

폼이 재설정된 후에 호출됩니다. 해당 요소는 일종의 기본 상태로 재설정되어야 합니다. <input> 요소의 경우 일반적으로 value 속성을 마크업에 설정된 value 특성과 일치하도록 설정하는 것이 포함됩니다. 체크박스의 경우 이는 checked 속성을 checked 특성과 일치하도록 설정하는 것과 관련이 있습니다.

`void formStateRestoreCallback(state, mode)`

다음 두 가지 상황 중 하나에서 호출됩니다.

브라우저가 요소의 상태를 복원할 때(예: 탐색 후 또는 브라우저가 다시 시작될 때)입니다. mode 인수는 "restore"입니다.
브라우저의 입력 지원 기능(예: 양식 자동 완성)이 값을 설정하는 경우 mode 인수는 "autocomplete"입니다.

첫 번째 인수의 유형은 setFormValue() 메서드가 호출된 방식에 따라 달라집니다.

양식 상태 복원

어떤 상황에서는, 예를 들어 페이지로 돌아가거나 브라우저를 다시 시작할 때, 브라우저가 사용자가 떠난 상태로 양식을 복원하려고 할 수 있습니다.

양식 연결 맞춤 요소의 경우 복원된 상태는 setFormValue() 메서드에 전달하는 값에서 가져옵니다. 이전 예제에 표시된 것처럼 단일 값 매개변수로 메서드를 호출하거나 두 개의 매개변수로 메서드를 호출할 수 있습니다.

this.internals_.setFormValue(value, state);

value는 컨트롤의 제출 가능한 값을 나타냅니다. 선택적인 state 매개변수는 컨트롤 상태의 내부적 표현으로, 서버로 전송되지 않는 데이터를 포함할 수 있습니다. state 매개변수는 value 매개변수와 동일한 유형(문자열, File 또는 FormData 객체)을 사용합니다.

state 매개변수는 값만으로는 컨트롤의 상태를 복원할 수 없을 때 유용합니다. 예를 들어, 팔레트나 RGB 색상 휠 등 여러 모드를 갖춘 색상 선택기를 만든다고 가정해 보겠습니다. 제출 가능한 값은 "#7fff00"와 같은 표준 형식의 선택된 색상입니다. 컨트롤을 특정 상태로 복원하려면 컨트롤이 어떤 모드에 있었는지도 알아야 하므로 상태는 "palette/#7fff00"와 비슷할 수 있습니다.

this.internals_.setFormValue(this.value_,
    this.mode_ + '/' + this.value_);

코드는 저장된 상태 값을 기반으로 상태를 복원해야 합니다.

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 doesn't handle autofill for form-associated custom elements.
  // In the autofill case, you might need to handle a raw value.
}

더 간단한 컨트롤 (예: 숫자 입력)의 경우 해당 값은 컨트롤을 이전 상태로 복원하기에 충분할 것입니다. setFormValue()를 호출할 때 state를 생략하면 값이 formStateRestoreCallback()에 전달됩니다.

formStateRestoreCallback(state, mode) {
  // Simple case, restore the saved value
  this.value_ = state;
}

기능 감지

기능 감지를 사용하여 formdata 이벤트와 폼 연결 맞춤 요소를 사용할 수 있는지 확인할 수 있습니다. 두 기능 모두에 대해 출시된 폴리필이 없습니다. 두 경우 모두 숨겨진 양식 요소를 추가하여 컨트롤의 값을 양식에 전파하는 방법으로 대체할 수 있습니다.

양식 연결 맞춤 요소의 고급 기능은 대부분 폴리필하기 어렵거나 불가능할 수 있습니다.

if ('FormDataEvent' in window) {
  // formdata event is supported
}

if ('ElementInternals' in window &&
    'setFormValue' in window.ElementInternals.prototype) {
  // Form-associated custom elements are supported
}

formdata 이벤트를 사용하면 숨겨진 <input> 요소를 만들지 않고도 제출 프로세스에 양식 데이터를 추가할 수 있는 인터페이스가 제공됩니다. 양식 연결 맞춤 요소 API를 사용하면 기본 제공 양식 컨트롤처럼 작동하는 맞춤 양식 컨트롤을 위한 새로운 기능 세트를 제공할 수 있습니다.