From d7a4719f14ad554b189015b02d6acad9e047e71c Mon Sep 17 00:00:00 2001 From: Yuanhao Geng <41546976+GYHHAHA@users.noreply.github.com> Date: Wed, 15 May 2024 10:50:14 +0800 Subject: [PATCH] doc(zh): sync getting started page at 3ab1e5e (#2234) * doc(zh): sync getting started page at 3ab1e5e * fix: use code v-pre * update: fix heading language * fix type * Apply suggestions from code review * Update packages/docs/zh/guide/index.md --------- Co-authored-by: Jinjiang --- packages/docs/zh/guide/index.md | 232 +++++++++++++++++++++++--------- 1 file changed, 169 insertions(+), 63 deletions(-) diff --git a/packages/docs/zh/guide/index.md b/packages/docs/zh/guide/index.md index a5014a82f..9d9d01ab1 100644 --- a/packages/docs/zh/guide/index.md +++ b/packages/docs/zh/guide/index.md @@ -1,100 +1,206 @@ # 入门 +href="https://vueschool.io/courses/vue-router-4-for-everyone" +title="在 Vue School 上学习如何使用 Vue Router 构建强大的单页应用">观看免费的 Vue Router 视频课程 -用 Vue + Vue Router 创建单页应用非常简单：通过 Vue.js，我们已经用组件组成了我们的应用。当加入 Vue Router 时，我们需要做的就是将我们的组件映射到路由上，让 Vue Router 知道在哪里渲染它们。下面是一个基本的例子： +Vue Router 是 Vue 官方的客户端路由解决方案。 -## HTML +客户端路由的作用是在单页应用 (SPA) 中将浏览器的 URL 和用户看到的内容绑定起来。当用户在应用中浏览不同页面时，URL 会随之更新，但页面不需要从服务器重新加载。 -```html - - +Vue Router 基于 Vue 的组件系统构建，你可以通过配置**路由**来告诉 Vue Router 为每个 URL 路径显示哪些组件。 -
+::: tip 学习基础 +这份指南假设你已经对 Vue 有了一定的了解。你不必是 Vue 的专家，但你也许偶尔需要查看 [Vue 的文档](https://cn.vuejs.org/)来了解某些特性。 +::: + +## 示例 + +为了引入一些核心概念，我们将使用如下的示例： + +- [Vue 演练场中的示例](https://play.vuejs.org/#eNqFVVtv2zYU/itn6gArmC05btEHTXXTFcWyYZeiLfYy7UGWji02EsmRlOPA8H/fIambnaRD4Fg61++c7yN9DJqc8eirDpKANVIoA0coFOYG30kJJ9gq0cBs3+Is412AEq1B1Xmi2L+ObpvX+3IpI5+b8aFqSJ+rjANErcbQp/v3RrTchLMXlDa7CuZBl07YUoONrCl/bQPT6np9i3UtbLPv0phenVm6L3rQRgm+W79vlULeIQaZmypJ484HxyN87xzRtq3rj+SE08mViX2dlOf7vuAnh/I3xu/AiDdZEGfB+mdBz3ArGkzj0f9sRr4hy5D2zr49ykvjvmdqeTmv9RfDe4i7uM6dxsNiaF9+l0+y+Ts2Qj3cMm3oa94Zfd0py4uBzYFPO6Br3ZPaGzpme9rtQGdxg2WUgOC6Y0PDG/jbjnL0vMAsnhEsQcU4UZaMbU/z8zC3x/PYsbcN/ueilaJW03nDoy1Y+VUkT+0nvHI9PVB6PJE8M44HN2iJ27yt+9q09ek+rFR1oZg0RM5FgmvboKlEqRP/BrATX4SDH171JgBD4CIvThXJVldhP7Y7J9DtxP4nxZKk+470cnFQVuseHh2TlTduWmMEh5uiZsUdSXPAcKlOH/hIZmfEjhODRtPaozNKjyiiGcqn75Ej0Pl3lMyHp2fFeMHnEB/SRia+ict6ep/GXBWV1UGHyGtgh5O1K0KvuC8T/duieoi6tLdvYUYg+rXTmKH3jLmeKoW0owLDI7h8IrnvfAKrIargxfQ/lA0LHjmr8w3W3X3w2dVMIGWchoH9ohEl1pFRrCE2fccsgCY/1Mh3piLjaknc+pujr3TOqedk0eSSrg/BiVU3WtY5dBYMks2CkRtrzoLKGKmTOG65vNtFtON4jLh5Fb2MlnFJJ2tijVA3i40S99rdV1ngNmtr31BQXOLeCFHrRS7Zcy0eBd68jl5H13HNNjFVjxkv8eBq94unMY0mQWzZ7mJIKwtWo/pTGkaCORs2p9+Z+1+dzagWB6BFhcXdE/av+uAhf1RI0+1xMpzJFWnOuz98/gMP9Dw4icW2puhvOD+hFnVrMfqwn1peEuxJnEP7i+OM8d0X/eFgkOt+KAt0FLIj8v03Rh/hvoxeTbaozUONOiq0/aGhX6w5aY1xn7cRqkSVwEoegMCyEl4sl8sf3d1H5RhfbATdKk0C10t5cHaZlyWBHSzUJeNUFtaQww/08Tenz65xSzf+NLJaTTuP5UcARVFMACSwpL9VVyE4/QesCg/V) + +让我们首先来看根组件, `App.vue`。 + +### App.vue + +```vue + ``` -### `router-link` +在这个 `template` 中使用了两个由 Vue Router 提供的组件: `RouterLink` 和 `RouterView`。 + +不同于常规的 `` 标签，我们使用组件 `RouterLink` 来创建链接。这使得 Vue Router 能够在不重新加载页面的情况下改变 URL，处理 URL 的生成、编码和其他功能。我们将会在之后的部分深入了解 `RouterLink` 组件。 -请注意，我们没有使用常规的 `a` 标签，而是使用一个自定义组件 `router-link` 来创建链接。这使得 Vue Router 可以在不重新加载页面的情况下更改 URL，处理 URL 的生成以及编码。我们将在后面看到如何从这些功能中获益。 +`RouterView` 组件可以使 Vue Router 知道你想要在哪里渲染当前 URL 路径对应的**路由组件**。它不一定要在 `App.vue` 中，你可以把它放在任何地方，但它需要在某处被导入，否则 Vue Router 就不会渲染任何东西。 -### `router-view` +上述示例还使用了 {{ $route.fullPath }} 。你可以在组件模板中使用 `$route` 来访问当前的路由对象。 -`router-view` 将显示与 URL 对应的组件。你可以把它放在任何地方，以适应你的布局。 + -## JavaScript +### 创建路由器实例 + +路由器实例是通过调用 `createRouter()` 函数创建的: ```js -// 1. 定义路由组件. -// 也可以从其他文件导入 -const Home = { template: '
Home
' } -const About = { template: '
About
' } - -// 2. 定义一些路由 -// 每个路由都需要映射到一个组件。 -// 我们后面再讨论嵌套路由。 +import { createMemoryHistory, createRouter } from 'vue-router' + +import HomeView from './HomeView.vue' +import AboutView from './AboutView.vue' + const routes = [ - { path: '/', component: Home }, - { path: '/about', component: About }, + { path: '/', component: HomeView }, + { path: '/about', component: AboutView }, ] -// 3. 创建路由实例并传递 `routes` 配置 -// 你可以在这里输入更多的配置，但我们在这里 -// 暂时保持简单 -const router = VueRouter.createRouter({ - // 4. 内部提供了 history 模式的实现。为了简单起见，我们在这里使用 hash 模式。 - history: VueRouter.createWebHashHistory(), - routes, // `routes: routes` 的缩写 +const router = createRouter({ + history: createMemoryHistory(), + routes, }) +``` -// 5. 创建并挂载根实例 -const app = Vue.createApp({}) -// 确保 _use_ 路由实例使 -// 整个应用支持路由。 -app.use(router) +这里的 `routes` 选项定义了一组路由，把 URL 路径映射到组件。其中，由 `component` 参数指定的组件就是先前在 `App.vue` 中被 `` 渲染的组件。这些路由组件通常被称为*视图*，但本质上它们只是普通的 Vue 组件。 -app.mount('#app') +其他可以设置的路由选项我们会在之后介绍，目前我们只需要 `path` 和 `component`。 + +这里的 `history` 选项控制了路由和 URL 路径是如何双向映射的。在演练场的示例里，我们使用了 `createMemoryHistory()`，它会完全忽略浏览器的 URL 而使用其自己内部的 URL。 这在演练场中可以正常工作，但是未必是你想要在实际应用中使用的。通常，你应该使用 `createWebHistory()` 或 `createWebHashHistory()`。我们将在[不同的历史记录模式](./essentials/history-mode)的部分详细介绍这个主题。 + +### 注册路由器插件 + +一旦创建了我们的路由器实例，我们就需要将其注册为插件，这一步骤可以通过调用 `use()` 来完成。 + +```js +createApp(App) + .use(router) + .mount('#app') +``` + +或等价地： -// 现在，应用已经启动了！ +```js +const app = createApp(App) +app.use(router) +app.mount('#app') ``` -通过调用 `app.use(router)`，我们会触发第一次导航且可以在任意组件中以 `this.$router` 的形式访问它，并且以 `this.$route` 的形式访问当前路由： +和大多数的 Vue 插件一样，`use()` 需要在 `mount()` 之前调用。 + +如果你好奇这个插件做了什么，它的职责包括： + +1. [全局注册](https://cn.vuejs.org/guide/components/registration.html#global-registration) `RouterView` 和 `RouterLink` 组件。 +2. 添加全局 `$router` 和 `$route` 属性。 +3. 启用 `useRouter()` 和 `useRoute()` 组合式函数。 +4. 触发路由器解析初始路由。 + +### 访问路由器和当前路由 + +你很可能想要在应用的其他地方访问路由器。 + +如果你是从 ES 模块导出路由器实例的，你可以将路由器实例直接导入到你需要它的地方。在一些情况下这是最好的方法，但如果我们在组件内部，那么我们还有其他选择。 + +在组件模板中，路由器实例将被暴露为 `$router`。这与同样被暴露的 `$route` 一样，但注意前者最后有一个额外的 `r`。 + +如果我们使用选项式 API，我们可以在 JavaScript 中如下访问这两个属性：`this.$router` 和 `this.$route`。在演练场示例中的 `HomeView.vue` 组件中，路由器就是这样获取的。 ```js -// Home.vue export default { - computed: { - username() { - // 我们很快就会看到 `params` 是什么 - return this.$route.params.username - }, - }, methods: { - goToDashboard() { - if (isAuthenticated) { - this.$router.push('/dashboard') - } else { - this.$router.push('/login') - } + goToAbout() { + this.$router.push('/about') }, }, } ``` -要在 `setup` 函数中访问路由，请调用 `useRouter` 或 `useRoute` 函数。我们将在 [Composition API](./advanced/composition-api.md#在-setup-中访问路由和当前路由) 中了解更多信息。 +这里调用了 `push()`，这是用于[编程式导航](./essentials/navigation)的方法。我们会在后面详细了解。 + + +对于组合式 API，我们不能通过 `this` 访问组件实例，所以 Vue Router 给我们提供了一些组合式函数。演练场示例中的 `AboutView.vue` 组件使用了这种方法： + +```vue + +``` + +你现在不一定要完全理解这段代码，关键是要知道可以通过 `useRoute()` 和 `useRouter()` 来访问路由器实例和当前路由。 + +### 下一步 + +如果你想要在 Vite 中使用完整的示例，你可以使用 [create-vue](https://github.com/vuejs/create-vue) 工具，它提供了在项目加入 Vue Router 的选项： + +::: code-group + +```bash [npm] +npm create vue@latest +``` + +```bash [yarn] +yarn create vue +``` + +```bash [pnpm] +pnpm create vue +``` + +::: + +上述通过 create-vue 创建的示例项目使用了与我们在这里看到的类似的功能，对于探索后续介绍的其他功能而言，也许你会觉得这是一个不错的起点。 + +## 本教程的约定 + +### 单文件组件 + +Vue Router 经常在配合打包工具 (如 Vite) 和[单文件组件](https://cn.vuejs.org/guide/introduction.html#single-file-components) (即 `.vue` 文件) 的应用中使用。本教程大多数的示例都是如此，但是 Vue Router 本身并不要求你使用构建工具或单文件组件。 + +例如，若你要使用 [Vue](https://cn.vuejs.org/guide/quick-start.html#using-vue-from-cdn) 和 [Vue Router](../installation#Direct-Download-CDN) 的使用全局构建版本，这些库将被暴露为全局对象，而不是导入： + +```js +const { createApp } = Vue +const { createRouter, createWebHistory } = VueRouter +``` + +### 组件 API 风格 + +Vue Router 可以使用组合式 API 或选项式 API 。在必要时，示例将会同时使用两种风格，组合式 API 示例通常会使用 `