Skip to content

docs(format): replace full width spaces #1092

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Aug 4, 2025
Merged
Show file tree
Hide file tree
Changes from all 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
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