useVModel

类别

导出体积

486 B

上次更改

8 months ago

用法

TypeScript

import { useVModel
 } from '@vueuse/core'

const props
 = defineProps
<{
  modelValue
: string
}>()
const emit
 = defineEmits
(['update:modelValue'])

const data
 = useVModel
(props
, 'modelValue', emit
)

import { useVModel } from '@vueuse/core'
const props = defineProps()
const emit = defineEmits(['update:modelValue'])
const data = useVModel(props, 'modelValue', emit)

Options API

import { useVModel
 } from '@vueuse/core'

export default {
  setup
(props
, { emit
 }) {
    const data
 = useVModel
(props
, 'data', emit
)

    console
.log
(data
.value
) // props.data
    data
.value
 = 'foo' // emit('update:data', 'foo')
  },
}

Options

Passive Mode

By default, useVModel returns a computed ref. In passive mode, it creates a local ref that syncs with the prop via watch, allowing deep reactivity tracking.

const data
 = useVModel(props, 'modelValue', emit, { passive
: true })

Deep Watching

When using passive: true, you can enable deep watching for nested object changes:

const data
 = useVModel(props, 'modelValue', emit, {
  passive
: true,
  deep
: true,
})

Clone Values

Clone the prop value to avoid mutating the original object. Set to true to use JSON.parse(JSON.stringify()) or provide a custom clone function.

const data
 = useVModel(props, 'modelValue', emit, {
  clone
: true,
  // or provide custom clone function
  // clone: (val) => structuredClone(val),
})

Default Value

Provide a default value when the prop is undefined:

const data
 = useVModel(props, 'modelValue', emit, {
  defaultValue
: 'default',
})

Custom Event Name

Override the default update:propName event name:

const data
 = useVModel(props, 'value', emit, {
  eventName
: 'change',
})

Emit Validation

Use shouldEmit to validate before emitting. Return false to prevent the emit:

const data
 = useVModel(props, 'modelValue', emit, {
  shouldEmit
: (value
) => {
    // Only emit if value is valid
    return value
.length > 0
  },
})

类型声明

显示类型声明

export interface UseVModelOptions
<T
, Passive
 extends boolean = false> {
  /**
   * 当 passive 设置为 `true` 时，它将使用 `watch` 来与 props 和 ref 同步。
   * 而不是依赖于 `v-model` 或 `.sync`。
   *
   * @default false
   */
  passive
?: Passive

  /**
   * 当设置了 eventName 时，它的值将用于覆盖 emit 事件的名称。
   *
   * @default undefined
   */
  eventName
?: string
  /**
   * 尝试检查嵌套对象或数组中属性的更改。
   * 仅在将 `passive` 选项设置为 `true` 时应用
   *
   * @default false
   */
  deep
?: boolean
  /**
   * 在未传递值时定义返回 ref 的默认值。
   *
   * @default undefined
   */
  defaultValue
?: T

  /**
   * 克隆 props。
   * 接受一个自定义克隆函数。
   * 当设置为 `true` 时，它将使用 `JSON.parse(JSON.stringify(value))` 进行克隆。
   *
   * @default false
   */
  clone
?: boolean | CloneFn
<T
>
  /**
   * 在触发 emit 事件之前的钩子，可用于表单验证。
   * 如果返回 false，则不会触发 emit 事件。
   *
   * @default undefined
   */
  shouldEmit
?: (v
: T
) => boolean
}
/**
 * Shorthand for v-model binding, props + emit -> ref
 *
 * @see https://vueuse.org/useVModel
 * @param props
 * @param key (default 'modelValue')
 * @param emit
 * @param options
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function useVModel
<
  P
 extends object,
  K
 extends keyof P
,
  Name
 extends string,
>(
  props
: P
,
  key
?: K
,
  emit
?: (name
: Name
, ...args
: any[]) => void,
  options
?: UseVModelOptions
<P
[K
], false>,
): WritableComputedRef
<P
[K
]>
export declare function useVModel
<
  P
 extends object,
  K
 extends keyof P
,
  Name
 extends string,
>(
  props
: P
,
  key
?: K
,
  emit
?: (name
: Name
, ...args
: any[]) => void,
  options
?: UseVModelOptions
<P
[K
], true>,
): Ref
<UnwrapRef
<P
[K
]>>