feat(compiler-sfc): introduce `defineModel` macro and `useModel` helper #8018

sxzz · 2023-04-03T18:47:43Z

⚠️ Status: Experimental

Summary

This PR introduces a new macro called defineModel that enhances the developer experience when using two-way binding props. With defineModel, v-model props can be declared and mutated like a ref.

The macro is a <script setup> only feature.
When compiled, it will declare a prop with the same name and a corresponding update:propName event.
Experimental feature. Introduced a new compiler script option defineModel, and it's disabled by default.

The PR also includes a new runtime helper function called useModel. This function is used as the underlying output of defineModel, and can be used in plain setup() functions where SFC isn't used. It works similarly to useVModel from VueUse.

Basic Usage

`defineModel`

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 options object can also specify an additional option, local. When set to true, the ref can be locally mutated even if the parent did not pass the matching v-model.

// default model (consumed via `v-model`)
const modelValue = defineModel()
   // ^? Ref<any>
modelValue.value = 10

const modelValue = defineModel<string>()
   // ^? Ref<string | undefined>
modelValue.value = "hello"

// default model with options, required removes possible undefined values
const modelValue = defineModel<stirng>({ required: true })
   // ^? Ref<string>

// 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 })
   // ^? Ref<number>

// local mutable model, can be mutated locally
// even if the parent did not pass the matching `v-model`.
const count = defineModel<number>('count', { local: true, default: 0 })

See demo

`useModel`

import { useModel } from 'vue'

export default {
  props: {
    modelValue: { type: Number, default: 0 },
  },
  emits: ['update:modelValue'],
  setup(props) {
    const modelValue = useModel(props, 'modelValue')
       // ^? Ref<number>

    return { modelValue }
  }
}

See demo

sqal · 2023-04-05T19:34:17Z

const modelValue = defineModel({ type: null, required: false, default: 0 })

// generated code
const __sfc__ = _defineComponent({
  props: {
    "modelValue": { required: true, ...{ type: null, required: false, default: 0 } },
  },
})

Can this output be optimized to modelValue: { type: null, required: false, default: 0 } ?

Second thing. Why is type any casted to Unknown?

const modelValue = defineModel<any>()

// output
"modelValue": { type: Unknown, required: true }

sxzz · 2023-04-05T22:07:01Z

@sqal Thanks for reviewing. The first issue can be optimized but it only happened in development mode. So now it's not very worth improving it.

The second issue is fixed now.

yyx990803 · 2023-04-06T09:49:55Z

packages/compiler-sfc/__tests__/compileScript.spec.ts

@@ -1391,12 +1509,12 @@ const emit = defineEmits(['a', 'b'])
      expect(content).toMatch(`const props = __props`)

      // foo has no default value, the Function can be dropped
-      expect(content).toMatch(`foo: null`)
-      expect(content).toMatch(`bar: { type: Boolean }`)
+      expect(content).toMatch(`foo: { required: true }`)


These should be avoided - in production mode required is useless since there will be no warnings / checks, so we should generate the minimal amount of options to save bundle size.

No, it's intentional. useModel requires required option to check if a prop is passive.

BTW required: false can still be omitted. (done)

packages/compiler-sfc/__tests__/compileScriptPropsDestructure.spec.ts

yyx990803 · 2023-04-06T09:58:56Z

packages/compiler-sfc/src/compileScript.ts

-    runtimeOptions += genRuntimeEmits(typeDeclaredEmits)
-  }
+
+  let propsDecl = genRuntimeProps()


Suggested change

let propsDecl = genRuntimeProps()

const propsDecl = genRuntimeProps()

Hope ESLint prefer-const can be enabled.

packages/compiler-sfc/src/compileScript.ts

packages/runtime-core/src/apiSetupHelpers.ts

vercel · 2023-04-06T11:31:51Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

1 Ignored Deployment

Name	Status	Preview	Updated (UTC)
sfc-playground	⬜️ Ignored (Inspect)		Apr 8, 2023 4:00am

jacekkarczmarczyk · 2023-04-28T09:35:27Z

packages/runtime-core/src/apiSetupHelpers.ts

+ * modelValue.value = "hello"
+ *
+ * // default model with options
+ * const modelValue = defineModel<stirng>({ required: true })


* const modelValue = defineModel<string>({ required: true })

…#8018)

Merkushin-AY · 2023-05-17T08:05:32Z

@sxzz Why is component that has defineModel not working without v-model from outside?

Example from your demo:
App.vue:

<script setup>
import Comp from './Comp.vue'
import {ref} from 'vue'
  
const count = ref(0)
</script>

<template>
  <Comp /> <!-- NOT WORKING -->
  <hr />
  <Comp v-model="count" />
  <hr />
  <input v-model="count"/>
  {{ count }}
</template>

Comp.vue:

<script setup lang=ts>
import { ref } from 'vue'

const modelValue = defineModel<number>({ default: 0 })
</script>

<template>
  <button @click="modelValue++">+</button>
  {{modelValue}}
</template>

So you have to write a bunch of excess code to fix it:
Comp.vue:

<script setup lang=ts>
import { ref, watchEffect } from 'vue'

const modelValue = defineModel<number>({ default: 0 })

const counter = ref(modelValue.value)

watchEffect(() => {
  counter.value = modelValue.value
})
</script>

<template>
  <button @click="() => {counter++; modelValue++;}">+</button>
  {{counter}}
</template>

loosheng · 2023-05-18T03:48:10Z

@Merkushin-AY You can see vuejs/rfcs#503 Local Mode Chapter.

coolCucumber-cat · 2023-05-26T06:56:54Z

When will this no longer be experimental and opt-in? Should I avoid using it in my project until it's stable?

sxzz changed the title ~~feat(compiler-sfc): introduce defineModel macro~~ feat(compiler-sfc): introduce defineModel macro and useModel helper Apr 3, 2023

sxzz force-pushed the feat/define-model branch 2 times, most recently from ed8c3fb to fdd91c6 Compare April 5, 2023 11:28

sxzz added 3 commits April 5, 2023 23:50

wip: defineModel

6c9ac2d

test: disallow

4607c27

wip

f72c1f2

sxzz force-pushed the feat/define-model branch from fdd91c6 to f72c1f2 Compare April 5, 2023 15:50

sxzz added 6 commits April 6, 2023 00:53

feat: done

c3aa008

test: add case

2f66129

feat: fn with default

5fa8165

chore: rename

12b9a91

refactor: re-organize

45d0784

test: add cases

87c4e00

sxzz marked this pull request as ready for review April 5, 2023 19:01

sxzz requested a review from yyx990803 April 5, 2023 19:02

sxzz added 3 commits April 6, 2023 03:07

refactor: remove default

e84cc32

feat: add doc

c448500

refactor: simplify

75f3a47

sxzz added 2 commits April 6, 2023 05:09

fix: add required for production mode

11149ec

feat: addRequiredToModels

e56ffa8

sxzz force-pushed the feat/define-model branch from 69da94c to e56ffa8 Compare April 5, 2023 21:32

sxzz added 2 commits April 6, 2023 05:37

fix: compiler

3550a15

fix: unknown type

43faf2e

yyx990803 requested changes Apr 6, 2023

View reviewed changes

fix: resolve PR comments

a7481c0

sxzz added 2 commits April 6, 2023 19:46

refactor: omit required: false

b1d7c1a

chore: remove useless test

ad04b27

sxzz requested a review from yyx990803 April 6, 2023 12:42

yyx990803 added 3 commits April 7, 2023 11:04

fix: fix mergeModels helper name

57de8d1

chore: small refactors

61e5b23

refactor: default useModel key + ensure prod/dev behavior consistency

63fa911

yyx990803 approved these changes Apr 7, 2023

View reviewed changes

yyx990803 added 4 commits April 7, 2023 13:31

refactor: still make name required for useModel

b59baf8

feat: improve defineModel typing

29e3a93

refactor: decouple props required option and local mode

b2c1269

chore: update defineModel comments doc

6f70962

yyx990803 merged commit 14f3d74 into main Apr 8, 2023
14 checks passed

yyx990803 deleted the feat/define-model branch April 8, 2023 04:13

yyx990803 mentioned this pull request Apr 28, 2023

Short word for @update:model-value #8177

Closed

jacekkarczmarczyk reviewed Apr 28, 2023

View reviewed changes

IAmSSH pushed a commit to IAmSSH/core that referenced this pull request May 14, 2023

feat(sfc): introduce defineModel macro and useModel helper (vuejs…

94a936c

…#8018)

ferreira-tb mentioned this pull request May 25, 2023

Usos de useVModel devem ser substituídos pelo novo defineModel ferreira-tb/ares#257

Open

Saeid-Za mentioned this pull request Mar 21, 2024

defineModel loses two way binding flow when parent adds event listeneres #10560

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(compiler-sfc): introduce `defineModel` macro and `useModel` helper #8018

feat(compiler-sfc): introduce `defineModel` macro and `useModel` helper #8018

sxzz commented Apr 3, 2023 •

edited

sqal commented Apr 5, 2023

sxzz commented Apr 5, 2023

yyx990803 Apr 6, 2023

sxzz Apr 6, 2023 •

edited

yyx990803 Apr 6, 2023

sxzz Apr 6, 2023

vercel bot commented Apr 6, 2023 •

edited

jacekkarczmarczyk Apr 28, 2023

Merkushin-AY commented May 17, 2023

loosheng commented May 18, 2023

coolCucumber-cat commented May 26, 2023

	let propsDecl = genRuntimeProps()
	const propsDecl = genRuntimeProps()

feat(compiler-sfc): introduce defineModel macro and useModel helper #8018

feat(compiler-sfc): introduce defineModel macro and useModel helper #8018

Conversation

sxzz commented Apr 3, 2023 • edited

Summary

Basic Usage

defineModel

useModel

sqal commented Apr 5, 2023

sxzz commented Apr 5, 2023

yyx990803 Apr 6, 2023

Choose a reason for hiding this comment

sxzz Apr 6, 2023 • edited

Choose a reason for hiding this comment

yyx990803 Apr 6, 2023

Choose a reason for hiding this comment

sxzz Apr 6, 2023

Choose a reason for hiding this comment

vercel bot commented Apr 6, 2023 • edited

jacekkarczmarczyk Apr 28, 2023

Choose a reason for hiding this comment

Merkushin-AY commented May 17, 2023

loosheng commented May 18, 2023

coolCucumber-cat commented May 26, 2023

feat(compiler-sfc): introduce `defineModel` macro and `useModel` helper #8018

feat(compiler-sfc): introduce `defineModel` macro and `useModel` helper #8018

sxzz commented Apr 3, 2023 •

edited

`defineModel`

`useModel`

sxzz Apr 6, 2023 •

edited

vercel bot commented Apr 6, 2023 •

edited