Skip to content

Commit 3d825c1

Browse files
levidingleviding
committed
update some have not translate characters from upstream
1 parent 078ddb0 commit 3d825c1

13 files changed

Lines changed: 146 additions & 190 deletions

File tree

‎8-web-components/4-template-element/article.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ Let's rewrite a Shadow DOM example from the previous chapter using `<template>`:
8787
</script>
8888
```
8989

90-
In the line `(*)` when we clone and insert `tmpl.content`, as it's `DocumentFragment`, its children (`<style>`, `<p>`) are inserted instead.
90+
In the line `(*)` when we clone and insert `tmpl.content`, as its `DocumentFragment`, its children (`<style>`, `<p>`) are inserted instead.
9191

9292
They form the shadow DOM:
9393

@@ -110,7 +110,7 @@ To summarize:
110110
The `<template>` tag is quite unique, because:
111111

112112
- The browser checks HTML syntax inside it (as opposed to using a template string inside a script).
113-
- ...But still allows to use any top-level HTML tags, even those that don't make sense without proper wrappers (e.g. `<tr>`).
113+
- ...But still allows use of any top-level HTML tags, even those that don't make sense without proper wrappers (e.g. `<tr>`).
114114
- The content becomes interactive: scripts run, `<video autoplay>` plays etc, when inserted into the document.
115115

116116
The `<template>` element does not feature any iteration mechanisms, data binding or variable substitutions, but we can implement those on top of it.

‎8-web-components/5-slots-composition/article.md‎

Lines changed: 43 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ customElements.define('user-card', class extends HTMLElement {
5858

5959
In the shadow DOM, `<slot name="X">` defines an "insertion point", a place where elements with `slot="X"` are rendered.
6060

61-
Then the browser performs "composition": it takes elements from the light DOM and renders them in corresponding slots of the shadow DOM. At the end, we have exactly what we want -- a generic component that can be filled with data.
61+
Then the browser performs "composition": it takes elements from the light DOM and renders them in corresponding slots of the shadow DOM. At the end, we have exactly what we want -- a component that can be filled with data.
6262

6363
Here's the DOM structure after the script, not taking composition into account:
6464

@@ -76,7 +76,7 @@ Here's the DOM structure after the script, not taking composition into account:
7676
</user-card>
7777
```
7878

79-
There's nothing odd here. We created the shadow DOM, so here it is. Now the element has both light and shadow DOM.
79+
We created the shadow DOM, so here it is, under `#shadow-root`. Now the element has both light and shadow DOM.
8080

8181
For rendering purposes, for each `<slot name="...">` in shadow DOM, the browser looks for `slot="..."` with the same name in the light DOM. These elements are rendered inside the slots:
8282

@@ -89,7 +89,7 @@ The result is called "flattened" DOM:
8989
#shadow-root
9090
<div>Name:
9191
<slot name="username">
92-
<!-- slotted element is inserted into the slot as a whole -->
92+
<!-- slotted element is inserted into the slot -->
9393
<span slot="username">John Smith</span>
9494
</slot>
9595
</div>
@@ -101,16 +101,16 @@ The result is called "flattened" DOM:
101101
</user-card>
102102
```
103103

104-
...But the "flattened" DOM is only created for rendering and event-handling purposes. That's how things are shown. The nodes are actually not moved around!
104+
...But the flattened DOM exists only for rendering and event-handling purposes. It's kind of "virtual". That's how things are shown. But the nodes in the document are actually not moved around!
105105

106-
That can be easily checked if we run `querySelector`: nodes are still at their places.
106+
That can be easily checked if we run `querySelectorAll`: nodes are still at their places.
107107

108108
```js
109109
// light DOM <span> nodes are still at the same place, under `<user-card>`
110-
alert( document.querySelector('user-card span').length ); // 2
110+
alert( document.querySelectorAll('user-card span').length ); // 2
111111
```
112112

113-
It may look bizarre, but for shadow DOM with slots we have one more "DOM level", the "flattened" DOM -- result of slot insertion. The browser renders it and uses for style inheritance, event propagation. But JavaScript still sees the document "as is", before flattening.
113+
So, the flattened DOM is derived from shadow DOM by inserting slots. The browser renders it and uses for style inheritance, event propagation (more about that later). But JavaScript still sees the document "as is", before flattening.
114114

115115
````warn header="Only top-level children may have slot=\"...\" attribute"
116116
The `slot="..."` attribute is only valid for direct children of the shadow host (in our example, `<user-card>` element). For nested elements it's ignored.
@@ -120,18 +120,43 @@ For example, the second `<span>` here is ignored (as it's not a top-level child
120120
<user-card>
121121
<span slot="username">John Smith</span>
122122
<div>
123-
<!-- bad slot, not top-level: -->
123+
<!-- invalid slot, must be direct child of user-card -->
124124
<span slot="birthday">01.01.2001</span>
125125
</div>
126126
</user-card>
127127
```
128-
129-
In practice, there's no sense in slotting a deeply nested element, so this limitation just ensures the correct DOM structure.
130128
````
131129

130+
If there are multiple elements in light DOM with the same slot name, they are appended into the slot, one after another.
131+
132+
For example, this:
133+
```html
134+
<user-card>
135+
<span slot="username">John</span>
136+
<span slot="username">Smith</span>
137+
</user-card>
138+
```
139+
140+
Gives this flattened DOM with two elements in `<slot name="username">`:
141+
142+
```html
143+
<user-card>
144+
#shadow-root
145+
<div>Name:
146+
<slot name="username">
147+
<span slot="username">John</span>
148+
<span slot="username">Smith</span>
149+
</slot>
150+
</div>
151+
<div>Birthday:
152+
<slot name="birthday"></slot>
153+
</div>
154+
</user-card>
155+
```
156+
132157
## Slot fallback content
133158

134-
If we put something inside a `<slot>`, it becomes the fallback content. The browser shows it if there's no corresponding filler in light DOM.
159+
If we put something inside a `<slot>`, it becomes the fallback, "default" content. The browser shows it if there's no corresponding filler in light DOM.
135160

136161
For example, in this piece of shadow DOM, `Anonymous` renders if there's no `slot="username"` in light DOM.
137162

@@ -141,11 +166,11 @@ For example, in this piece of shadow DOM, `Anonymous` renders if there's no `slo
141166
</div>
142167
```
143168

144-
## Default slot
169+
## Default slot: first unnamed
145170

146171
The first `<slot>` in shadow DOM that doesn't have a name is a "default" slot. It gets all nodes from the light DOM that aren't slotted elsewhere.
147172

148-
For example, let's add the default slot to our `<user-card>` that collects any unslotted information about the user:
173+
For example, let's add the default slot to our `<user-card>` that shows all unslotted information about the user:
149174

150175
```html run autorun="no-epub" untrusted height=140
151176
<script>
@@ -243,7 +268,7 @@ The shadow DOM template with proper slots:
243268
```
244269

245270
1. `<span slot="title">` goes into `<slot name="title">`.
246-
2. There are many `<li slot="item">` in the template, but only one `<slot name="item">` in the template. That's perfectly normal. All elements with `slot="item"` get appended to `<slot name="item">` one after another, thus forming the list.
271+
2. There are many `<li slot="item">` in the template, but only one `<slot name="item">` in the template. So all such `<li slot="item">` are appended to `<slot name="item">` one after another, thus forming the list.
247272

248273
The flattened DOM becomes:
249274

@@ -293,15 +318,15 @@ Here's the full demo:
293318

294319
Of course, we can add more functionality to it: events, methods and so on.
295320

296-
## Monitoring slots
321+
## Updating slots
297322

298323
What if the outer code wants to add/remove menu items dynamically?
299324

300325
**The browser monitors slots and updates the rendering if slotted elements are added/removed.**
301326

302327
Also, as light DOM nodes are not copied, but just rendered in slots, the changes inside them immediately become visible.
303328

304-
So we don't have to do anything to update rendering. But if the component wants to know about slot changes, then `slotchange` event is available.
329+
So we don't have to do anything to update rendering. But if the component code wants to know about slot changes, then `slotchange` event is available.
305330

306331
For example, here the menu item is inserted dynamically after 1 second, and the title changes after 2 seconds:
307332

@@ -406,7 +431,7 @@ setTimeout(() => {
406431

407432
## Summary
408433

409-
Slots allow to show light DOM children in shadow DOM.
434+
Usually, if an element has shadow DOM, then its light DOM is not displayed. Slots allow to show elements from light DOM in specified places of shadow DOM.
410435

411436
There are two kinds of slots:
412437

@@ -427,6 +452,6 @@ If we'd like to know what we're showing, we can track slot contents using:
427452
- `slotchange` event -- triggers the first time a slot is filled, and on any add/remove/replace operation of the slotted element, but not its children. The slot is `event.target`.
428453
- [MutationObserver](info:mutation-observer) to go deeper into slot content, watch changes inside it.
429454

430-
Now, as we have elements from light DOM in the shadow DOM, let's see how to style them properly. The basic rule is that shadow elements are styled inside, and light elements -- outside, but there are notable exceptions.
455+
Now, as we know how to show elements from light DOM in shadow DOM, let's see how to style them properly. The basic rule is that shadow elements are styled inside, and light elements -- outside, but there are notable exceptions.
431456

432457
We'll see the details in the next chapter.

0 commit comments

Comments
 (0)