Vue3 Documentation Quick Start

1. Setup

Combination API:

• The setup option should be a function
• setup option function accepts two parameters: props and context
• setup option function needs to return the content to be exposed to the component
• setup needs to be returned using return before it can be used by the component, including data and methods

1. The first parameter in the setup function — props

props in the setup function are responsive, and will be updated when new props are passed in.

export default {
  props: {
    title: String
  },
  setup(props) {
    console.log(props.title)
  }
}

However, because props are reactive, you cannot use ES6 destructuring because it would eliminate the responsiveness of the props.
If you need to destructure the prop, you can do so safely by using toRefs in the setup function.

import { toRefs } from 'vue'

setup(props) {
    const { title } = toRefs(props)

    console.log(title.value)
}

2. context

The second parameter in the setup function - contextcontext is a plain JavaScript object that exposes the properties of the three components.

xport default {
  setup(props, context) {
    // Attribute (non-responsive object)
    console.log(context.attrs)

    // Slot (non-responsive object)
    console.log(context.slots)

    // Trigger event (method)
    console.log(context.emit)
  }
}

context is a plain JavaScript object, that is, it is not reactive, which means you can safely use ES6 destructuring on the context

export default {
  setup(props, { attrs, slots, emit }) {
    ...
  }
}

2. Return value of setup function

1. The return value of the setup function - object

If setup returns an object, you can access the properties of that object in your component's template just like props property passed to setup :

<template>
  <!-- It will be automatically unpacked when used in the template, so .value is not needed -->
  <div>{{ readersNumber }} {{ book.title }}</div>
</template>

<script>
  import { ref, reactive } from 'vue'

  export default {
    setup() {
      const readersNumber = ref(0)
      const book = reactive({ title: 'Vue 3 Guide' })

      // expose to template
      return {
        readersNumber,
        book
      }
    }
  }
</script>

Note: refs returned from setup are automatically unwrapped when accessed in templates, so you should not use .value in templates.

3. Responsive System API

1. reactive

reactive() takes a plain object and returns a responsive proxy for that plain object. Equivalent to Vue.observable() in 2.x

const obj = reactive({ count: 0 })

Responsive transformations are "deep": they affect all nested properties inside the object. Based on the ES2015 Proxy implementation, the returned proxy object is not equal to the original object. It is recommended to use only proxy objects and avoid relying on the original objects.

<template>
  <div id="app">{ state.count }</div>
</template>

<script>
import { reactive } from 'vue'
export default {
  setup() {
    // state is now a reactive state const state = reactive({
      count: 0,
    })
  }
}
</script>

2. ref

Accepts a value and returns a responsive, mutable ref object. A ref object has a single property .value that points to the internal value.

const count = ref(0)
console.log(count.value) // 0

count.value++
console.log(count.value) // 1

If ref passed in is an object, the reactive method will be called to perform a deep response conversion.

Access in template:

When ref is returned as a property of the rendering context (i.e. in the object returned by setup() ) and used in a template, it is automatically unwrapped without the need to write .value in the template:

<template>
  <div>{{ count }}</div>
</template>

<script>
  export default {
    setup() {
      return {
        count: ref(0),
      }
    },
  }
</script>

Access as a property of a responsive object:

When ref is accessed or modified as property of a reactive object, value value will also be automatically unwrapped, and its behavior is similar to that of a normal property:

const count = ref(0)
const state = reactive({
  count,
})

console.log(state.count) // 0

state.count = 1
console.log(count.value) // 1

Note: If you assign a new ref to an existing ref , the old ref will be replaced:

const otherCount = ref(2)

state.count = otherCount
console.log(state.count) // 2
console.log(count.value) // 1

Note: ref will be unwrapped only when nested in reactive Object . When accessing ref from native collection classes such as Array or Map , it will not be automatically unwrapped:

const arr = reactive([ref(0)])
// .value is needed here
console.log(arr[0].value)

const map = reactive(new Map([['foo', ref(0)]]))
// .value is needed here
console.log(map.get('foo').value)

Type definitions:

interface Ref<T> {
  value: T
}

function ref<T>(value: T): Ref<T>

Sometimes we may need to make a more complex type annotation for ref . We can override the default deduction by passing a generic type argument when calling ref :

const foo = ref<string | number>('foo') // Type of foo: Ref<string | number>

foo.value = 123 // Passes!

3. computed

There are two ways to use the responsive computed API :

(1) Pass in a getter function and return a ref object that cannot be manually modified by default.

const count = ref(1)
const plusOne = computed(() => count.value + 1)

console.log(plusOne.value) // 2

plusOne.value++ // Error!

(2) Pass in an object with get and set functions to create a computational state that can be manually modified.

const count = ref(1)
const plusOne = computed({
  get: () => count.value + 1,
  set: (val) => {
    count.value = val - 1
  },
})

plusOne.value = 1
console.log(count.value) // 0

Type definitions:

// read-only function computed<T>(getter: () => T): Readonly<Ref<Readonly<T>>>

// Modifiable function computed<T>(options: {
  get: () => T
  set: (value: T) => void
}): Ref<T>

4. readonly

Pass an object (responsive or normal) or ref and return a read-only proxy to the original object. A read-only proxy is "deep", and any nested properties inside the object are also read-only.

const original = reactive({ count: 0 })

const copy = readonly(original)

watchEffect(() => {
  // Dependency tracking console.log(copy.count)
})

// Modifications on original will trigger listeners on copy original.count++

// Cannot modify copy and will be warned copy.count++ // warning!

5. watchEffect

Immediately executes a function passed in, and reactively tracks its dependencies and re-runs the function if its dependencies change.

const count = ref(0)

watchEffect(() => console.log(count.value))
//-> print out 0

setTimeout(() => {
  count.value++
  //-> print out 1
}, 100)

5.1 Stop listening

When watchEffect is called in a component's setup() function or a lifecycle hook, the listener is linked to the component's lifecycle and automatically stopped when the component is uninstalled.

In some cases, you can also explicitly call the return value to stop listening:

const stop = watchEffect(() => {
  /* ... */
})

// Then stop()

5.2 Clearing Side Effects

Sometimes a side-effect function performs some asynchronous side effects that need to be cleaned up when it is invalid (i.e. the state has changed before it completes). Therefore, the function passed in by the listening side effect can receive an onInvalidate function as an input parameter to register a callback when the cleanup fails. This invalidation callback is triggered when the following happens:

• When the side effect is about to be re-executed
• The listener is stopped (when the component is unmounted if watchEffect is used in setup() or lifecycle hooks)
  

watchEffect((onInvalidate) => {
  const token = performAsyncOperation(id.value)
  onInvalidate(() => {
    // When the id changes or stops listening // Cancel the previous asynchronous operation token.cancel()
  })
})

The reason we register the invalidation callback by passing a function instead of returning it from the callback (like in React useEffect ) is because the return value is important for asynchronous error handling.

When performing data requests, the side-effect function is often an asynchronous function:

const data = ref(null)
watchEffect(async () => {
  data.value = await fetchData(props.id)
})

We know that asynchronous functions implicitly return a Promise , but the cleanup function must be registered before Promise is resolve . Additionally, Vue relies on this returned Promise to automatically handle potential errors on Promise chain.

5.3 Side Effect Refresh Timing

Vue 's responsive system caches side-effect functions and refreshes them asynchronously, which avoids unnecessary repeated calls caused by multiple state changes in the same tick. In the core implementation, the component's update function is also a monitored side effect. When a user-defined side effect function is queued, it is executed after all components are updated:

<template>
  <div>{{ count }}</div>
</template>

<script>
  export default {
    setup() {
      const count = ref(0)

      watchEffect(() => {
        console.log(count.value)
      })

      return {
        count,
      }
    },
  }
</script>

In this example:

count will be printed synchronously on the initial run. When changing count , the side effect will be executed after the component is updated.

Please note: the initialization run is executed before the component mounted . Therefore, if you wish to access DOM (or a template ref) when writing a side-effect function, do it in onMounted hook:

onMounted(() => {
  watchEffect(() => {
    // You can access DOM or template refs here
  })
})

If the side effect needs to be re-run synchronously or before the component is updated, we can pass an object with a flush property as options (defaults to ' post '):

// Run watchEffect synchronously(
  () => {
    /* ... */
  },
  {
    flush: 'sync',
  }
)

// Execute watchEffect(
  () => {
    /* ... */
  },
  {
    flush: 'pre',
  }
)

5.4 Listener Debugging

onTrack and onTrigger options can be used to debug the behavior of a listener.

• onTrack is called when a reactive object property or a ref is tracked as a dependency.
• onTrigger is called when a dependency change causes a side effect to be triggered
  

Both callbacks will receive a debugger event containing information about the dependencies. It is recommended to write debugger statements in the following callbacks to check dependencies:

watchEffect(
  () => {
    /* Side effects */
  },
  {
    onTrigger(e) {
      debugger
    },
  }
)

onTrack and onTrigger are only available in development mode.

Type definitions:

function watchEffect(
  effect: (onInvalidate: InvalidateCbRegistrator) => void,
  options?: WatchEffectOptions
): StopHandle

interface WatchEffectOptions {
  flush?: 'pre' | 'post' | 'sync'
  onTrack?: (event: DebuggerEvent) => void
  onTrigger?: (event: DebuggerEvent) => void
}

interface DebuggerEvent {
  effect: ReactiveEffect
  target: any
  type: OperationTypes
  key: string | symbol | undefined
}

type InvalidateCbRegistrator = (invalidate: () => void) => void

type StopHandle = () => void

6. watch

watch API is exactly equivalent to 2.x this.$watch (and the corresponding options in watch ). watch needs to listen to a specific data source and perform side effects in the callback function. The default is lazy execution, which means the callback is only executed when the watched source changes.

• Compared to watchEffect，watch allows us to:

1. Lazy execution of side effects;
2. Make it clearer which state changes trigger listeners to re-run side effects;
3. Access the values ​​before and after the listening state changes.

• Listening to a single data source

1. The data source of a listener can be a getter function that returns a value, or it can be a ref:

// Listen to a getter
const state = reactive({ count: 0 })
watch(
  () => state.count,
  (count, prevCount) => {
    /* ... */
  }
)

// Listen to a ref directly
const count = ref(0)
watch(count, (count, prevCount) => {
  /* ... */
})

6.1 Listening to Multiple Data Sources

watcher can also use arrays to listen to multiple sources simultaneously:

watch([fooRef, barRef], ([foo, bar], [prevFoo, prevBar]) => {
  /* ... */
})

6.2 Behaviors shared with watchEffect

watch and watchEffect behave the same way in stopping listening, clearing side effects (correspondingly onInvalidate will be passed as the third parameter of the callback), side effect refresh timing, and listener debugging.

Type definitions:

// Listen to a single data source function watch<T>(
  source: WatcherSource<T>,
  callback:
    value: T,
    oldValue: T,
    onInvalidate: InvalidateCbRegistrator
  ) => void,
  options?: WatchOptions
): StopHandle

// Listen to multiple data sources function watch<T extends WatcherSource<unknown>[]>(
  sources: T
  callback:
    values: MapSources<T>,
    oldValues: MapSources<T>,
    onInvalidate: InvalidateCbRegistrator
  ) => void,
  options? : WatchOptions
): StopHandle

type WatcherSource<T> = Ref<T> | (() => T)

type MapSources<T> = {
  [K in keyof T]: T[K] extends WatcherSource<infer V> ? V : never
}

// For common properties, please refer to the type definition of `watchEffect` interface WatchOptions extends WatchEffectOptions {
  immediate?: boolean // default: false
  deep?: boolean
}

This is the end of this article about the quick start of vue3 document organization. For more relevant vue3 document organization content, please search 123WORDPRESS.COM's previous articles or continue to browse the following related articles. I hope everyone will support 123WORDPRESS.COM in the future!