📖 概述

useId() 是 Vue 3 中的一个组合式 API 函数，用于生成唯一的标识符。它确保在服务端渲染（SSR）和客户端渲染之间生成一致的 ID，避免水合不匹配的问题。

🎯 基本概念

什么是 useId？

useId() 返回一个唯一的字符串标识符，该标识符在组件的整个生命周期内保持不变，并且在服务端和客户端之间保持一致。

使用场景

🏷️ 为表单元素生成唯一 ID
🔗 关联 label 和 input 元素
🎯 为 ARIA 属性提供唯一标识
🔍 为测试提供稳定的选择器

🔧 函数签名

function useId(): string;

💻 代码示例

🚀 基础用法

<script setup lang="ts">
import { useId } from "vue";// 生成唯一标识符
const id = useId();console.log(id); // 例如: "v-1a2b3c4d"
</script><template><div><label :for="id">用户名</label><input :id="id" type="text" /></div>
</template>

🏷️ 表单元素关联

<script setup lang="ts">
import { useId } from "vue";const inputId = useId();
const checkboxId = useId();
</script><template><div class="form-group"><label :for="inputId">邮箱地址</label><input :id="inputId" type="email" placeholder="请输入邮箱" /><div class="checkbox-group"><input :id="checkboxId" type="checkbox" /><label :for="checkboxId">订阅新闻</label></div></div>
</template>

🎯 ARIA 属性支持

<script setup lang="ts">
import { useId } from "vue";const dialogId = useId();
const descriptionId = useId();
</script><template><divrole="dialog":aria-labelledby="dialogId":aria-describedby="descriptionId"><h2 :id="dialogId">确认删除</h2><p :id="descriptionId">此操作不可撤销，请确认是否继续。</p><button @click="confirm">确认</button><button @click="cancel">取消</button></div>
</template>

🔍 多个组件实例

<script setup lang="ts">
import { useId } from "vue";// 每个组件实例都会生成不同的 ID
const containerId = useId();
const listId = useId();
</script><template><div :id="containerId" class="dropdown"><button :aria-expanded="isOpen" :aria-controls="listId">选择选项</button><ul :id="listId" role="listbox" v-show="isOpen"><li role="option" v-for="item in items" :key="item.id">{{ item.name }}</li></ul></div>
</template>

⚖️ 与其他 ID 生成方式的对比

❌ 不推荐的方式

<script setup lang="ts">
// 使用 Math.random() - 服务端和客户端不一致
const randomId = Math.random().toString(36).substr(2, 9);// 使用 Date.now() - 可能导致重复
const timestampId = Date.now().toString();
</script>

✅ 推荐使用 useId

<script setup lang="ts">
import { useId } from "vue";// 使用 useId - 服务端和客户端一致
const stableId = useId();
</script>

⚠️ 注意事项

🔢 ID 唯一性

useId() 生成的 ID 在同一个组件实例中是唯一的，但在不同的组件实例中会不同：

<script setup lang="ts">
import { useId } from "vue";const id1 = useId(); // 第一个组件实例的 ID
const id2 = useId(); // 第二个组件实例的 ID// id1 !== id2
</script>

📝 SSR 兼容性

useId() 确保在服务端渲染和客户端水合时生成相同的 ID：

<script setup lang="ts">
import { useId } from "vue";const id = useId();// 在服务端和客户端都会生成相同的 ID
// 避免了水合不匹配的问题
</script>

🛡️ 使用限制

useId() 只能在组件的 setup 函数或 <script setup> 中使用：

<script setup lang="ts">
import { useId } from "vue";// ✅ 正确：在 setup 中使用
const id = useId();// ❌ 错误：不能在事件处理函数中使用
const handleClick = () => {const newId = useId(); // 这会导致错误
};
</script>

🎯 最佳实践

1️⃣ 为表单元素生成 ID

<script setup lang="ts">
import { useId } from "vue";const inputId = useId();
const textareaId = useId();
const selectId = useId();
</script><template><form><div class="form-field"><label :for="inputId">姓名</label><input :id="inputId" type="text" /></div><div class="form-field"><label :for="textareaId">描述</label><textarea :id="textareaId"></textarea></div><div class="form-field"><label :for="selectId">城市</label><select :id="selectId"><option value="beijing">北京</option><option value="shanghai">上海</option></select></div></form>
</template>

2️⃣ 组合多个 useId

<script setup lang="ts">
import { useId } from "vue";const baseId = useId();
const inputId = `${baseId}-input`;
const labelId = `${baseId}-label`;
const errorId = `${baseId}-error`;
</script><template><div class="form-control"><label :id="labelId" :for="inputId">密码</label><input:id="inputId":aria-labelledby="labelId":aria-describedby="errorId"type="password"/><span :id="errorId" class="error-message"> 密码长度至少6位 </span></div>
</template>

3️⃣ 在可复用组件中使用

<script setup lang="ts">
import { useId } from "vue";interface Props {label?: string;error?: string;
}const props = defineProps<Props>();
const inputId = useId();
const errorId = useId();
</script><template><div class="input-wrapper"><label v-if="label" :for="inputId">{{ label }}</label><input :id="inputId" :aria-describedby="errorId" v-bind="$attrs" /><span v-if="error" :id="errorId" class="error">{{ error }}</span></div>
</template>