Vue3组件onMounted绑定事件失效，添加setTimeout后恢复正常的原因排查

我在Vue3中开发了一个带多行与分页功能的表格单元格简化组件，代码如下：

<template>
    <div class="list-cell">
        <div
            v-for="(value, index) in lines"
            ref="items"
            :key="index"
            class="list-cell--item"
        >
            {{ value }}
        </div>
    </div>
</template>

<script setup lang="ts">
import { Ref, ref, onMounted, onUnmounted, PropType } from 'vue';

const items: Ref<HTMLElement[]> = ref([]);

defineProps({
    lines: { type: Array as PropType<string[]>, default: () => [] },
});

const handleMouseEnter = () => {
    console.log(1);
};
const handleMouseLeave = () => {
    console.log(2);
};

onMounted(() => {
    items.value.forEach((item) => {
        item.addEventListener('mouseenter', handleMouseEnter);
        item.addEventListener('mouseleave', handleMouseLeave);
    });
});
onUnmounted(() => {
    items.value.forEach((item) => {
        item.removeEventListener('mouseenter', handleMouseEnter);
        item.removeEventListener('mouseleave', handleMouseLeave);
    });
});
</script>

我在onMounted钩子内通过ref给元素绑定mouseenter和mouseleave事件，但并非所有单元格都能正常触发日志输出；但如果给事件绑定代码加5秒setTimeout延迟，所有单元格就能正确触发日志：

setTimeout(() => {
    items.value.forEach((item) => {
        item.addEventListener('mouseenter', handleMouseEnter);
        item.addEventListener('mouseleave', handleMouseLeave);
    });
}, 5000);

请问这一现象的原因是什么？

以下是使用该单元格组件的表格代码：

<Table>
    <TableHeader
        slot="table-header"
        :columns="tableColumns"
    />
    <TableBody
        slot="table-body"
    >
        <TableRow
            v-for="(entity, index1) in dataSource"
            :key="currentItemOffset + index1"
            :row="entity"
            rowid="index1"
        >
            <TableCell
                v-for="(item, index2) in entity"
                :key="currentItemOffset + index2"
            >
                <ComponentWithIssue
                    :lines="item"
                ></ComponentWithIssue>
            </TableCell>
        </TableRow>
    </TableBody>
</Table>

核心原因 #

问题出在表格分页渲染时机和组件onMounted钩子执行时机不匹配：

• 你的表格带分页功能，dataSource大概率是异步加载的（比如切换分页时请求新数据），或者表格内部做了虚拟滚动、延迟渲染这类优化。
• 当ComponentWithIssue的onMounted执行时，表格当前行可能还没完成DOM渲染，或者lines props还没拿到正确数据——导致v-for生成的<div class="list-cell--item">元素还没挂载到DOM上，此时items.value是空数组或者不完整，自然没法给所有元素绑定事件。
• 加5秒setTimeout后，异步数据加载完成、表格DOM也渲染完毕，items.value能获取到所有元素，事件绑定就正常了。

另外，v-for用index当key，结合分页时的currentItemOffset，会触发Vue虚拟DOM的复用机制：分页切换时Vue可能复用旧的组件实例，旧的onMounted不会重新执行，但新的lines数据生成了新DOM元素，这些新元素没被绑定事件。

正确解决方案 #

不用setTimeout这种不可靠的延迟方式，推荐两种更合理的处理方式：

方式1：用Vue原生事件绑定（最推荐）

直接在模板里绑定事件，不用手动操作DOM和事件监听，Vue会自动处理元素的创建和销毁：

<template>
    <div class="list-cell">
        <div
            v-for="(value, index) in lines"
            :key="value + index" <!-- 尽量用唯一标识当key，避免复用问题 -->
            class="list-cell--item"
            @mouseenter="handleMouseEnter"
            @mouseleave="handleMouseLeave"
        >
            {{ value }}
        </div>
    </div>
</template>

<script setup lang="ts">
import { PropType } from 'vue';

defineProps({
    lines: { type: Array as PropType<string[]>, default: () => [] },
});

const handleMouseEnter = () => {
    console.log(1);
};
const handleMouseLeave = () => {
    console.log(2);
};
</script>

这种方式完全不用手动管理事件的添加和移除，Vue会在元素渲染时自动绑定，销毁时自动解绑，还能避免DOM操作带来的时机问题。

方式2：监听lines props变化，动态绑定事件

如果必须手动操作DOM，要监听lines的变化，在数据更新后重新绑定事件，同时用nextTick确保DOM已经更新：

<template>
    <div class="list-cell">
        <div
            v-for="(value, index) in lines"
            ref="items"
            :key="value + index"
            class="list-cell--item"
        >
            {{ value }}
        </div>
    </div>
</template>

<script setup lang="ts">
import { Ref, ref, onMounted, onUnmounted, watch, nextTick, PropType } from 'vue';

const items: Ref<HTMLElement[]> = ref([]);
const props = defineProps({
    lines: { type: Array as PropType<string[]>, default: () => [] },
});

const handleMouseEnter = () => {
    console.log(1);
};
const handleMouseLeave = () => {
    console.log(2);
};

const bindEvents = () => {
    // 先解绑旧事件，避免重复绑定
    items.value.forEach(item => {
        item.removeEventListener('mouseenter', handleMouseEnter);
        item.removeEventListener('mouseleave', handleMouseLeave);
    });
    // 绑定新事件
    items.value.forEach(item => {
        item.addEventListener('mouseenter', handleMouseEnter);
        item.addEventListener('mouseleave', handleMouseLeave);
    });
};

onMounted(async () => {
    await nextTick(); // 等待DOM渲染完成
    bindEvents();
});

// 监听lines变化，更新事件绑定
watch(() => props.lines, async () => {
    await nextTick(); // 等待DOM更新完成
    bindEvents();
}, { deep: true });

onUnmounted(() => {
    bindEvents(); // 解绑所有事件
});
</script>

同时注意把v-for的key从index改成更唯一的值（比如value + index，如果value唯一可以直接用value），避免Vue复用组件实例导致的逻辑异常。

内容的提问来源于stack exchange，提问作者sgch