diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index 00bf21dbd4..85e6f09a0c 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -14,7 +14,7 @@ const sidebar = { '/guide/list', '/guide/events', '/guide/forms', - '/guide/component-basics', + '/guide/component-basics' ] }, { @@ -53,7 +53,12 @@ const sidebar = { { title: 'Scaling Up', collapsable: false, - children: ['/guide/routing', '/guide/state-management', '/guide/ssr', '/guide/accessibility'] + children: [ + '/guide/routing', + '/guide/state-management', + '/guide/ssr', + '/guide/accessibility' + ] }, { title: 'Migration to Vue 3', @@ -69,6 +74,7 @@ const sidebar = { api: [ '/api/application-config', '/api/application-api', + '/api/global-api', { title: 'Options', collapsable: false, diff --git a/src/api/application-api.md b/src/api/application-api.md index 8e2651ca97..7d3239ab48 100644 --- a/src/api/application-api.md +++ b/src/api/application-api.md @@ -271,4 +271,4 @@ setTimeout(() => app.unmount('#my-app'), 5000) When this method is called on the same plugin multiple times, the plugin will be installed only once. -- **See also:** [Plugins](TODO) +- **See also:** [Plugins](../guide/plugins.html) diff --git a/src/api/composition-api.md b/src/api/composition-api.md index ef4843c068..2454bc6ca2 100644 --- a/src/api/composition-api.md +++ b/src/api/composition-api.md @@ -170,7 +170,7 @@ function setup(props: Data, context: SetupContext): Data ``` ::: tip -To get type inference for the arguments passed to `setup()`, the use of [`defineComponent`](TODO) is needed. +To get type inference for the arguments passed to `setup()`, the use of [defineComponent](global-api.html#definecomponent) is needed. ::: ## Lifecycle Hooks diff --git a/src/api/computed-watch-api.md b/src/api/computed-watch-api.md index 03e97ce6f9..9ba0fb7989 100644 --- a/src/api/computed-watch-api.md +++ b/src/api/computed-watch-api.md @@ -218,7 +218,7 @@ type StopHandle = () => void ## `watch` -The `watch` API is the exact equivalent of the Options API [this.\$watch](./instance-methods.html#watch) (and the corresponding [watch](./options-data.html#watch) option). `watch` requires watching a specific data source and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed. +The `watch` API is the exact equivalent of the Options API [this.$watch](./instance-methods.html#watch) (and the corresponding [watch](./options-data.html#watch) option). `watch` requires watching a specific data source and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed. - Compared to [watchEffect](#watcheffect), `watch` allows us to: diff --git a/src/api/global-api.md b/src/api/global-api.md new file mode 100644 index 0000000000..36ebb85971 --- /dev/null +++ b/src/api/global-api.md @@ -0,0 +1,217 @@ +# Global API + +## createApp + +Returns an application instance which provides an application context. The entire component tree mounted by the application instance share the same context. + +```js +const app = Vue.createApp({}) +``` + +You can chain other methods after `createApp`, they can be found in [Application API](./application-api.html) + +### Arguments + +The function receives a root component options object as a first parameter: + +```js +const app = Vue.createApp({ + data() { + return { + ... + } + }, + methods: {...}, + computed: {...} + ... +}) +``` + +With the second parameter, we can pass root props to the application: + +```js +const app = Vue.createApp( + { + props: ['username'] + }, + { username: 'Evan' } +) +``` + + +```html +
+ + {{ username }} +
+``` + +### Typing + +```ts +interface Data { + [key: string]: unknown +} + +export type CreateAppFunction = ( + rootComponent: PublicAPIComponent, + rootProps?: Data | null +) => App +``` + +## h + +Returns a returns "virtual node", usually abbreviated to **VNode**: a plain object which contains information describing to Vue what kind of node it should render on the page, including descriptions of any child nodes. It is intended for manually written [render functions](../guide/render-function.md): + +```js +render() { + return Vue.h('h1', {}, 'Some title') +} +``` + +### Arguments + +Accepts three arguments: `tag`, `props` and `children` + +#### tag + +- **Type:** `String | Object | Function | null` + +- **Details:** + + An HTML tag name, a component, an async component or null. Using null would render a comment. This parameter is required + +#### props + +- **Type:** `Object` + +- **Details:** + + An object corresponding to the attributes, props and events we would use in a template. Optional + +#### children + +- **Type:** `String | Array | Object` + +- **Details:** + + Children VNodes, built using `h()`, or using strings to get "text VNodes" or an object with slots. Optional + + ```js + h('div', {}, [ + 'Some text comes first.', + h('h1', 'A headline'), + h(MyComponent, { + someProp: 'foobar' + }) + ]) + ``` + +## defineComponent + +Implementation-wise `defineComponent` does nothing but return the object passed to it. However, in terms of typing, the returned value has a synthetic type of a constructor for manual render function, TSX and IDE tooling support. + +### Arguments + +An object with component options + +```js +import { defineComponent } from 'vue' + +const MyComponent = defineComponent({ + data() { + return { count: 1 } + }, + methods: { + increment() { + this.count++ + } + } +}) +``` + +## defineAsyncComponent + +Creates an async component that will be loaded only when it's necessary. + +### Arguments + +For basic usage, `defineAsyncComponent` can accept a a factory function returning a `Promise`. Promise's `resolve` callback should be called when you have retrieved your component definition from the server. You can also call `reject(reason)` to indicate the load has failed. + +```js +import { defineAsyncComponent } from 'vue' + +const AsyncComp = defineAsyncComponent(() => + import('./components/AsyncComponent.vue') +) + +app.component('async-component', AsyncComp) +``` + +When using [local registration](../guide/component-registration.html#local-registration), you can also directly provide a function that returns a `Promise`: + +```js +import { createApp, defineAsyncComponent } from 'vue' + +createApp({ + // ... + components: { + components: { + AsyncComponent: defineAsyncComponent(() => + import('./components/AsyncComponent.vue') + ) + } + } +}) +``` + +For advanced usage, `defineAsyncComponent` can accept an object: + +The `defineAsyncComponent` method can also return an object of the following format: + +```js +import { defineAsyncComponent } from 'vue' + +const AsyncComp = defineAsyncComponent({ + // The factory function + loader: () => import('./Foo.vue') + // A component to use while the async component is loading + loadingComponent: LoadingComponent, + // A component to use if the load fails + errorComponent: ErrorComponent, + // Delay before showing the loading component. Default: 200ms. + delay: 200, + // The error component will be displayed if a timeout is + // provided and exceeded. Default: Infinity. + timeout: 3000, + // A function that returns a boolean indicating whether the async component should retry when the loader promise rejects + retryWhen: error => error.code !== 404, + // Maximum allowed retries number + maxRetries: 3, + // Defining if component is suspensible + suspensible: false +}) +``` + +**See also**: [Dynamic and Async components](../guide/component-dynamic-async.html) + +## nextTick + +Defer the callback to be executed after the next DOM update cycle. Use it immediately after you’ve changed some data to wait for the DOM update. + +```js +import { createApp, nextTick } from 'vue' + +const app = createApp({ + setup() { + const message = ref('Hello!') + const changeMessage = async newMessage => { + message.value = newMessage + await nextTick() + console.log('Now DOM is updated') + } + } +}) +``` + +**See also**: [`$nextTick` instance method](instance-methods.html#nexttick) diff --git a/src/api/instance-methods.md b/src/api/instance-methods.md index 21482fa45c..b5f490c832 100644 --- a/src/api/instance-methods.md +++ b/src/api/instance-methods.md @@ -251,7 +251,7 @@ - **Usage:** - Defer the callback to be executed after the next DOM update cycle. Use it immediately after you've changed some data to wait for the DOM update. This is the same as the global `Vue.nextTick`, except that the callback's `this` context is automatically bound to the instance calling this method. + Defer the callback to be executed after the next DOM update cycle. Use it immediately after you've changed some data to wait for the DOM update. This is the same as the global `nextTick`, except that the callback's `this` context is automatically bound to the instance calling this method. - **Example:** @@ -274,4 +274,4 @@ }) ``` -- **See also:** [Vue.nextTick](TODO) +- **See also:** [nextTick](global-api.html#nexttick) diff --git a/src/api/options-composition.md b/src/api/options-composition.md index 375aa79a31..689b01f685 100644 --- a/src/api/options-composition.md +++ b/src/api/options-composition.md @@ -221,7 +221,7 @@ The `setup` function is a new component option. It serves as the entry point for ``` - Note that [refs](TODO) returned from `setup` are automatically unwrapped when accessed in the template so there's no need for `.value` in templates. + Note that [refs](refs-api.html#ref) returned from `setup` are automatically unwrapped when accessed in the template so there's no need for `.value` in templates. - **Usage with Render Functions / JSX** @@ -318,4 +318,4 @@ The `setup` function is a new component option. It serves as the entry point for - Having `props` as a separate argument makes it easier to type it individually without messing up the types of other properties on the context. It also makes it possible to keep a consistent signature across `setup`, `render` and plain functional components with TSX support. -- **See also:** [Composition API](TODO) +- **See also:** [Composition API](composition-api.html) diff --git a/src/api/options-dom.md b/src/api/options-dom.md index a101afa87a..6ed7ec7837 100644 --- a/src/api/options-dom.md +++ b/src/api/options-dom.md @@ -62,4 +62,4 @@ The `render` function has priority over the render function compiled from `template` option or in-DOM HTML template of the mounting element ::: -- **See also:** [Render Functions](TODO) +- **See also:** [Render Functions](../guide/render-function.html) diff --git a/src/guide/component-basics.md b/src/guide/component-basics.md index 617dd94cd4..395a357d63 100644 --- a/src/guide/component-basics.md +++ b/src/guide/component-basics.md @@ -75,7 +75,7 @@ For example, you might have components for a header, sidebar, and content area, To use these components in templates, they must be registered so that Vue knows about them. There are two types of component registration: **global** and **local**. So far, we've only registered components globally, using `component` method of created app: ```js -const app = Vue.createApp() +const app = Vue.createApp({}) app.component('my-component-name', { // ... options ... diff --git a/src/guide/component-dynamic-async.md b/src/guide/component-dynamic-async.md index adce11fc9a..4035f19c78 100644 --- a/src/guide/component-dynamic-async.md +++ b/src/guide/component-dynamic-async.md @@ -76,7 +76,7 @@ const AsyncComp = defineAsyncComponent(() => app.component('async-component', AsyncComp) ``` -You can also use `defineAsyncComponent` when [registering a component locally](components-registration.html#Local-Registration): +You can also use `defineAsyncComponent` when [registering a component locally](component-registration.html#local-registration): ```js import { createApp, defineAsyncComponent } from 'vue' @@ -97,4 +97,4 @@ Async components are _suspensible_ by default. This means if it has a [` "hello from component!" ``` -In most cases, you should only use it for custom option handling like demonstrated in the example above. It's also a good idea to ship them as [Plugins](TODO) to avoid duplicate application. +In most cases, you should only use it for custom option handling like demonstrated in the example above. It's also a good idea to ship them as [Plugins](plugins.html) to avoid duplicate application. ## Custom Option Merge Strategies diff --git a/src/guide/render-function.md b/src/guide/render-function.md index 905471dce4..7319c815e3 100644 --- a/src/guide/render-function.md +++ b/src/guide/render-function.md @@ -89,7 +89,6 @@ Before we dive into render functions, it’s important to know a little about ho

My title

Some text content -
``` diff --git a/src/guide/state-management.md b/src/guide/state-management.md index ceac0866b3..381b8cc2e9 100644 --- a/src/guide/state-management.md +++ b/src/guide/state-management.md @@ -4,9 +4,6 @@ Large applications can often grow in complexity, due to multiple pieces of state scattered across many components and the interactions between them. To solve this problem, Vue offers [vuex](https://github.com/vuejs/vuex), our own Elm-inspired state management library. It even integrates into [vue-devtools](https://github.com/vuejs/vue-devtools), providing zero-setup access to [time travel debugging](https://raw.githubusercontent.com/vuejs/vue-devtools/master/media/demo.gif). - -
Watch a video explanation on Vue Mastery
- ### Information for React Developers If you're coming from React, you may be wondering how vuex compares to [redux](https://github.com/reactjs/redux), the most popular Flux implementation in that ecosystem. Redux is actually view-layer agnostic, so it can easily be used with Vue via [simple bindings](https://classic.yarnpkg.com/en/packages?q=redux%20vue&p=1). Vuex is different in that it _knows_ it's in a Vue app. This allows it to better integrate with Vue, offering a more intuitive API and improved development experience. diff --git a/src/guide/template-syntax.md b/src/guide/template-syntax.md index 683b4d5858..818ae19601 100644 --- a/src/guide/template-syntax.md +++ b/src/guide/template-syntax.md @@ -4,7 +4,7 @@ Vue.js uses an HTML-based template syntax that allows you to declaratively bind Under the hood, Vue compiles the templates into Virtual DOM render functions. Combined with the reactivity system, Vue is able to intelligently figure out the minimal number of components to re-render and apply the minimal amount of DOM manipulations when the app state changes. -If you are familiar with Virtual DOM concepts and prefer the raw power of JavaScript, you can also [directly write render functions](TODO:render-function.html) instead of templates, with optional JSX support. +If you are familiar with Virtual DOM concepts and prefer the raw power of JavaScript, you can also [directly write render functions](render-function.html) instead of templates, with optional JSX support. ## Interpolations @@ -18,7 +18,7 @@ The most basic form of data binding is text interpolation using the "Mustache" s The mustache tag will be replaced with the value of the `msg` property on the corresponding data object. It will also be updated whenever the data object's `msg` property changes. -You can also perform one-time interpolations that do not update on data change by using the [v-once directive](TODO:../api/#v-once), but keep in mind this will also affect any other bindings on the same node: +You can also perform one-time interpolations that do not update on data change by using the [v-once directive](../api/directives.html#v-once), but keep in mind this will also affect any other bindings on the same node: ```html This will never change: {{ msg }} @@ -26,7 +26,7 @@ You can also perform one-time interpolations that do not update on data change b ### Raw HTML -The double mustaches interprets the data as plain text, not HTML. In order to output real HTML, you will need to use the [`v-html` directive](TODO:../api/#v-html): +The double mustaches interprets the data as plain text, not HTML. In order to output real HTML, you will need to use the [`v-html` directive](../api/directives.html#v-html): ```html

Using mustaches: {{ rawHtml }}