suspense

Author: yyx990803

src/guide/built-ins/suspense.md

@@ -1,15 +1,134 @@
-# Suspense <Badge type="warning" text="experimental" />
+---
+aside: deep
+---
 
-## Basic Usage
+# Suspense
+
+:::warning Experimental Feature
+`<Suspense>` is an experimental feature. It is not guaranteed to reach stable status and the API may change before it does.
+:::
+
+`<Suspense>` is a built-in component for orchestrating async dependencies in a component tree. It can render a loading state while waiting for multiple nested async dependencies down the component tree to be resolved.
+
+## Async Dependencies
+
+To explain the problem `<Suspense>` is trying to solve and how it interacts with these async dependencies, let's imagine a component hierarchy like the following:
+
+```
+<Suspense>
+└─ <Dashboard>
+   ├─ <Profile>
+   │  └─ <FriendStatus> (component with async setup())
+   └─ <Content>
+      ├─ <ActivityFeed> (async component)
+      └─ <Stats> (async component)
+```
+
+In the component tree there are multiple nested components whose rendering depends on some async resource to be resolved first. Without `<Suspense>`, each of them will need to handle its own loading / error and loaded states. In the worst case scenario, we may see three loading spinners on the page, with content displayed at different times.
+
+The `<Suspense>` component gives us the ability to display top-level loading / error states while we wait on these nested async dependencies to be resolved.
+
+There are two types of async dependencies that `<Suspense>` can wait on:
+
+1. Components with an async `setup()` hook. This includes components with `<script setup>` that contains top-level `await` expressions.
+
+2. [Async Components](/guide/components/async.html).
 
 ### `async setup()`
 
+A Composition API component's `setup()` hook can be async:
+
+```js
+export default {
+  async setup() {
+    const res = await fetch(...)
+    const posts = await res.json()
+    return {
+      posts
+    }
+  }
+}
+```
+
+If using `<script setup>`, the presence of top-level `await` expressions automatically makes the component an async dependency:
+
+```vue
+<script setup>
+const res = await fetch(...)
+const posts = await res.json()
+</script>
+
+<template>
+  {{ posts }}
+</template>
+```
+
 ### Async Components
 
-Async components are _suspensible_ by default. This means if it has a `<Suspense>` in the parent chain, it will be treated as an async dependency of that `<Suspense>`. In this case, the loading state will be controlled by the `<Suspense>`, and the component's own loading, error, delay and timeout options will be ignored.
+Async components are **"suspensible"** by default. This means that if it has a `<Suspense>` in the parent chain, it will be treated as an async dependency of that `<Suspense>`. In this case, the loading state will be controlled by the `<Suspense>`, and the component's own loading, error, delay and timeout options will be ignored.
 
 The async component can opt-out of `Suspense` control and let the component always control its own loading state by specifying `suspensible: false` in its options.
 
 ## Loading State
 
+The `<Suspense>` component has two slots: `#default` and `#fallback`. Both slots only allow for **one** immediate child node. The node in the default slot is shown if possible. If not, the node in the fallback slot will be shown instead.
+
+```vue-html
+<Suspense>
+  <!-- component with nested async dependencies -->
+  <Dashboard />
+
+  <!-- loading state via #fallback slot -->
+  <template #fallback>
+    Loading...
+  </template>
+</Suspense>
+```
+
+On initial render, `<Suspense>` will render its default slot content in memory. If any async dependencies are encountered during the process, it will enter **pending** state. During pending state, the fallback content will be displayed. When all encountered async dependencies have been resolved, `<Suspense>` enters **resolved** state and the resolved default slot content is displayed.
+
+If no async dependencies were encountered during the initial render, `<Suspense>` will directly go into resolved state.
+
+Once in resolved state, `<Suspense>` will only revert to pending state if the root node of the `#default` slot is replaced. New async dependencies nested deeper in the tree will **not** cause the `<Suspense>` to revert into pending state.
+
+When a revert happens, fallback content will not be immediately displayed. Instead, `<Suspense>` will display the previous `#default` content while waiting for the new content and its async dependencies to be resolved. This behavior can be configured with the `timeout` prop: `<Suspense>` will switch to fallback content if it takes longer than `timeout` to render the new default content. A `timeout` value of `0` will cause the fallback content to be displayed immediately when default content is replaced.
+
+## Events
+
+In addition to the `pending` event, the `<suspense>` component also has `resolve` and `fallback` events. The `resolve` event is emitted when new content has finished resolving in the `default` slot. The `fallback` event is fired when the contents of the `fallback` slot are shown.
+
+The events could be used, for example, to show a loading indicator in front of the old DOM while new components are loading.
+
 ## Error Handling
+
+`<Suspense>` currently does not provide error handling via the component itself - however, you can use the [`errorCaptured`](/api/options-lifecycle.html#errorcaptured) option or the [`onErrorCaptured()`](/api/composition-api-lifecycle.html#onerrorcaptured) hook to capture and handle async errors in the parent component of `<Suspense>`.
+
+## Combining with Other Components
+
+It is common to want to use `<Suspense>` in combination with the [`<Transition>`](./transition) and [`<KeepAlive>`](./keep-alive) components. The nesting order of these components is important to get them all working correctly.
+
+In addition, these components are often used in conjunction with the `<RouterView>` component from [Vue Router](https://next.router.vuejs.org/).
+
+The following example shows how to nest these components so that they all behave as expected. For simpler combinations you can remove the components that you don't need:
+
+```vue-html
+<RouterView v-slot="{ Component }">
+  <template v-if="Component">
+    <Transition mode="out-in">
+      <KeepAlive>
+        <Suspense>
+          <!-- main content -->
+          <component :is="Component"></component>
+
+          <!-- loading state -->
+          <template #fallback>
+            Loading...
+          </template>
+        </Suspense>
+      </KeepAlive>
+    </Transition>
+  </template>
+</RouterView>
+```
+
+Vue Router has built-in support for [lazily loading components](https://next.router.vuejs.org/guide/advanced/lazy-loading.html) using dynamic imports. These are distinct from async components and currently they will not trigger `<Suspense>`. However, they can still have async components as descendants and those can trigger `<Suspense>` in the usual way.

src/guide/components/slots.md

@@ -232,6 +232,24 @@ Here's the code passing content to all three slots to `<BaseLayout>` using the s
 </BaseLayout>
 ```
 
+When a component accepts both default slot and named slots, all top-level non-`<template>` nodes are implciitly treated as content for default slot. So the above can also be written as:
+
+```vue-html
+<BaseLayout>
+  <template #header>
+    <h1>Here might be a page title</h1>
+  </template>
+
+  <!-- implicit default slot -->
+  <p>A paragraph for the main content.</p>
+  <p>And another one.</p>
+
+  <template #footer>
+    <p>Here's some contact info</p>
+  </template>
+</BaseLayout>
+```
+
 Now everything inside the `<template>` elements will be passed to the corresponding slots. The final rendered HTML will be:
 
 ```html