ShadowRoot

Shadow DOM API 的 ShadowRoot 接口是一个 DOM 子树的根节点, 它与文档的主DOM树分开渲染。

You can retrieve a reference to an element's shadow root using its Element.shadowRoot property, provided it was created using Element.attachShadow() with the mode option set to open.

属性

ShadowRoot.delegatesFocus 只读
Returns a boolean that indicates whether delegatesFocus was set when the shadow was attached (see Element.attachShadow()).
ShadowRoot.host 只读
ShadowRoot 附加的宿主 DOM 元素。
ShadowRoot.innerHTML
ShadowRoot 内部的 DOM 树。
ShadowRoot.mode 只读
ShadowRoot 的模式——可以是 open 或者 closed。这定义了 shadow root 的内部实现是否可被 JavaScript 访问及修改 — 也就是说,该实现是否公开,例如,<video> 标签内部实现无法被 JavaScript 访问及修改。

Properties included from DocumentOrShadowRoot

The ShadowRoot interface includes the following properties defined on the DocumentOrShadowRoot mixin. Note that this is currently only implemented by Chrome; other browsers still implement them on the Document interface.

DocumentOrShadowRoot.activeElement 只读
Returns the Element within the shadow tree that has focus.
DocumentOrShadowRoot.styleSheets 只读
Returns a StyleSheetList of CSSStyleSheet objects for stylesheets explicitly linked into, or embedded in a document.

方法

The ShadowRoot interface includes the following methods defined on the DocumentOrShadowRoot mixin. Note that this is currently only implemented by Chrome; other browsers still implement them on the Document interface.

DocumentOrShadowRoot.getSelection()
Returns a Selection object representing the range of text selected by the user, or the current position of the caret.
DocumentOrShadowRoot.elementFromPoint()
Returns the topmost element at the specified coordinates.
DocumentOrShadowRoot.elementsFromPoint()
Returns an array of all elements at the specified coordinates.
DocumentOrShadowRoot.caretPositionFromPoint()
Returns a CaretPosition object containing the DOM node containing the caret, and caret's character offset within that node.

例子

The following snippets are taken from our life-cycle-callbacks example (see it live also), which creates an element that displays a square of a size and color specified in the element's attributes.

Inside the <custom-square> element's class definition we include some life cycle callbacks that make a call to an external function, updateStyle(), which actually applies the size and color to the element. You'll see that we are passing it this (the custom element itself) as a parameter.

connectedCallback() {
  console.log('Custom square element added to page.');
  updateStyle(this);
}

attributeChangedCallback(name, oldValue, newValue) {
  console.log('Custom square element attributes changed.');
  updateStyle(this);
}

In the updateStyle() function itself, we get a reference to the shadow DOM using Element.shadowRoot. From here we use standard DOM traversal techniques to find the <style> element inside the shadow DOM and then update the CSS found inside it:

function updateStyle(elem) {
  var shadow = elem.shadowRoot;
  var childNodes = shadow.childNodes;
  for(var i = 0; i < childNodes.length; i++) {
    if(childNodes[i].nodeName === 'STYLE') {
      childNodes[i].textContent =
        'div {' +
          'width: ' + elem.getAttribute('l') + 'px;' +
          'height: ' + elem.getAttribute('l') + 'px;' +
          'background-color: ' + elem.getAttribute('c') + ';' +
        '}';
    }
  }
}

规范

Specification Status Comment
DOM
Interface ShadowRoot
Living Standard

浏览器兼容性

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
ShadowRoot
Experimental
Chrome Full support 57Edge No support No
Notes
No support No
Notes
Notes In Development
Firefox Full support 63
Full support 63
No support 59 — 63
Disabled
Disabled From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 40Safari Full support 10.1WebView Android Full support 57Chrome Android Full support 57Firefox Android Full support 63
Full support 63
No support 59 — 63
Disabled
Disabled From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 41Safari iOS Full support 10.3Samsung Internet Android Full support 6.0
delegatesFocus
Experimental
Chrome Full support 57Edge No support NoFirefox ? IE No support NoOpera ? Safari No support NoWebView Android Full support 57Chrome Android Full support 57Firefox Android ? Opera Android ? Safari iOS No support NoSamsung Internet Android ?
Features included from the DocumentOrShadowRoot mixin
Experimental
Chrome Full support 57Edge No support No
Notes
No support No
Notes
Notes Features still implemented on the Document interface
Firefox Full support 63IE No support NoOpera Full support 40Safari No support No
Notes
No support No
Notes
Notes Features still implemented on the Document interface
WebView Android Full support 57Chrome Android Full support 57Firefox Android Full support 63Opera Android Full support 41Safari iOS No support No
Notes
No support No
Notes
Notes Features still implemented on the Document interface
Samsung Internet Android Full support 6.0
host
Experimental
Chrome Full support 57Edge No support No
Notes
No support No
Notes
Notes In Development
Firefox Full support 63
Full support 63
No support 59 — 63
Disabled
Disabled From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 40Safari Full support 10.1WebView Android Full support 57Chrome Android Full support 57Firefox Android Full support 63
Full support 63
No support 59 — 63
Disabled
Disabled From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 41Safari iOS Full support 10.3Samsung Internet Android Full support 6.0
innerHTML
ExperimentalNon-standard
Chrome Full support 57Edge No support No
Notes
No support No
Notes
Notes In Development
Firefox Full support 63
Full support 63
No support 59 — 63
Disabled
Disabled From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 40Safari Full support 10.1WebView Android Full support 57Chrome Android Full support 57Firefox Android Full support 63
Full support 63
No support 59 — 63
Disabled
Disabled From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 41Safari iOS Full support 10.3Samsung Internet Android Full support 6.0
mode
Experimental
Chrome Full support 57Edge No support No
Notes
No support No
Notes
Notes In Development
Firefox Full support 63
Full support 63
No support 59 — 63
Disabled
Disabled From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 40Safari Full support 10.1WebView Android Full support 57Chrome Android Full support 57Firefox Android Full support 63
Full support 63
No support 59 — 63
Disabled
Disabled From version 59 until version 63 (exclusive): this feature is behind the dom.webcomponents.shadowdom.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 41Safari iOS Full support 10.3Samsung Internet Android Full support 6.0

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.
See implementation notes.
See implementation notes.
User must explicitly enable this feature.
User must explicitly enable this feature.