解决 Vue.js 中 $refs 在循环内失效的 TypeError 问题

本文深入探讨了 vue.js 中 `this.$refs` 在 `v-for` 循环内使用时可能导致的 `typeerror: this.$refs.xxx.show is not a function` 错误。该错误通常源于 `ref` 属性在循环中被重复定义，导致 `this.$refs` 无法正确获取单个组件实例。教程将详细解释其根本原因，并提供将带 `ref` 的组件移至循环外部的解决方案，确保 `this.$refs` 始终指向唯一的组件实例，从而有效解决此问题。

在 Vue.js 应用开发中，我们经常需要直接访问子组件或 DOM 元素。Vue 提供了一个特殊的属性 ref 来实现这一目的。当 ref 属性被注册后，可以通过 this.$refs 对象来访问对应的 DOM 元素或组件实例。例如，this.$refs.myComponent 将指向模板中 ref="myComponent" 的组件实例。然而，当在 v-for 循环中使用带有 ref 属性的组件时，可能会遇到 TypeError: this.$refs.xxx.show is not a function 这样的错误。

理解 this.$refs 的工作机制

this.$refs 是一个对象，它包含所有注册了 ref 属性的 DOM 元素或组件实例。通常情况下，我们为组件或 DOM 元素设置一个唯一的 ref 名称，并通过 this.$refs.refName 来获取它。当 Vue 渲染组件时，它会收集这些 ref，并在组件实例上暴露 this.$refs 对象。

错误现象：TypeError: this.$refs.xxx.show is not a function

当在一个 v-for 循环内部放置一个带有 ref 属性的组件，并尝试通过 this.$refs.refName 来调用其方法时，例如 this.$refs.confirmDialogue.show()，可能会抛出 TypeError: this.$refs.confirmDialogue.show is not a function 错误。奇怪的是，在循环外部使用相同逻辑的按钮却能正常工作。

让我们看一个典型的场景：一个 ConfirmDialogue 组件被设计成一个弹窗，通过 show() 方法来显示。在一个表格中，每个行都有一个删除按钮，点击后需要弹出确认对话框。

立即学习“前端免费学习笔记（深入）”；

问题代码示例：

<!-- 这是一个表格行，在 v-for 循环中生成 -->
<template>
    <tr>
        <td>...</td>
        <td id="buttonCell">
            <button class="button" @click="doDelete">删除</button>
            <!-- 问题所在：ConfirmDialogue 在循环内部被重复渲染 -->
            <confirm-dialogue ref="confirmDialogue"></confirm-dialogue>
        </td>
    </tr>
</template>

<script>
import ConfirmDialogue from "../confirmDialogue/ConfirmDialogue.vue";

export default {
    name: "bookElements",
    components: { ConfirmDialogue },
    methods: {
        async doDelete() {
            // 尝试调用 this.$refs.confirmDialogue.show()
            const ok = await this.$refs.confirmDialogue.show({
                title: '删除确认',
                message: '确定要删除吗？',
                okButton: '删除',
            });
            if (ok) {
                alert('已成功删除');
            }
        },
    },
};
</script>

当 <tr> 元素在一个 v-for 循环中被渲染多次时，每个 <tr> 都会包含一个 <confirm-dialogue ref="confirmDialogue"></confirm-dialogue> 实例。

根本原因分析

这个 TypeError 的根本原因在于 this.$refs 的行为。当一个 ref 属性被用于 v-for 循环内部的多个元素或组件时，this.$refs.refName 不再是一个单一的组件实例，而是一个组件实例数组。

AI建筑知识问答

用人工智能ChatGPT帮你解答所有建筑问题

22

查看详情

例如，如果循环渲染了 9 个 ConfirmDialogue 组件，那么 this.$refs.confirmDialogue 将是一个包含 9 个 ConfirmDialogue 实例的数组。当你尝试在数组上直接调用 show() 方法时，JavaScript 会抛出 TypeError，因为数组本身没有 show 方法。

而在循环外部的正常工作按钮，其对应的 ConfirmDialogue 组件只被渲染了一次，this.$refs.confirmDialogue 是一个单一的组件实例，因此 show() 方法可以被正确调用。

解决方案：将带有 ref 的组件移出循环

对于像确认对话框这样通常只需要一个全局实例的组件，最佳实践是将其放置在模板的顶层或父组件中，确保它只被渲染一次。这样，this.$refs.confirmDialogue 就能始终指向唯一的组件实例。

修正后的代码示例：

<template>
    <div>
        <!-- 将 ConfirmDialogue 移到模板的顶层，确保它只被渲染一次 -->
        <confirm-dialogue ref="confirmDialogue"></confirm-dialogue>

        <!-- 以下是 v-for 循环渲染的表格内容 -->
        <table>
            <thead>
                <tr>
                    <th>...</th>
                    <th>操作</th>
                </tr>
            </thead>
            <tbody>
                <!-- 假设这是在一个 v-for 循环中 -->
                <tr v-for="item in items" :key="item.id">
                    <td>{{ item.name }}</td>
                    <td>
                        <button class="button" @click="doDelete(item)">删除</button>
                        <!-- 这里不再需要重复渲染 ConfirmDialogue -->
                    </td>
                </tr>
            </tbody>
        </table>
    </div>
</template>

<script>
import ConfirmDialogue from "../confirmDialogue/ConfirmDialogue.vue";

export default {
    name: "bookElements",
    components: { ConfirmDialogue },
    data() {
        return {
            items: [
                { id: 1, name: '项目A' },
                { id: 2, name: '项目B' },
                // ...更多数据
            ],
        };
    },
    methods: {
        async doDelete(item) {
            // 现在 this.$refs.confirmDialogue 始终指向唯一的实例
            const ok = await this.$refs.confirmDialogue.show({
                title: '删除确认',
                message: `确定要删除 ${item.name} 吗？`,
                okButton: '删除',
            });
            if (ok) {
                alert(`${item.name} 已成功删除`);
            }
        },
    },
};
</script>

通过将 <confirm-dialogue ref="confirmDialogue"></confirm-dialogue> 移到 <template> 的根目录下，它只会被渲染一次。无论有多少个删除按钮，它们都将调用同一个 ConfirmDialogue 实例的 show() 方法。对话框本身是隐藏的，直到被调用 show() 方法才显示，因此将其放置在顶部并不会影响页面布局。

注意事项与最佳实践

1. ref 的唯一性： 除非你明确需要获取一个组件的多个实例（此时 this.$refs.refName 会是一个数组），否则应确保 ref 名称在当前组件实例的模板中是唯一的。
2. 谨慎使用 $refs： 尽管 $refs 提供了一种直接访问子组件或 DOM 的方式，但过度依赖它可能会导致组件之间的耦合度过高，不利于组件的复用和维护。通常，Vue 推崇通过 Props 进行父子通信，通过 Events 进行子父通信。
3. 何时使用 $refs：
   • 管理焦点、文本选择或媒体播放。
   • 集成第三方 DOM 库。
   • 执行动画。
   • 在父组件中直接调用子组件的方法（如本例中的弹窗显示）。
4. 动态 ref： 如果确实需要在 v-for 中为每个实例设置 ref 并单独访问，可以使用动态 ref。例如 ref="itemRefs[item.id]"，然后通过 this.$refs.itemRefs[itemId] 来访问特定实例。但这种场景相对较少，且需要更复杂的管理逻辑。

总结

TypeError: this.$refs.xxx.show is not a function 错误在 Vue.js 中，当一个带有 ref 属性的组件被放置在 v-for 循环内部，并尝试以单实例方式访问时，是一个常见的陷阱。其根本原因在于 this.$refs.refName 在循环中会变成一个组件实例数组。解决此问题的关键在于将那些只需要一个单一实例的组件（如全局确认对话框）移出循环，确保其 ref 始终指向唯一的组件实例。遵循 Vue 的通信原则并谨慎使用 $refs，将有助于构建更健壮、可维护的 Vue.js 应用。

以上就是解决 Vue.js 中 $refs 在循环内失效的 TypeError 问题的详细内容，更多请关注php中文网其它相关文章！