Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .zhlintignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
> {#
? {#
! {#
<span class="options-api">
<span class="composition-api">
</span>
) [[源码]
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"dev": "vitepress",
"build": "vitepress build",
"preview": "vitepress preview",
"lint": "zhlint 'src/{api,about,guide,sponsor,translations,tutorial}/**/*.md'",
"lint": "zhlint \"src/{api,about,guide,sponsor,translations,tutorial}/**/*.md\"",
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

消除在 linux、windows 平台执行差异

"clean": "rm -rf .vitepress/dist",
"sync": "node scripts/sync.js",
"preinstall": "npx only-allow pnpm",
Expand Down
8 changes: 4 additions & 4 deletions src/about/translation.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ aside: deep

但也有例外的情况,某些英文单词我们倾向于选择不翻译、用原词。开发者常常与一部分英语单词打交道,许多英语单词甚至作为了开发框架或操作系统的专有名词,直接抛出这个单词也的确能够帮助用户更好的理解、锁定所讲的是什么概念。

3. **更符合中文的表述方式**:我们必须正视英语和中文本身的差异与不同,由于表达方式和语法结构的区别,常常一个结构复杂的多重定语从句很难逐字逐词地直译成中文,翻译出的句子应符合母语者的叙述习惯,即尽可能避免英语式的倒装哪怕讲述方式与作者原文有较大区别,表述尽可能口语化。最好的方式应该是将视线从单个句子中移出来,结合上下文先进行理解再用中文的习惯性表达将其重新复述出来。
3. **更符合中文的表述方式**:我们必须正视英语和中文本身的差异与不同,由于表达方式和语法结构的区别,常常一个结构复杂的多重定语从句很难逐字逐词地直译成中文,翻译出的句子应符合母语者的叙述习惯,即尽可能避免英语式的倒装(哪怕讲述方式与作者原文有较大区别),表述尽可能口语化。最好的方式应该是将视线从单个句子中移出来,结合上下文先进行理解再用中文的习惯性表达将其重新复述出来。

## 格式规范

Expand Down Expand Up @@ -90,12 +90,12 @@ aside: deep
- 逗号、句号、分号、冒号、叹号、问号,统一使用全角字符:,。;:!?
- 破折号使用:——
- 引号统一使用 “ ” 和 ‘ ’
- 括号统一使用全角括号 ()
- 括号统一使用半角括号 ()
- 非注释部分的代码除外,保留英文标点符号。

#### 内联代码或代码关键字

- 务必用反引号即英文输入法下,按键盘上 Tab 键上方的那个键将内容括起来。
- 务必用反引号(即英文输入法下,按键盘上 Tab 键上方的那个键)将内容括起来。
- 包括代码注释中出现代码或代码关键字时,也要括起来。

#### 空格的使用
Expand Down Expand Up @@ -256,7 +256,7 @@ Vitepress 和 Vuepress 中对以上两种写法的渲染视觉效果为:

在 Markdown 文档中 `[title](link)` 形式的链接非常常用,而 Vue 文档中大量使用了这一语法,用来作章节的跳转。

链接中有时还会带有锚点以 `#` 作前缀用来定位到页面的对应位置,例如 `[props 大小写格式](/guide/components/props.html#prop-name-casing)`。
链接中有时还会带有锚点(以 `#` 作前缀)用来定位到页面的对应位置,例如 `[props 大小写格式](/guide/components/props.html#prop-name-casing)`。

但是在 VitePress 中,由于锚点是对应 Markdown 内容中的 “标题行” 的,因此若改动了英文内容的标题行,别处引用此处的锚点就是失效了:

Expand Down
4 changes: 2 additions & 2 deletions src/api/application.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,12 +155,12 @@
/* ... */
})
// 注册对象形式的指令
// 注册(对象形式的指令)
app.directive('myDirective', {
/* 自定义指令钩子 */
})
// 注册函数形式的指令
// 注册(函数形式的指令)
app.directive('myDirective', () => {
/* ... */
})
Expand Down
8 changes: 4 additions & 4 deletions src/api/composition-api-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,16 +86,16 @@ export default {
```js
export default {
setup(props, context) {
// 透传 Attributes非响应式的对象,等价于 $attrs
// 透传 Attributes (非响应式的对象,等价于 $attrs)
console.log(context.attrs)

// 插槽非响应式的对象,等价于 $slots
// 插槽(非响应式的对象,等价于 $slots)
console.log(context.slots)

// 触发事件函数,等价于 $emit
// 触发事件(函数,等价于 $emit)
console.log(context.emit)

// 暴露公共属性(函数)
// 暴露公共属性(函数)
console.log(context.expose)
}
}
Expand Down
4 changes: 2 additions & 2 deletions src/api/options-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -217,9 +217,9 @@

**错误捕获注意事项**

- 在使用异步 `setup()` 函数使用了顶层 `await`的组件中,即使 `setup()` 抛出了错误,Vue 也会尝试渲染组件模板。这可能会导致更多错误,因为在渲染组件模板时,可能会尝试访问失败的 `setup()` 上下文中不存在的属性。当捕获这类组件的错误时,应当同时准备好捕获异步 `setup()`永远会先抛出错误和失败的渲染过程中的错误。
- 在使用异步 `setup()` 函数 (使用了顶层 `await`) 的组件中,即使 `setup()` 抛出了错误,Vue 也会尝试渲染组件模板。这可能会导致更多错误,因为在渲染组件模板时,可能会尝试访问失败的 `setup()` 上下文中不存在的属性。当捕获这类组件的错误时,应当同时准备好捕获异步 `setup()` (永远会先抛出错误) 和失败的渲染过程中的错误。

- <sup class="vt-badge" data-text="SSR only"></sup> 在 `<Suspense>` 的父组件中替换出错的子组件会导致 SSR 的激活不匹配。相反,尽量将可能抛出错误的逻辑从子组件的 `setup()` 中抽成一个独立的函数并在父组件的 `setup()` 中执行,这样就可以安全地 `try/catch` 执行过程,并在渲染实际的子组件前根据需要进行替换。
- <sup class="vt-badge" data-text="SSR only"></sup>在 `<Suspense>` 的父组件中替换出错的子组件会导致 SSR 的激活不匹配。相反,尽量将可能抛出错误的逻辑从子组件的 `setup()` 中抽成一个独立的函数并在父组件的 `setup()` 中执行,这样就可以安全地 `try/catch` 执行过程,并在渲染实际的子组件前根据需要进行替换。

## renderTracked <sup class="vt-badge dev-only" /> {#rendertracked}

Expand Down
2 changes: 1 addition & 1 deletion src/guide/best-practices/performance.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ import { defineAsyncComponent } from 'vue'

// 会为 Foo.vue 及其依赖创建单独的一个块
// 它只会按需加载
//即该异步组件在页面中被渲染时
// (即该异步组件在页面中被渲染时)
const Foo = defineAsyncComponent(() => import('./Foo.vue'))
```

Expand Down
8 changes: 4 additions & 4 deletions src/guide/best-practices/production-deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,16 @@

## 不使用构建工具 {#without-build-tools}

如果你没有使用任何构建工具,而是从 CDN 或其他源来加载 Vue,请确保在部署时使用的是生产环境版本以 `.prod.js` 结尾的构建文件。生产环境版本会被最小化,并移除了所有仅用于开发环境的代码分支。
如果你没有使用任何构建工具,而是从 CDN 或其他源来加载 Vue,请确保在部署时使用的是生产环境版本(以 `.prod.js` 结尾的构建文件)。生产环境版本会被最小化,并移除了所有仅用于开发环境的代码分支。

- 如果需要使用全局变量版本通过 `Vue` 全局变量访问:请使用 `vue.global.prod.js`。
- 如果需要 ESM 版本通过原生 ESM 导入访问:请使用 `vue.esm-browser.prod.js`。
- 如果需要使用全局变量版本(通过 `Vue` 全局变量访问):请使用 `vue.global.prod.js`。
- 如果需要 ESM 版本(通过原生 ESM 导入访问):请使用 `vue.esm-browser.prod.js`。

更多细节请参考[构建文件指南](https://github.com/vuejs/core/tree/main/packages/vue#which-dist-file-to-use)。

## 使用构建工具 {#with-build-tools}

通过 `create-vue`基于 Vite或是 Vue CLI基于 webpack搭建的项目都已经预先做好了针对生产环境的配置。
通过 `create-vue` (基于 Vite) 或是 Vue CLI (基于 webpack) 搭建的项目都已经预先做好了针对生产环境的配置。

如果使用了自定义的构建,请确保:

Expand Down
6 changes: 3 additions & 3 deletions src/guide/built-ins/suspense.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,10 @@ outline: deep
<Suspense>
└─ <Dashboard>
├─ <Profile>
│ └─ <FriendStatus>组件有异步的 setup()
│ └─ <FriendStatus> (组件有异步的 setup())
└─ <Content>
├─ <ActivityFeed> 异步组件
└─ <Stats>异步组件
├─ <ActivityFeed> (异步组件)
└─ <Stats> (异步组件)
```

在这个组件树中有多个嵌套组件,要渲染出它们,首先得解析一些异步资源。如果没有 `<Suspense>`,则它们每个都需要处理自己的加载、报错和完成状态。在最坏的情况下,我们可能会在页面上看到三个旋转的加载态,在不同的时间显示出内容。
Expand Down
4 changes: 2 additions & 2 deletions src/guide/components/props.md
Original file line number Diff line number Diff line change
Expand Up @@ -445,7 +445,7 @@ Vue 组件可以更细致地声明对传入的 props 的校验要求。比如我
```js
defineProps({
// 基础类型检查
// 给出 `null` 和 `undefined` 值则会跳过任何类型检查
// (给出 `null` 和 `undefined` 值则会跳过任何类型检查)
propA: Number,
// 多种可能的类型
propB: [String, Number],
Expand Down Expand Up @@ -505,7 +505,7 @@ defineProps({
export default {
props: {
// 基础类型检查
//给出 `null` 和 `undefined` 值则会跳过任何类型检查
// (给出 `null` 和 `undefined` 值则会跳过任何类型检查)
propA: Number,
// 多种可能的类型
propB: [String, Number],
Expand Down
2 changes: 1 addition & 1 deletion src/guide/essentials/template-refs.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ watchEffect(() => {
if (input.value) {
input.value.focus()
} else {
// 此时还未挂载,或此元素已经被卸载例如通过 v-if 控制
// 此时还未挂载,或此元素已经被卸载(例如通过 v-if 控制)
}
})
```
Expand Down
2 changes: 1 addition & 1 deletion src/guide/essentials/watchers.md
Original file line number Diff line number Diff line change
Expand Up @@ -346,7 +346,7 @@ watchEffect(async () => {
})
```

这个例子中,回调会立即执行,不需要指定 `immediate: true`。在执行期间,它会自动追踪 `todoId.value` 作为依赖和计算属性类似。每当 `todoId.value` 变化时,回调会再次执行。有了 `watchEffect()`,我们不再需要明确传递 `todoId` 作为源值。
这个例子中,回调会立即执行,不需要指定 `immediate: true`。在执行期间,它会自动追踪 `todoId.value` 作为依赖(和计算属性类似)。每当 `todoId.value` 变化时,回调会再次执行。有了 `watchEffect()`,我们不再需要明确传递 `todoId` 作为源值。

你可以参考一下[这个例子](/examples/#fetching-data)的 `watchEffect` 和响应式的数据请求的操作。

Expand Down
4 changes: 2 additions & 2 deletions src/guide/extras/web-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,10 +106,10 @@ const MyVueElement = defineCustomElement({
customElements.define('my-vue-element', MyVueElement)

// 你也可以编程式地实例化元素:
// 必须在注册之后
// (必须在注册之后)
document.body.appendChild(
new MyVueElement({
// 初始化 props(可选)
// 初始化 props (可选)
})
)
```
Expand Down
2 changes: 1 addition & 1 deletion src/guide/scaling-up/ssr.md
Original file line number Diff line number Diff line change
Expand Up @@ -268,7 +268,7 @@ Vite 提供了内置的 [Vue 服务端渲染支持](https://cn.vitejs.dev/guide/
推荐的解决方案是在每个请求中为整个应用创建一个全新的实例,包括 router 和全局 store。然后,我们使用[应用层级的 provide 方法](/guide/components/provide-inject#app-level-provide)来提供共享状态,并将其注入到需要它的组件中,而不是直接在组件中将其导入:

```js
// app.js 在服务端和客户端间共享
// app.js (在服务端和客户端间共享)
import { createSSRApp } from 'vue'
import { createStore } from './store.js'

Expand Down
Loading