Using templates and slots

这篇翻译不完整。请帮忙从英语翻译这篇文章

这篇文章阐述了如何 使用 <template><slot> 元素创建一个弹性(flexible) 模板,这个模板将用在web 组件的 shadow(阴影) DOM上

关于模板的事实

当你想想在一个网页上重复使用同一个 html 脚本的结构片断时,使用某一种模板比复制 html 结构代码更有意义.  这已经是可能 的, 但是使用  HTML 的 <template>(现代浏览器已经很好支持)元素更加简单.  这个模板元素不会被DOM 渲染但是仍然能被 javascript 引用.

让我们看一个普通的简短的例子:

<template id="my-paragraph">
  <p>My paragraph</p>
</template>

上面的代码不会展示在你的页面中,直到你用 JavaScript 获取它的引用,然后添加(append) 到DOM中, 如下面的代码:

let template = document.getElementById('my-paragraph');
let templateContent = template.content;
document.body.appendChild(templateContent);

很简单,但是你已经看到了该如何使用了。

和web 组件一起使用模板

模板(Templates) 本身是有用的,  但是与 web 组件(web component) 一起使用效果加好.  定义一个 web 组件使用模板作为阴影(shadow)DOM 的内容. 我们叫它 <my-paragraph>:

customElements.define('my-paragraph',
  class extends HTMLElement {
    constructor() {
      super();
      let template = document.getElementById('my-paragraph');
      let templateContent = template.content;

      const shadowRoot = this.attachShadow({mode: 'open'})
        .appendChild(templateContent.cloneNode(true));
  }
})

要注意的关键是我们使用Node.cloneNode() 方法添加了模板(template) 的拷贝到阴影(shadow) 的根结点上.

因为我们添加了模板的内容了到阴影(shadow) DOM, 我们可以加入一些样式信息到模板(template)的 <style> 标签里, 稍后封装到自定义的元素中. 如果将它添加到一个标准的DOM是不起作用的

比如:

<template id="my-paragraph">
  <style>
    p {
      color: white;
      background-color: #666;
      padding: 5px;
    }
  </style>
  <p>My paragraph</p>
</template>

现在我们将它添加自己的 HTML 档案中试试看:

<my-paragraph></my-paragraph>

Note: 虽然模板(templates) 在浏览器中很好的支持了, 但是 Shadow DOM 还没有.  Shadow DOM 在 Chrome 和 Opera已经支持了. 火狐也快了(注:翻译的时候已经支持了);  将火狐的preferences(地址栏输入 about:config) 的dom.webcomponents.enabled 设为 true. 火狐的实现将在60/61版本开启. Safari 已经支持 shadow DOM了, Edge也正在努力.

使用槽(slot) 添加灵活度

顺利到这一步,  元素不是很灵活. 我们只能在里面放一点文本, 甚至没有普通的 p标签管用! 我们使用 <slot> 让它能在单个实例中通过声明式的语法展示不同的文本. 这个功能比 <template>支持的更少, 在Chrome 53, Opera 40, Safari 10, 火狐 59 中支持, Edge不支持.

槽(slot) 使用 name 属性作为id, 你能在模板(tempalte) 中定义任意的 html 片断作为占位符,在模板对象被使用在html 脚本中时.

如果你想添加一个槽(slot) 到这个普通的例子,我们将模板(tempalte) 的 p 标签改成下面这样:

<p><slot name="my-text">My default text</slot></p>

如果模板对象添加到html 脚本中时槽(slot)的内容还没定义, 或者浏览器不支持槽(slot) , <my-paragraph>  将显示默认的 "My default text".

要定义槽(slot) 的内容, 我们添加一段含有slot 属性的 html结构到 <my-paragraph> 元素中,slot 属性的值就是任何你想填的槽的名字

<my-paragraph>
  <span slot="my-text">Let's have some different text!</span>
</my-paragraph>

或者

<my-paragraph>
  <ul slot="my-text">
    <li>Let's have some different text!</li>
    <li>In a list!</li>
  </ul>
</my-paragraph>

以上为例.

Note: 将能被插入到槽(slot)中的元素视为 Slotable; 称已经插入到slot 中的元素叫 slotted.

这就我们普通的例子,你想更深入了解你可以 在GitHub上查看 (也可以看 在线运行).

更深入的例子

为了了结这篇文章,我们来个看一个不简单的.

下面的一组代码集展示我们如何联合使用 <slot><template> 以及一些 JavaScript来

注意,技术上讲没有<template> 使用 <slot> 也是可以的, 例如.,  <slot> 在一个常规的<div> 标签里, 仍然有占位符的特性, 就你在阴影(Shadow)DOM 中一样, 这样我们能避免需要先获取模板对象的 content 属性再使用它的麻烦. 然而这个特性在向一个 <template> 元素中添加槽时更加实用, 因为你不会基于一个渲染的元素定义一个模式.

另外,就算它还没有渲染,使用<template>时,作为模板的容器应该语义上应当干净. 而且 <template>   可以直接挂一些对象, 如  <td> ,当加到一个 <div> 中时会隐藏.

Note: 查看在完整的例子在 element-details ( 在线运行 ).

使用槽(slot) 创建一个模板

首先,我们在<template> 使用  <slot> 标签创建一个"element-details-template"包含一些 命名的槽(named slot)  的 文档片断(document fragment)

<template id="element-details-template">
  <style>
  details {font-family: "Open Sans Light",Helvetica,Arial}
  .name {font-weight: bold; color: #217ac0; font-size: 120%}
  h4 { margin: 10px 0 -8px 0; }
  h4 span { background: #217ac0; padding: 2px 6px 2px 6px }
  h4 span { border: 1px solid #cee9f9; border-radius: 4px }
  h4 span { color: white }
  .attributes { margin-left: 22px; font-size: 90% }
  .attributes p { margin-left: 16px; font-style: italic }
  </style>
  <details>
    <summary>
      <span>
        <code class="name">&lt;<slot name="element-name">NEED NAME</slot>&gt;</code>
        <i class="desc"><slot name="description">NEED DESCRIPTION</slot></i>
      </span>
    </summary>
    <div class="attributes">
      <h4><span>Attributes</span></h4>
      <slot name="attributes"><p>None</p></slot>
    </div>
  </details>
  <hr>
</template>

上面这个<template> 有几个特征

从<template> 中创建一个新的 <element-details> 对象

接下来,我们定义一个新的 <element-details> 元素然后用 Element.attachShadow 来将它附着到它的 阴影(shadow) root, 这个阴影上我们创建了 <template> 元素. 这和我们上面使用的简单例子中的一样.

customElements.define('element-details',
  class extends HTMLElement {
    constructor() {
      super();
      var template = document
        .getElementById('element-details-template')
        .content;
      const shadowRoot = this.attachShadow({mode: 'open'})
        .appendChild(template.cloneNode(true));
  }
})

结合命名的 slots 使用自定义元素 <element-details>

Now let’s take that <element-details> element and actually use it in our document.

<element-details>
  <span slot="element-name">slot</span>
  <span slot="description">A placeholder inside a web
    component that users can fill with their own markup,
    with the effect of composing different DOM trees
    together.</span>
  <dl slot="attributes">
    <dt>name</dt>
    <dd>The name of the slot.</dd>
  </dl>
</element-details>

<element-details>
  <span slot="element-name">template</span>
  <span slot="description">A mechanism for holding client-
    side content that is not to be rendered when a page is
    loaded but may subsequently be instantiated during
    runtime using JavaScript.</span>
</element-details> 

About that snippet, notice these points:

  • The snippet has two instances of <element-details> elements which both use the slot attribute to reference the named slots "element-name" and "description" we put in the <element-details> shadow root .
  • Only the first of those two <element-details> elements references the "attributes" named slot. The second <element-details> element lacks any reference to the "attributes" named slot.
  • The first <element-details> element references the "attributes" named slot using a <dl> element with <dt> and <dd> children.

添加一些最终的样式

As a finishing touch, we'll add a tiny bit more CSS for the <dl>, <dt>, and <dd> elements in our doc.

  dl { margin-left: 6px; }
  dt { font-weight: bold; color: #217ac0; font-size: 110% }
  dt { font-family: Consolas, "Liberation Mono", Courier }
  dd { margin-left: 16px }

结果

Finally let’s put all the snippets together and see what the rendered result looks like.

ScreenshotLive sample

Notice the following points about this rendered result:

  • Even though the instances of the <element-details> element in the document do not directly use the <details> element, they get rendered using <details> because the shadow root causes them to get populated with that.
  • Within the rendered <details> output, the content in the <element-details> elements fills the named slots from the shadow root. In other words, the DOM tree from the <element-details> elements get composed together with the content of the shadow root.
  • For both <element-details> elements, an Attributes heading gets automatically added from the shadow root before the position of the "attributes" named slot.
  • Because the first <element-details> has a <dl> element which explicitly references the "attributes" named slot from its shadow root, the contents of that <dl> replace the "attributes" named slot from the shadow root.
  • Because the second <element-details> doesn’t explicitly reference the "attributes" named slot from its shadow root, its content for that named slot gets filled with the default content for it from the shadow root.

文档标签和贡献者

此页面的贡献者: xrr2016, zxk7516
最后编辑者: xrr2016,