diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 3e400c4cb..cc3806ac9 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -181,15 +181,15 @@ export const sidebar: ThemeConfig['sidebar'] = { link: '/guide/essentials/event-handling' }, { text: '表单输入绑定', link: '/guide/essentials/forms' }, - { - text: '生命周期', - link: '/guide/essentials/lifecycle' - }, { text: '侦听器', link: '/guide/essentials/watchers' }, { text: '模板引用', link: '/guide/essentials/template-refs' }, { text: '组件基础', link: '/guide/essentials/component-basics' + }, + { + text: 'Lifecycle Hooks', + link: '/guide/essentials/lifecycle' } ] }, diff --git a/.vitepress/theme/components/VueMasteryBanner.vue b/.vitepress/theme/components/VueMasteryBanner.vue deleted file mode 100644 index 0b42c4e69..000000000 --- a/.vitepress/theme/components/VueMasteryBanner.vue +++ /dev/null @@ -1,253 +0,0 @@ - - - - - - - diff --git a/src/guide/built-ins/teleport.md b/src/guide/built-ins/teleport.md index c45eed3ed..8d76b6c3f 100644 --- a/src/guide/built-ins/teleport.md +++ b/src/guide/built-ins/teleport.md @@ -4,9 +4,9 @@ ## 基本用法 {#basic-usage} -有时我们可能会遇到这样的场景：一个组件模板的一部分在逻辑上从属于该组件，但从整个应用视图的角度来看，它在 DOM 中应该被渲染在整个 Vue 应用外部的其他地方。 +有时我们可能会遇到这样的场景：一个组件模板的一部分在逻辑上从属于该组件，但从整个应用视图的角度来看，它在 DOM 中应该被渲染在其他地方，甚至在整个 Vue 应用外部。 -这类场景最常见的例子就是全屏的模态框。理想情况下，我们希望触发模态框的按钮和模态框本身是在同一个组件中，因为它们都与组件的开关状态有关。但这意味着该模态框将与按钮一起渲染在应用 DOM 结构里很深的地方。这会导致该模态框的 CSS 布局代码很难写。 +这类场景最常见的例子就是全屏的模态框。理想情况下，我们希望触发模态框的按钮和模态框本身的代码是在同一个组件中，因为它们都与组件的开关状态有关。但这意味着该模态框将与按钮一起渲染在应用 DOM 结构里很深的地方。这会导致该模态框的 CSS 布局代码很难写。 试想下面这样的 HTML 结构： @@ -159,7 +159,7 @@ const open = ref(false) ## 禁用 Teleport {#disabling-teleport} -在某些场景下可能需要视情况禁用 ``。举例来说，我们想要在桌面端将一个组件当做浮层来渲染，但在移动端则当作行内组件。我们可以通过对 `` 动态地传入一个 `disabled` prop 来处理这两种不同情况。 +在某些场景下可能需要视情况禁用 ``。举例来说，我们想要在桌面端将一个组件当做浮层来渲染，但在移动端则当作行内组件。我们可以通过对 `` 动态地传入一个 `disabled` prop 来处理这两种不同情况： ```vue-html @@ -167,11 +167,11 @@ const open = ref(false) ``` -这里的 `isMobile` 状态可以根据 CSS media query 的不同结果动态地更新。 +然后我们可以动态地更新 `isMobile`。 ## 多个 Teleport 共享目标 {#multiple-teleports-on-the-same-target} -一个可重用的模态框组件可能同时存在多个实例。对于此类场景，多个 `` 组件可以将其内容挂载在同一个目标元素上，而顺序就是简单的顺次追加，后挂载的将排在目标元素下更后面的位置上。 +一个可重用的 `` 组件可能同时存在多个实例。对于此类场景，多个 `` 组件可以将其内容挂载在同一个目标元素上，而顺序就是简单的顺次追加，后挂载的将排在目标元素下更后面的位置上，但都在目标元素中。 比如下面这样的用例： diff --git a/src/guide/components/registration.md b/src/guide/components/registration.md index 7f176d5d9..0e120c6a0 100644 --- a/src/guide/components/registration.md +++ b/src/guide/components/registration.md @@ -138,4 +138,4 @@ export default { 在单文件组件和内联字符串模板中，我们都推荐这样做。但是，PascalCase 的标签名在 DOM 内模板中是不可用的，详情参见 [DOM 内模板解析注意事项](/guide/essentials/component-basics#in-dom-template-parsing-caveats)。 -为了方便，Vue 支持将模板中使用 kebab-case 的标签解析为使用 PascalCase 注册的组件。这意味着一个以 `MyComponent` 为名注册的组件，在模板中可以通过 `` 或 `` 引用。这让我们能够使用同样的 JavaScript 组件注册代码来配合不同来源的模板。 +为了方便，Vue 支持将模板中使用 kebab-case 的标签解析为使用 PascalCase 注册的组件。这意味着一个以 `MyComponent` 为名注册的组件，在模板 (或由 Vue 渲染的 HTML 元素) 中可以通过 `` 或 `` 引用。这让我们能够使用同样的 JavaScript 组件注册代码来配合不同来源的模板。 diff --git a/src/guide/components/slots.md b/src/guide/components/slots.md index 32150caa0..fe5f8118f 100644 --- a/src/guide/components/slots.md +++ b/src/guide/components/slots.md @@ -298,12 +298,12 @@ function BaseLayout(slots) { ## 条件插槽 {#conditional-slots} -有时你需要根据插槽是否存在来渲染某些内容。 +有时你需要根据内容是否被传入了插槽来渲染某些内容。 你可以结合使用 [$slots](/api/component-instance.html#slots) 属性与 [v-if](/guide/essentials/conditional.html#v-if) 来实现。 在下面的示例中，我们定义了一个卡片组件，它拥有三个条件插槽：`header`、`footer` 和 `default`。 -当 header、footer 或 default 存在时，我们希望包装它们以提供额外的样式： +当 header、footer 或 default 的内容存在时，我们希望包装它以提供额外的样式： ```vue-html ``` +:::warning 注意 +同时使用 `v-if` 和 `v-for` 是**不推荐的**，因为这样二者的优先级不明显。 + +两种常见的情况可能导致这种用法： + +- 过滤列表中的项目 (例如，`v-for="user in users" v-if="user.isActive"`)。在这种情况下，可以用一个新的计算属性来替换 `users`，该属性返回过滤后的列表 (例如 `activeUsers`)。 + +- 避免渲染应该隐藏的列表 (例如 `v-for="user in users" v-if="shouldShowUsers"`)。在这种情况下，将 `v-if` 移至容器元素 (如 `ul`、`ol`)。 +::: + ## 通过 key 管理状态 {#maintaining-state-with-key} Vue 默认按照“就地更新”的策略来更新通过 `v-for` 渲染的元素列表。当数据项的顺序改变时，Vue 不会随之移动 DOM 元素的顺序，而是就地更新每个元素，确保它们在原本指定的索引位置上渲染。 @@ -267,7 +273,7 @@ Vue 默认按照“就地更新”的策略来更新通过 `v-for` 渲染的元 `key` 在这里是一个通过 `v-bind` 绑定的特殊 attribute。请不要和[在 `v-for` 中使用对象](#v-for-with-an-object)里所提到的对象属性名相混淆。 ::: -[推荐](/style-guide/rules-essential#use-keyed-v-for)在任何可行的时候为 `v-for` 提供一个 `key` attribute，除非所迭代的 DOM 内容非常简单 (例如：不包含组件或有状态的 DOM 元素)，或者你想有意采用默认行为来提高性能。 +推荐在任何可行的时候为 `v-for` 提供一个 `key` attribute，除非所迭代的 DOM 内容非常简单 (例如：不包含组件或有状态的 DOM 元素)，或者你想有意采用默认行为来提高性能。 `key` 绑定的值期望是一个基础类型的值，例如字符串或 number 类型。不要用对象作为 `v-for` 的 key。关于 `key` attribute 的更多用途细节，请参阅 [`key` API 文档](/api/built-in-special-attributes#key)。 diff --git a/src/guide/essentials/template-refs.md b/src/guide/essentials/template-refs.md index 102ab7410..e79c6dd0e 100644 --- a/src/guide/essentials/template-refs.md +++ b/src/guide/essentials/template-refs.md @@ -314,6 +314,8 @@ defineExpose({ 当父组件通过模板引用获取到了该组件的实例时，得到的实例类型为 `{ a: number, b: number }` (ref 都会自动解包，和一般的实例一样)。 +请注意，defineExpose 必须在任何 await 操作之前调用。否则，在 await 操作后暴露的属性和方法将无法访问。 + TypeScript 用户请参考：[为组件的模板引用标注类型](/guide/typescript/composition-api#typing-component-template-refs) diff --git a/src/guide/extras/web-components.md b/src/guide/extras/web-components.md index 88e9a80ac..57ae4d2a3 100644 --- a/src/guide/extras/web-components.md +++ b/src/guide/extras/web-components.md @@ -238,7 +238,7 @@ export function register() { } ``` -消费者可以使用 Vue 文件中的元素 +消费者可以使用 Vue 文件中的元素： ```vue