CustomElementRegistry.define()

Die define() Methode der CustomElementRegistry Schnittstelle beschreibt ein neues benutzerdefiniertes Element.

Es gibt zwei Arten von benutzerdefinierten Elementen, die erstellt werden können:

  • Autonomes benutzerdefiniertes Element: Eigenständige Elemente; Sie erben nicht von eingebauten HTML-Elementen.
  • Angepasstes integriertes Element: Diese Elemente erben und erweitern eingebaute HTML-Elemente.

Syntax

customElements.define(name, constructor, options);

Parameter

name
Name des neuen benutzerdefinierten Elements. Beachte, dass Namen von benutzerdefinierten Elementen einen Bindestrich enthalten müssen.
constructor
Konstruktor für das neue, benutzerdefinierte Element.
options Optional
Objekt, das steuert, wie das Element definiert ist. Eine Option wird derzeit unterstützt:
  • extends: String des Namens eines integrierten Elements das erweitert werden soll. Wird verwendet um ein angepasstes integriertes Element  zu erzeugen.

Return value

Void.

Ausnahmebehandlung

Exception Description
NotSupportedError

Das CustomElementRegistry enthält bereits einen Eintrag mit dem gleichen Namen oder dem gleichen Konstruktor (oder ist auf andere Weise bereits definiert), oder extends ist angegeben und es ist ein gültiger benutzerdefinierter Elementname oder extends ist angegeben, aber das Element, das es zu erweitern versucht, ist ein unbekanntes Element.

SyntaxError Der angegebene Name ist kein gültiger benutzerdefinierter Elementname.
TypeError Der referenzierte Konstruktor ist kein Konstruktor.

Hinweis: Du wirst oftmals  NotSupportedErrors geworfen bekommen, die so erscheinen als würde define() fehlschlagen, aber stattdessen wahrscheinlich ein Problem mit {domxref("Element.attachShadow()")}} sind.

Beispiele

Autonomes benutzerdefiniertes Element

Der folgende Code entstammt dem popup-info-box-web-component Beispiel (siehe Live).

// Create a class for the element
class PopUpInfo extends HTMLElement {
  constructor() {
    // Always call super first in constructor
    super();

    // Create a shadow root
    var shadow = this.attachShadow({mode: 'open'});

    // Create spans
    var wrapper = document.createElement('span');
    wrapper.setAttribute('class','wrapper');
    var icon = document.createElement('span');
    icon.setAttribute('class','icon');
    icon.setAttribute('tabindex', 0);
    var info = document.createElement('span');
    info.setAttribute('class','info');

    // Take attribute content and put it inside the info span
    var text = this.getAttribute('text');
    info.textContent = text;

    // Insert icon
    var imgUrl;
    if(this.hasAttribute('img')) {
      imgUrl = this.getAttribute('img');
    } else {
      imgUrl = 'img/default.png';
    }
    var img = document.createElement('img');
    img.src = imgUrl;
    icon.appendChild(img);

    // Create some CSS to apply to the shadow dom
    var style = document.createElement('style');

    style.textContent = '.wrapper {' +
                           'position: relative;' +
                        '}' +

                         '.info {' +
                            'font-size: 0.8rem;' +
                            'width: 200px;' +
                            'display: inline-block;' +
                            'border: 1px solid black;' +
                            'padding: 10px;' +
                            'background: white;' +
                            'border-radius: 10px;' +
                            'opacity: 0;' +
                            'transition: 0.6s all;' +
                            'position: absolute;' +
                            'bottom: 20px;' +
                            'left: 10px;' +
                            'z-index: 3;' +
                          '}' +

                          'img {' +
                            'width: 1.2rem' +
                          '}' +

                          '.icon:hover + .info, .icon:focus + .info {' +
                            'opacity: 1;' +
                          '}';

    // attach the created elements to the shadow dom

    shadow.appendChild(style);
    shadow.appendChild(wrapper);
    wrapper.appendChild(icon);
    wrapper.appendChild(info);
  }
}

// Define the new element
customElements.define('popup-info', PopUpInfo);
<popup-info img="img/alt.png" text="Your card validation code (CVC) is an extra
                                    security feature — it is the last 3 or 4 
                                    numbers on the back of your card.">

Hinweis: Konstruktoren für autonome benutzerdefinierte Elemente müssen HTMLElement extenden.

Benutzerdefiniertes integriertes Element

Der folgende Code entstammt dem word-count-web-component Beispiel (siehe Live).

// Create a class for the element
class WordCount extends HTMLParagraphElement {
  constructor() {
    // Always call super first in constructor
    super();

    // count words in element's parent element
    var wcParent = this.parentNode;

    function countWords(node){
      var text = node.innerText || node.textContent
      return text.split(/\s+/g).length;
    }

    var count = 'Words: ' + countWords(wcParent);

    // Create a shadow root
    var shadow = this.attachShadow({mode: 'open'});

    // Create text node and add word count to it
    var text = document.createElement('span');
    text.textContent = count;

    // Append it to the shadow root
    shadow.appendChild(text);


    // Update count when element content changes
    setInterval(function() {
      var count = 'Words: ' + countWords(wcParent);
      text.textContent = count;
    }, 200)

  }
}

// Define the new element
customElements.define('word-count', WordCount, { extends: 'p' });
<p is="word-count"></p>

Spezifikationen

Spezifikation Status Kommentar
HTML Living Standard
Die Definition von 'customElements.define()' in dieser Spezifikation.
Lebender Standard Initial definition.

Browserkompatibilität

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid WebviewChrome für AndroidFirefox für AndroidOpera für AndroidSafari auf iOSSamsung Internet
define
Experimentell
Chrome Vollständige Unterstützung 66
Hinweise
Vollständige Unterstützung 66
Hinweise
Hinweise Support for 'Customized built-in elements' as well.
Vollständige Unterstützung 54
Hinweise
Hinweise Support for 'Autonomous custom elements' only.
Edge Keine Unterstützung Nein
Hinweise
Keine Unterstützung Nein
Hinweise
Hinweise In Development
Firefox Vollständige Unterstützung 63
Vollständige Unterstützung 63
Keine Unterstützung 59 — 63
Deaktiviert
Deaktiviert From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.customelements.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Keine Unterstützung ? — 59
Deaktiviert
Deaktiviert Until version 59 (exclusive): this feature is behind the dom.webcomponents.enabled preference (needs to be set to true) and the dom.webcomponents.customelements.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Keine Unterstützung NeinOpera Vollständige Unterstützung 53
Hinweise
Vollständige Unterstützung 53
Hinweise
Hinweise Support for 'Customized built-in elements' as well.
Vollständige Unterstützung 41
Hinweise
Hinweise Support for 'Autonomous custom elements' only.
Safari Vollständige Unterstützung 10.1
Hinweise
Vollständige Unterstützung 10.1
Hinweise
Hinweise Supports 'Autonomous custom elements' but not 'Customized built-in elements'
WebView Android Vollständige Unterstützung 66
Hinweise
Vollständige Unterstützung 66
Hinweise
Hinweise Support for 'Customized built-in elements' as well.
Vollständige Unterstützung 54
Hinweise
Hinweise Support for 'Autonomous custom elements' only.
Chrome Android Vollständige Unterstützung 66
Hinweise
Vollständige Unterstützung 66
Hinweise
Hinweise Support for 'Customized built-in elements' as well.
Vollständige Unterstützung 54
Hinweise
Hinweise Support for 'Autonomous custom elements' only.
Firefox Android Vollständige Unterstützung 63
Vollständige Unterstützung 63
Keine Unterstützung 59 — 63
Deaktiviert
Deaktiviert From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.customelements.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Keine Unterstützung ? — 59
Deaktiviert
Deaktiviert Until version 59 (exclusive): this feature is behind the dom.webcomponents.enabled preference (needs to be set to true) and the dom.webcomponents.customelements.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Vollständige Unterstützung 47
Hinweise
Vollständige Unterstützung 47
Hinweise
Hinweise Support for 'Customized built-in elements' as well.
Vollständige Unterstützung 41
Hinweise
Hinweise Support for 'Autonomous custom elements' only.
Safari iOS Vollständige Unterstützung 10.3
Hinweise
Vollständige Unterstützung 10.3
Hinweise
Hinweise Supports 'Autonomous custom elements' but not 'Customized built-in elements'
Samsung Internet Android Vollständige Unterstützung 6.0
Hinweise
Vollständige Unterstützung 6.0
Hinweise
Hinweise Support for 'Autonomous custom elements' only.

Legende

Vollständige Unterstützung  
Vollständige Unterstützung
Keine Unterstützung  
Keine Unterstützung
Experimentell. Das Verhalten kann sich zukünftig ändern.
Experimentell. Das Verhalten kann sich zukünftig ändern.
Siehe Implementierungshinweise.
Siehe Implementierungshinweise.
Benutzer muss dieses Feature explizit aktivieren.
Benutzer muss dieses Feature explizit aktivieren.