diff --git a/src/.vuepress/components/intro-1.vue b/src/.vuepress/components/intro-1.vue new file mode 100644 index 0000000000..345d7a3eb0 --- /dev/null +++ b/src/.vuepress/components/intro-1.vue @@ -0,0 +1,15 @@ + + + \ No newline at end of file diff --git a/src/.vuepress/components/intro-2.vue b/src/.vuepress/components/intro-2.vue new file mode 100644 index 0000000000..ef983df5f7 --- /dev/null +++ b/src/.vuepress/components/intro-2.vue @@ -0,0 +1,17 @@ + + + \ No newline at end of file diff --git a/src/.vuepress/components/intro-3.vue b/src/.vuepress/components/intro-3.vue new file mode 100644 index 0000000000..55a4082824 --- /dev/null +++ b/src/.vuepress/components/intro-3.vue @@ -0,0 +1,15 @@ + + + \ No newline at end of file diff --git a/src/.vuepress/components/intro-4.vue b/src/.vuepress/components/intro-4.vue new file mode 100644 index 0000000000..fdb25a851e --- /dev/null +++ b/src/.vuepress/components/intro-4.vue @@ -0,0 +1,23 @@ + + + \ No newline at end of file diff --git a/src/.vuepress/components/intro-5.vue b/src/.vuepress/components/intro-5.vue new file mode 100644 index 0000000000..398dcda010 --- /dev/null +++ b/src/.vuepress/components/intro-5.vue @@ -0,0 +1,21 @@ + + + \ No newline at end of file diff --git a/src/.vuepress/components/intro-6.vue b/src/.vuepress/components/intro-6.vue new file mode 100644 index 0000000000..9999de0b4e --- /dev/null +++ b/src/.vuepress/components/intro-6.vue @@ -0,0 +1,16 @@ + + + \ No newline at end of file diff --git a/src/.vuepress/components/intro-7.vue b/src/.vuepress/components/intro-7.vue new file mode 100644 index 0000000000..fe52af5550 --- /dev/null +++ b/src/.vuepress/components/intro-7.vue @@ -0,0 +1,28 @@ + + + \ No newline at end of file diff --git a/src/.vuepress/public/images/components.png b/src/.vuepress/public/images/components.png new file mode 100644 index 0000000000..eb70aa81ea Binary files /dev/null and b/src/.vuepress/public/images/components.png differ diff --git a/src/.vuepress/styles/index.styl b/src/.vuepress/styles/index.styl new file mode 100644 index 0000000000..e8251f3738 --- /dev/null +++ b/src/.vuepress/styles/index.styl @@ -0,0 +1,14 @@ +.theme-default-content:not(.custom) { + max-width 960px +} + +.demo { + font-family: sans-serif; + border: 1px solid #eee; + border-radius: 2px; + padding: 20px 30px; + margin-top: 1em; + margin-bottom: 40px; + user-select: none; + overflow-x: auto; +} \ No newline at end of file diff --git a/src/README.md b/src/README.md index 514648d455..254fbb8cc8 100644 --- a/src/README.md +++ b/src/README.md @@ -4,7 +4,7 @@ heroImage: /logo.png heroText: Vue.js tagline: The Progressive JavaScript Framework actionText: Get Started → -actionLink: /docs/ +actionLink: /guide/introduction features: - title: Approachable details: Already know HTML, CSS and JavaScript? Read the guide and start building things in no time! diff --git a/src/guide/introduction.md b/src/guide/introduction.md index e2d9895dc9..ab6f04d2f8 100644 --- a/src/guide/introduction.md +++ b/src/guide/introduction.md @@ -2,11 +2,11 @@ ## What is Vue.js? -Vue (pronounced /vjuː/, like **view**) is a **progressive framework** for building user interfaces. Unlike other monolithic frameworks, Vue is designed from the ground up to be incrementally adoptable. The core library is focused on the view layer only, and is easy to pick up and integrate with other libraries or existing projects. On the other hand, Vue is also perfectly capable of powering sophisticated Single-Page Applications when used in combination with [modern tooling](single-file-components.html) and [supporting libraries](https://github.com/vuejs/awesome-vue#components--libraries). +Vue (pronounced /vjuː/, like **view**) is a **progressive framework** for building user interfaces. Unlike other monolithic frameworks, Vue is designed from the ground up to be incrementally adoptable. The core library is focused on the view layer only, and is easy to pick up and integrate with other libraries or existing projects. On the other hand, Vue is also perfectly capable of powering sophisticated Single-Page Applications when used in combination with [modern tooling](TODO:single-file-components.html) and [supporting libraries](https://github.com/vuejs/awesome-vue#components--libraries). If you’d like to learn more about Vue before diving in, we created a video walking through the core principles and a sample project. -If you are an experienced frontend developer and want to know how Vue compares to other libraries/frameworks, check out the [Comparison with Other Frameworks](comparison.html). +If you are an experienced frontend developer and want to know how Vue compares to other libraries/frameworks, check out the [Comparison with Other Frameworks](TODO:comparison.html).
Watch a free video course on Vue Mastery
@@ -34,4 +34,254 @@ or: The [Installation](installation.md) page provides more options of installing Vue. Note: We **do not** recommend that beginners start with `vue-cli`, especially if you are not yet familiar with Node.js-based build tools. -If you prefer something more interactive, you can also check out [this tutorial series on Scrimba](https://scrimba.com/g/gvuedocs), which gives you a mix of screencast and code playground that you can pause and play around with anytime. \ No newline at end of file +## Declarative Rendering + +At the core of Vue.js is a system that enables us to declaratively render data to the DOM using straightforward template syntax: + +``` html +
+ {{ message }} +
+``` +``` js +const App = { + data: { + message: 'Hello Vue!' + } +} + +Vue.createApp().mount(App, '#app') +``` + + +We have already created our very first Vue app! This looks pretty similar to rendering a string template, but Vue has done a lot of work under the hood. The data and the DOM are now linked, and everything is now **reactive**. How do we know? Change the `message` property in the code snippet below to a different value. You the rendered example update accordingly: ![placeholder sandbox link](https://codesandbox.io/s/xenodochial-meninsky-rxlt4) + +In addition to text interpolation, we can also bind element attributes like this: + +``` html +
+ + Hover your mouse over me for a few seconds + to see my dynamically bound title! + +
+``` +``` js +const App2 = { + data: { + message: 'You loaded this page on ' + new Date().toLocaleString() + } +} + +Vue.createApp().mount(App2, '#app-2') +``` + +Here we are encountering something new. The `v-bind` attribute you are seeing is called a **directive**. Directives are prefixed with `v-` to indicate that they are special attributes provided by Vue, and as you may have guessed, they apply special reactive behavior to the rendered DOM. Here, it is basically saying "keep this element's `title` attribute up-to-date with the `message` property on the Vue instance." + +## Conditionals and Loops + +It's easy to toggle the presence of an element, too: + +``` html +
+ Now you see me +
+``` +```js +const App3 = { + data: { + message: 'You loaded this page on ' + new Date().toLocaleString() + } +} + +Vue.createApp().mount(App3, '#app-3') +``` + + +This example demonstrates that we can bind data to not only text and attributes, but also the **structure** of the DOM. Moreover, Vue also provides a powerful transition effect system that can automatically apply [transition effects](TODO) when elements are inserted/updated/removed by Vue. + +You can change `seen` from `true` to `false` in the sandbox below to check the effect: https://codesandbox.io/s/basic-conditional-rendering-eptpp + +There are quite a few other directives, each with its own special functionality. For example, the `v-for` directive can be used for displaying a list of items using the data from an Array: + +``` html +
+
    +
  1. + {{ todo.text }} +
    2. +
+
+``` +``` js +const App4 = { + data: { + todos: [ + { text: 'Learn JavaScript' }, + { text: 'Learn Vue' }, + { text: 'Build something awesome' } + ] + } +} + +Vue.createApp().mount(App4, '#app-4') +``` + + +## Handling User Input + +To let users interact with your app, we can use the `v-on` directive to attach event listeners that invoke methods on our Vue instances: + +``` html +
+

{{ message }}

+ +
+``` +``` js +const App5 = { + data: { + message: 'Hello Vue.js!' + }, + methods: { + reverseMessage() { + this.message = this.message.split('').reverse().join('') + } + } +} + +Vue.createApp().mount(App5, '#app-5') +``` + + +Note that in this method we update the state of our app without touching the DOM - all DOM manipulations are handled by Vue, and the code you write is focused on the underlying logic. + +Vue also provides the `v-model` directive that makes two-way binding between form input and app state a breeze: + +``` html +
+

{{ message }}

+ +
+``` +``` js +const App6 = { + data: { + message: 'Hello Vue!' + } +} + +Vue.createApp().mount(App6, '#app-6') +``` + + +## Composing with Components + +The component system is another important concept in Vue, because it's an abstraction that allows us to build large-scale applications composed of small, self-contained, and often reusable components. If we think about it, almost any type of application interface can be abstracted into a tree of components: + +![Component Tree](/images/components.png) + +In Vue, a component is essentially a Vue instance with pre-defined options. Registering a component in Vue is straightforward: we create a component object as we did with `App` objects and we define it in parent's `components` option: + +``` js +// Define a new component called todo-item +const TodoItem = { + template: '
  • This is a todo
    • ' +} + +const App = { + components: { + 'todo-item': TodoItem + } +} + +Vue.createApp().mount(...) +``` + +Now you can compose it in another component's template: + +```html +
      + + +
    +``` + +But this would render the same text for every todo, which is not super interesting. We should be able to pass data from the parent scope into child components. Let's modify the component definition to make it accept a [prop](TODO:components.html#Props): + +``` js +const TodoItem = { + props: ['todo'], + template: '
  • {{ todo.text }}
    • ' +} +``` + +Now we can pass the todo into each repeated component using `v-bind`: + +``` html +
    +
      + + +
    +
    +``` +``` js +const TodoItem = { + props: ['todo'], + template: '
  • {{ todo.text }}
    • ' +} + +const App7 = { + data: { + groceryList: [ + { id: 0, text: 'Vegetables' }, + { id: 1, text: 'Cheese' }, + { id: 2, text: 'Whatever else humans are supposed to eat' } + ] + }, + components: { + 'todo-item': TodoItem + } +} + +Vue.createApp().mount(App7, '#app-7') +``` + + +This is a contrived example, but we have managed to separate our app into two smaller units, and the child is reasonably well-decoupled from the parent via the props interface. We can now further improve our `` component with more complex template and logic without affecting the parent app. + +In a large application, it is necessary to divide the whole app into components to make development manageable. We will talk a lot more about components [later in the guide](TODO:components.md), but here's an (imaginary) example of what an app's template might look like with components: + +``` html +
    + + + + + +
    +``` + +### Relation to Custom Elements + +You may have noticed that Vue components are very similar to **Custom Elements**, which are part of the [Web Components Spec](https://www.w3.org/wiki/WebComponents/). That's because Vue's component syntax is loosely modeled after the spec. For example, Vue components implement the [Slot API](https://github.com/w3c/webcomponents/blob/gh-pages/proposals/Slots-Proposal.md) and the `is` special attribute. However, there are a few key differences: + +1. The Web Components Spec has been finalized, but is not natively implemented in every browser. Safari 10.1+, Chrome 54+ and Firefox 63+ natively support web components. In comparison, Vue components don't require any polyfills and work consistently in all supported browsers (IE9 and above). When needed, Vue components can also be wrapped inside a native custom element. + +2. Vue components provide important features that are not available in plain custom elements, most notably cross-component data flow, custom event communication and build tool integrations. + +Although Vue doesn't use custom elements internally, it has [great interoperability](https://custom-elements-everywhere.com/#vue) when it comes to consuming or distributing as custom elements. Vue CLI also supports building Vue components that register themselves as native custom elements. + +## Ready for More? + +We've briefly introduced the most basic features of Vue.js core - the rest of this guide will cover them and other advanced features with much finer details, so make sure to read through it all! \ No newline at end of file