Skip to content

Commit c9e28e3

Browse files
yyx990803yyx990803
authored
3.1 Updates (#1078)
1 parent 2cb2d87 commit c9e28e3

File tree

10 files changed

+238
-170
lines changed

10 files changed

+238
-170
lines changed

‎src/api/application-config.md

Lines changed: 90 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -77,27 +77,6 @@ const app = createApp({})
7777
app.config.globalProperties.$http = () => {}
7878
```
7979

80-
## isCustomElement
81-
82-
- **Type:** `(tag: string) => boolean`
83-
84-
- **Default:** `undefined`
85-
86-
- **Usage:**
87-
88-
```js
89-
// any element starting with 'ion-' will be recognized as a custom one
90-
app.config.isCustomElement = tag => tag.startsWith('ion-')
91-
```
92-
93-
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`.
94-
95-
> Note that all native HTML and SVG tags don't need to be matched in this function - Vue parser performs this check automatically
96-
97-
::: tip Important
98-
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).
99-
:::
100-
10180
## optionMergeStrategies
10281

10382
- **Type:** `{ [key: string]: Function }`
@@ -113,7 +92,7 @@ const app = createApp({
11392
}
11493
})
11594

116-
app.config.optionMergeStrategies.hello = (parent, child, vm) => {
95+
app.config.optionMergeStrategies.hello = (parent, child) => {
11796
return `Hello, ${child}`
11897
}
11998

@@ -126,7 +105,7 @@ app.mixin({
126105

127106
Define merging strategies for custom options.
128107

129-
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.
108+
The merge strategy receives the value of that option defined on the parent and child instances as the first and second arguments, respectively.
130109

131110
- **See also:** [Custom Option Merging Strategies](../guide/mixins.html#custom-option-merge-strategies)
132111

@@ -139,3 +118,91 @@ The merge strategy receives the value of that option defined on the parent and c
139118
- **Usage**:
140119

141120
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.
121+
122+
## compilerOptions <Badge text="3.1+" />
123+
124+
- **Type:** `Object`
125+
126+
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).
127+
128+
::: tip Important
129+
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.
130+
131+
- 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).
132+
133+
- 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).
134+
:::
135+
136+
### compilerOptions.isCustomElement
137+
138+
- **Type:** `(tag: string) => boolean`
139+
140+
- **Default:** `undefined`
141+
142+
- **Usage:**
143+
144+
```js
145+
// any element starting with 'ion-' will be recognized as a custom one
146+
app.config.compilerOptions.isCustomElement = tag => tag.startsWith('ion-')
147+
```
148+
149+
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`.
150+
151+
> Note that all native HTML and SVG tags don't need to be matched in this function - Vue parser performs this check automatically.
152+
153+
### compilerOptions.whitespace
154+
155+
- **Type:** `'condense' | 'preserve'`
156+
157+
- **Default:** `'condense'`
158+
159+
- **Usage:**
160+
161+
```js
162+
app.config.compilerOptions.whitespace = 'preserve'
163+
```
164+
165+
By default, Vue removes/condenses whitespaces between template elements to produce more efficient compiled output:
166+
167+
1. Leading / ending whitespaces inside an element are condensed into a single space
168+
2. Whitespaces between elements that contain newlines are removed
169+
3. Consecutive whitespaces in text nodes are condensed into a single space
170+
171+
Setting the value to `'preserve'` will disable (2) and (3).
172+
173+
### compilerOptions.delimiters
174+
175+
- **Type:** `Array<string>`
176+
177+
- **Default:** `{{ "['\u007b\u007b', '\u007d\u007d']" }}`
178+
179+
- **Usage:**
180+
181+
```js
182+
// Delimiters changed to ES6 template string style
183+
app.config.compilerOptions.delimiters = ['${', '}']
184+
```
185+
186+
Sets the delimiters used for text interpolation within the template.
187+
188+
Typically this is used to avoid conflicting with server-side frameworks that also use mustache syntax.
189+
190+
### compilerOptions.comments
191+
192+
- **Type:** `boolean`
193+
194+
- **Default:** `false`
195+
196+
- **Usage:**
197+
198+
```js
199+
app.config.compilerOptions.comments = true
200+
```
201+
202+
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.
203+
204+
This option is typically used when Vue is used with other libraries that rely on HTML comments.
205+
206+
## isCustomElement <Badge text="deprecated" type="warning"/>
207+
208+
Deprecated in 3.1.0. Use [`compilerOptions.isCustomElement`](#compileroptions-iscustomelement) instead.

‎src/api/composition-api.md

Lines changed: 66 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -4,32 +4,51 @@
44
55
## `setup`
66

7-
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
7+
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.
88

99
- **Arguments:**
1010

1111
- `{Data} props`
1212
- `{SetupContext} context`
1313

14+
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`.
15+
16+
If you need to check the absence of an optional prop, you can give it a Symbol as its default value:
17+
18+
```js
19+
const isAbsent = Symbol()
20+
21+
export default {
22+
props: {
23+
foo: { default: isAbsent }
24+
},
25+
setup(props) {
26+
if (props.foo === isAbsent) {
27+
// foo was not provided.
28+
}
29+
}
30+
}
31+
```
32+
1433
- **Typing**:
1534

16-
```ts
17-
interface Data {
18-
[key: string]: unknown
19-
}
35+
```ts
36+
interface Data {
37+
[key: string]: unknown
38+
}
2039

21-
interface SetupContext {
22-
attrs: Data
23-
slots: Slots
24-
emit: (event: string, ...args: unknown[]) => void
25-
}
40+
interface SetupContext {
41+
attrs: Data
42+
slots: Slots
43+
emit: (event: string, ...args: unknown[]) => void
44+
}
2645

27-
function setup(props: Data, context: SetupContext): Data
28-
```
46+
function setup(props: Data, context: SetupContext): Data
47+
```
2948

30-
::: tip
31-
To get type inference for the arguments passed to `setup()`, the use of [defineComponent](global-api.html#definecomponent) is needed.
32-
:::
49+
::: tip
50+
To get type inference for the arguments passed to `setup()`, the use of [defineComponent](global-api.html#definecomponent) is needed.
51+
:::
3352

3453
- **Example**
3554

@@ -129,48 +148,52 @@ The component instance context is also set during the synchronous execution of l
129148

130149
- **Typing**:
131150

132-
```ts
133-
interface InjectionKey<T> extends Symbol {}
134-
135-
function provide<T>(key: InjectionKey<T> | string, value: T): void
136-
137-
// without default value
138-
function inject<T>(key: InjectionKey<T> | string): T | undefined
139-
// with default value
140-
function inject<T>(key: InjectionKey<T> | string, defaultValue: T): T
141-
// with factory
142-
function inject<T>(
143-
key: InjectionKey<T> | string,
144-
defaultValue: () => T,
145-
treatDefaultAsFactory: true
146-
): T
147-
```
151+
```ts
152+
interface InjectionKey<T> extends Symbol {}
153+
154+
function provide<T>(key: InjectionKey<T> | string, value: T): void
155+
156+
// without default value
157+
function inject<T>(key: InjectionKey<T> | string): T | undefined
158+
// with default value
159+
function inject<T>(key: InjectionKey<T> | string, defaultValue: T): T
160+
// with factory
161+
function inject<T>(
162+
key: InjectionKey<T> | string,
163+
defaultValue: () => T,
164+
treatDefaultAsFactory: true
165+
): T
166+
```
148167

149-
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:
168+
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:
150169

151-
```ts
152-
import { InjectionKey, provide, inject } from 'vue'
170+
```ts
171+
import { InjectionKey, provide, inject } from 'vue'
153172
154-
const key: InjectionKey<string> = Symbol()
173+
const key: InjectionKey<string> = Symbol()
155174
156-
provide(key, 'foo') // providing non-string value will result in error
175+
provide(key, 'foo') // providing non-string value will result in error
157176
158-
const foo = inject(key) // type of foo: string | undefined
159-
```
177+
const foo = inject(key) // type of foo: string | undefined
178+
```
160179

161-
If using string keys or non-typed symbols, the type of the injected value will need to be explicitly declared:
180+
If using string keys or non-typed symbols, the type of the injected value will need to be explicitly declared:
162181

163-
```ts
164-
const foo = inject<string>('foo') // string | undefined
165-
```
182+
```ts
183+
const foo = inject<string>('foo') // string | undefined
184+
```
166185

167186
- **See also**:
168187
- [Provide / Inject](../guide/component-provide-inject.html)
169188
- [Composition API Provide / Inject](../guide/composition-api-provide-inject.html)
170189

171190
## `getCurrentInstance`
172191

173-
`getCurrentInstance` enables access to an internal component instance useful for advanced usages or for library creators.
192+
`getCurrentInstance` enables access to an internal component instance.
193+
194+
:::warning
195+
`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.
196+
:::
174197

175198
```ts
176199
import { getCurrentInstance } from 'vue'

‎src/api/directives.md

Lines changed: 2 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -454,31 +454,6 @@
454454
- **See also:**
455455
- [Data Binding Syntax - interpolations](../guide/template-syntax.html#text)
456456

457-
## v-is
457+
## v-is <Badge text="deprecated" type="warning" />
458458

459-
> Note: this section only affects cases where Vue templates are directly written in the page's HTML.
460-
461-
- **Expects:** string literal
462-
463-
- **Limited to:** native HTML elements
464-
465-
- **Usage:** When using in-DOM templates, the template is subject to native HTML parsing rules. Some HTML elements, such as `<ul>`, `<ol>`, `<table>` and `<select>` have restrictions on what elements can appear inside them, and some elements such as `<li>`, `<tr>`, and `<option>` can only appear inside certain other elements. As a workaround, we can use `v-is` directive on these elements:
466-
467-
```html
468-
<table>
469-
<tr v-is="'blog-post-row'"></tr>
470-
</table>
471-
```
472-
473-
:::warning
474-
`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:
475-
476-
```html
477-
<!-- Incorrect, nothing will be rendered -->
478-
<tr v-is="blog-post-row"></tr>
479-
480-
<!-- Correct -->
481-
<tr v-is="'blog-post-row'"></tr>
482-
```
483-
484-
:::
459+
Deprecated in 3.1.0. Use [`is` attribute with `vue:` prefix](/api/special-attributes.html#is) instead.

‎src/api/options-misc.md

Lines changed: 28 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -10,29 +10,6 @@
1010

1111
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 `<AnonymousComponent>`, which isn't very informative. By providing the `name` option, you will get a much more informative component tree.
1212

13-
## delimiters
14-
15-
- **Type:** `Array<string>`
16-
17-
- **Default:** `{{ "['\u007b\u007b', '\u007d\u007d']" }}`
18-
19-
- **Restrictions:** This option is only available in the full build, with in-browser template compilation.
20-
21-
- **Details:**
22-
23-
Sets the delimiters used for text interpolation within the template.
24-
25-
Typically this is used to avoid conflicting with server-side frameworks that also use mustache syntax.
26-
27-
- **Example:**
28-
29-
```js
30-
createApp({
31-
// Delimiters changed to ES6 template string style
32-
delimiters: ['${', '}']
33-
})
34-
```
35-
3613
## inheritAttrs
3714

3815
- **Type:** `boolean`
@@ -64,3 +41,31 @@
6441
```
6542

6643
- **See also:** [Disabling Attribute Inheritance](../guide/component-attrs.html#disabling-attribute-inheritance)
44+
45+
## compilerOptions <Badge text="3.1+" />
46+
47+
- **Type:** `Object`
48+
49+
- **Details:**
50+
51+
This is the component-level equivalent of the [app-level `compilerOptions` config](/api/application-config.html#compileroptions).
52+
53+
- **Usage:**
54+
55+
```js
56+
const Foo = {
57+
// ...
58+
compilerOptions: {
59+
delimiters: ['${', '}'],
60+
comments: true
61+
}
62+
}
63+
```
64+
65+
::: tip Important
66+
Similar to the app-level `compilerOptions` config, this option is only respected when using the full build with in-browser template compilation.
67+
:::
68+
69+
## delimiters <Badge text="deprecated" type="warning" />
70+
71+
Deprecated in 3.1.0. Use `compilerOptions.delimiters` instead.

0 commit comments

Comments
 (0)