组件：Hooks

组件内使用的组合式函数，只能在组件函数体的同步执行阶段调用。

useId()

生成唯一 ID，用于表单元素的 id 和 htmlFor 关联。

类型定义

declare function useId(prefix?: string): string

参数

参数	类型	说明
`prefix`	`string`	可选的 ID 前缀，默认使用 `app.config.idPrefix`

返回值

类型	说明
`string`	唯一 ID 字符串

示例

tsx

import { useId } from 'vitarx'

function Input() {
  const id = useId()
  return (
    <div>
      <label htmlFor={id}>Label</label>
      <input id={id} />
    </div>
  )
}

useModel()

创建双向绑定模型，用于实现 v-model。

类型定义

declare function useModel<T extends AnyProps, K extends keyof T>(
  props: T,
  propName: K,
  defaultValue?: T[K]
): ModelRef<T, K>

参数

参数	类型	说明
`props`	`T`	组件 props 对象
`propName`	`K`	要绑定的 prop 名称
`defaultValue`	`T[K]`	可选的默认值

返回值

类型	说明
`ModelRef<T, K>`	模型引用对象，包含 `value` 和事件属性

示例

tsx

import { useModel } from 'vitarx'

function MyInput(props: { modelValue: string }) {
  const model = useModel(props, 'modelValue')
  return <input {...model} />
}

参考：v-model

useRef()

创建 DOM 元素或组件实例的引用。

类型定义

declare function useRef<T>(): ShallowRef<
  | (T extends HostElement
      ? T
      : T extends HostElementTag
        ? HostElement<T>
        : T extends Component
          ? ComponentPublicInstance
          : T)
  | null
>

返回值

类型	说明
`ShallowRef<T \| null>`	引用对象，初始值为 `null`

示例

DOM 元素引用：

tsx

import { useRef, onMounted } from 'vitarx'

function MyComponent() {
  const elRef = useRef<HTMLDivElement>()

  onMounted(() => {
    if (elRef.value) {
      console.log(elRef.value.offsetWidth)
    }
  })

  return <div ref={elRef}>Content</div>
}

组件实例引用：

tsx

import { useRef } from 'vitarx'

function Parent() {
  const childRef = useRef<typeof Child>()

  return <Child ref={childRef} />
}

参考：组件 ref

useApp()

获取当前应用实例，未获取到则抛出异常。

类型定义

declare function useApp<T extends App = App>(): T

返回值

类型	说明
`App`	当前应用实例

注意事项

useApp() 只能在组件函数体的同步执行阶段调用，不能在生命周期钩子或异步回调中调用。

示例

tsx

import { useApp } from 'vitarx'

function MyComponent() {
  const app = useApp()
  return <div>{app.config.idPrefix}</div>
}

useInstance()

获取当前组件实例。

类型定义

declare function useInstance(allowEmpty?: false): ComponentInstance
declare function useInstance(allowEmpty: true): ComponentInstance | null

参数

参数	类型	说明
`allowEmpty`	`boolean`	是否允许返回 `null`，默认 `false`

返回值

调用方式	返回值	说明
`useInstance()`	`ComponentInstance`	当前组件实例
`useInstance(true)`	`ComponentInstance \| null`	允许为空

useView()

获取当前视图对象。

类型定义

declare function useView(allowEmpty?: false): ComponentView
declare function useView(allowEmpty: true): ComponentView | null

参数

参数	类型	说明
`allowEmpty`	`boolean`	是否允许返回 `null`，默认 `false`

返回值

调用方式	返回值	说明
`useView()`	`ComponentView`	当前组件视图
`useView(true)`	`ComponentView \| null`	允许为空

useChildren()

获取子组件列表。

类型定义

declare function useChildren(children?: RenderChildren): ResolvedChildren

参数

参数	类型	说明
`children`	`RenderChildren`	可选的子节点

返回值

类型	说明
`ResolvedChildren`	解析后的子视图数组

示例

tsx

import { useChildren, onMounted } from 'vitarx'

function Parent() {
  const children = useChildren()

  onMounted(() => {
    console.log('子组件数量:', children.length)
  })

  return (
    <div>
      <Child />
      <Child />
    </div>
  )
}

useFastChild()

快速获取单个子组件实例。

类型定义

declare function useFastChild(children?: RenderChildren): View | null

返回值

类型	说明
`View \| null`	第一个子视图

useSuspense()

获取最近的 Suspense 上下文。

类型定义

declare function useSuspense(): ShallowRef<number> | undefined

返回值

类型	说明
`ShallowRef<number> \| undefined`	Suspense 计数器引用，不在 Suspense 内则为 `undefined`

WARNING