diff --git a/src/api/application-config.md b/src/api/application-config.md index 0f70f89247..0bd8bdc2b1 100644 --- a/src/api/application-config.md +++ b/src/api/application-config.md @@ -77,27 +77,6 @@ const app = createApp({}) app.config.globalProperties.$http = () => {} ``` -## isCustomElement - -- **Type:** `(tag: string) => boolean` - -- **Default:** `undefined` - -- **Usage:** - -```js -// any element starting with 'ion-' will be recognized as a custom one -app.config.isCustomElement = tag => tag.startsWith('ion-') -``` - -Specifies a method to recognize custom elements defined outside of Vue (e.g., using the Web Components APIs). If component matches this condition, it won't need local or global registration and Vue won't throw a warning about an `Unknown custom element`. - -> Note that all native HTML and SVG tags don't need to be matched in this function - Vue parser performs this check automatically - -::: tip Important -This config option is only respected when using the runtime compiler. If you are using the runtime-only build, `isCustomElement` must be passed to `@vue/compiler-dom` in the build setup instead - for example, via the [`compilerOptions` option in vue-loader](https://vue-loader.vuejs.org/options.html#compileroptions). -::: - ## optionMergeStrategies - **Type:** `{ [key: string]: Function }` @@ -113,7 +92,7 @@ const app = createApp({ } }) -app.config.optionMergeStrategies.hello = (parent, child, vm) => { +app.config.optionMergeStrategies.hello = (parent, child) => { return `Hello, ${child}` } @@ -126,7 +105,7 @@ app.mixin({ Define merging strategies for custom options. -The merge strategy receives the value of that option defined on the parent and child instances as the first and second arguments, respectively. The context application instance is passed as the third argument. +The merge strategy receives the value of that option defined on the parent and child instances as the first and second arguments, respectively. - **See also:** [Custom Option Merging Strategies](../guide/mixins.html#custom-option-merge-strategies) @@ -139,3 +118,91 @@ The merge strategy receives the value of that option defined on the parent and c - **Usage**: Set this to `true` to enable component init, compile, render and patch performance tracing in the browser devtool performance/timeline panel. Only works in development mode and in browsers that support the [performance.mark](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) API. + +## compilerOptions + +- **Type:** `Object` + +Configure runtime compiler options. Values set on this object will be passed to the in-browser template compiler and affect every component in the configured app. Note you can also override these options on a per-component basis using the [`compilerOptions` option](/api/options-misc.html#compileroptions). + +::: tip Important +This config option is only respected when using the full build (i.e. the standalone `vue.js` that can compile templates in the browser). If you are using the runtime-only build with a build setup, compiler options must be passed to `@vue/compiler-dom` via build tool configurations instead. + +- For `vue-loader`: [pass via the `compilerOptions` loader option](https://vue-loader.vuejs.org/options.html#compileroptions). Also see [how to configure it in `vue-cli`](https://cli.vuejs.org/guide/webpack.html#modifying-options-of-a-loader). + +- For `vite`: [pass via `@vitejs/plugin-vue` options](https://github.com/vitejs/vite/tree/main/packages/plugin-vue#example-for-passing-options-to-vuecompiler-dom). +::: + +### compilerOptions.isCustomElement + +- **Type:** `(tag: string) => boolean` + +- **Default:** `undefined` + +- **Usage:** + +```js +// any element starting with 'ion-' will be recognized as a custom one +app.config.compilerOptions.isCustomElement = tag => tag.startsWith('ion-') +``` + +Specifies a method to recognize custom elements defined outside of Vue (e.g., using the Web Components APIs). If component matches this condition, it won't need local or global registration and Vue won't throw a warning about an `Unknown custom element`. + +> Note that all native HTML and SVG tags don't need to be matched in this function - Vue parser performs this check automatically. + +### compilerOptions.whitespace + +- **Type:** `'condense' | 'preserve'` + +- **Default:** `'condense'` + +- **Usage:** + +```js +app.config.compilerOptions.whitespace = 'preserve' +``` + +By default, Vue removes/condenses whitespaces between template elements to produce more efficient compiled output: + +1. Leading / ending whitespaces inside an element are condensed into a single space +2. Whitespaces between elements that contain newlines are removed +3. Consecutive whitespaces in text nodes are condensed into a single space + +Setting the value to `'preserve'` will disable (2) and (3). + +### compilerOptions.delimiters + +- **Type:** `Array` + +- **Default:** `{{ "['\u007b\u007b', '\u007d\u007d']" }}` + +- **Usage:** + +```js +// Delimiters changed to ES6 template string style +app.config.compilerOptions.delimiters = ['${', '}'] +``` + +Sets the delimiters used for text interpolation within the template. + +Typically this is used to avoid conflicting with server-side frameworks that also use mustache syntax. + +### compilerOptions.comments + +- **Type:** `boolean` + +- **Default:** `false` + +- **Usage:** + +```js +app.config.compilerOptions.comments = true +``` + +By default, Vue will remove HTML comments inside templates in production. Setting this option to `true` will force Vue to preserve comments even in production. Comments are always preserved during development. + +This option is typically used when Vue is used with other libraries that rely on HTML comments. + +## isCustomElement + +Deprecated in 3.1.0. Use [`compilerOptions.isCustomElement`](#compileroptions-iscustomelement) instead. diff --git a/src/api/composition-api.md b/src/api/composition-api.md index 4f518614b9..14405575f7 100644 --- a/src/api/composition-api.md +++ b/src/api/composition-api.md @@ -4,32 +4,51 @@ ## `setup` -A component option that is executed **before** the component is created, once the `props` are resolved, and serves as the entry point for composition API's +A component option that is executed **before** the component is created, once the `props` are resolved. It serves as the entry point for composition APIs. - **Arguments:** - `{Data} props` - `{SetupContext} context` + Similar to `this.$props` when using Options API, the `props` object will only contain explicitly declared props. Also, all declared prop keys will be present on the `props` object, regardless of whether it was passed by the parent component or not. Absent optional props will have a value of `undefined`. + + If you need to check the absence of an optional prop, you can give it a Symbol as its default value: + + ```js + const isAbsent = Symbol() + + export default { + props: { + foo: { default: isAbsent } + }, + setup(props) { + if (props.foo === isAbsent) { + // foo was not provided. + } + } + } + ``` + - **Typing**: -```ts -interface Data { - [key: string]: unknown -} + ```ts + interface Data { + [key: string]: unknown + } -interface SetupContext { - attrs: Data - slots: Slots - emit: (event: string, ...args: unknown[]) => void -} + interface SetupContext { + attrs: Data + slots: Slots + emit: (event: string, ...args: unknown[]) => void + } -function setup(props: Data, context: SetupContext): Data -``` + function setup(props: Data, context: SetupContext): Data + ``` -::: tip -To get type inference for the arguments passed to `setup()`, the use of [defineComponent](global-api.html#definecomponent) is needed. -::: + ::: tip + To get type inference for the arguments passed to `setup()`, the use of [defineComponent](global-api.html#definecomponent) is needed. + ::: - **Example** @@ -129,40 +148,40 @@ The component instance context is also set during the synchronous execution of l - **Typing**: -```ts -interface InjectionKey extends Symbol {} - -function provide(key: InjectionKey | string, value: T): void - -// without default value -function inject(key: InjectionKey | string): T | undefined -// with default value -function inject(key: InjectionKey | string, defaultValue: T): T -// with factory -function inject( - key: InjectionKey | string, - defaultValue: () => T, - treatDefaultAsFactory: true -): T -``` + ```ts + interface InjectionKey extends Symbol {} + + function provide(key: InjectionKey | string, value: T): void + + // without default value + function inject(key: InjectionKey | string): T | undefined + // with default value + function inject(key: InjectionKey | string, defaultValue: T): T + // with factory + function inject( + key: InjectionKey | string, + defaultValue: () => T, + treatDefaultAsFactory: true + ): T + ``` -Vue provides an `InjectionKey` interface which is a generic type that extends `Symbol`. It can be used to sync the type of the injected value between the provider and the consumer: + Vue provides an `InjectionKey` interface which is a generic type that extends `Symbol`. It can be used to sync the type of the injected value between the provider and the consumer: -```ts -import { InjectionKey, provide, inject } from 'vue' + ```ts + import { InjectionKey, provide, inject } from 'vue' -const key: InjectionKey = Symbol() + const key: InjectionKey = Symbol() -provide(key, 'foo') // providing non-string value will result in error + provide(key, 'foo') // providing non-string value will result in error -const foo = inject(key) // type of foo: string | undefined -``` + const foo = inject(key) // type of foo: string | undefined + ``` -If using string keys or non-typed symbols, the type of the injected value will need to be explicitly declared: + If using string keys or non-typed symbols, the type of the injected value will need to be explicitly declared: -```ts -const foo = inject('foo') // string | undefined -``` + ```ts + const foo = inject('foo') // string | undefined + ``` - **See also**: - [Provide / Inject](../guide/component-provide-inject.html) @@ -170,7 +189,11 @@ const foo = inject('foo') // string | undefined ## `getCurrentInstance` -`getCurrentInstance` enables access to an internal component instance useful for advanced usages or for library creators. +`getCurrentInstance` enables access to an internal component instance. + +:::warning +`getCurrentInstance` is only exposed for advanced use cases, typically in libraries. Usage of `getCurrentInstance` is strongly discouraged in application code. Do **NOT** use it as an escape hatch to get the equivalent of `this` in Composition API. +::: ```ts import { getCurrentInstance } from 'vue' diff --git a/src/api/directives.md b/src/api/directives.md index 7ef2c4bb9f..70263f2f3d 100644 --- a/src/api/directives.md +++ b/src/api/directives.md @@ -454,31 +454,6 @@ - **See also:** - [Data Binding Syntax - interpolations](../guide/template-syntax.html#text) -## v-is +## v-is -> Note: this section only affects cases where Vue templates are directly written in the page's HTML. - -- **Expects:** string literal - -- **Limited to:** native HTML elements - -- **Usage:** When using in-DOM templates, the template is subject to native HTML parsing rules. Some HTML elements, such as `
    `, `
      `, `` and ``, and `
      - -
      -``` - -:::warning -`v-is` functions like a dynamic 2.x `:is` binding - so to render a component by its registered name, its value should be a JavaScript string literal: - -```html - - - - - -``` - -::: +Deprecated in 3.1.0. Use [`is` attribute with `vue:` prefix](/api/special-attributes.html#is) instead. diff --git a/src/api/options-misc.md b/src/api/options-misc.md index 1f5243ae7f..80275bbb0d 100644 --- a/src/api/options-misc.md +++ b/src/api/options-misc.md @@ -10,29 +10,6 @@ Another benefit of specifying a `name` option is debugging. Named components result in more helpful warning messages. Also, when inspecting an app in the [vue-devtools](https://github.com/vuejs/vue-devtools), unnamed components will show up as ``, which isn't very informative. By providing the `name` option, you will get a much more informative component tree. -## delimiters - -- **Type:** `Array` - -- **Default:** `{{ "['\u007b\u007b', '\u007d\u007d']" }}` - -- **Restrictions:** This option is only available in the full build, with in-browser template compilation. - -- **Details:** - - Sets the delimiters used for text interpolation within the template. - - Typically this is used to avoid conflicting with server-side frameworks that also use mustache syntax. - -- **Example:** - - ```js - createApp({ - // Delimiters changed to ES6 template string style - delimiters: ['${', '}'] - }) - ``` - ## inheritAttrs - **Type:** `boolean` @@ -64,3 +41,31 @@ ``` - **See also:** [Disabling Attribute Inheritance](../guide/component-attrs.html#disabling-attribute-inheritance) + +## compilerOptions + +- **Type:** `Object` + +- **Details:** + + This is the component-level equivalent of the [app-level `compilerOptions` config](/api/application-config.html#compileroptions). + +- **Usage:** + + ```js + const Foo = { + // ... + compilerOptions: { + delimiters: ['${', '}'], + comments: true + } + } + ``` + + ::: tip Important + Similar to the app-level `compilerOptions` config, this option is only respected when using the full build with in-browser template compilation. + ::: + +## delimiters + +Deprecated in 3.1.0. Use `compilerOptions.delimiters` instead. \ No newline at end of file diff --git a/src/api/special-attributes.md b/src/api/special-attributes.md index 96ebc7ffe0..5dc0ad7962 100644 --- a/src/api/special-attributes.md +++ b/src/api/special-attributes.md @@ -56,15 +56,27 @@ - **Expects:** `string | Object (component’s options object)` -Used for [dynamic components](../guide/component-dynamic-async.html). + Used for [dynamic components](../guide/component-dynamic-async.html). -For example: + For example: + + ```html + + + ``` + +- **Usage on native elements** -```html - - -``` + When the `is` attribute is used on a native HTML element, it will be interpreted as a [Customized built-in element](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-customized-builtin-example), which is a native web platform feature. + + There is, however, a use case where you may need Vue to replace a native element with a Vue component, as explained in [DOM Template Parsing Caveats](/guide/component-basics.html#dom-template-parsing-caveats). You can prefix the value of the `is` attribute with `vue:` so that Vue will render the element as a Vue component instead: + + ```html + + +
      + ``` - **See also:** - [Dynamic Components](../guide/component-dynamic-async.html) - - [DOM Template Parsing Caveats](../guide/component-basics.html#dom-template-parsing-caveats) + - [RFC explaining the change from Vue 2](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0027-custom-elements-interop.md#customized-built-in-elements) diff --git a/src/guide/component-basics.md b/src/guide/component-basics.md index 64c2a32f03..fa9f4312dc 100644 --- a/src/guide/component-basics.md +++ b/src/guide/component-basics.md @@ -406,6 +406,18 @@ That's all you need to know about dynamic components for now, but once you've fi ## DOM Template Parsing Caveats +If you are writing your Vue templates directly in the DOM, Vue will have to retrieve the template string from the DOM. This leads to some caveats due to browsers' native HTML parsing behavior. + +:::tip +It should be noted that the limitations discussed below only apply if you are writing your templates directly in the DOM. They do NOT apply if you are using string templates from the following sources: + +- String templates (e.g. `template: '...'`) +- [Single-file (`.vue`) components](single-file-component.html) +- `