update zh docs translations

refinajs · Jan 17, 2024 · 14a6b23 · 14a6b23 · vercel · Jan 17, 2024
1 parent 11dd239
commit 14a6b23
Show file tree

Hide file tree

Showing 52 changed files with 1,003 additions and 75 deletions.
diff --git a/docs/zh/README.md b/docs/zh/README.md
@@ -0,0 +1,5 @@
+# Refina.js Docs
+
+Visit the docs at https\://refina.vercel.app/ and https\://refinajs.github.io/refina.
+
+Some of the code and content are borrowed from [Vue.js docs](https://github.com/vuejs/docs). Thanks to their great work!
diff --git a/docs/zh/guide/apis/app-hooks.md b/docs/zh/guide/apis/app-hooks.md
@@ -20,6 +20,10 @@
 
 永久钩子可以通过 `_.$app.permanentHooks` 访问。
 
+## `initContext` 钩子
+
+在该钩子中初始化上下文对象。
+
 ## `beforeMain` 钩子
 
 在应用的主函数被调用之前调用，无论处于 `UPDATE` 或 `RECV` 状态下。

diff --git a/docs/zh/guide/apis/directives.md b/docs/zh/guide/apis/directives.md
@@ -40,9 +40,9 @@ $app(_ => {
 
 与 `_.$app.update` 等价。
 
-## `_.$setD`
+## `_.$updateModel`
 
-设置一个 `D` 所包含的值，并触发页面更新。
+设置一个 `Model` 所包含的值，并触发页面更新。
 
 ## `_.$ev`
 

diff --git a/docs/zh/guide/apis/util-funcs.md b/docs/zh/guide/apis/util-funcs.md
@@ -88,21 +88,17 @@ $app.use(Basics)(_ => {
 
 在当前位置嵌入一个视图。
 
-参见 [嵌入视图](../essentials/view.md#embedding-views)。
-
-与 [传递视图参数](../essentials/view.md#passing-parameters)。
-
 ## `_.asyncEmbed`
 
-在当前位置嵌入一个异步加载的视图。
+在当前位置嵌入异步加载的内容。
 
 **例子**
 
 ```ts
 _.asyncEmbed(() => import("./myView.ts"));
 ```
 
-这将从 `./myView.ts` 异步地加载视图。这对代码拆分有帮助。
+这将从 `./someContent.ts` 异步地加载内容。这对代码拆分有帮助。
 
 :::info
 

diff --git a/docs/zh/guide/essentials/application.md b/docs/zh/guide/essentials/application.md
@@ -41,7 +41,7 @@ $app.use(Plugin1).use(Plugin2, param1, param2).use(Plugin3)(_ => {
 
 :::warning
 
-由于 TypeScript 的限制，如果仅导入插件却不安装它，其类型仍然在上下文对象中可见。 但是如果你使用这些实际上并没有安装的插件，会产生运行时错误。
+由于 TypeScript 的限制，如果仅导入插件却不安装它，其类型仍然在上下文对象中可见。 但是如果你使用这些实际上并没有安装的插件，会产生运行时错误。 但是如果你使用这些实际上并没有安装的插件，会产生运行时错误。
 
 :::
 

diff --git a/docs/zh/guide/essentials/component.md b/docs/zh/guide/essentials/component.md
@@ -9,8 +9,8 @@
 Refina 中有3种组件：
 
 - **输出型组件**：只负责渲染页面内容的组件。 如：`h1`, `p`...
-- **事件型组件**：会触发一个事件的组件。 如：`button`, `input`...
-- **状态型组件**：含有一个状态的组件。 如：`checkbox`, `radio`...
+- **事件型组件**：会触发一个事件的组件。 如：`button`, `input`... 如：`button`, `input`...
+- **状态型组件**：含有一个状态的组件。 如：`checkbox`, `radio`... 如：`checkbox`, `radio`...
 
 :::info
 
@@ -22,7 +22,7 @@ Refina 中有3种组件：
 
 ## 额外的 props {#extra-props}
 
-有时一个组件有很多可选的 props。这使得将这些 props 通过组件函数参数传入十分不便。 这时我们可以使用 [`_.$props` 指令](../apis/directives.md#props) 向下一个组件以按名称传入的方式添加多个额外的 prop。
+有时一个组件有很多可选的 props。这使得将这些 props 通过组件函数参数传入十分不便。 有时一个组件有很多可选的 props。这使得将这些 props 通过组件函数参数传入十分不便。 这时我们可以使用 [`_.$props` 指令](../apis/directives.md#props) 向下一个组件以按名称传入的方式添加多个额外的 prop。
 
 ```ts
 $app.use(MdUI)(_ => {
@@ -54,9 +54,9 @@ $app.use(MdUI)(_ => {
 
 如果一个组件不包括任何非文本节点的 DOM 元素，那么它的主元素的值为 `undefined`。
 
-主元素应当是组件的视觉核心。 向组件添加的类名与样式将被设置在主元素上。
+主元素应当是组件的视觉核心。 向组件添加的类名与样式将被设置在主元素上。 组件的底层实现是一个上下文函数。 所以创建一个不属于上述种类的组件是完全可行的。
 
-组件可以通过调用 `this,$main()` 指令来设置下一个元素为主元素。 默认地，组件渲染的第一个元素将被视为组件的主元素。
+组件可以通过调用 `this,$main()` 指令来设置下一个元素为主元素。 默认地，组件渲染的第一个元素将被视为组件的主元素。 默认地，组件渲染的第一个元素将被视为组件的主元素。
 
 :::info
 

diff --git a/docs/zh/guide/essentials/context.md b/docs/zh/guide/essentials/context.md
@@ -26,7 +26,7 @@ Refina 的很多 API 通过上下文对象提供。
 
 1. **文本节点**：即`_.t`。
 2. **底层元素**：原始的 DOM 元素，名称有 `_` 作为前缀，如 `_._div` 和 `_._svgPath`。
-3. **插件提供的组件函数**：比如由 `Basics` 插件提供的 `_.button` 、由 `MdUI` 插件提供的 `_.mdButton`。 它们的名称不含有 `_` 前缀。
+3. **插件提供的组件函数**：比如由 `Basics` 插件提供的 `_.button` 、由 `MdUI` 插件提供的 `_.mdButton`。 它们的名称不含有 `_` 前缀。 **工具函数**：一些实用工具，并不渲染组件/元素。
 
 ## 工具函数
 

diff --git a/docs/zh/guide/essentials/event.md b/docs/zh/guide/essentials/event.md
@@ -33,7 +33,7 @@ $app.use(Basics)(_ => {
 
 作为一个类 ImGUI 的框架，Refina 不需要一个”响应式系统“来监听状态的变化。
 
-因此你可以直接以最普通的方式定义状态，即使用 `let` 语句。 即，不需要通过 `ref` 或 `reactive` 或 `useState` 来创建状态。
+因此你可以直接以最普通的方式定义状态，即使用 `let` 语句。 因此你可以直接以最普通的方式定义状态，即使用 `let` 语句。 即，不需要通过 `ref` 或 `reactive` 或 `useState` 来创建状态。
 
 :::warning
 
@@ -47,7 +47,7 @@ $app.use(Basics)(_ => {
 
 因为大部分组件或元素没有或**仅有一个**常用的事件，Refina 以返回值的形式体现事件是否被触发。
 
-比如，`_.button` 的返回值是一给布尔值。当按钮被按下时，`_.button` 会返回一次 `true`，其余时刻，它将返回 `false`。 因此你可以使用 `if` 语句或 `&&` 运算符来处理该事件。
+比如，`_.button` 的返回值是一给布尔值。当按钮被按下时，`_.button` 会返回一次 `true`，其余时刻，它将返回 `false`。 因此你可以使用 `if` 语句或 `&&` 运算符来处理该事件。 因此你可以使用 `if` 语句或 `&&` 运算符来处理该事件。
 
 :::tip
 

diff --git a/docs/zh/guide/essentials/input.md b/docs/zh/guide/essentials/input.md
@@ -28,17 +28,17 @@ $app.use(Basics)(_ => {
 
 <BasicInputVue />
 
-## 数据包裹
+## Model 对象
 
-### `d` 函数
+### `model` 函数
 
 因为在 JavaScript 中没有办法直接引用原始值，我们需要将原始值包裹在一个对象中来实现引用的效果。`d` 函数即是通过创建一个类型为 **`PD`** 的对象来包裹原始值。
 
-### 将对象的属性转化为 `PD`
+### 将对象的属性转化为一个 model
 
 你可能想要将输入框的值读/写到一个对象的某个属性。
 
-`fromProp` 函数可以将对象的属性转化为一个 `PD`。
+`fromModel` 函数可以将对象的属性转化为一个 model。
 
 ```ts
 import { fromProp } from "refina";
@@ -57,11 +57,9 @@ $app.use(Basics)(_ => {
 type D<T> = T | PD<T>;
 ```
 
-大部分 Refina 组件的参数都是 `D<...>` 类型的。因此你可以传入原始值或其被包裹形成的`PD`对象作为参数传入。
-
-### `getD` 函数
+### `d` 函数
 
-该函数可以从类型为 `D` 的值中取出原始值。
+该函数可以从类型为 `Model` 的值中取出原始值。
 
 ```ts
 const intrinsicValue = 1;
@@ -73,19 +71,13 @@ assert(getD(wrappedValue) === 1);
 
 :::info
 
-如果数据包裹由 `d` 函数创建，那么它的类型是 `PD<T>`, 因此你不需要使用 `getD` 函数。 你可以直接访问 `wrappedValue.value`.
+如果数据包裹由 `d` 函数创建，那么它的类型是 `PD<T>`, 因此你不需要使用 `getD` 函数。 你可以直接访问 `wrappedValue.value`. You can access `yourModel.value` directly.
 
 :::
 
 ### `_.$setD` 函数
 
-与 `getD` 函数相对应，这个函数可以设置类型为 `D` 中的数据的值。
-
-:::info
-
-之所以没有 `setD` 函数，是因为当值改变时应当自动地触发 `UPDATE` 调用。而这需要通过一个上下文对象才能实现。
-
-:::
+与 `valueOf` 函数相对应，这个函数可以设置类型为 `Model` 中的数据的值，并触发应用的更新。
 
 ## 另一种获取用户输入的方式。
 

diff --git a/docs/zh/guide/essentials/lowlevel.md b/docs/zh/guide/essentials/lowlevel.md
@@ -12,7 +12,7 @@ import LowlevelVue from "snippets/lowlevel.vue";
 
 :::info
 
-如果一个现有的组件已经满足你的需要，请使用它，因为底层渲染更冗长并容易写错。
+如果一个现有的组件已经满足你的需要，请使用它，因为底层渲染更冗长并容易写错。 函数签名
 
 :::
 

diff --git a/docs/zh/guide/essentials/rendering-basics.md b/docs/zh/guide/essentials/rendering-basics.md
@@ -53,7 +53,7 @@ $app.use(Basics)(_ => {
 
 这是因为视图函数的返回值总是会被忽略。
 
-你也可以使用 `&&` 来将数个一定返回真值的语句和最后一个语句连接，将多个语句转换为表达式，并省区花括号。
+你也可以使用 `&&` 来将数个一定返回真值的语句和最后一个语句连接，将多个语句转换为表达式，并省去花括号。
 
 比如，
 

diff --git a/docs/zh/guide/essentials/view.md b/docs/zh/guide/essentials/view.md
@@ -2,8 +2,6 @@
 
 视图是一个函数，它渲染一部分页面。
 
-视图可以被看作简化版的组件，它们直接的区别[稍后](#view-vs-component)会被讨论。
-
 它往往被用于拆分页面或复用页面重复出现的部分。
 
 ## 使用方式
@@ -44,30 +42,9 @@ $app(_ => {
 
 推荐将较大的视图编写在一个单独的文件中，并将这个视图作为默认导出。
 
-## 嵌入视图 {#embedding-views}
-
-如果视图没有参数，它可以直接作为某个组件的一个“内容”参数，就像表示嵌套层级的箭头函数那样。
-
-如果你想要直接在当前位置嵌入视图，而不是将其传入某个组件，你可以使用 [`_.embed`](../apis/util-funcs.md#embed)。
-
-:::info
-
-如果你确定这个视图只会再你的应用中使用一次，你可以把视图作为函数直接调用：
-
-```ts
-_.div(_ => {
-  _.span("my view");
-  myView(_);
-});
-```
-
-出于一致性的考虑，不建议这么做。
-
-:::
-
 ## 传入视图参数 {#passing-parameters}
 
-视图可以有参数。 你可以使用普通的语法定义视图参数：
+视图可以有参数。 你可以使用普通的语法定义视图参数： 你可以使用普通的语法定义视图参数：
 
 ```ts
 export default $view((_, name: string, id?: number) => {

diff --git a/docs/zh/guide/introduction.md b/docs/zh/guide/introduction.md
@@ -27,18 +27,59 @@ import CounterVue from 'snippets/counter.vue'
 
 上面的例子展示了Refina的两个核心功能：
 
-- **声明式渲染**: 不需要像 JSX 或 Vue template 那样的 DSL，只需普通的 JavaScript/TypeScript 就可以编写应用。 因此所有 JavaScript 与 TypeScript 开发工具都可以在 Refina 开发中直接使用。
+- **声明式渲染**: 不需要像 JSX 或 Vue template 那样的 DSL，只需普通的 JavaScript/TypeScript 就可以编写应用。 因此所有 JavaScript 与 TypeScript 开发工具都可以在 Refina 开发中直接使用。 因此所有 JavaScript 与 TypeScript 开发工具都可以在 Refina 开发中直接使用。
 
-- **响应性**：Refina 采用类 ImGUI 的状态管理模式。 你只需要像 Svelte 那样以最普通的方式的定义状态。 当状态改变时，Refina 会自动地更新页面。
+- **响应性**：Refina 采用类 ImGUI 的状态管理模式。 你只需要像 Svelte 那样以最普通的方式的定义状态。 当状态改变时，Refina 会自动地更新页面。 你只需要像 Svelte 那样以最普通的方式的定义状态。 当状态改变时，Refina 会自动地更新页面。
 
 你可能已经有了些疑问——先别急。 请继续看下去，以宏观地了解 Refina 作为一个框架提供了什么。
 
 :::tip 预备知识
 
-文档接下来的内容会假设你对 HTML、CSS 和 JavaScript 已经基本熟悉。 如果你对前端开发完全陌生，最好不要直接从一个框架开始进行入门学习——最好是掌握了基础知识再回到这里。 如有需要，你可以通过这些 [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript)、[HTML](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML) 和 [CSS](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps) 概述来检验你的知识水平。 如果之前有其他框架的经验会很有帮助，但也不是必须的。
+文档接下来的内容会假设你对 HTML、CSS 和 JavaScript 已经基本熟悉。 如果你对前端开发完全陌生，最好不要直接从一个框架开始进行入门学习——最好是掌握了基础知识再回到这里。 文档接下来的内容会假设你对 HTML、CSS 和 JavaScript 已经基本熟悉。 如果你对前端开发完全陌生，最好不要直接从一个框架开始进行入门学习——最好是掌握了基础知识再回到这里。 如有需要，你可以通过这些 [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript)、[HTML](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML) 和 [CSS](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps) 概述来检验你的知识水平。 如果之前有其他框架的经验会很有帮助，但也不是必须的。 如果之前有其他框架的经验会很有帮助，但也不是必须的。
 
 :::
 
-## 尝试使用 Refina
-
-你可以在 [**Playground**](/misc/playground) 快速尝试使用 Refina 开发。
+## 选择你的学习路径
+
+不同的开发者有不同的学习方式。 尽管在可能的情况下，我们推荐你通读所有内容，但你还是可以自由地选择一种自己喜欢的学习路径！
+
+<div class="vt-box-container next-steps">
+  <a class="vt-box" href="../tutorial/">
+    <p class="next-steps-link">尝试互动教程</p>
+    <p class="next-steps-caption">适合喜欢边动手边学的读者。</p>
+  </a>
+  <a class="vt-box" href="./quick-start">
+    <p class="next-steps-link">继续阅读该指南</p>
+    <p class="next-steps-caption">该指南会带你深入了解框架所有方面的细节。</p>
+  </a>
+  <a class="vt-box" href="/misc/playground">
+    <p class="next-steps-link">前往演练场</p>
+    <p class="next-steps-caption">自由地探索 Refina。</p>
+  </a>
+</div>
+
+<style scoped>
+.next-steps > * {
+  text-decoration: none;
+}
+.next-steps .vt-box {
+  border: 1px solid transparent;
+}
+.next-steps .vt-box:hover {
+  border-color: var(--vp-c-brand);
+  transition: border-color .3s cubic-bezier(.25,.8,.25,1);
+}
+.next-steps-link {
+  font-size: 20px;
+  line-height: 1.4;
+  letter-spacing: -.02em;
+  margin-bottom: .75em;
+  display: block;
+  color: var(--vp-c-brand);
+}
+.next-steps-caption {
+  margin-bottom: 0;
+  color: var(--vp-c-text-2);
+  transition: color .5s;
+}
+</style>
diff --git a/docs/zh/guide/quick-start.md b/docs/zh/guide/quick-start.md
@@ -7,15 +7,15 @@
 
 :::
 
-在本节中，我们将介绍如何在本地搭建 Refina 应用。 创建的项目将使用基于 [Vite](https://vitejs.dev) 的构建设置。
+在本节中，我们将介绍如何在本地搭建 Refina 应用。 在本节中，我们将介绍如何在本地搭建 Refina 应用。 创建的项目将使用基于 [Vite](https://vitejs.dev) 的构建设置。
 
-确保你安装了最新版本的 [Node.js](https://nodejs.org/)，并且你的当前工作目录正是打算创建项目的目录。 在命令行中运行以下命令 (不要带上 `>` 符号)：
+确保你安装了最新版本的 [Node.js](https://nodejs.org/)，并且你的当前工作目录正是打算创建项目的目录。 在命令行中运行以下命令 (不要带上 `>` 符号)： 在命令行中运行以下命令 (不要带上 `>` 符号)：
 
 ```sh
 > npm create refina@latest   # 推荐使用 pnpm
 ```
 
-这一指令将会安装并执行 [create-refina](https://github.com/refinajs/refina/tree/main/packages/creator)，它是 Refina 官方的项目脚手架工具。 你将会看到一些诸如组件库和 TailwindCSS 之类的可选功能提示：
+这一指令将会安装并执行 [create-refina](https://github.com/refinajs/refina/tree/main/packages/creator)，它是 Refina 官方的项目脚手架工具。 你将会看到一些诸如组件库和 TailwindCSS 之类的可选功能提示： 你将会看到一些诸如组件库和 TailwindCSS 之类的可选功能提示：
 
 ![Create Refina](/media/create-refina.png)
 
@@ -44,7 +44,7 @@
 
 你现在应该已经运行起来了你的第一个 Refinan 项目！
 
-现在打开 `src/app.ts` 文件，你可以看见应用的主体代码。 你可以编辑它，并在浏览器中实时查看更改。
+现在打开 `src/app.ts` 文件，你可以看见应用的主体代码。 你可以编辑它，并在浏览器中实时查看更改。 你可以编辑它，并在浏览器中实时查看更改。
 
 :::info
 

diff --git a/docs/zh/guide/why.md b/docs/zh/guide/why.md
@@ -4,7 +4,7 @@
 
 对于大部分前端页面，长什么样、要做什么，往往只需要三言两语就能说明白。 但是若要通过传统的前端框架实现它，往往需要写数百行代码。
 
-传统的前端框架，比如 Vue，配合组件库，比如 Vuetify，允许你编写出细节完善、视觉美观的应用。 但是即使是一些“大厂”，也没能总是产出那么高质量的应用，因为开发效率的原因。 这即是说，即使开发者有能力，往往也会由于没有时间而无法做出相当完美的应用。 结果就是，许多传统前端框架的能力几乎得不到发挥，而为拥有这些能力所作的一些设计反而在很多情况下称为了负担。
+传统的前端框架，比如 Vue，配合组件库，比如 Vuetify，允许你编写出细节完善、视觉美观的应用。 但是即使是一些“大厂”，也没能总是产出那么高质量的应用，因为开发效率的原因。 这即是说，即使开发者有能力，往往也会由于没有时间而无法做出相当完美的应用。 结果就是，许多传统前端框架的能力几乎得不到发挥，而为拥有这些能力所作的一些设计反而在很多情况下称为了负担。 但是即使是一些“大厂”，也没能总是产出那么高质量的应用，因为开发效率的原因。 这即是说，即使开发者有能力，往往也会由于没有时间而无法做出相当完美的应用。 结果就是，许多传统前端框架的能力几乎得不到发挥，而为拥有这些能力所作的一些设计反而在很多情况下称为了负担。
 
 除了传统前端框架，我们其实需要一个**首先关注开发效率**，其次是功能的完整性，再其次是运行时性能的前端框架。
 
@@ -28,7 +28,7 @@
 
 - **纯 TypeScript 构建页面**
 
-  无需像 JSX 或 Vue SFC 那样的 DSL。 渲染和逻辑使用同样的、普通的 TypeScript 语法。相关的工具链也都完全兼容。
+  无需像 JSX 或 Vue SFC 那样的 DSL。 渲染和逻辑使用同样的、普通的 TypeScript 语法。相关的工具链也都完全兼容。 渲染和逻辑使用同样的、普通的 TypeScript 语法。相关的工具链也都完全兼容。
 
 ## 效果
 

diff --git a/docs/zh/misc/contact.md b/docs/zh/misc/contact.md
@@ -13,4 +13,4 @@
 
 - **邀请链接**: [Join Refina.js](https://discord.gg/2hjDhfpgzK)
 
-> 该服务器可能并不活跃。 如果你有任何问题，欢迎通过邮箱或QQ群联系。
+> 该服务器可能并不活跃。 如果你有任何问题，欢迎通过邮箱或QQ群联系。 如果你有任何问题，欢迎通过邮箱或QQ群联系。
diff --git a/docs/zh/std-comps/introduction.md b/docs/zh/std-comps/introduction.md
@@ -14,11 +14,11 @@ Refina 的标准组件是常用的，且*有一定复杂度*的组件。 不能
 
 :::tip
 
-在本文档的示例中，我们使用 `x` 前缀来表示标准组件。 比如，`_.xButton`。
+在本文档的示例中，我们使用 `x` 前缀来表示标准组件。 比如，`_.xButton`。 比如，`_.xButton`。
 
-但是，在实际开发中，需要加上你所使用的组件库的前缀。 比如，MdUI 中的按钮是 `_.mdButton`，而在 FluentUI 中是 `_.fButton`。
+但是，在实际开发中，需要加上你所使用的组件库的前缀。 但是，在实际开发中，需要加上你所使用的组件库的前缀。 比如，MdUI 中的按钮是 `_.mdButton`，而在 FluentUI 中是 `_.fButton`。
 
-由 `@refina/basic-components` 提供的组件没有前缀。 比如 `_.button`。
+由 `@refina/basic-components` 提供的组件没有前缀。 比如 `_.button`。 比如 `_.button`。
 
 :::