+ Caught a mistake or want to contribute to the documentation? - - {{ editLinkText }} -
{{ lastUpdatedText }}: diff --git a/src/.vuepress/theme/data/patreon-sponsors.js b/src/.vuepress/theme/data/patreon-sponsors.js index 6a87bd9927..cec7435de7 100644 --- a/src/.vuepress/theme/data/patreon-sponsors.js +++ b/src/.vuepress/theme/data/patreon-sponsors.js @@ -7,10 +7,10 @@ export default { ], "special_sponsors": [ { - "url": "https://autocode.com/", - "img": "autocode.svg", - "name": "Autocode", - "description": "Build app-to-app workflows and connect APIs" + "url": "https://www.dcloud.io/hbuilderx.html?hmsr=vue-en&hmpl=&hmcu=&hmkw=&hmci=", + "img": "hbuilder.png", + "name": "HBuilder", + "description": "An IDE for Vue" } ], "platinum_sponsors": [ @@ -36,8 +36,13 @@ export default { }, { "url": "https://www.storyblok.com/", - "img": "storyblok.png", + "img": "storyblok.svg", "name": "Storyblok" + }, + { + "url": "https://ionicframework.com/vue?utm_source=partner&utm_medium=referral&utm_campaign=vuesponsorship&utm_content=vuedocs", + "img": "ionic.png", + "name": "Ionic" } ], "gold_sponsors": [ diff --git a/src/.vuepress/theme/layouts/404.vue b/src/.vuepress/theme/layouts/404.vue index 2cbfa0f179..915deb1d51 100644 --- a/src/.vuepress/theme/layouts/404.vue +++ b/src/.vuepress/theme/layouts/404.vue @@ -3,7 +3,13 @@
404
-{{ getMsg() }}+
++ +Whoops! This page doesn't exist.
+
+ New pages are added to the documentation all the time. This page might not be included in all of the translations yet. +
hi
+
+```
+
+Into the following:
+
+```vue
+
+
+
+ hi
+
+```
+
+### Child Component Root Elements
+
+With `scoped`, the parent component's styles will not leak into child components. However, a child component's root node will be affected by both the parent's scoped CSS and the child's scoped CSS. This is by design so that the parent can style the child root element for layout purposes.
+
+### Deep Selectors
+
+If you want a selector in `scoped` styles to be "deep", i.e. affecting child components, you can use the `:deep()` pseudo-class:
+
+```vue
+
+```
+
+The above will be compiled into:
+
+```css
+.a[data-v-f3f3eg9] .b {
+ /* ... */
+}
+```
+
+:::tip
+DOM content created with `v-html` are not affected by scoped styles, but you can still style them using deep selectors.
+:::
+
+### Slotted Selectors
+
+By default, scoped styles do not affect contents rendered by `red
+ + + +``` + +### Usage with Composition API + +The injected classes can be accessed in `setup()` and ` + + +``` + +The syntax works with [` + + +hello
+ + + +``` + +The actual value will be compiled into a hashed CSS custom property, so the CSS is still static. The custom property will be applied to the component's root element via inline styles and reactively updated if the source value changes. diff --git a/src/api/sfc-tooling.md b/src/api/sfc-tooling.md new file mode 100644 index 0000000000..f38bc59292 --- /dev/null +++ b/src/api/sfc-tooling.md @@ -0,0 +1,94 @@ +# SFC Tooling + +## Online Playgrounds + +You don't need to install anything on your machine to try out Vue SFCs - there are many online playgrounds that allow you to do so right in the browser: + +- [Vue SFC Playground](https://sfc.vuejs.org) (official, deployed from latest commit) +- [VueUse Playground](https://play.vueuse.org) +- [Vue on CodeSandbox](https://codesandbox.io/s/vue-3) +- [Vue on Repl.it](https://replit.com/@templates/VueJS-with-Vite) +- [Vue on Codepen](https://codepen.io/pen/editor/vue) +- [Vue on StackBlitz](https://stackblitz.com/fork/vue) + +It is also recommended to use these online playgrounds to provide reproductions when reporting bugs. + +## Project Scaffolding + +### Vite + +[Vite](https://vitejs.dev/) is a lightweight and fast build tool with first-class Vue SFC support. It is created by Evan You, who is also the author of Vue itself! To get started with Vite + Vue, simply run: + +```sh +npm init vite@latest +``` + +Then select the Vue template and follow the instructions. + +- To learn more about Vite, check out the [Vite docs](https://vitejs.dev/guide/). +- To configure Vue-specific behavior in a Vite project, for example passing options to the Vue compiler, check out the docs for [@vitejs/plugin-vue](https://github.com/vitejs/vite/tree/main/packages/plugin-vue#readme). + +The [SFC Playground](https://sfc.vuejs.org/) also supports downloading the files as a Vite project. + +### Vue CLI + +[Vue CLI](https://cli.vuejs.org/) is the official webpack-based build tool for Vue projects. To get started with Vue CLI: + +```sh +npm install -g @vue/cli +vue create hello-vue +``` + +- To learn more about Vue CLI, check out [Vue CLI docs](https://cli.vuejs.org/guide/installation.html). + +### Vite or Vue CLI? + +We recommend starting new projects with Vite as it offers significantly better development experience in terms of dev server startup and HMR update performance ([details](https://vitejs.dev/guide/why.html)). Only go with Vue CLI if you rely on specific webpack features (e.g. Module Federation). + +If you are a [Rollup](https://rollupjs.org/) user, you can safely adopt Vite as it uses Rollup for production builds and supports a Rollup-compatible plugin system. [Even Rollup's maintainer recommends Vite as THE web development wrapper for Rollup](https://twitter.com/lukastaegert/status/1412119729431584774). + +## IDE Support + +The recommended IDE setup is [VSCode](https://code.visualstudio.com/) + the [Volar](https://github.com/johnsoncodehk/volar) extension. Volar provides syntax highlighting and advanced IntelliSense for template expressions, component props and even slots validation. We strongly recommend this setup if you want to get the best possible experience with Vue SFCs, especially if you are also using TypeScript. + +[WebStorm](https://www.jetbrains.com/webstorm/) also provides decent support for Vue SFCs. However, do note as of now its support for ` ``` @@ -141,6 +172,8 @@ watchEffect( The `flush` option also accepts `'sync'`, which forces the effect to always trigger synchronously. This is however inefficient and should be rarely needed. +In Vue >= 3.2.0, `watchPostEffect` and `watchSyncEffect` aliases can also be used to make the code intention more obvious. + ### Watcher Debugging The `onTrack` and `onTrigger` options can be used to debug a watcher's behavior. @@ -201,15 +234,48 @@ watch(count, (count, prevCount) => { A watcher can also watch multiple sources at the same time using an array: ```js -const firstName = ref(''); -const lastName = ref(''); +const firstName = ref('') +const lastName = ref('') watch([firstName, lastName], (newValues, prevValues) => { - console.log(newValues, prevValues); + console.log(newValues, prevValues) }) -firstName.value = "John"; // logs: ["John",""] ["", ""] -lastName.value = "Smith"; // logs: ["John", "Smith"] ["John", ""] +firstName.value = 'John' // logs: ["John", ""] ["", ""] +lastName.value = 'Smith' // logs: ["John", "Smith"] ["John", ""] +``` + +However, if you are changing both watched sources simultaneously in the same function, the watcher will be executed only once: + +```js{9-13} +setup() { + const firstName = ref('') + const lastName = ref('') + + watch([firstName, lastName], (newValues, prevValues) => { + console.log(newValues, prevValues) + }) + + const changeValues = () => { + firstName.value = 'John' + lastName.value = 'Smith' + // logs: ["John", "Smith"] ["", ""] + } + + return { changeValues } +} +``` + +Note that multiple synchronous changes will only trigger the watcher once. + +It is possible to force the watcher to trigger after every change by using the setting `flush: 'sync'`, though that isn't usually recommended. Alternatively, [nextTick](/api/global-api.html#nexttick) can be used to wait for the watcher to run before making further changes. e.g.: + +```js +const changeValues = async () => { + firstName.value = 'John' // logs: ["John", ""] ["", ""] + await nextTick() + lastName.value = 'Smith' // logs: ["John", "Smith"] ["John", ""] +} ``` ### Watching Reactive Objects @@ -222,8 +288,9 @@ const numbers = reactive([1, 2, 3, 4]) watch( () => [...numbers], (numbers, prevNumbers) => { - console.log(numbers, prevNumbers); - }) + console.log(numbers, prevNumbers) + } +) numbers.push(5) // logs: [1,2,3,4,5] [1,2,3,4] ``` @@ -231,62 +298,51 @@ numbers.push(5) // logs: [1,2,3,4,5] [1,2,3,4] Attempting to check for changes of properties in a deeply nested object or array will still require the `deep` option to be true: ```js -const state = reactive({ - id: 1, - attributes: { - name: "", - }, -}); +const state = reactive({ + id: 1, + attributes: { + name: '' + } +}) watch( () => state, (state, prevState) => { - console.log( - "not deep ", - state.attributes.name, - prevState.attributes.name - ); + console.log('not deep', state.attributes.name, prevState.attributes.name) } -); +) watch( () => state, (state, prevState) => { - console.log( - "deep ", - state.attributes.name, - prevState.attributes.name - ); + console.log('deep', state.attributes.name, prevState.attributes.name) }, { deep: true } -); +) -state.attributes.name = "Alex"; // Logs: "deep " "Alex" "Alex" +state.attributes.name = 'Alex' // Logs: "deep" "Alex" "Alex" ``` However, watching a reactive object or array will always return a reference to the current value of that object for both the current and previous value of the state. To fully watch deeply nested objects and arrays, a deep copy of values may be required. This can be achieved with a utility such as [lodash.cloneDeep](https://lodash.com/docs/4.17.15#cloneDeep) ```js -import _ from 'lodash'; +import _ from 'lodash' const state = reactive({ id: 1, attributes: { - name: "", - }, -}); + name: '' + } +}) watch( () => _.cloneDeep(state), (state, prevState) => { - console.log( - state.attributes.name, - prevState.attributes.name - ); + console.log(state.attributes.name, prevState.attributes.name) } -); +) -state.attributes.name = "Alex"; // Logs: "Alex" "" +state.attributes.name = 'Alex' // Logs: "Alex" "" ``` ### Shared Behavior with `watchEffect` diff --git a/src/guide/reactivity-fundamentals.md b/src/guide/reactivity-fundamentals.md index 49caf3256f..baddc43a41 100644 --- a/src/guide/reactivity-fundamentals.md +++ b/src/guide/reactivity-fundamentals.md @@ -74,7 +74,7 @@ When a ref is returned as a property on the render context (the object returned ``` :::tip -If you don't need to access the actual object instance, you can wrap it in a `reactive`: +If you don't want to access the actual object instance, you can wrap it in a `reactive`: ```js nested: reactive({ diff --git a/src/guide/single-file-component.md b/src/guide/single-file-component.md index df5927be3a..5078f7823a 100644 --- a/src/guide/single-file-component.md +++ b/src/guide/single-file-component.md @@ -2,173 +2,85 @@ ## Introduction -In many Vue projects, global components will be defined using `app.component()`, followed by `app.mount('#app')` to target a container element in the body of every page. +Vue Single File Components (aka `*.vue` files, abbreviated as **SFC**) is a special file format that allows us to encapsulate the template, logic, **and** styling of a Vue component in a single file. Here's an example SFC: -This can work very well for small to medium-sized projects, where JavaScript is only used to enhance certain views. In more complex projects however, or when your frontend is entirely driven by JavaScript, these disadvantages become apparent: - -- **Global definitions** force unique names for every component -- **String templates** lack syntax highlighting and require ugly slashes for multiline HTML -- **No CSS support** means that while HTML and JavaScript are modularized into components, CSS is conspicuously left out -- **No build step** restricts us to HTML and ES5 JavaScript, rather than preprocessors like Pug (formerly Jade) and Babel - -All of these are solved by **single-file components** with a `.vue` extension, made possible with build tools such as Webpack or Browserify. - -Here's an example of a file we'll call `Hello.vue`: - -
-
-Now we get:
-
-- [Complete syntax highlighting](https://github.com/vuejs/awesome-vue#source-code-editing)
-- [CommonJS modules](https://webpack.js.org/concepts/modules/#what-is-a-webpack-module)
-- [Component-scoped CSS](https://vue-loader.vuejs.org/en/features/scoped-css.html)
-
-As promised, we can also use preprocessors such as Pug, Babel (with ES2015 modules), and Stylus for cleaner and more feature-rich components.
-
-
-
-These specific languages are only examples. You could as easily use TypeScript, SCSS, PostCSS, or whatever other preprocessors that help you be productive. If using Webpack with `vue-loader`, it also has first-class support for CSS Modules.
-
-### What About Separation of Concerns?
-
-One important thing to note is that **separation of concerns is not equal to separation of file types.** In modern UI development, we have found that instead of dividing the codebase into three huge layers that interweave with one another, it makes much more sense to divide them into loosely-coupled components and compose them. Inside a component, its template, logic and styles are inherently coupled, and collocating them actually makes the component more cohesive and maintainable.
-
-Even if you don't like the idea of Single-File Components, you can still leverage its hot-reloading and pre-compilation features by separating your JavaScript and CSS into separate files:
+```vue
+
-```html
-
- This will be pre-compiled
+ {{ greeting }}
- - -``` - -## Getting Started - -### Example Sandbox - -If you want to dive right in and start playing with single-file components, check out [this simple todo app](https://codesandbox.io/s/vue-todo-list-app-with-single-file-component-vzkl3?file=/src/App.vue) on CodeSandbox. - -### For Users New to Module Build Systems in JavaScript - -With `.vue` components, we're entering the realm of advanced JavaScript applications. That means learning to use a few additional tools if you haven't already: -- **Node Package Manager (npm)**: Read the [Getting Started guide](https://docs.npmjs.com/packages-and-modules/getting-packages-from-the-registry) section about how to get packages from the registry. - -- **Modern JavaScript with ES2015/16**: Read through Babel's [Learn ES2015 guide](https://babeljs.io/docs/en/learn). You don't have to memorize every feature right now, but keep this page as a reference you can come back to. - -After you've taken a day to dive into these resources, we recommend checking out [Vue CLI](https://cli.vuejs.org/). Follow the instructions and you should have a Vue project with `.vue` components, ES2015, webpack and hot-reloading in no time! - -### For Advanced Users - -The CLI takes care of most of the tooling configurations for you, but also allows fine-grained customization through its own [config options](https://cli.vuejs.org/config/). - -In case you prefer setting up your own build setup from scratch, you will need to manually configure webpack with [vue-loader](https://vue-loader.vuejs.org). To learn more about webpack itself, check out [their official docs](https://webpack.js.org/configuration/) and [webpack learning academy](https://webpack.academy/p/the-core-concepts). - -### Building with rollup - -Most of the time when developing a third-party library we want to build it in a way that allows the consumers of the library to [tree shake](https://webpack.js.org/guides/tree-shaking/) it. To enable tree-shaking we need to build `esm` modules. Since webpack and, in turn, vue-cli do not support building `esm` modules we need to rely on [rollup](https://rollupjs.org/). - -#### Installing Rollup - -We will need to install Rollup and a few dependencies: - -```bash -npm install --save-dev rollup @rollup/plugin-commonjs rollup-plugin-vue + ``` -These are the minimal amount of rollup plugins that we need to use to compile the code in an `esm` module. We may want to also add [rollup-plugin-babel](https://github.com/rollup/plugins/tree/master/packages/babel) to transpile their code and [node-resolve](https://github.com/rollup/plugins/tree/master/packages/node-resolve) if we use dependencies that we want to bundle with our library. +As we can see, Vue SFC is a natural extension of the classic trio of HTML, CSS and JavaScript. Each `*.vue` file consists of three types of top-level language blocks: ``, ` +``` + +As you can see, without annotating the `evt` argument correctly, TypeScript will throw an error when we try to access the value of the `` element. The solution is to cast the event target with a correct type: + +```ts +const handleChange = (evt: Event) => { + console.log((evt.target as HTMLInputElement).value) +} +``` diff --git a/src/guide/web-components.md b/src/guide/web-components.md new file mode 100644 index 0000000000..20436165be --- /dev/null +++ b/src/guide/web-components.md @@ -0,0 +1,243 @@ +# Vue and Web Components + +[Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) is an umbrella term for a set of web native APIs that allows developers to create reusable custom elements. + +We consider Vue and Web Components to be primarily complementary technologies. Vue has excellent support for both consuming and creating custom elements. Whether you are integrating custom elements into an existing Vue application, or using Vue to build and distribute custom elements, you are in good company. + +## Using Custom Elements in Vue + +Vue [scores a perfect 100% in the Custom Elements Everywhere tests](https://custom-elements-everywhere.com/libraries/vue/results/results.html). Consuming custom elements inside a Vue application largely works the same as using native HTML elements, with a few things to keep in mind: + +### Skipping Component Resolution + +By default, Vue will attempt to resolve a non-native HTML tag as a registered Vue component before falling back to rendering it as a custom element. This will cause Vue to emit a "failed to resolve component" warning during development. To let Vue know that certain elements should be treated as custom elements and skip component resolution, we can specify the [`compilerOptions.isCustomElement` option](/api/application-config.html#compileroptions). + +If you are using Vue with a build setup, the option should be passed via build configs since it is a compile-time option. + +#### Example Vite Config + +```js +// vite.config.js +import vue from '@vitejs/plugin-vue' + +export default { + plugins: [ + vue({ + template: { + compilerOptions: { + // treat all tags with a dash as custom elements + isCustomElement: tag => tag.includes('-') + } + } + }) + ] +} +``` + +#### Example Vue CLI Config + +```js +// vue.config.js +module.exports = { + chainWebpack: config => { + config.module + .rule('vue') + .use('vue-loader') + .tap(options => ({ + ...options, + compilerOptions: { + // treat any tag that starts with ion- as custom elements + isCustomElement: tag => tag.startsWith('ion-') + } + })) + } +} +``` + +### Passing DOM Properties + +Since DOM attributes can only be strings, we need to pass complex data to custom elements as DOM properties. When setting props on a custom element, Vue 3 automatically checks DOM-property presence using the `in` operator and will prefer setting the value as a DOM property if the key is present. This means that, in most cases, you won't need to think about this if the custom element follows the [recommended best practices](https://developers.google.com/web/fundamentals/web-components/best-practices#aim-to-keep-primitive-data-attributes-and-properties-in-sync,-reflecting-from-property-to-attribute,-and-vice-versa.). + +However, there could be rare cases where the data must be passed as a DOM property, but the custom element does not properly define/reflect the property (causing the `in` check to fail). In this case, you can force a `v-bind` binding to be set as a DOM property using the `.prop` modifier: + +```html +hello
+