Рекомендации по использованию пользовательских элементов

Пользовательские элементы позволяют создавать собственные HTML-теги. В этом контрольном списке представлены лучшие практики, которые помогут вам создавать высококачественные элементы.

Пользовательские элементы позволяют расширять HTML и определять собственные теги. Это невероятно мощная функция, но она также низкоуровневая, а это значит, что не всегда понятно, как лучше всего реализовать свой собственный элемент.

Чтобы помочь вам получить наилучшие впечатления, мы составили этот контрольный список. Он разрушает все, что, по нашему мнению, необходимо для создания хорошо управляемого пользовательского элемента.

Контрольный список

Тень ДОМ

Атрибуты и свойства

События

Объяснители

Не переопределяйте автора страницы

Вполне возможно, что разработчик, использующий ваш элемент, захочет переопределить некоторые его начальные состояния. Например, изменение role ARIA или возможности фокусировки с помощью tabindex . Прежде чем применять собственные значения, проверьте, установлены ли эти и другие глобальные атрибуты.

connectedCallback() {
  if (!this.hasAttribute('role'))
    this.setAttribute('role', 'checkbox');
  if (!this.hasAttribute('tabindex'))
    this.setAttribute('tabindex', 0);

Сделать свойства ленивыми

Разработчик может попытаться установить свойство вашего элемента до загрузки его определения. Это особенно актуально, если разработчик использует платформу, которая обрабатывает загрузку компонентов, вставку их на страницу и привязку их свойств к модели.

В следующем примере Angular декларативно привязывает свойство isChecked своей модели к свойству checked флажка. Если определение Howto-checkbox было загружено отложенно, возможно, что Angular попытается установить проверенное свойство до обновления элемента.

<howto-checkbox [checked]="defaults.isChecked"></howto-checkbox>

Пользовательский элемент должен обрабатывать этот сценарий, проверяя, были ли уже установлены какие-либо свойства для его экземпляра. <howto-checkbox> демонстрирует этот шаблон с помощью метода _upgradeProperty() .

connectedCallback() {
  ...
  this._upgradeProperty('checked');
}

_upgradeProperty(prop) {
  if (this.hasOwnProperty(prop)) {
    let value = this[prop];
    delete this[prop];
    this[prop] = value;
  }
}

_upgradeProperty() захватывает значение из необновленного экземпляра и удаляет свойство, чтобы оно не затеняло собственный установщик свойств пользовательского элемента. Таким образом, когда определение элемента наконец загрузится, оно сможет сразу же отразить правильное состояние.

Избегайте проблем с повторным входом

Соблазнительно использовать attributeChangedCallback() для отражения состояния базового свойства, например:

// When the [checked] attribute changes, set the checked property to match.
attributeChangedCallback(name, oldValue, newValue) {
  if (name === 'checked')
    this.checked = newValue;
}

Но это может создать бесконечный цикл, если установщик свойства также отражает атрибут.

set checked(value) {
  const isChecked = Boolean(value);
  if (isChecked)
    // OOPS! This will cause an infinite loop because it triggers the
    // attributeChangedCallback() which then sets this property again.
    this.setAttribute('checked', '');
  else
    this.removeAttribute('checked');
}

Альтернативой является разрешение установщику свойства отразить атрибут, а получателю определить его значение на основе атрибута.

set checked(value) {
  const isChecked = Boolean(value);
  if (isChecked)
    this.setAttribute('checked', '');
  else
    this.removeAttribute('checked');
}

get checked() {
  return this.hasAttribute('checked');
}

В этом примере добавление или удаление атрибута также приведет к установке свойства.

Наконец, attributeChangedCallback() можно использовать для обработки побочных эффектов, таких как применение состояний ARIA.

attributeChangedCallback(name, oldValue, newValue) {
  const hasValue = newValue !== null;
  switch (name) {
    case 'checked':
      // Note the attributeChangedCallback is only handling the *side effects*
      // of setting the attribute.
      this.setAttribute('aria-checked', hasValue);
      break;
    ...
  }
}