{"canonical_url":"https://engineer.company/uk/glossary/web-components/","content_markdown":"# Вебкомпоненти\n\n## Що це таке\n\nВебкомпоненти, англійською Web Components, — це загальна назва групи можливостей\nбраузера, які дають розробникам змогу визначати власні елементи HTML. Сторінка\nпотім використовує такий елемент, як будь-який інший тег. Стандарти називають\nскладники власними іменами: custom elements та елементи `template` і `slot`\nописує Стандарт HTML, а тіньові дерева (shadow trees) — Стандарт DOM. Збірна\nназва походить із заголовка документа\n[*Introduction to Web Components*](https://www.w3.org/TR/components-intro/) —\nWorking Group Note, яку W3C опублікував 24 липня 2014 року, а згодом припинив\nроботу над нею й позначив як документ, на який не варто посилатися.\n\nКористувацький елемент (custom element) визначає клас JavaScript, що розширює\n`HTMLElement`, і його реєструють під певною назвою через\n`customElements.define()`. Визначення пояснює синтаксичному аналізатору HTML, як\nстворювати елемент і як елемент має реагувати на зміни, і відтоді його можна\nстворити з розмітки, через `document.createElement()` або через `new`. Назва\nпочинається з малої латинської літери ASCII, не містить великих літер ASCII й\nобов'язково містить дефіс. Дефіс відділяє власні назви від самої мови: Стандарт\nHTML обіцяє, що відтепер до HTML, SVG і MathML не додаватимуть елементів із\nдефісом у назві.\n\nЄ два різновиди. Автономний користувацький елемент (autonomous custom element),\nяк-от `\u003cflag-icon country=\"nl\"\u003e` із самого стандарту, починає як звичайний\nелемент без вбудованого значення. Розширений вбудований елемент (customized\nbuilt-in element) доповнює наявний елемент. Приклад стандарту — клас, що\nрозширює `HTMLButtonElement`, реєструється з `{ extends: \"button\" }` і\nвикористовується як `\u003cbutton is=\"plastic-button\"\u003e`. Такий елемент зберігає все,\nщо робить кнопку кнопкою, зокрема поведінку фокуса, надсилання форми й атрибут\n`disabled`.\n\nТіньове дерево — це окреме дерево вузлів, прикріплене до елемента, який\nназивають його хостом; звичайне дерево хоста Стандарт DOM називає light tree.\n`attachShadow()` створює тіньовий корінь (shadow root) у режимі open або closed,\nі лише в режимі open властивість хоста `shadowRoot` його повертає. Елемент\n`slot` у тіньовому дереві хоста позначає місце, де з'являються власні дочірні\nелементи хоста. Він показує призначені йому вузли, а коли їх немає, то власний\nвміст, і іменований слот забирає ті дочірні елементи, чий атрибут `slot` містить\nйого ім'я. Елемент `template` зберігає фрагмент HTML, який не відображається і\nякий скрипт може клонувати. З атрибутом `shadowrootmode` елемент `template`\nпредставляє декларативний тіньовий корінь, тож тіньове дерево можна записати й\nпросто в розмітці.\n\n## Чому це важливо\n\nВигаданий тег колись мало що давав: Стандарт HTML зазначає, що такі елементи\nісторично суперечили стандарту й були не надто функціональними. Користувацький\nелемент — повноправний учасник документа. Синтаксичний аналізатор його\nконструює, методи DOM його створюють, а його клас визначає, що відбувається,\nколи змінюються його атрибути або коли його вставляють на сторінку чи прибирають\nіз неї.\n\nВизначенню не обов'язково йти першим. Елемент, який синтаксичний аналізатор уже\nстворив, стає користувацьким, щойно для його назви зареєструють визначення, і\nСтандарт HTML називає це оновленням (upgrade). Доти елемент вважається\nневизначеним, приблизно як `span`, тож текст і посилання в ньому показуються як\nє. Стандарт прямо каже, що оновлення дають змогу прогресивно покращувати вміст\nкористувацьких елементів.\n\nКористувацький елемент може також брати участь у формах і в дереві доступності.\nКлас, що задає `static formAssociated = true` і викликає `attachInternals()`,\nотримує об'єкт `ElementInternals`, а метод `setFormValue()` цього об'єкта дає\nелементу значення, яке форма надсилає так само, як і для будь-якого іншого\nелемента керування. Той самий об'єкт задає типову роль і типові стани ARIA, що\nдіють, доки автор сторінки не перевизначить їх атрибутом `role` або відповідними\nатрибутами `aria-*`, а ще може тримати власні стани, до яких таблиці стилів\nзвертаються псевдокласом `:state()`.\n\nДля команди тіньове дерево цінне тим, що компонент стає самодостатнім: звичайні селектори сторінки не проникають у його внутрішнє тіньове дерево,\nа компонент сам вирішує, які частини відкрити для стилізації ззовні.\nУспадковані значення й custom properties усе ж можуть потрапляти всередину,\nа на вміст light tree, розміщений у слотах, і далі діють селектори сторінки. Там, де кілька\nбібліотек ділять одну сторінку, Стандарт HTML пропонує scoped registries, які\nстворюють через `new CustomElementRegistry()`, щоб елементи цих бібліотек могли\nспівіснувати й бібліотекам не доводилося узгоджувати між собою назви.\n\n## Як це виглядає на практиці\n\nКартка товару показує, як складники працюють разом. Сторінка містить вміст як\nзвичайну розмітку, з атрибутом `slot` на тому елементі, який має потрапити в\nіменований слот:\n\n```html\n\u003cproduct-card\u003e\n  \u003cspan slot=\"name\"\u003eДубовий табурет\u003c/span\u003e\n  \u003ca href=\"/kramnytsia/dubovyi-taburet/\"\u003eДетальніше\u003c/a\u003e\n\u003c/product-card\u003e\n\u003cscript type=\"module\" src=\"product-card.mjs\"\u003e\u003c/script\u003e\n```\n\nМодуль визначає елемент. Шаблон будується один раз, і кожна картка отримує\nвласну його копію у відкритому тіньовому корені:\n\n```js\nconst template = document.createElement(\"template\");\ntemplate.innerHTML = `\n  \u003ch2 part=\"title\"\u003e\u003cslot name=\"name\"\u003eТовар без назви\u003c/slot\u003e\u003c/h2\u003e\n  \u003cslot\u003e\u003c/slot\u003e\n`;\n\nclass ProductCard extends HTMLElement {\n  constructor() {\n    super();\n    const root = this.attachShadow({ mode: \"open\" });\n    root.append(template.content.cloneNode(true));\n  }\n}\n\nif (!customElements.get(\"product-card\")) {\n  customElements.define(\"product-card\", ProductCard);\n}\n```\n\nСторінка стилізує заголовок через єдину частину, яку компонент відкриває\nназовні:\n\n```css\nproduct-card::part(title) {\n  font-size: 1.25rem;\n}\n```\n\nПоки `product-card.mjs` не виконався, картка лишається невизначеним елементом, і\nчитач бачить назву товару й посилання як звичайний вміст у тексті. Коли модуль\nвиконується, `define()` реєструє клас, і картка, що вже є на сторінці,\nоновлюється. Конструктор прикріплює до неї тіньовий корінь і наповнює його\nклоном вмісту шаблону. Елемент `span` призначається слоту з назвою `name` і\nз'являється в заголовку. Посилання не має атрибута `slot`, тож потрапляє до\nбезіменного слота за замовчуванням. Картка без назви натомість показує власний\nвміст слота, «Товар без назви». Перевірка через `customElements.get()` не дає\nзайвій копії модуля, що прийшла з іншим пакетом, змусити `define()` кинути\nпомилку.\n\nСпільні компоненти допомагають, лише коли ними справді користуються, і в\nпортфоліо сайту є проєкт саме про це.\n[Дизайн-система iOS 26 «Liquid Glass»](/uk/portfolio/designed-an-ios-26-liquid-glass-design-system/)\nпочинає з інтерфейсу, у якому кожен новий екран винаходить власні кнопки, бейджі\nй картки, щоразу трохи інакші, аж поки кожна зміна не вимагає правити п'ять\nсаморобних версій того самого. Відповідь, яку описує сторінка, — канонічний\nнабір компонентів, з яких має складатися кожен екран, серед них Card, Label,\nButton, GlassIconButton і DirectoryGrid, і правила лінтингу, що відхиляють\nсаморобний бейдж чи чіп і вказують натомість на канонічний компонент. Сторінка\nне каже, чи ці компоненти є користувацькими елементами, але саму дисципліну\nможна перенести: одне визначення на компонент, яке тримають інструменти, а не\nпам'ять рецензента. Реєстр користувацьких елементів забезпечує першу половину:\nвін відхиляє нове визначення для назви, яку вже зайнято.\n\n## Де виникають проблеми\n\n**Назва з дефісом підміняє роль.** Стандарт HTML каже прямо: «An autonomous\ncustom element does not have any special meaning: it represents its children».\nПриклад стандарту `taco-button` показує, чого це коштує: щоб поводитися як\nкнопка, елементу потрібні `tabindex`, роль ARIA `button`, доступна назва,\n`aria-disabled`, обробка клавіатури, яка перетворює Enter і пробіл на клік, і\nстилі для вимкненого стану. Навіть тоді користувацький елемент не може задати\nтипову поведінку фокуса, тож `tabindex=\"0\"` може розходитися з тим, як кнопки\nповодяться на платформі. Там, де елемент спирається на наявний, стандарт каже,\nщо розширений вбудований елемент легше розробляти, підтримувати й\nвикористовувати. Дайте автономному елементу типову роль і типові стани через\n`ElementInternals`, а не залишайте їх на кожну сторінку, що його використовує.\n\n**Конструктор робить усю роботу.** Стандарт HTML ставить вимоги до конструкторів\nкористувацьких елементів: першим іде виклик `super()` без аргументів; атрибути й\nдочірні елементи не можна перевіряти, бо створений, але не оновлений елемент їх\nне має; і конструктор не повинен додавати елементу атрибути чи дочірні елементи.\nКонструктор, що порушує ці правила, може дати елемент, який синтаксичний\nаналізатор або методи DOM не здатні створити. Використовуйте конструктор для\nпочаткового стану, типових значень, обробників подій і тіньового кореня, а\nзавантаження й рендеринг перенесіть у `connectedCallback`.\n\n**Від `connectedCallback` чекають, що він спрацює один раз.** Він може\nспрацювати й кілька разів. За замовчуванням переміщення елемента викликає\n`disconnectedCallback`, а потім `connectedCallback`, тож елемент скидає свій\nстан, наче його прибрали й вставили знову. Захищайте одноразове налаштування\nпрапорцем і прибирайте в `disconnectedCallback` те, що запустив\n`connectedCallback`. Якщо елемент має зберігати стан, коли його переміщують\nчерез `moveBefore()`, визначте `connectedMoveCallback`: самої його наявності\nдосить, щоб замінити типову пару, навіть із порожнім тілом.\n\n**Назву визначають двічі.** `customElements.define()` кидає `NotSupportedError`,\nколи назву або клас уже зареєстровано, і `SyntaxError`, коли назва недійсна,\nнаприклад через відсутній дефіс або велику літеру. Перевіряйте через\n`customElements.get()`, перш ніж визначати, а бібліотеці, яка має співіснувати з\nіншими, дайте власний scoped registry.\n\n**Режим closed вважають захистом.** Режим closed ховає корінь від властивості\nхоста `shadowRoot` і приховує внутрішні вузли зі шляху події composed path\nдля обробників, що перебувають поза цим закритим тіньовим деревом. CSS Shadow Parts прямо каже, що\nтіньові дерева навмисно не є межею безпеки, а лише зручністю для авторів\nсторінок. Тримайте секрети поза компонентами й обирайте режим closed заради його\nвпливу на зовнішній код, а не як замок.\n\n**`attachShadow()` викликають там, де він не може спрацювати.** Стандарт DOM\nдозволяє тіньовий корінь лише на елементах із дійсною назвою користувацького\nелемента та на короткому списку вбудованих елементів, серед яких `div`,\n`section`, `p` і `span`, але не `button`. На розширеній вбудованій кнопці виклик\nкидає `NotSupportedError`. Інакше він поводиться й на елементі, що вже має\nкорінь: якщо корінь декларативний і в тому самому режимі, виклик очищає його й\nповертає, а якщо ні, то кидає помилку. Спершу перевіряйте, чи тіньовий корінь\nуже існує, щоб розмітку, яку сервер надіслав у декларативному корені, зберегти,\nа не стерти.\n\n**Від стилів сторінки чекають, що вони проникнуть усередину.** CSS Shadow Parts\nназиває цю межу бар'єром для стилів і зауважує, що вона ускладнює стилізацію\nкомпонента й тоді, коли сторінка справді цього хоче. Відкривайте назовні\nатрибутом `part` ті елементи, які сторінці дозволено стилізувати, і стилізуйте\nїх ззовні через `::part()`. Компонентові всередині іншого компонента потрібен\n`exportparts` на внутрішньому хості, щоб передати свої частини далі до сторінки.\nДля кольорів і відступів, які мають іти за сторінкою, використовуйте custom\nproperties, задані на хості: вони успадковуються в тіньове дерево компонента.\n\n**Вміст з'являється лише після скрипту.** Компонент, що пише весь свій текст із\nJavaScript, ховає його від читачів, доки не завантажиться визначення, а якщо\nскрипт зламається, читачі його так і не побачать. Тримайте вміст у light tree й\nпризначайте його слотам, як це робить картка товару, щоб оновлення покращувало\nте, що вже є на сторінці. Там, де вміст мусить зачекати, власний приклад\nСтандарту HTML ховає його, доки проміс від `customElements.whenDefined()` не\nбуде виконано для кожного елемента, що відповідає селектору `:not(:defined)`.\n\n## Що почитати далі\n\n- [HTML Standard: Custom elements](https://html.spec.whatwg.org/multipage/custom-elements.html)\n  — правила назв, вимоги до конструкторів, оновлення, елементи, пов'язані з\n  формами, і `ElementInternals`, з розібраними прикладами.\n- [DOM Standard: Shadow tree](https://dom.spec.whatwg.org/#shadow-trees)\n  — тіньові корені та їхні хости, слоти й призначені їм вузли, а також кроки, що\n  стоять за `attachShadow()`.\n- [HTML Standard: Scripting](https://html.spec.whatwg.org/multipage/scripting.html)\n  — елемент `template` з атрибутом `shadowrootmode` і елемент `slot`.\n- [CSS Shadow Parts](https://www.w3.org/TR/css-shadow-parts-1/)\n  — Working Draft W3C від 16 грудня 2025 року, що визначає `part`, `exportparts`\n  і псевдоелемент `::part()`.\n\n\u003chttps://engineer.company/uk/glossary/web-components/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"Як custom elements, тіньові дерева й елементи template і slot дають команді власні теги HTML: розібраний приклад і пастки, яких варто уникати.","formats":{"gemtext":"https://engineer.company/uk/glossary/web-components/index.gmi","gopher":"https://engineer.company/uk/glossary/web-components/gophermap","html":"https://engineer.company/uk/glossary/web-components/","json":"https://engineer.company/uk/glossary/web-components/index.json","markdown":"https://engineer.company/uk/glossary/web-components/index.md","pdf":"https://engineer.company/uk/glossary/web-components/index.pdf"},"kind":"page","language":"uk","title":"Що таке вебкомпоненти?","url":"https://engineer.company/uk/glossary/web-components/","version":1}