Add extendValidator prop

[btea]

• Start Date: (2025-01-19)
• Target Major Version: (3.x)
• Reference Issues: (fill in existing related issues, if any)
• Implementation PR: (leave this empty)

Summary

Expand the warning information of validator verification to provide clearer error prompts.

Basic example

<script setup>
defineProps({
  num: {
    type: Number,
    extendValidator(name, value, props, warn) {
	  if (typeof value !== 'number') {
		warn(`[Custom Component]: Invalid prop: custom validator check failed for prop "${name}", expected type number, but got ${typeof value}`)
	  } else (!Number.isInteger(value)) {
		warn(`[Custom Component]: Invalid prop: custom validator check failed for prop "${name}", expected an integer.`)
	  }
    }
  }
})
</script>

Motivation

In custom components, we usually validate many props for a better user experience. Currently, the validator function will only return true or false. If it is false, it means that the validation has failed and a warning message will be thrown inside vue.

However, the warning message only indicates that a prop check failed, but users cannot customize and expand more specific error descriptions.

Detailed design

In order not to affect the original users, it may be a good idea to add a new function to give users more customization space.

refer #Basic example

Drawbacks

In most cases, the current validator function will suffice. (This proposal is merely to optimize the development experience based on the original one.)

Alternatives

Add new parameters based on the original validator and make different processing according to different parameters.

Adoption strategy

Unresolved questions

N/A

[jacekkarczmarczyk]

Can't you just add console.warn in normal validator?

[btea]

In the current implementation second argument of validator is props object, calling an object would throw an exception

Yes, I know, so I changed the warn in your example to the third parameter, passed the warn function inside vue in, and called it directly. The result is shown in the figure above.

- if (validator && !validator(value, props))
+ if (validator && !validator(value, props, warn))

https://github.com/vuejs/core/blob/82da43d167462bc36c5e94e4a99dca12ea15d08b/packages/runtime-core/src/componentProps.ts#L708

[jacekkarczmarczyk]

But the warn function you're passing doesn't suppress the original warning as I suggested in my comment with examples

[btea]

So what you mean is actually to modify the internal logic of warn, and then decide whether to print warning information inside vue based on the parameters you pass in. Right?

[jacekkarczmarczyk]

No, you can create a new function that calls the original warn with custom message and optionally surpresses the original validator warning and pass this function instead of original warn

[btea]

I seem to understand what you mean. However, I think it is better to add a new method according to my current implementation, without changing the original logic, and basically will not cause any impact on the original users. vuejs/core#12738