From 8603c43ad7c1cb156f5fc5bd67abdc795a842c7b Mon Sep 17 00:00:00 2001 From: julieng Date: Sun, 18 Sep 2022 07:08:56 +0200 Subject: [PATCH 1/2] move *.html to *.md --- files/ru/web/web_components/{index.html => index.md} | 0 .../web_components/using_custom_elements/{index.html => index.md} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename files/ru/web/web_components/{index.html => index.md} (100%) rename files/ru/web/web_components/using_custom_elements/{index.html => index.md} (100%) diff --git a/files/ru/web/web_components/index.html b/files/ru/web/web_components/index.md similarity index 100% rename from files/ru/web/web_components/index.html rename to files/ru/web/web_components/index.md diff --git a/files/ru/web/web_components/using_custom_elements/index.html b/files/ru/web/web_components/using_custom_elements/index.md similarity index 100% rename from files/ru/web/web_components/using_custom_elements/index.html rename to files/ru/web/web_components/using_custom_elements/index.md From fbfff6f0eb8861c397a77abca05864e31e577964 Mon Sep 17 00:00:00 2001 From: julieng Date: Sun, 18 Sep 2022 07:09:01 +0200 Subject: [PATCH 2/2] convert content to md --- files/ru/web/web_components/index.md | 355 ++++++++---------- .../using_custom_elements/index.md | 202 +++++----- 2 files changed, 265 insertions(+), 292 deletions(-) diff --git a/files/ru/web/web_components/index.md b/files/ru/web/web_components/index.md index 6db73b2ebf8f3a..bf6f582e3e8ca9 100644 --- a/files/ru/web/web_components/index.md +++ b/files/ru/web/web_components/index.md @@ -3,203 +3,158 @@ title: Веб-компоненты slug: Web/Web_Components translation_of: Web/Web_Components --- -

{{DefaultAPISidebar("Веб-компоненты")}}

- -

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

- -

Понятия и использование

- -

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

- -

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

- - - -

Базовый подход к реализации веб-компонента обычно выглядит примерно так:

- -
    -
  1. Создайте класс, в котором вы указываете функциональность своего веб-компонента, используя синтаксис классов ECMAScript 2015 (дополнительную информацию см. в разделе Классы).
    2. -
  2. Зарегистрируйте свой новый настраиваемый элемент с помощью метода {{domxref("CustomElementRegistry.define()")}}, передав ему имя элемента, который будет определён, класс или функцию, в которых указана его функциональность, и, необязательно, от какого элемента он наследуется.
    3. -
  3. При необходимости прикрепите теневую DOM к настраиваемому элементу с помощью метода {{domxref("Element.attachShadow()")}}. Добавьте дочерние элементы, обработчики событий и т.д. в теневой DOM, используя обычные методы DOM.
    4. -
  4. При необходимости определите HTML template, используя {{htmlelement("template")}} и {{htmlelement("slot")}}. Снова используйте обычные методы DOM, чтобы клонировать шаблон и прикрепить его к вашей теневой DOM.
    5. -
  5. Используйте свой настраиваемый элемент везде, где хотите, на своей странице, как и любой обычный элемент HTML.
    6. -
- -

Учебники

- -
-
Использование пользовательских элементов
-
Руководство, показывающее, как использовать функции настраиваемых элементов для создания простых веб-компонентов, а также рассказывает про колбэки жизненного цикла и некоторые другие более сложные функции.
-
Использование shadow DOM
-
Руководство, которое рассматривает основы теневой DOM, показывает, как прикрепить теневую DOM к элементу, добавлять к теневому дереву DOM, стилизовать его и многое другое.
-
Использование шаблонов и слотов
-
Руководство, показывающее, как определить повторно используемую структуру HTML с помощью элементов {{htmlelement("template")}} и {{htmlelement ("slot")}}, а затем использовать эту структуру внутри ваших веб-компонентов.
-
- -

Справка

- -

Пользовательские элементы

- -
-
{{domxref("CustomElementRegistry")}}
-
Содержит функции, связанные с настраиваемыми элементами, в первую очередь с методом {{domxref("CustomElementRegistry.define()")}}, используемым для регистрации новых настраиваемых элементов, чтобы их можно было затем использовать в вашем документе.
-
{{domxref("Window.customElements")}}
-
Возвращает ссылку на объект CustomElementRegistry.
-
Обратные вызовы жизненного цикла
-
Специальные колбэк-функции, определённые внутри определения класса настраиваемого элемента, которые влияют на его поведение: -
    -
  • connectedCallback: вызывается, когда настраиваемый элемент впервые подключается к DOM документа.
    • -
  • disconnectedCallback: вызывается, когда пользовательский элемент отключается от DOM документа.
    • -
  • adoptedCallback: вызывается, когда настраиваемый элемент перемещается в новый документ.
    • -
  • attributeChangedCallback: вызывается при добавлении, удалении или изменении одного из атрибутов настраиваемого элемента.
    • -
-
-
Расширения для создания пользовательских встроенных элементов
-
-
    -
  • Глобальный атрибут HTML {{htmlattrxref("is")}}: позволяет указать, что стандартный элемент HTML должен вести себя как зарегистрированный встроенный пользовательский элемент.
    • -
  • Параметр «is» метода {{domxref("Document.createElement()")}}: позволяет создать экземпляр стандартного HTML-элемента, который ведёт себя как заданный зарегистрированный настраиваемый встроенный элемент.
    • -
-
-
Псевдоклассы CSS
-
Псевдоклассы, относящиеся конкретно к настраиваемым элементам: -
    -
  • {{cssxref(":defined")}}: Соответствует любому заданному элементу, включая встроенные элементы и настраиваемые элементы, определённые с помощью CustomElementRegistry.define().
    • -
  • {{cssxref(":host")}}: Выбирает теневой хост теневого DOM, содержащего CSS, внутри которого он используется.
    • -
  • {{cssxref(":host()")}}: Выбирает теневой хост теневой DOM, содержащий CSS, внутри которого он используется (так что вы можете выбрать пользовательский элемент изнутри его теневой DOM) - но только если селектор, указанный в качестве параметра функции, совпадает с теневым хостом.
    • -
  • {{cssxref(":host-context()")}}: Выбирает теневой хост теневой DOM, содержащий CSS, внутри которого он используется (так что вы можете выбрать пользовательский элемент изнутри его теневой DOM) - но только если селектор, указанный в качестве параметра функции, совпадает с предком(-ами) теневого хоста в том месте, где он находится внутри иерархии DOM.
    • -
-
-
Псевдоэлементы CSS
-
Псевдоэлементы, относящиеся конкретно к настраиваемым элементам: -
    -
  • {{cssxref("::part")}}: Представляет любой элемент в теневом дереве, имеющий соответствующий атрибут {{HTMLAttrxRef("part")}}.
    • -
-
-
- -

Shadow DOM

- -
-
{{domxref("ShadowRoot")}}
-
Представляет корневой узел поддерева теневой модели DOM.
-
{{domxref("DocumentOrShadowRoot")}}
-
Миксин, определяющий функции, доступные для всех документов и теневых корневых узлов.
-
Расширения {{domxref("Element")}}
-
Расширения интерфейса Element, связанные с теневой DOM: -
    -
  • Метод {{domxref("Element.attachShadow()")}} прикрепляет теневое дерево DOM к указанному элементу.
    • -
  • Свойство {{domxref ("Element.shadowRoot")}} возвращает теневой корневой узел, прикреплённый к указанному элементу, или значение null, если корневой узел не прикреплён.
    • -
-
-
Соответствующие дополнения {{domxref("Node")}}
-
Дополнения к интерфейсу Node, относящиеся к теневой DOM: -
    -
  • Метод {{domxref("Node.getRootNode()")}} возвращает корень объекта контекста, который необязательно включает теневой корневой узел, если он доступен.
    • -
  • Свойство {{domxref("Node.isConnected")}} возвращает логическое значение, указывающее, подключён ли узел (прямо или косвенно) к объекту контекста, например объект {{domxref("Document")}} в случае обычного DOM или {{domxref("ShadowRoot")}} в случае теневого DOM.
    • -
-
-
Расширения {{domxref("Event")}}
-
Расширения интерфейса Event, относящиеся к теневой модели DOM: -
    -
  • {{domxref("Event.composed")}}: возвращает {{jsxref("Boolean")}}, который указывает, будет ли событие распространяться через границу теневой DOM в стандартную DOM (true) или нет (false).
    • -
  • {{domxref ("Event.composedPath")}}: возвращает путь к событию (объекты, для которых будут вызваны обработчики). Это не включает узлы в теневых деревьях, если теневой корневой узел был создан с закрытым {{domxref("ShadowRoot.mode")}}.
    • -
-
-
- -

HTML templates

- -
-
{{htmlelement("template")}}
-
Содержит фрагмент HTML, который не отображается при первоначальной загрузке содержащего документа, но может отображаться во время выполнения с помощью JavaScript, который в основном используется в качестве основы для структур настраиваемых элементов. Связанный интерфейс DOM - {{domxref("HTMLTemplateElement")}}.
-
{{htmlelement("slot")}}
-
Заполнитель внутри веб-компонента, который можно заполнить собственной разметкой, что позволяет создавать отдельные деревья DOM и представлять их вместе. Связанный интерфейс DOM - {{domxref("HTMLSlotElement")}}.
-
Глобальный HTML атрибут slot
-
Назначает слот элементу в теневом дереве теневого DOM.
-
{{domxref("Slotable")}}
-
Миксин, реализованный как узлами {{domxref("Element")}}, так и {{domxref("Text")}}, определяющий функции, которые позволяют им стать содержимым элемента {{htmlelement("slot")}}. Миксин определяет один атрибут, {{domxref("Slotable.assignedSlot")}}, который возвращает ссылку на слот, в который вставлен узел.
-
{{domxref("Element")}} extensions
-
Расширения интерфейса Element, относящиеся к слотам: -
    -
  • {{domxref("Element.slot")}}: Возвращает имя слота теневого DOM, прикреплённого к элементу.
    • -
-
-
Псевдоэлементы CSS
-
Псевдоэлементы, относящиеся конкретно к слотам: -
    -
  • {{cssxref("::slotted")}}: Соответствует любому содержимому, вставленному в слот.
    • -
-
-
Событие {{event("slotchange")}}
-
Вызывается для экземпляра {{domxref("HTMLSlotElement")}} (элемент {{htmlelement("slot")}}) при изменении узла(-ов), содержащихся в этом слоте.
-
- -

Примеры

- -

Мы создаём ряд примеров в репозитории GitHub с примерами веб-компонентов. Со временем будет добавлено больше.

- -

Спецификации

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
СпецификацияСтатусКомментарии
{{SpecName("HTML WHATWG","scripting.html#the-template-element","<template> element")}}{{Spec2("HTML WHATWG")}}Определение {{HTMLElement("template")}}.
{{SpecName("HTML WHATWG","custom-elements.html#custom-elements","custom elements")}}{{Spec2("HTML WHATWG")}}Определение пользовательских HTML-элементов
{{SpecName("DOM WHATWG","#shadow-trees","shadow trees")}}{{Spec2("DOM WHATWG")}}Определение Shadow DOM
{{SpecName("HTML Imports", "", "")}}{{Spec2("HTML Imports")}}Начальное определение HTML импорта
{{SpecName("Shadow DOM", "", "")}}{{Spec2("Shadow DOM")}}Начальное определение Shadow DOM
- -

Совместимость с браузерами

- -

В основном:

- - - -

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

- -

Смотрите также

- - +{{DefaultAPISidebar("Веб-компоненты")}} + +Веб-компоненты - это набор различных технологий, позволяющих создавать повторно используемые настраиваемые элементы с их функциональностью, инкапсулированной отдельно от остальной части вашего кода - и использовать их в ваших веб-приложениях. + +## Понятия и использование + +Как разработчики, все мы знаем, что как можно больше повторного использования кода - хорошая идея. Традиционно это было не так просто для пользовательских структур разметки - подумайте о сложном HTML (и связанном с ним стиле и сценарии), которые вам иногда приходилось писать для визуализации пользовательских элементов управления UI, и о том, как их многократное использование может превратить вашу страницу в беспорядок если вы не будете осторожны. + +Веб-компоненты направлены на решение таких проблем - они состоят из трёх основных технологий, которые можно использовать вместе для создания универсальных настраиваемых элементов с инкапсулированной функциональностью, которые можно повторно использовать где угодно, не опасаясь коллизий кода. + +- **Пользовательские элементы**: набор API-интерфейсов JavaScript, позволяющих определять пользовательские элементы и их поведение, которые затем можно использовать по желанию в пользовательском интерфейсе. +- **Shadow DOM**: набор API-интерфейсов JavaScript для прикрепления инкапсулированного «теневого» дерева DOM к элементу, который отображается отдельно от DOM основного документа, и управления соответствующими функциями. Таким образом, вы можете сохранить функции элемента в секрете, поэтому для них можно создавать сценарии и стили, не опасаясь коллизий с другими частями документа. +- **HTML templates**: элементы {{HTMLElement("template")}} и {{HTMLElement("slot")}} позволяют создавать шаблоны разметки, которых не видно на отображаемой странице. Затем их можно многократно использовать в качестве основы структуры настраиваемого элемента. + +Базовый подход к реализации веб-компонента обычно выглядит примерно так: + +1. Создайте класс, в котором вы указываете функциональность своего веб-компонента, используя синтаксис классов ECMAScript 2015 (дополнительную информацию см. в разделе [Классы](/ru/docs/Web/JavaScript/Reference/Classes)). +2. Зарегистрируйте свой новый настраиваемый элемент с помощью метода {{domxref("CustomElementRegistry.define()")}}, передав ему имя элемента, который будет определён, класс или функцию, в которых указана его функциональность, и, необязательно, от какого элемента он наследуется. +3. При необходимости прикрепите теневую DOM к настраиваемому элементу с помощью метода {{domxref("Element.attachShadow()")}}. Добавьте дочерние элементы, обработчики событий и т.д. в теневой DOM, используя обычные методы DOM. +4. При необходимости определите HTML template, используя {{htmlelement("template")}} и {{htmlelement("slot")}}. Снова используйте обычные методы DOM, чтобы клонировать шаблон и прикрепить его к вашей теневой DOM. +5. Используйте свой настраиваемый элемент везде, где хотите, на своей странице, как и любой обычный элемент HTML. + +## Учебники + +- [Использование пользовательских элементов](/ru/docs/Web/Web_Components/Using_custom_elements) + - : Руководство, показывающее, как использовать функции настраиваемых элементов для создания простых веб-компонентов, а также рассказывает про колбэки жизненного цикла и некоторые другие более сложные функции. +- [Использование shadow DOM](/ru/docs/Web/Web_Components/Using_shadow_DOM) + - : Руководство, которое рассматривает основы теневой DOM, показывает, как прикрепить теневую DOM к элементу, добавлять к теневому дереву DOM, стилизовать его и многое другое. +- [Использование шаблонов и слотов](/ru/docs/Web/Web_Components/Using_templates_and_slots) + - : Руководство, показывающее, как определить повторно используемую структуру HTML с помощью элементов {{htmlelement("template")}} и {{htmlelement ("slot")}}, а затем использовать эту структуру внутри ваших веб-компонентов. + +## Справка + +### Пользовательские элементы + +- {{domxref("CustomElementRegistry")}} + - : Содержит функции, связанные с настраиваемыми элементами, в первую очередь с методом {{domxref("CustomElementRegistry.define()")}}, используемым для регистрации новых настраиваемых элементов, чтобы их можно было затем использовать в вашем документе. +- {{domxref("Window.customElements")}} + - : Возвращает ссылку на объект `CustomElementRegistry`. +- [Обратные вызовы жизненного цикла](/ru/docs/Web/Web_Components/Using_custom_elements#Использование_lifecycle_callbacks) + + - : Специальные колбэк-функции, определённые внутри определения класса настраиваемого элемента, которые влияют на его поведение: + + - `connectedCallback`: вызывается, когда настраиваемый элемент впервые подключается к DOM документа. + - `disconnectedCallback`: вызывается, когда пользовательский элемент отключается от DOM документа. + - `adoptedCallback`: вызывается, когда настраиваемый элемент перемещается в новый документ. + - `attributeChangedCallback`: вызывается при добавлении, удалении или изменении одного из атрибутов настраиваемого элемента. + +- Расширения для создания пользовательских встроенных элементов + + - : + + - Глобальный атрибут HTML {{htmlattrxref("is")}}: позволяет указать, что стандартный элемент HTML должен вести себя как зарегистрированный встроенный пользовательский элемент. + - Параметр «is» метода {{domxref("Document.createElement()")}}: позволяет создать экземпляр стандартного HTML-элемента, который ведёт себя как заданный зарегистрированный настраиваемый встроенный элемент. + +- Псевдоклассы CSS + + - : Псевдоклассы, относящиеся конкретно к настраиваемым элементам: + + - {{cssxref(":defined")}}: Соответствует любому заданному элементу, включая встроенные элементы и настраиваемые элементы, определённые с помощью `CustomElementRegistry.define()`. + - {{cssxref(":host")}}: Выбирает теневой хост [теневого DOM](/ru/docs/Web/Web_Components/Using_shadow_DOM), содержащего CSS, внутри которого он используется. + - {{cssxref(":host()")}}: Выбирает теневой хост [теневой DOM](/ru/docs/Web/Web_Components/Using_shadow_DOM), содержащий CSS, внутри которого он используется (так что вы можете выбрать пользовательский элемент изнутри его теневой DOM) - но только если селектор, указанный в качестве параметра функции, совпадает с теневым хостом. + - {{cssxref(":host-context()")}}: Выбирает теневой хост [теневой DOM](/ru/docs/Web/Web_Components/Using_shadow_DOM), содержащий CSS, внутри которого он используется (так что вы можете выбрать пользовательский элемент изнутри его теневой DOM) - но только если селектор, указанный в качестве параметра функции, совпадает с предком(-ами) теневого хоста в том месте, где он находится внутри иерархии DOM. + +- Псевдоэлементы CSS + + - : Псевдоэлементы, относящиеся конкретно к настраиваемым элементам: + + - {{cssxref("::part")}}: Представляет любой элемент в [теневом дереве](/ru/docs/Web/Web_Components/Using_shadow_DOM), имеющий соответствующий атрибут {{HTMLAttrxRef("part")}}. + +### Shadow DOM + +- {{domxref("ShadowRoot")}} + - : Представляет корневой узел поддерева теневой модели DOM. +- {{domxref("DocumentOrShadowRoot")}} + - : Миксин, определяющий функции, доступные для всех документов и теневых корневых узлов. +- Расширения {{domxref("Element")}} + + - : Расширения интерфейса `Element`, связанные с теневой DOM: + + - Метод {{domxref("Element.attachShadow()")}} прикрепляет теневое дерево DOM к указанному элементу. + - Свойство {{domxref ("Element.shadowRoot")}} возвращает теневой корневой узел, прикреплённый к указанному элементу, или значение `null`, если корневой узел не прикреплён. + +- Соответствующие дополнения {{domxref("Node")}} + + - : Дополнения к интерфейсу `Node`, относящиеся к теневой DOM: + + - Метод {{domxref("Node.getRootNode()")}} возвращает корень объекта контекста, который необязательно включает теневой корневой узел, если он доступен. + - Свойство {{domxref("Node.isConnected")}} возвращает логическое значение, указывающее, подключён ли узел (прямо или косвенно) к объекту контекста, например объект {{domxref("Document")}} в случае обычного DOM или {{domxref("ShadowRoot")}} в случае теневого DOM. + +- Расширения {{domxref("Event")}} + + - : Расширения интерфейса `Event`, относящиеся к теневой модели DOM: + + - {{domxref("Event.composed")}}: возвращает {{jsxref("Boolean")}}, который указывает, будет ли событие распространяться через границу теневой DOM в стандартную DOM (`true`) или нет (`false`). + - {{domxref ("Event.composedPath")}}: возвращает путь к событию (объекты, для которых будут вызваны обработчики). Это не включает узлы в теневых деревьях, если теневой корневой узел был создан с закрытым {{domxref("ShadowRoot.mode")}}. + +### HTML templates + +- {{htmlelement("template")}} + - : Содержит фрагмент HTML, который не отображается при первоначальной загрузке содержащего документа, но может отображаться во время выполнения с помощью JavaScript, который в основном используется в качестве основы для структур настраиваемых элементов. Связанный интерфейс DOM - {{domxref("HTMLTemplateElement")}}. +- {{htmlelement("slot")}} + - : Заполнитель внутри веб-компонента, который можно заполнить собственной разметкой, что позволяет создавать отдельные деревья DOM и представлять их вместе. Связанный интерфейс DOM - {{domxref("HTMLSlotElement")}}. +- Глобальный HTML атрибут [`slot`](/ru/docs/Web/HTML/Global_attributes/slot) + - : Назначает слот элементу в теневом дереве теневого DOM. +- {{domxref("Slotable")}} + - : Миксин, реализованный как узлами {{domxref("Element")}}, так и {{domxref("Text")}}, определяющий функции, которые позволяют им стать содержимым элемента {{htmlelement("slot")}}. Миксин определяет один атрибут, {{domxref("Slotable.assignedSlot")}}, который возвращает ссылку на слот, в который вставлен узел. +- {{domxref("Element")}} extensions + + - : Расширения интерфейса `Element`, относящиеся к слотам: + + - {{domxref("Element.slot")}}: Возвращает имя слота теневого DOM, прикреплённого к элементу. + +- Псевдоэлементы CSS + + - : Псевдоэлементы, относящиеся конкретно к слотам: + + - {{cssxref("::slotted")}}: Соответствует любому содержимому, вставленному в слот. + +- Событие {{event("slotchange")}} + - : Вызывается для экземпляра {{domxref("HTMLSlotElement")}} (элемент {{htmlelement("slot")}}) при изменении узла(-ов), содержащихся в этом слоте. + +## Примеры + +Мы создаём ряд примеров в репозитории GitHub с [примерами веб-компонентов](https://github.com/mdn/web-components-examples). Со временем будет добавлено больше. + +## Спецификации + +| Спецификация | Статус | Комментарии | +| ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| {{SpecName("HTML WHATWG","scripting.html#the-template-element","<template> element")}} | {{Spec2("HTML WHATWG")}} | Определение {{HTMLElement("template")}}. | +| {{SpecName("HTML WHATWG","custom-elements.html#custom-elements","custom elements")}} | {{Spec2("HTML WHATWG")}} | Определение [пользовательских HTML-элементов](/ru/docs/Web/Web_Components/Использование_пользовательских_элементов) | +| {{SpecName("DOM WHATWG","#shadow-trees","shadow trees")}} | {{Spec2("DOM WHATWG")}} | Определение [Shadow DOM](/ru/docs/Web/Web_Components/Using_shadow_DOM) | +| {{SpecName("HTML Imports", "", "")}} | {{Spec2("HTML Imports")}} | Начальное определение [HTML импорта](/ru/docs/Web/Web_Components/HTML_Imports) | +| {{SpecName("Shadow DOM", "", "")}} | {{Spec2("Shadow DOM")}} | Начальное определение [Shadow DOM](/ru/docs/Web/Web_Components/Using_shadow_DOM) | + +## Совместимость с браузерами + +В основном: + +- Веб-компоненты по умолчанию поддерживаются в Firefox (версия 63), Chrome и Opera. +- Safari поддерживает ряд функций веб-компонентов, но меньше, чем указанные выше браузеры. +- Edge работает над реализацией. + +Для получения подробной информации о поддержке определённых функций браузером обратитесь к перечисленным выше справочным страницам. + +## Смотрите также + +- [webcomponents.org](https://www.webcomponents.org/) - сайт с примерами веб-компонентов, учебными пособиями и другой информацией. +- [FAST](https://fast.design/) - это библиотека веб-компонентов, созданная Microsoft, которая предлагает несколько пакетов для использования в зависимости от потребностей вашего проекта. [Fast Element](https://github.com/microsoft/fast/tree/master/packages/web-components/fast-element) - это лёгкое средство для простого создания производительных, эффективных с точки зрения памяти и совместимых со стандартами веб-компонентов. [Fast Foundation](https://github.com/microsoft/fast/tree/master/packages/web-components/fast-foundation) - это библиотека классов, шаблонов и других утилит веб-компонентов, построенная на основе fast-element, предназначенная для создания зарегистрированных веб-компонентов. +- [Hybrids](https://github.com/hybridsjs/hybrids) - библиотека веб-компонентов с открытым исходным кодом, которая предпочитает простые объекты и чистые функции `class` и `this` синтаксису. Он предоставляет простой и функциональный API для создания пользовательских элементов. +- [Polymer](https://www.polymer-project.org/) - каркас веб-компонентов Google - набор полифилов, улучшений и примеров. На данный момент самый простой способ кроссбраузерно использовать веб-компоненты. +- [Snuggsi](https://github.com/devpunks/snuggsi#readme) - Простые веб-компоненты размером \~ 1 КБ, _включая полифил_ - Все, что вам нужно, это браузер и базовое понимание классов HTML, CSS и JavaScript для продуктивной работы. +- [Slim.js](https://github.com/slimjs/slim.js) - библиотека веб-компонентов с открытым исходным кодом - высокопроизводительная библиотека для быстрой и простой разработки компонентов; расширяемая, подключаемая и кросс-платформенная. +- [Stencil](https://stenciljs.com/) - набор инструментов для создания многоразовых масштабируемых систем проектирования в веб-компонентах. diff --git a/files/ru/web/web_components/using_custom_elements/index.md b/files/ru/web/web_components/using_custom_elements/index.md index a41a485c3cd91b..fb2061f5f2c5c9 100644 --- a/files/ru/web/web_components/using_custom_elements/index.md +++ b/files/ru/web/web_components/using_custom_elements/index.md @@ -4,35 +4,34 @@ slug: Web/Web_Components/Using_custom_elements translation_of: Web/Web_Components/Using_custom_elements original_slug: Web/Web_Components/Использование_пользовательских_элементов --- -
{{DefaultAPISidebar("Web Components")}}
+{{DefaultAPISidebar("Web Components")}} -

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

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

Примечание: Пользовательские элементы поддерживаются по умолчанию в Firefox, Chrome и Opera. Safari пока поддерживает только автономные пользовательские компоненты, Edge также работает над реализацией.

-
+> **Примечание:** Пользовательские элементы поддерживаются по умолчанию в Firefox, Chrome и Opera. Safari пока поддерживает только автономные пользовательские компоненты, Edge также работает над реализацией. -

Высокоуровневый обзор

+## Высокоуровневый обзор -

Контроллером пользовательских элементов веб-документа является объект {{domxref("CustomElementRegistry")}} — этот элемент позволяет регистрировать пользовательские элементы на веб-странице, возвращает информацию о зарегистрированных элементах и т.п.

+Контроллером пользовательских элементов веб-документа является объект {{domxref("CustomElementRegistry")}} — этот элемент позволяет регистрировать пользовательские элементы на веб-странице, возвращает информацию о зарегистрированных элементах и т.п. -

Чтобы зарегистрировать пользовательский элемент на странице, используйте метод {{domxref("CustomElementRegistry.define()")}} method. Он принимает аргументы:

+Чтобы зарегистрировать пользовательский элемент на странице, используйте метод {{domxref("CustomElementRegistry.define()")}} method. Он принимает аргументы: - +- {{domxref("DOMString")}} - имя элемента. Обратите внимание, что в именах пользовательских элементах [должен содержаться дефис](https://stackoverflow.com/questions/22545621/do-custom-elements-require-a-dash-in-their-name); они не могут состоять только из одного слова. +- Объект типа [class](/ru/docs/Web/JavaScript/Reference/Classes), определяющий поведение элемента. +- Опционально объект options, имеющий свойство `extends`, соответствующее встроенному элементу, от которого наследует объект. -

К примеру, мы можем определить пользовательский элемент word-count element:

+К примеру, мы можем определить пользовательский элемент [word-count element](https://mdn.github.io/web-components-examples/word-count-web-component/): -
customElements.define('word-count', WordCount, { extends: 'p' });
+```js +customElements.define('word-count', WordCount, { extends: 'p' }); +``` -

Этот элемент называется word-count, объект соответствующего класса называется WordCount, и он наследует элементу {{htmlelement("p")}}.

+Этот элемент называется `word-count`, объект соответствующего класса называется `WordCount`, и он наследует элементу {{htmlelement("p")}}. -

Объект класса пользовательского элемента определяется с помощью синтаксиса классов ES 2015. Например, WordCount имеют следующую структуру:

+Объект класса пользовательского элемента определяется с помощью синтаксиса классов ES 2015. Например, `WordCount` имеют следующую структуру: -
class WordCount extends HTMLParagraphElement {
+```js
+class WordCount extends HTMLParagraphElement {
   constructor() {
     // Всегда первым делом вызывайте super() в конструкторе
     super();
@@ -41,30 +40,30 @@ original_slug: Web/Web_Components/Использование_пользоват
 
     ...
   }
-}
+} +``` -

Это простой пример, но его можно дополнить. Можно определить специальные lifecycle callbacks, которые будут вызваны в определённые моменты жизненного цикла элемента. Например, connectedCallback будет вызван, когда пользовательский элемент оказывается впервые встроен в DOM, а attributeChangedCallback вызывается, когда пользовательскому элементу добавляют, удаляют или изменяют какой-то атрибут.

+Это простой пример, но его можно дополнить. Можно определить специальные lifecycle callbacks, которые будут вызваны в определённые моменты жизненного цикла элемента. Например, `connectedCallback` будет вызван, когда пользовательский элемент оказывается впервые встроен в DOM, а `attributeChangedCallback` вызывается, когда пользовательскому элементу добавляют, удаляют или изменяют какой-то атрибут. -

Подробнее об этом в секции Using the lifecycle callbacks ниже.

+Подробнее об этом в секции [Using the lifecycle callbacks](#using_the_lifecycle_callbacks) ниже. -

Есть два типа пользовательских элементов:

+Есть два типа пользовательских элементов: - +- **Автономные пользовательские элементы** независимы — они не наследуют встроенным HTML-элементам. Их используют на странице просто как обычный HTML-элемент. Например, `` или `document.createElement("popup-info")`. +- **Модифицированные встроенные элементы** наследуют базовым HTML-элементам. Чтобы создать один из них, вы определяете элемент, от которого они унаследованы (как в примерах выше), и используете их как обычный базовый элемент, но с добавлением атрибута/свойства с именем пользовательского элемента {{htmlattrxref("is")}}. Например `

`, или `document.createElement("p", { is: "word-count" })`. -

Разбор простых примеров

+## Разбор простых примеров -

А сейчас давайте разберём ещё несколько простых примеров, иллюстрирующих подробности создания пользовательских элементов.

+А сейчас давайте разберём ещё несколько простых примеров, иллюстрирующих подробности создания пользовательских элементов. -

Автономные пользовательские элементы

+### Автономные пользовательские элементы -

Рассмотрим пример автономного пользовательского элемента — <popup-info-box> (см. работающий пример). Он содержит изображение и строку, и встраивает изображение в страницу. Когда на изображение наводят фокус, компонент показывает всплывающую подсказку с текстом.

+Рассмотрим пример автономного пользовательского элемента — [``](https://github.com/mdn/web-components-examples/tree/master/popup-info-box-web-component) (см. [работающий пример](https://mdn.github.io/web-components-examples/popup-info-box-web-component/)). Он содержит изображение и строку, и встраивает изображение в страницу. Когда на изображение наводят фокус, компонент показывает всплывающую подсказку с текстом. -

Прежде всего файл JavaScript определяет класс PopUpInfo, наследующий от {{domxref("HTMLElement")}}. Автономные пользовательские элементы почти всегда наследуют HTMLElement.

+Прежде всего файл JavaScript определяет класс `PopUpInfo`, наследующий от {{domxref("HTMLElement")}}. Автономные пользовательские элементы почти всегда наследуют `HTMLElement`. -
class PopUpInfo extends HTMLElement {
+```js
+class PopUpInfo extends HTMLElement {
   constructor() {
     // Всегда первым делом вызывайте super() в конструкторе
     super();
@@ -73,13 +72,15 @@ original_slug: Web/Web_Components/Использование_пользоват
 
     ...
   }
-}
+} +``` -

В этом фрагменте кода содержится определение конструктора {{jsxref("Classes.constructor","constructor")}} класса, которое всегда начинается с вызова super() чтобы отработала цепочка прототипного наследования.

+В этом фрагменте кода содержится определение конструктора {{jsxref("Classes.constructor","constructor")}} класса, которое всегда начинается с вызова [`super()`](/en-US/docs/Web/JavaScript/Reference/Operators/super) чтобы отработала цепочка прототипного наследования. -

Внутри конструктора мы определяем всю функциональность, которую получит элемент при создании его объекта. В данном случае мы добавляем shadow root к пользовательскому элементу, производим манипуляции с DOM, чтобы создать определённую структуру shadow DOM внутри элемента — которая затем присоединяется к shadow root — и наконец добавляем CSS к shadow root, чтобы задать его стиль.

+Внутри конструктора мы определяем всю функциональность, которую получит элемент при создании его объекта. В данном случае мы добавляем shadow root к пользовательскому элементу, производим манипуляции с DOM, чтобы создать определённую структуру shadow DOM внутри элемента — которая затем присоединяется к shadow root — и наконец добавляем CSS к shadow root, чтобы задать его стиль. -
// Создание shadow root
+```js
+// Создание shadow root
 var shadow = this.attachShadow({mode: 'open'});
 
 // Создание spans
@@ -117,29 +118,33 @@ style.textContent = '.wrapper {' +
 shadow.appendChild(style);
 shadow.appendChild(wrapper);
 wrapper.appendChild(icon);
-wrapper.appendChild(info);
+wrapper.appendChild(info); +``` -

Наконец, регистрируем пользовательский элемент в CustomElementRegistry с помощью метода define(), который упоминался ранее — в качестве параметров мы передаём ему имя элемента и имя класса, который содержит его функциональность:

+Наконец, регистрируем пользовательский элемент в `CustomElementRegistry` с помощью метода `define()`, который упоминался ранее — в качестве параметров мы передаём ему имя элемента и имя класса, который содержит его функциональность: -
customElements.define('popup-info', PopUpInfo);
+```js +customElements.define('popup-info', PopUpInfo); +``` -

Теперь он доступен для использования на нашей странице. В HTML мы используем его так:

+Теперь он доступен для использования на нашей странице. В HTML мы используем его так: -
<popup-info img="img/alt.png" text="Код валидации вашей карты (CVC)
+```html
+
+  на обороте вашей карты.">
+```
 
-

-
Примечание: вы можете прочитать полный исходный код на JavaScript здесь.

-

+> **Примечание:** вы можете прочитать [полный исходный код на JavaScript](https://github.com/mdn/web-components-examples/blob/master/popup-info-box-web-component/main.js) здесь.
 
-
Модифицированные встроенные элементы

+### Модифицированные встроенные элементы
 
-
Теперь давайте взглянем на другой пример модифицированного пользовательского элемента — раскрывающийся список (см. действующий пример). Он превращает любой ненумерованный список в раскрывающееся/складывающееся меню.

+Теперь давайте взглянем на другой пример модифицированного пользовательского элемента — [раскрывающийся список](https://github.com/mdn/web-components-examples/tree/master/expanding-list-web-component) ([см. действующий пример](https://mdn.github.io/web-components-examples/expanding-list-web-component/)). Он превращает любой ненумерованный список в раскрывающееся/складывающееся меню.
 
-
Первым делом определим класс элемента наподобие того, как это делалось выше:

+Первым делом определим класс элемента наподобие того, как это делалось выше:
 
-
class ExpandingList extends HTMLUListElement {
+```js
+class ExpandingList extends HTMLUListElement {
   constructor() {
     // Всегда первым делом вызываем super() в конструкторе
     super();
@@ -148,58 +153,64 @@ wrapper.appendChild(info);

 
     ...
   }
-}
+} +``` -

Здесь мы не будем во всех подробностях описывать функциональность элемента, вы можете понять как он работает, посмотрев исходный код. Единственное принципиальное различие с предыдущим примером состоит в том, что мы используем интерфейс {{domxref("HTMLUListElement")}}, а не {{domxref("HTMLElement")}}. Так что у него есть все характеристики элемента {{htmlelement("ul")}}, плюс дополнительная функциональность, которую определили мы. Это и отличает модифицированный встроенный элемент от автономного пользовательского элемента.

+Здесь мы не будем во всех подробностях описывать функциональность элемента, вы можете понять как он работает, посмотрев исходный код. Единственное принципиальное различие с предыдущим примером состоит в том, что мы используем интерфейс {{domxref("HTMLUListElement")}}, а не {{domxref("HTMLElement")}}. Так что у него есть все характеристики элемента {{htmlelement("ul")}}, плюс дополнительная функциональность, которую определили мы. Это и отличает модифицированный встроенный элемент от автономного пользовательского элемента. -

Далее мы регистрируем этот элемент с помощью метода define() как в прошлом примере, только на сей раз мы добавляем объект options, который определяет, какому встроенному элементу наследует данный:

+Далее мы регистрируем этот элемент с помощью метода `define()` как в прошлом примере, только на сей раз мы добавляем объект options, который определяет, какому встроенному элементу наследует данный: -
customElements.define('expanding-list', ExpandingList, { extends: "ul" });
+```js +customElements.define('expanding-list', ExpandingList, { extends: "ul" }); +``` -

Встроенный элемент используется на веб-странице немного по-другому:

+Встроенный элемент используется на веб-странице немного по-другому: -
<ul is="expanding-list">
+```html
+
    
 
   ...
 
-</ul>
+ +``` -

Вы задаёте элемент <ul> как обычно, но указываете имя модифицированного элемента в атрибуте is.

+Вы задаёте элемент `
    ` как обычно, но указываете имя модифицированного элемента в атрибуте `is`. -
    -

    Замечание: Полный исходный код на JavaScript доступен здесь.

    -
    +> **Примечание:** **Замечание**: Полный [исходный код на JavaScript](https://github.com/mdn/web-components-examples/blob/master/expanding-list-web-component/main.js) доступен здесь. -

    Использование lifecycle callbacks

    +## Использование lifecycle callbacks -

    Вы можете определить несколько разных колбэков в конструкторе пользовательских элементов, которые сработают на разных этапах жизненного цикла элемента:

    +Вы можете определить несколько разных колбэков в конструкторе пользовательских элементов, которые сработают на разных этапах жизненного цикла элемента: -
      -
    • connectedCallback: Срабатывает, когда пользовательский элемент впервые добавляется в DOM.
      • -
    • disconnectedCallback: Срабатывает, когда пользовательский элемент удаляется из DOM.
      • -
    • adoptedCallback: Срабатывает, когда пользовательский элемент перемещён в новый документ.
      • -
    • attributeChangedCallback: Срабатывает, когда пользовательскому элементу добавляют, удаляют или изменяют атрибут.
      • -
    +- `connectedCallback`: Срабатывает, когда пользовательский элемент впервые добавляется в DOM. +- `disconnectedCallback`: Срабатывает, когда пользовательский элемент удаляется из DOM. +- `adoptedCallback`: Срабатывает, когда пользовательский элемент перемещён в новый документ. +- `attributeChangedCallback`: Срабатывает, когда пользовательскому элементу добавляют, удаляют или изменяют атрибут. -

    Посмотрим на них в действии. Код ниже взят из примера life-cycle-callbacks (см. его в действии). Это тривиальный пример, создающий на странице цветной квадрат. Вот как выглядит код пользовательского элемента:

    +Посмотрим на них в действии. Код ниже взят из примера [life-cycle-callbacks](https://github.com/mdn/web-components-examples/tree/master/life-cycle-callbacks) ([см. его в действии](https://mdn.github.io/web-components-examples/life-cycle-callbacks/)). Это тривиальный пример, создающий на странице цветной квадрат. Вот как выглядит код пользовательского элемента: -
    <custom-square l="100" c="red"></custom-square>
    +```html + +``` -

    Конструктор класса очень простой — мы просто добавляем shadow DOM к элементу, а затем добавляем пустые элементы {{htmlelement("div")}} и {{htmlelement("style")}} к shadow root:

    +Конструктор класса очень простой — мы просто добавляем shadow DOM к элементу, а затем добавляем пустые элементы {{htmlelement("div")}} и {{htmlelement("style")}} к shadow root: -
    var shadow = this.attachShadow({mode: 'open'});
+```js
+var shadow = this.attachShadow({mode: 'open'});
 
 var div = document.createElement('div');
 var style = document.createElement('style');
 shadow.appendChild(style);
-shadow.appendChild(div);
    +shadow.appendChild(div); +``` -

    Наиболее важная функция в этом примере updateStyle() — она принимает элемент, находит его shadow root, находит его элемент <style>, и добавляет {{cssxref("width")}}, {{cssxref("height")}}, и {{cssxref("background-color")}} к стилям.

    +Наиболее важная функция в этом примере `updateStyle()` — она принимает элемент, находит его shadow root, находит его элемент `