vue3-core/packages/runtime-core/src/apiSetupHelpers.ts

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

482 lines
13 KiB
TypeScript
Raw Normal View History

import {
type LooseRequired,
type Prettify,
type UnionToIntersection,
extend,
isArray,
isFunction,
isPromise,
} from '@vue/shared'
import {
type SetupContext,
createSetupContext,
getCurrentInstance,
setCurrentInstance,
unsetCurrentInstance,
} from './component'
import type { EmitFn, EmitsOptions, ObjectEmitsOptions } from './componentEmits'
import type {
ComponentOptionsMixin,
ComponentOptionsWithoutProps,
ComputedOptions,
MethodOptions,
} from './componentOptions'
2023-02-03 17:10:31 +08:00
import type {
ComponentObjectPropsOptions,
ComponentPropsOptions,
ExtractPropTypes,
PropOptions,
2023-02-03 17:10:31 +08:00
} from './componentProps'
import { warn } from './warning'
import type { SlotsType, StrictUnwrapSlotsType } from './componentSlots'
import type { Ref } from '@vue/reactivity'
2021-06-27 09:11:57 +08:00
// dev only
const warnRuntimeUsage = (method: string) =>
warn(
`${method}() is a compiler-hint helper that is only usable inside ` +
`<script setup> of a single file component. Its arguments should be ` +
`compiled away and passing it at runtime has no effect.`,
)
/**
2021-06-27 09:11:57 +08:00
* Vue `<script setup>` compiler macro for declaring component props. The
* expected argument is the same as the component `props` option.
*
* Example runtime declaration:
* ```js
* // using Array syntax
* const props = defineProps(['foo', 'bar'])
* // using Object syntax
* const props = defineProps({
* foo: String,
* bar: {
* type: Number,
* required: true
* }
* })
* ```
*
* Equivalent type-based declaration:
2021-06-27 09:11:57 +08:00
* ```ts
* // will be compiled into equivalent runtime declarations
* const props = defineProps<{
* foo?: string
* bar: number
* }>()
* ```
2023-04-02 10:02:33 +08:00
*
* @see {@link https://vuejs.org/api/sfc-script-setup.html#defineprops-defineemits}
2021-06-27 09:11:57 +08:00
*
* This is only usable inside `<script setup>`, is compiled away in the
* output and should **not** be actually called at runtime.
*/
2021-06-27 09:11:57 +08:00
// overload 1: runtime props w/ array
export function defineProps<PropNames extends string = string>(
props: PropNames[],
): Prettify<Readonly<{ [key in PropNames]?: any }>>
2021-06-27 09:11:57 +08:00
// overload 2: runtime props w/ object
export function defineProps<
2021-06-27 09:11:57 +08:00
PP extends ComponentObjectPropsOptions = ComponentObjectPropsOptions,
>(props: PP): Prettify<Readonly<ExtractPropTypes<PP>>>
2021-06-27 09:11:57 +08:00
// overload 3: typed-based declaration
export function defineProps<TypeProps>(): DefineProps<
LooseRequired<TypeProps>,
BooleanKey<TypeProps>
>
// implementation
2020-11-26 23:01:36 +08:00
export function defineProps() {
if (__DEV__) {
2021-06-27 09:11:57 +08:00
warnRuntimeUsage(`defineProps`)
}
2020-11-25 05:55:43 +08:00
return null as any
}
2023-12-09 00:34:28 +08:00
export type DefineProps<T, BKeys extends keyof T> = Readonly<T> & {
readonly [K in BKeys]-?: boolean
}
type BooleanKey<T, K extends keyof T = keyof T> = K extends any
? [T[K]] extends [boolean | undefined]
? K
: never
: never
2021-06-27 09:11:57 +08:00
/**
* Vue `<script setup>` compiler macro for declaring a component's emitted
* events. The expected argument is the same as the component `emits` option.
*
* Example runtime declaration:
* ```js
* const emit = defineEmits(['change', 'update'])
* ```
*
* Example type-based declaration:
2021-06-27 09:11:57 +08:00
* ```ts
* const emit = defineEmits<{
* // <eventName>: <expected arguments>
* change: []
* update: [value: string] // named tuple syntax
2021-06-27 09:11:57 +08:00
* }>()
*
* emit('change')
* emit('update', 1)
* ```
*
* This is only usable inside `<script setup>`, is compiled away in the
* output and should **not** be actually called at runtime.
2023-04-02 10:02:33 +08:00
*
* @see {@link https://vuejs.org/api/sfc-script-setup.html#defineprops-defineemits}
2021-06-27 09:11:57 +08:00
*/
// overload 1: runtime emits w/ array
export function defineEmits<EE extends string = string>(
emitOptions: EE[],
): EmitFn<EE[]>
export function defineEmits<E extends EmitsOptions = EmitsOptions>(
emitOptions: E,
): EmitFn<E>
export function defineEmits<
T extends ((...args: any[]) => any) | Record<string, any[]>,
>(): T extends (...args: any[]) => any ? T : ShortEmits<T>
// implementation
export function defineEmits() {
2020-11-26 23:01:36 +08:00
if (__DEV__) {
2021-06-27 09:11:57 +08:00
warnRuntimeUsage(`defineEmits`)
}
2020-11-25 05:55:43 +08:00
return null as any
}
type RecordToUnion<T extends Record<string, any>> = T[keyof T]
type ShortEmits<T extends Record<string, any>> = UnionToIntersection<
RecordToUnion<{
[K in keyof T]: (evt: K, ...args: T[K]) => void
}>
>
2021-06-27 09:11:57 +08:00
/**
* Vue `<script setup>` compiler macro for declaring a component's exposed
* instance properties when it is accessed by a parent component via template
* refs.
*
2022-01-21 14:18:34 +08:00
* `<script setup>` components are closed by default - i.e. variables inside
2021-06-27 09:11:57 +08:00
* the `<script setup>` scope is not exposed to parent unless explicitly exposed
* via `defineExpose`.
*
* This is only usable inside `<script setup>`, is compiled away in the
* output and should **not** be actually called at runtime.
2023-04-02 10:02:33 +08:00
*
* @see {@link https://vuejs.org/api/sfc-script-setup.html#defineexpose}
2021-06-27 09:11:57 +08:00
*/
2022-01-21 14:18:34 +08:00
export function defineExpose<
Exposed extends Record<string, any> = Record<string, any>,
>(exposed?: Exposed) {
if (__DEV__) {
2021-06-27 09:11:57 +08:00
warnRuntimeUsage(`defineExpose`)
}
}
2023-04-02 10:02:33 +08:00
/**
* Vue `<script setup>` compiler macro for declaring a component's additional
* options. This should be used only for options that cannot be expressed via
* Composition API - e.g. `inheritAttrs`.
2023-04-02 10:02:33 +08:00
*
* @see {@link https://vuejs.org/api/sfc-script-setup.html#defineoptions}
*/
export function defineOptions<
RawBindings = {},
D = {},
C extends ComputedOptions = {},
M extends MethodOptions = {},
Mixin extends ComponentOptionsMixin = ComponentOptionsMixin,
Extends extends ComponentOptionsMixin = ComponentOptionsMixin,
>(
options?: ComponentOptionsWithoutProps<
{},
RawBindings,
D,
C,
M,
Mixin,
Extends
> & { emits?: undefined; expose?: undefined; slots?: undefined },
): void {
if (__DEV__) {
warnRuntimeUsage(`defineOptions`)
}
}
export function defineSlots<
S extends Record<string, any> = Record<string, any>,
>(): StrictUnwrapSlotsType<SlotsType<S>> {
if (__DEV__) {
warnRuntimeUsage(`defineSlots`)
}
return null as any
}
export type ModelRef<T, M extends string | number | symbol = string> = Ref<T> &
[ModelRef<T, M>, Record<M, true | undefined>]
export type DefineModelOptions<T = any> = {
get?: (v: T) => any
set?: (v: T) => any
}
/**
* Vue `<script setup>` compiler macro for declaring a
* two-way binding prop that can be consumed via `v-model` from the parent
* component. This will declare a prop with the same name and a corresponding
* `update:propName` event.
*
* If the first argument is a string, it will be used as the prop name;
* Otherwise the prop name will default to "modelValue". In both cases, you
* can also pass an additional object which will be used as the prop's options.
*
* The the returned ref behaves differently depending on whether the parent
* provided the corresponding v-model props or not:
* - If yes, the returned ref's value will always be in sync with the parent
* prop.
* - If not, the returned ref will behave like a normal local ref.
*
* @example
* ```ts
* // default model (consumed via `v-model`)
* const modelValue = defineModel<string>()
* modelValue.value = "hello"
*
* // default model with options
2023-05-19 07:59:09 +08:00
* const modelValue = defineModel<string>({ required: true })
*
* // with specified name (consumed via `v-model:count`)
* const count = defineModel<number>('count')
* count.value++
*
* // with specified name and default value
* const count = defineModel<number>('count', { default: 0 })
* ```
*/
export function defineModel<T, M extends string | number | symbol = string>(
options: { required: true } & PropOptions<T> & DefineModelOptions<T>,
): ModelRef<T, M>
export function defineModel<T, M extends string | number | symbol = string>(
options: { default: any } & PropOptions<T> & DefineModelOptions<T>,
): ModelRef<T, M>
export function defineModel<T, M extends string | number | symbol = string>(
options?: PropOptions<T> & DefineModelOptions<T>,
): ModelRef<T | undefined, M>
export function defineModel<T, M extends string | number | symbol = string>(
name: string,
options: { required: true } & PropOptions<T> & DefineModelOptions<T>,
): ModelRef<T, M>
export function defineModel<T, M extends string | number | symbol = string>(
name: string,
options: { default: any } & PropOptions<T> & DefineModelOptions<T>,
): ModelRef<T, M>
export function defineModel<T, M extends string | number | symbol = string>(
name: string,
options?: PropOptions<T> & DefineModelOptions<T>,
): ModelRef<T | undefined, M>
export function defineModel(): any {
if (__DEV__) {
warnRuntimeUsage('defineModel')
}
}
2021-06-27 09:11:57 +08:00
type NotUndefined<T> = T extends undefined ? never : T
type InferDefaults<T> = {
[K in keyof T]?: InferDefault<T, T[K]>
2021-06-27 09:11:57 +08:00
}
type NativeType = null | number | string | boolean | symbol | Function
type InferDefault<P, T> =
| ((props: P) => T & {})
| (T extends NativeType ? T : never)
type PropsWithDefaults<
T,
Defaults extends InferDefaults<T>,
BKeys extends keyof T,
> = Readonly<Omit<T, keyof Defaults>> & {
readonly [K in keyof Defaults]-?: K extends keyof T
? Defaults[K] extends undefined
? T[K]
: NotUndefined<T[K]>
: never
} & {
readonly [K in BKeys]-?: K extends keyof Defaults
? Defaults[K] extends undefined
? boolean | undefined
: boolean
: boolean
}
2021-06-27 09:11:57 +08:00
/**
* Vue `<script setup>` compiler macro for providing props default values when
* using type-based `defineProps` declaration.
2021-06-27 09:11:57 +08:00
*
* Example usage:
* ```ts
* withDefaults(defineProps<{
* size?: number
* labels?: string[]
* }>(), {
* size: 3,
* labels: () => ['default label']
* })
* ```
*
* This is only usable inside `<script setup>`, is compiled away in the output
* and should **not** be actually called at runtime.
2023-04-02 10:02:33 +08:00
*
* @see {@link https://vuejs.org/guide/typescript/composition-api.html#typing-component-props}
2021-06-27 09:11:57 +08:00
*/
export function withDefaults<
T,
BKeys extends keyof T,
Defaults extends InferDefaults<T>,
>(
props: DefineProps<T, BKeys>,
2021-06-27 09:11:57 +08:00
defaults: Defaults,
): PropsWithDefaults<T, Defaults, BKeys> {
2021-06-27 09:11:57 +08:00
if (__DEV__) {
warnRuntimeUsage(`withDefaults`)
}
2021-06-27 09:11:57 +08:00
return null as any
}
2021-06-27 09:11:57 +08:00
export function useSlots(): SetupContext['slots'] {
return getContext().slots
}
export function useAttrs(): SetupContext['attrs'] {
return getContext().attrs
}
2021-06-23 22:31:32 +08:00
function getContext(): SetupContext {
const i = getCurrentInstance()!
if (__DEV__ && !i) {
warn(`useContext() called without active instance.`)
}
return i.setupContext || (i.setupContext = createSetupContext(i))
}
/**
* @internal
*/
export function normalizePropsOrEmits(
props: ComponentPropsOptions | EmitsOptions,
) {
return isArray(props)
? props.reduce(
(normalized, p) => ((normalized[p] = null), normalized),
{} as ComponentObjectPropsOptions | ObjectEmitsOptions,
)
: props
}
2021-06-27 09:11:57 +08:00
/**
* Runtime helper for merging default declarations. Imported by compiled code
* only.
* @internal
*/
export function mergeDefaults(
raw: ComponentPropsOptions,
2021-06-27 09:11:57 +08:00
defaults: Record<string, any>,
): ComponentObjectPropsOptions {
const props = normalizePropsOrEmits(raw)
2021-06-27 09:11:57 +08:00
for (const key in defaults) {
if (key.startsWith('__skip')) continue
let opt = props[key]
if (opt) {
if (isArray(opt) || isFunction(opt)) {
opt = props[key] = { type: opt, default: defaults[key] }
} else {
opt.default = defaults[key]
}
} else if (opt === null) {
opt = props[key] = { default: defaults[key] }
2021-06-27 09:11:57 +08:00
} else if (__DEV__) {
warn(`props default key "${key}" has no corresponding declaration.`)
}
if (opt && defaults[`__skip_${key}`]) {
opt.skipFactory = true
}
2021-06-27 09:11:57 +08:00
}
return props
}
/**
* Runtime helper for merging model declarations.
* Imported by compiled code only.
* @internal
*/
export function mergeModels(
a: ComponentPropsOptions | EmitsOptions,
b: ComponentPropsOptions | EmitsOptions,
) {
if (!a || !b) return a || b
if (isArray(a) && isArray(b)) return a.concat(b)
return extend({}, normalizePropsOrEmits(a), normalizePropsOrEmits(b))
}
/**
* Used to create a proxy for the rest element when destructuring props with
* defineProps().
* @internal
*/
export function createPropsRestProxy(
props: any,
excludedKeys: string[],
): Record<string, any> {
const ret: Record<string, any> = {}
for (const key in props) {
if (!excludedKeys.includes(key)) {
Object.defineProperty(ret, key, {
enumerable: true,
get: () => props[key],
})
}
}
return ret
}
/**
* `<script setup>` helper for persisting the current instance context over
* async/await flows.
*
* `@vue/compiler-sfc` converts the following:
*
* ```ts
* const x = await foo()
* ```
*
* into:
*
* ```ts
* let __temp, __restore
* const x = (([__temp, __restore] = withAsyncContext(() => foo())),__temp=await __temp,__restore(),__temp)
* ```
* @internal
*/
export function withAsyncContext(getAwaitable: () => any) {
const ctx = getCurrentInstance()!
if (__DEV__ && !ctx) {
warn(
`withAsyncContext called without active current instance. ` +
`This is likely a bug.`,
)
}
let awaitable = getAwaitable()
unsetCurrentInstance()
if (isPromise(awaitable)) {
awaitable = awaitable.catch(e => {
setCurrentInstance(ctx)
throw e
})
}
return [awaitable, () => setCurrentInstance(ctx)]
}