Vue3 v-cloak 指令

Vue3 内置指令

v-cloak 指令用于隐藏未编译的模板，直到组件实例准备完成。

基本说明

v-cloak 指令用于解决使用 DOM 模板时的"未编译模板闪烁"问题。当用户访问页面时，可能会看到原始的 {{ }} mustache 标签，直到 Vue 组件挂载并渲染内容。

v-cloak 会保留在元素上，直到关联的组件实例挂载完成。结合 CSS 规则，可以在此期间隐藏原始模板。

期望类型: 无（不接受表达式）
作用: 隐藏未编译的模板，直到组件准备完成。

注意：此指令仅在无构建步骤的设置中需要。

基本用法

在使用 v-cloak 时，需要配合 CSS 规则：

实例

/* CSS 规则：隐藏带有 v-cloak 的元素 */
[v-cloak] {
display: none;
}

实例

<div v-cloak>
{{ message }}
</div>

当编译完成时，v-cloak 属性会自动从元素上移除，元素才会显示出来。

使用场景

v-cloak 主要用于以下场景：

1、使用 CDN 引入 Vue

当使用 CDN 方式引入 Vue 而没有构建步骤时，页面加载到 Vue 脚本之间的短暂时间内，模板可能还未编译：

实例

<!DOCTYPE html>
<html>
<head>
<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
<style>
[v-cloak] {
display: none;
}
</style>
</head>
<body>
<div id="app">
<div v-cloak>
{{ message }}
</div>
</div>

<script>
const { createApp } = Vue

createApp({
data() {
return {
message: 'Hello Vue!'
}
}
}).mount('#app')
</script>
</body>
</html>

2、复杂模板结构

对于包含多个数据绑定的复杂模板，v-cloak 可以防止用户看到未渲染的内容：

实例

<div v-cloak>
<h1>{{ title }}</h1>
<p>欢迎，{{ username }}</p>
<ul>
<li v-for="item in items" :key="item.id">
{{ item.name }}
</li>
</ul>
</div>

v-cloak 的工作原理

页面加载时，Vue 尚未初始化，元素上的 v-cloak 属性存在
CSS 规则 [v-cloak] { display: none; } 隐藏了这些元素
Vue 初始化并编译模板，创建响应式数据
组件挂载后，Vue 自动移除 v-cloak 属性
元素显示，呈现渲染后的内容

注意事项

仅用于无构建步骤的场景：在使用构建工具（如 Vite、Webpack）时，模板在构建阶段已经编译好，不需要使用 v-cloak。

实例

/* 确保 v-cloak 规则在所有样式之前加载 */
/* 建议将 CSS 放在 head 中 */

<head>
<style>
[v-cloak] {
display: none;
}
</style>
</head>

需要配合 CSS 使用：v-cloak 本身不会隐藏内容，必须配合 CSS 规则才能生效。

与现代构建工具的区别

在使用现代构建工具（如 Vite）时，不需要使用 v-cloak，因为：

模板在构建阶段预先编译
JavaScript 打包后内联或异步加载
初始 HTML 不包含未编译的模板语法

因此，v-cloak 主要用于传统的 CDN 引入方式或简单的 HTML 页面场景。