vuetify0

Vuetify0

无头 Vue 3 组件和组合式函数。仅提供行为和 ARIA 支持。

48 个组件、74 个组合式函数、27 个工具。

安装

pnpm install @vuetify/v0

import { createSelection, useBreakpoints } from '@vuetify/v0'
import { Tabs, Dialog } from '@vuetify/v0/components'

在此仓库中，从 #v0/（#v0/composables、#v0/utilities、#v0/constants/globals）导入内部模块。发布后的导入路径为 @vuetify/v0、@vuetify/v0/components、@vuetify/v0/utilities 和 @vuetify/v0/constants。

大多数 use* 组合式函数无需插件即可运行，并会回退到默认值。但 useDate 例外：必须使用适配器安装 createDatePlugin，否则调用会抛出异常。若要在整个应用中使用主题、区域设置、存储或断点，请安装 createThemePlugin、createLocalePlugin、createStoragePlugin 或 createBreakpointsPlugin。

选择功能和按钮。两者都不需要插件。

<script setup lang="ts">
  import { createSelection } from '@vuetify/v0'
  import { Button } from '@vuetify/v0/components'

  const filters = createSelection({ multiple: true })

  filters.register({ id: 'open' })
</script>

<template>
  <Button.Root @click="filters.toggle('open')">
    {{ filters.selectedIds.has('open') ? 'Open' : 'Closed' }}
  </Button.Root>
</template>

决策表

匹配第一列。如果某一行符合，就使用对应的 API。这些行涵盖了常见情况。其余组件、组合式函数和实用工具列在此技能的末尾。

问题	使用	类别
原生 <button>（点击、提交、切换）	Button	操作
覆盖层、对话框或模态框	Dialog	披露
弹出框或锚定覆盖层	Popover	披露
内联状态消息 / 实时区域消息	Alert	语义
单选状态（标签页、主题选择器）	createSingle	选择
多选状态（筛选器、标签选择器）	createSelection	选择
带三态的全选	createGroup	选择
树形 / 嵌套选择（树视图、菜单）	createNested	选择
向导 / 轮播步骤跟踪	createStep	选择
基于 ID 的值存储（在子组件间共享）	createModel	选择
带异步验证和脏状态跟踪的表单	createForm + createValidation	表单
滑块 / 范围 / 旋钮状态	createSlider	表单
自动补全 / 组合框	createCombobox	表单
数字微调输入框	createNumberField / createNumeric	表单
一次性密码 / 验证码值	createOtp	表单
分页或虚拟化列表	createPagination, createVirtual	数据
可排序 / 可筛选表格	DataTable / createDataTable, createFilter	数据
可编辑 / 跨行跨列数据网格	DataGrid / createDataGrid	数据
根据路由派生的面包屑导航	createBreadcrumbs	语义
溢出 / 响应式菜单（隐藏溢出的项目）	createOverflow	语义
类型安全的 provide/inject	createContext	基础
ID → 值的响应式注册表	createRegistry	注册
自动消失队列（Snackbar、Toast）	createQueue	注册
撤销 / 重做历史记录	createTimeline	注册
设计令牌图（主题、间距比例）	createTokens	注册
弹出框、工具提示或菜单的位置	usePopover	系统
进入 / 离开动画编排	usePresence	系统
焦点约束（非原生对话框、抽屉）	useFocusTrap	系统
循环 tabindex（列表、菜单栏）	useRovingFocus	系统
虚拟焦点（组合框列表框）	useVirtualFocus	系统
点击外部 / 键盘快捷键 / 事件监听器	useClickOutside, useHotkey, useEventListener	系统
尺寸、交叉或变更观察	useResizeObserver, useIntersectionObserver, useMutationObserver	系统
带暂停 / 恢复功能的 rAF 循环或 setTimeout	useRaf, useTimer	系统
响应式断点	useBreakpoints, useMediaQuery	插件
本地化字符串 + 日期 / 数字格式	useLocale, useDate	插件
主题（浅色 / 深色 / 自定义调色板）	useTheme	插件
RTL 方向感知	useRtl	插件
覆盖层的 z-index 堆叠	useStack	插件
通知 / Snackbar 队列插件	useNotifications	插件
功能标志 / 权限检查	useFeatures, usePermissions	插件
持久化状态（localStorage / sessionStorage）	useStorage	插件
适配器支持的结构化日志	useLogger	插件
SSR 安全的挂载检测	useHydration	插件

规则

实用工具

编写辅助函数前，先检查这些工具。仓库内：#v0/utilities。已发布：@vuetify/v0/utilities。

• 类型守卫：isFunction, isString, isNumber, isBoolean, isObject, isArray, isNull, isUndefined, isNullOrUndefined, isPrimitive, isSymbol, isNaN, isElement
• mergeDeep, clamp, range, useId

浏览器检查

IN_BROWSER, SUPPORTS_TOUCH, SUPPORTS_MATCH_MEDIA, SUPPORTS_OBSERVER, SUPPORTS_INTERSECTION_OBSERVER, SUPPORTS_MUTATION_OBSERVER。

仓库内：#v0/constants/globals。已发布：@vuetify/v0/constants。请使用这些项代替 typeof window。

响应式

• 基本类型使用 shallowRef
• 对象和数组使用 ref
• 派生值使用 toRef
• 仅使用 computed 缓存开销较大的操作

复合组件

根组件拥有状态。子组件是具名子组件，通过 createContext 读取状态。

<script setup lang="ts">
  import { Tabs } from '@vuetify/v0/components'
  import { shallowRef } from 'vue'

  const active = shallowRef('overview')
</script>

<template>
  <Tabs.Root v-model="active">
    <Tabs.List>
      <Tabs.Item value="overview">Overview</Tabs.Item>
      <Tabs.Item value="details">Details</Tabs.Item>
    </Tabs.List>
    <Tabs.Panel value="overview">Overview content</Tabs.Panel>
    <Tabs.Panel value="details">Details content</Tabs.Panel>
  </Tabs.Root>
</template>

可用组件：

• 基础组件： AspectRatio（稳定）、Atom（稳定）、Portal、Presence
• 提供器： Group（稳定）、Locale、Scrim、Selection（稳定）、Single（稳定）、Step（稳定）、Theme（稳定）
• 操作： Button、Toggle（稳定）
• 表单： Checkbox（稳定）、Combobox、Form、Input、NumberField、Otp、Radio（稳定）、Rating、Select、Slider、Switch（稳定）
• 披露组件： AlertDialog、Collapsible（稳定）、Dialog、ExpansionPanel、Menu、Popover、Tabs（稳定）、Tooltip、Tour、Treeview
• 语义组件： Alert、Avatar、Breadcrumbs、Carousel、Image、Overflow、Pagination、Progress、Snackbar、Splitter
• 数据组件： DataGrid、DataTable、Kanban、Virtualizer

计划中（尚未导出 — 请勿导入）：

• DatePicker、DateRangePicker、TimePicker

更多复合组件示例：references/component-examples.md。

Vuetify MCP

连接 Vuetify MCP 服务后，可用其获取指南或发行说明：

• vuetify-mcp:get_vuetify0_component_list
• vuetify-mcp:get_vuetify0_composable_list
• vuetify-mcp:get_vuetify0_component_guide
• vuetify-mcp:get_vuetify0_composable_guide
• vuetify-mcp:get_vuetify0_installation_guide

资源

• 文档：https://0.vuetifyjs.com
• API 参考：references/REFERENCE.md
• 选择模式：references/selection-patterns.md
• 反模式：references/anti-patterns.md
• 组件与组合式函数：references/layer-decisions.md
• 编写复合组件：references/authoring-guide.md

完整 API 概览

公共组合式函数和实用工具。已标注 (mature)、(stable) 和 (draft)。未标注的条目均为预览版。

组合式函数

基础：

• createContext — 基于 Vue 的 provide/inject 构建的类型安全依赖注入工厂。在组件树之间共享状态，无需逐层传递 prop。（稳定）
• createPlugin — 用于创建 Vue 插件的工厂，支持类型化依赖注入和生命周期钩子。（稳定）
• createTrinity — 为 Vue 的 provide/inject 依赖注入模式生成类型化的 [useX, provideX, defaultX] 元组。（稳定）

注册：

• createQueue — 用于基于时间的集合的 FIFO 队列，支持自动超时移除以及暂停/恢复。
• createRegistry — 有序键值集合的基础。条目使用 ID 和索引注册，并可按 ID、索引或值查找。（稳定）
• createTimeline — 基于 createRegistry 构建的有界撤销/重做历史记录，支持配置大小上限。
• createTokens — 设计令牌注册表，支持分层集合、别名解析和命名空间。

表单：

• createCombobox — 用于自定义实现的底层组合框协调器。大多数用户应改用 Combobox 组件。
• createDatePicker — 无头日期状态，支持日历网格几何、单日期和日期范围模式、预设范围、最小值/最大值边界及禁用日期规则。优先采用可组合设计，且不依赖 @internationalized/date。（草稿）
• createForm — 协调多个输入项的验证。提供 submit()、reset() 和聚合有效性状态。
• createInput — 共享的表单字段基础组件，提供验证状态、ARIA ID 生成和自动表单注册。
• createNumberField — 数值，支持区域设置感知格式化、步长吸附、最小值/最大值/步长边界，以及文本输入的解析和提交。
• createNumeric — 纯数值运算，支持有界数值、步长吸附、范围钳制和浮点精度修正。
• createOtp — 定长的一次性密码或验证码，支持模式限定输入和完成状态检测。
• createRating — 带离散项的有界数值。设置大小后，即可获取可遍历的项目，每项具有完整/半颗/空状态。支持以 0.5 为增量的半步长。
• createSlider — 用于单滑块、范围滑块和多滑块的滑块状态组合式函数。处理数值运算、步长吸附和百分比转换。
• createTimePicker — 分段时间值，包含小时、分钟和秒字段，支持 12/24 小时制、上下午处理、步长吸附及最小值/最大值边界。（草稿）
• createValidation — 单个输入项的验证，支持响应式规则、异步验证和 Standard Schema。

选择：

• createGroup — 支持三态（混合/不确定状态）选择，适用于复选框树、分组切换项，以及任何可能部分选中项目的模式。（稳定）
• createModel — 响应式值存储，通过双向选择绑定包装一个 ref。（稳定）
• createNested — 基于 createGroup 构建的层级树管理，支持父子关系、打开/关闭状态和可插拔遍历策略。（稳定）
• createSelection — 用于管理集合中项目选择的组合式函数，具备自动索引和生命周期管理。（稳定）
• createSingle — 扩展 createSelection，强制单项选择并自动清除之前的选择。（稳定）
• createStep — 扩展 createSingle，支持有界或循环导航。专为向导、多步表单和引导流程设计。（稳定）

数据：

• createDataGrid — 无头数据网格，支持列布局、单元格编辑、行排序和行跨越。
• createDataTable — 基于 v0 基础组件构建的可组合数据表。将排序、筛选、分页、选择和展开组合为单个管线。
• createFilter — 用于根据搜索查询筛选项目数组的组合式函数，支持基本类型值和复杂对象，并可自定义筛选逻辑。
• createKanban — 用于卡片列的双层看板状态，支持列重排、列内重排和跨列 transfer 基础操作。
• createPagination — 轻量级组合式函数，用于管理分页状态，提供导航方法和计算所得的可见页面项。
• createSortable — 有序列表状态，支持 move、swap 和 reorder 修改操作。
• createVirtual — 虚拟滚动组合式函数，仅渲染可见项目，从而高效呈现大型列表。

语义：

• createBreadcrumbs — 扩展 createSingle 的组合式函数，用于面包屑导航并自动截断路径。
• createOverflow — 根据可用宽度计算容器中可容纳的项目数，适用于分页、面包屑和类似 UI 的响应式截断。
• createProgress — 用于跟踪一个或多个分段进度的组合式函数，支持百分比计算和不确定状态检测。

插件：

• useBreakpoints — 使用命名断点进行响应式视口检测，便于构建响应式布局。（稳定）
• useDate — 使用 Temporal API 操作日期，支持本地化格式设置和适配器。
• useFeatures — 管理应用中的功能标志和变体。
• useHydration — 控制 SSR 水合时机，避免不匹配并优化客户端渲染。
• useLocale — i18n 插件，支持消息翻译、数字格式设置和语言区域切换。
• useLogger — 应用日志记录，支持可配置级别、筛选，以及适配常用日志库的可替换适配器。
• useNotifications — 通知生命周期管理，支持严重性级别、状态变更、Toast 排队和自动关闭。
• usePermissions — 基于角色的访问控制，支持操作、主体和上下文感知条件。
• useReducedMotion — 遵循或覆盖用户的 prefers-reduced-motion 设置，并提供响应式标志和 body 数据属性，供仅使用 CSS 的使用方使用。
• useRtl — 从右向左的文本方向管理，支持响应式状态和子树覆盖。
• useRules — 验证规则管理，支持 Standard Schema 和自定义别名。
• useStack — 覆盖层 z-index 协调器，支持自动堆叠顺序和父子嵌套。
• useStorage — 响应式存储，支持自动序列化、缓存和 SSR 安全操作。（稳定）
• useTheme — 主题管理，支持多个主题、CSS 自定义属性和令牌别名解析。（稳定）
• useTooltip — 在某个区域内共享工具提示的打开、关闭和跳过延迟默认值；附近的工具提示一旦已有一个打开，便会立即打开。
• useTour — 无头式引导游览序列器：步骤收集、激活器注册、表单控制导航、以编程方式激活/停用，以及每个步骤的进入/离开/完成处理器和事件。基于 createStep、createRegistry 和 createForm 构建。

系统：

• useClickOutside — 用于检测指定元素外部点击并自动清理的组合式函数。
• useDelay — 安排打开和关闭过渡，提供启动、停止、暂停和恢复控制，并以响应式方式查看待处理的延迟。
• useDragDrop — 无头拖放原语。管理两个注册表——可拖动项和区域——以及活动拖动状态。
• useEventListener — 用于处理 DOM 事件并在组件卸载时自动清理的组合式函数。
• useFocusTrap — 将 Tab 和 Shift+Tab 的焦点限制在根元素内；激活时将焦点移入其中，停用时恢复先前聚焦的元素。
• useHotkey — 用于处理快捷键组合和序列的组合式函数，支持感知平台的修饰键并自动清理。
• useImage — 将图像加载状态作为响应式状态机进行跟踪，状态包括空闲、加载中、已加载和错误。
• useIntersectionObserver — 使用 Intersection Observer API 检测元素进入或离开视口，并自动清理的组合式函数。（稳定）
• useLazy — 用于延迟内容渲染直至首次激活的组合式函数，可选择在停用时重置。
• useMediaQuery — 用于响应式匹配 CSS 媒体查询并自动清理的组合式函数。
• useMutationObserver — 使用 Mutation Observer API 检测 DOM 变化并自动清理的组合式函数。（稳定）
• usePopover — 原生弹出层 API，支持可插拔的定位适配器。默认使用 CSS 锚点定位；可为每个实例或通过 createPopoverPlugin 在整个应用中替换为 FloatingUIPopoverAdapter（或任何 PopoverAdapter）。
• usePresence — 与动画无关的挂载生命周期管理。
• useRaf — 将回调节流至下一帧动画，并通过先取消再请求进行去重。作用域释放时自动清理。
• useResizeObserver — 使用 Resize Observer API 检测元素尺寸变化并自动清理的组合式函数。（稳定）
• useRovingFocus — 用于复合控件的键盘导航，按方向键在项目间移动焦点并跳过禁用项。
• useTimer — 支持暂停／恢复并跟踪剩余时间的响应式计时器组合式函数。
• useToggleScope — 根据响应式布尔条件有条件地管理 Vue effect scope 并自动清理的组合式函数。
• useTypeahead — 将输入字符与列表项进行前缀匹配，累积字符持续一秒，并在重复输入同一字母时循环切换。
• useVirtualFocus — 用于键盘导航的组合式函数，DOM 焦点保持在单个控件元素上，同时视觉高亮在项目间移动。

响应性：

• useProxyModel — 用于与选择上下文双向同步 refs 的组合式函数，从而将 v-model 与选择状态无缝集成。（稳定）
• useProxyRegistry — 用于注册表集合的响应式代理包装器，在项目注册或注销时自动更新 refs。

转换器：

• toArray — 将任意值（包括 null 和 undefined）转换为数组。（稳定）
• toElement — 将 refs、getter、原始 DOM 元素或 Vue 组件实例解析为单个 Element | undefined。（稳定）
• toHighlight — 将文本拆分为匹配和未匹配的片段，返回普通的 HighlightChunk[]，用于搜索词高亮。
• toReactive — 将 MaybeRef 对象转换为响应式代理，自动解包 ref 并支持 Map／Set。

实用工具

• apca
• clamp — 将值限制在最小值和最大值之间（稳定）
• findMatchRanges — 查找查询字符串在字符串中的匹配范围，可选择折叠任一侧的重音符号。
• foreground
• getActiveElement — 遍历开放的 shadow root，找到最深层获得焦点的元素。在 SSR 环境下返回 null。
• hexToRgb
• isArray — 检查值是否为数组（成熟）
• isBoolean — 检查值是否为布尔值（成熟）
• isElement — 检查值是否为 DOM 元素（成熟）
• isFunction — 检查值是否为函数（成熟）
• isNaN — 检查值是否为 NaN（非数字）（成熟）
• isNull — 检查值是否为 null（成熟）
• isNullOrUndefined — 检查值是否为 null 或 undefined（成熟）
• isNumber — 检查值是否为数字（成熟）
• isObject — 检查值是否为普通对象（不包括 null 和数组）（成熟）
• isPrimitive — 检查值是否为原始值（字符串、数字或布尔值）（稳定）
• isString — 检查值是否为字符串（成熟）
• isSymbol — 检查值是否为 symbol（成熟）
• isThenable — 检查值是否为 thenable（任何带有 .then 方法的对象）。
• isUndefined — 检查值是否为 undefined（成熟）
• isV0Error — 用于 v0 抛出错误的类型守卫。
• mergeDeep — 将源对象深度合并到目标对象中，并返回一个新对象（稳定）
• pxToNumber — 将 CSS 像素长度解析为数字；如果长度无法解析，则返回调用方提供的备用值。
• range — 创建由连续数字组成的数组（成熟）
• rgbToHex
• useId — 生成唯一 ID；在组件上下文中使用 Vue 的 useId（稳定）
• V0Error — v0 内部抛出的结构化错误。