feat: framework 文档修改

mini/framework/ACSS 语法参考.md

@@ -1,22 +1,22 @@
-ACSS 是一套样式语言，用于描述 AXML 的组件样式，决定 AXML 的组件的显示效果。
+ACSS 是一套样式语言，用于描述 AXML 的组件样式，决定 AXML 组件的显示效果。
 
-为适应广大前端开发者，ACSS 和 CSS 规则完全一致，100% 可以用。同时为更适合开发小程序，对 CSS 进行了扩充，ACSS 支持 px，rpx，vh，vw 等单位。
+为适应广大前端开发者，ACSS 和 CSS 规则完全一致，100% 可以用。同时，为更适合开发小程序，对 CSS 进行了扩充，ACSS 支持 `px`，`rpx`，`vh`，`vw` 等单位。
 
 ACSS 已经帮开发者做了不同手机端的样式兼容性处理。
 
 # rpx
 
-rpx（responsive pixel）可以根据屏幕宽度进行自适应，规定屏幕宽为 750rpx。以 Apple iPhone6 为例，屏幕宽度为 375px，共有 750 个物理像素，则 750 rpx = 375 px = 750 物理像素，1rpx = 0.5 px = 1 物理像素。
+rpx（responsive pixel）是根据屏幕宽度自适应的像素单位，规定屏幕宽为 750rpx。以 Apple iPhone6 为例，屏幕宽度为 375px，共有 750 个物理像素，则 750 rpx = 375 px = 750 物理像素，1 rpx = 0.5 px = 1 物理像素。
 
-| **设备** | **rpx 换算 px（屏幕宽度 / 750）** | **px 换算 rpx（750 / 屏幕宽度）** |
-| --- | --- | --- |
-| iPhone5 | 1rpx = 0.42px | 1px = 2.34rpx |
-| iPhone6 | 1rpx = 0.5px | 1px = 2rpx |
-| iPhone6 Plus | 1rpx = 0.552px | 1px = 1.81rpx |
+| 设备         | rpx 换算 px（屏幕宽度 / 750） | px 换算 rpx（750 / 屏幕宽度） |
+| ------------ | ----------------------------- | ----------------------------- |
+| iPhone5      | 1 rpx = 0.42 px               | 1 px = 2.34 rpx               |
+| iPhone6      | 1 rpx = 0.5 px                | 1 px = 2 rpx                  |
+| iPhone6 Plus | 1 rpx = 0.552 px              | 1 px = 1.81 rpx               |
 
 # 样式导入
 
-使用 `@import` 语句可以导入外联样式表，`@import` 后需要加上外联样式表相对路径，用`;` 表示结束。
+使用 `@import` 语句可以导入外联样式表，`@import` 后面需要加上外联样式表的相对路径，用分号（`;`）表示结束。
 
 **示例代码**：
 
@@ -35,14 +35,13 @@ rpx（responsive pixel）可以根据屏幕宽度进行自适应，规定屏幕
 }
 ```
 
-导入路径支持从 node_modules 目录载入第三方模块，例如 page.acss。
+导入路径支持从 node_modules 目录载入第三方模块，例如 third-party/page.acss。
 
 ```css
-@import './button.acss'; /*相对路径*/
-@import '/button.acss'; /*项目绝对路径*/
-@import 'third-party/page.acss'; /*第三方 npm 包路径*/
+@import './button.acss'; /* 相对路径 */
+@import '/button.acss'; /* 项目绝对路径 */
+@import 'third-party/page.acss'; /* 第三方 npm 包路径 */
 ```
-
 # 内联样式
 
 组件上支持使用 `style`、`class` 属性来控制样式。
@@ -52,12 +51,12 @@ rpx（responsive pixel）可以根据屏幕宽度进行自适应，规定屏幕
 用于接收动态样式，样式在运行时会进行解析。行内样式不支持 `!important` 优先级规则。
 
 ```html
-<view style="color:{{color}};" />
+<view style="color: {{color}};" />
 ```
 
 ## class 属性
 
-用于接收静态样式，属性值是样式规则中类选择器名（样式类名）的集合，样式类名不需要带上`.`，多个类名间以空格分隔。请静态样式写进 class 中，避免将静态样式写进 style 中，以免影响渲染速度。
+用于接收静态样式，属性值是样式规则中类选择器名（样式类名）的集合，样式类名不需要带上 `.`，多个类名间以空格分隔。请将静态样式写进 class 中，避免将静态样式写进 style 中，以免影响渲染速度。
 
 ```html
 <view class="my-awesome-view" />
@@ -69,30 +68,29 @@ rpx（responsive pixel）可以根据屏幕宽度进行自适应，规定屏幕
 
 **注意**：
 
-- `.a-`，`.am-` 开头的类选择器为系统组件占用，不可使用。
+- `.a-`、`.am-` 开头的类选择器为系统组件占用，不可使用。
 - 不支持属性选择器。
 
 # 全局样式与局部样式
 
-- app.acss 中的样式为全局样式，作用于每一个页面。
-- 页面文件夹内的 .acss 文件中定义的样式为局部样式，只作用在对应的页面，并会覆盖 app.acss 中相同的选择器。
+- `app.acss` 中的样式为全局样式，作用于每一个页面。
+- 页面文件夹内的 `.acss` 文件中定义的样式为局部样式，只作用在对应的页面，并会覆盖 `app.acss` 中相同的选择器。
 
 # 本地资源引用
 
-ACSS 文件里的本地资源引用请使用绝对路径的方式，不支持相对路径引用，例如下方示例。
+ACSS 文件里的本地资源引用请使用绝对路径的方式，不支持相对路径引用。例如下方示例。
 
 ```css
 /* 支持 */
 background-image: url('/images/ant.png');
 /* 不支持 */
 background-image: url('./images/ant.png');
 ```
-
 # 常见问题
 
 ## Q：一个 axml 引用多个自定义组件或 template 模板、include 等，造成样式之间相互影响、样式污染怎么办？
 
-A：对于基础库小于 2.7.2 的小程序，可使用 class 命名空间处理样式隔离。从基础库版本 2.7.2 开始，可以在自定义组件的 JSON 文件中配置 styleIsolation，避免页面的样式影响到外部。例如：
+A：对于基础库版本小于 `2.7.2` 的小程序，可使用 class 命名空间处理样式隔离。从基础库版本 `2.7.2` 开始，可以在自定义组件的 `JSON` 文件中配置 `styleIsolation`，避免页面的样式影响到外部。例如：
 
 ```json
 {
@@ -102,12 +100,12 @@ A：对于基础库小于 2.7.2 的小程序，可使用 class 命名空间处
 
 该选项支持以下取值：
 
-- apply-shared 表示 app.acss 样式以及其他（设置了 shared 的页面和其他自定义组件）的样式将影响到自定义组件，但自定义组件 ACSS 中指定的样式不会影响外部。
-- shared（默认）表示 app.acss 样式以及其他（设置了 shared 的页面和其他自定义组件）的样式将影响到页面，自定义组件 ACSS 中指定的样式也会影响到外部。
+- `apply-shared` 表示 `app.acss` 样式以及其他设置了 `shared` 的页面和其他自定义组件的样式将影响到自定义组件，而自定义组件 `ACSS` 中定义的样式不会影响外部。
+- `shared`（默认）表示 `app.acss` 样式以及其他设置了 `shared` 的页面和其他自定义组件的样式将影响到页面，而自定义组件 `ACSS` 中指定的样式也会影响到外部。
 
-## Q：设置页面高度 100% 为什么没用？
+## Q：设置页面高度 `100%` 为什么没用？
 
-A：设置 100%，需要依赖父容器的高度，父容器没有高度那么 100% 就是 0。或者添加绝对定位也可解决，如不添加，会自适应页面的内容。
+A：设置为 `100%` 时，需要依赖父容器的高度。如果父容器没有高度，那么 `100%` 实际上就是 `0`。另外，也可以通过添加绝对定位解决问题。如果不添加绝对定位，页面的高度将会自适应内容的大小。
 
 # 相关文档
 

mini/framework/AXML/AXML介绍.md

@@ -1,14 +1,14 @@
 [openvideo-axml 介绍](https://gw.alipayobjects.com/v/portal_cjapev/afts/video/A*jrdoTagCX1sAAAAAAAAAAAAAAQAAAQ)
 
-AXML 是小程序框架设计的一套标签语言，结合基础组件、事件系统，可以构建出小程序页面的结构。AXML 语法可分为五个部分：[数据绑定](https://opendocs.alipay.com/mini/framework/data-binding)、[条件渲染](https://opendocs.alipay.com/mini/framework/conditional-render)、[列表渲染](https://opendocs.alipay.com/mini/framework/list-render)、[模板](https://opendocs.alipay.com/mini/framework/axml-template)、[引用](https://opendocs.alipay.com/mini/framework/import)。
+AXML 是小程序框架设计的一套标签语言，结合基础组件和事件系统，可以构建出小程序页面的结构。AXML 语法可分为五个部分：[数据绑定](https://opendocs.alipay.com/mini/framework/data-binding)、[条件渲染](https://opendocs.alipay.com/mini/framework/conditional-render)、[列表渲染](https://opendocs.alipay.com/mini/framework/list-render)、[模板](https://opendocs.alipay.com/mini/framework/axml-template)、[引用](https://opendocs.alipay.com/mini/framework/import)。
 
 # 数据绑定
 
 ## AXML 示例代码
 
 ```html
 <!-- axml -->
-<view> {{ message }} </view>
+<view>{{ message }}</view>
 ```
 
 ## .js 示例代码
@@ -17,22 +17,21 @@ AXML 是小程序框架设计的一套标签语言，结合基础组件、事件
 // page.js
 Page({
   data: {
-    message: 'Hello World',
-  },
+    message: 'Hello World'
+  }
 });
 ```
 
 ## 效果示例
 
 ![](https://cdn.nlark.com/yuque/0/2022/png/179989/1660805803075-4df8eb16-58e7-463c-9c2f-ae6e862cc9e6.png)
-
 # 列表渲染
 
 ## AXML 示例代码
 
 ```html
 <!-- axml -->
-<view a:for="{{list}}"> {{ item }} </view>
+<view a:for="{{list}}">{{item}}</view>
 ```
 
 ## .js 示例代码
@@ -41,15 +40,14 @@ Page({
 // page.js
 Page({
   data: {
-    list: [1, 2, 3, 4, 5],
-  },
+    list: [1, 2, 3, 4, 5]
+  }
 });
 ```
 
 ## 效果示例
 
 ![](https://cdn.nlark.com/yuque/0/2022/png/179989/1660805811400-c7379ce5-1026-43eb-8aa2-10f39922a087.png)
-
 # 条件渲染
 
 ## AXML 示例代码
@@ -75,7 +73,6 @@ Page({
 ## 效果示例
 
 ![](https://cdn.nlark.com/yuque/0/2022/png/179989/1660805818878-f36efae3-5fed-4362-9cee-1f8da95569c2.png)
-
 # 模板
 
 ## AXML 示例代码
@@ -104,7 +101,7 @@ Page({
       deadline: '2022-09-15',
     },
     taskB: {
-      taskDescription: '读完三国演义',
+      taskDescription: '读完《三国演义》',
       deadline: '2022-10-15',
     },
   },

mini/framework/AXML/列表渲染.md

@@ -1,6 +1,6 @@
 # a:for
 
-在组件上使用 `a:for` 属性可以绑定一个数组，即可使用数组中各项的数据重复渲染该组件。数组当前项的下标变量名默认为 `index`，数组当前项的变量名默认为 `item`。
+在组件上使用 `a:for` 属性可以绑定一个数组，以此使用数组中各项的数据来重复渲染该组件。数组当前项的下标变量名默认为 `index`，数组当前项的变量名默认为 `item`。
 
 ```html
 <view a:for="{{array}}"> {{index}}: {{item.message}} </view>
@@ -21,15 +21,15 @@ Page({
 });
 ```
 
-使用 `a:for-item` 可以指定数组当前元素的变量名。使用 `a:for-index` 可以指定数组当前下标的变量名。
+通过 `a:for-item` 可以自定义数组当前元素的变量名，`a:for-index` 允许指定数组当前下标的变量名。
 
 ```html
 <view a:for="{{array}}" a:for-index="idx" a:for-item="itemName">
   {{idx}}: {{itemName.message}}
 </view>
 ```
 
-`a:for` 支持嵌套。 以下是九九乘法表的嵌套示例代码。
+`a:for` 属性支持嵌套使用。下列代码示例展示了一个九九乘法表的嵌套 `a:for` 应用。
 
 ```html
 <view a:for="{{[1, 2, 3, 4, 5, 6, 7, 8, 9]}}" a:for-item="i">
@@ -38,7 +38,6 @@ Page({
   </view>
 </view>
 ```
-
 # block a:for
 
 与 `block a:if` 类似，可以将 `a:for` 用在 `<block/>` 标签上，以渲染一个包含多节点的结构块。
@@ -49,18 +48,17 @@ Page({
   <view> {{item}} </view>
 </block>
 ```
+# `a:key`
 
-# a:key
-
-如果列表项位置会动态改变或者有新项目添加到列表中，同时希望列表项保持特征和状态（例如 `<input/>` 中的输入内容，`<switch/>` 的选中状态），需要使用 `a:key` 来指定列表项的唯一标识。 `a:key` 的值以两种形式来提供：
+如果列表项位置会动态改变或者有新项目添加到列表中，同时希望列表项保持特征和状态（例如 `<input/>` 中的输入内容，`<switch/>` 的选中状态），需要使用 `a:key` 来指定列表项的唯一标识。`a:key` 的值以两种形式来提供：
 
-- 字符串：代表列表项某个属性，属性值需要是列表中唯一的字符串或数字，例如 ID，并且不能动态改变。
-- 保留关键字 `*this`，代表列表项本身，并且它是唯一的字符串或者数字，例如当数据改变触发重新渲染时，会校正带有 `key` 的组件，框架会确保数据重新被排序，而不是重新创建，这可以使组件保持自身状态，提高列表渲染效率。
+- 字符串：代表列表项某个属性，该属性值需要是列表中唯一的字符串或数字，例如 ID，并且不能动态改变。
+- 保留关键字 `*this`，代表列表项本身，并且它是唯一的字符串或者数字。例如，当数据改变触发重新渲染时，带有 `key` 的组件会被框架校正，确保数据重新排序而不是重新创建。这可以让组件保持自身状态，提高列表渲染效率。
 
 **注意**：
 
-- 如不提供 `a:key`，则会提示 warning。
-- 如果明确知道列表是静态，或者不用关注其顺序，则可以忽略。
+- 如果不提供 `a:key`，则会出现警告提示。
+- 如果明确知道列表是静态的，或者不需要关注其顺序，可以省略 `a:key`。
 
 下面是示例代码：
 
@@ -77,24 +75,23 @@ Page({
 ```javascript
 Page({
   data: {
-    list: ['1', '2', '3', '4'],
+    list: ['1', '2', '3', '4']
   },
   bringToFront(e) {
     const { value } = e.target.dataset;
-    const list = this.data.list.concat();
+    const list = [...this.data.list];
     const index = list.indexOf(value);
     if (index !== -1) {
       list.splice(index, 1);
       list.unshift(value);
       this.setData({ list });
     }
-  },
+  }
 });
 ```
-
 # key
 
-`key` 是比 `a:key` 更通用的写法，里面可以填充任意表达式和字符串。 **注意：** `key` 不能设置在 block 上。下面是示例代码：
+`key` 是比 `a:key` 更通用的写法，里面可以填充任意表达式和字符串。**注意**：`key` 不能设置在 `block` 上。下面是示例代码：
 
 ```html
 <view class="container">

mini/framework/AXML/引入 SJS.md

@@ -1,44 +1,48 @@
-`import-sjs` 标签用于将 SJS 脚本文件定义的符号引入当前 AXML 文件，并在表达式中使用。更多关于 SJS 的介绍可查看 [SJS 介绍](https://opendocs.alipay.com/mini/framework/sjs)。
+`<import-sjs>` 标签用于将 SJS 脚本文件定义的符号引入当前 AXML 文件，并在表达式中使用。了解更多关于 SJS 的信息，请访问 [SJS 介绍](https://opendocs.alipay.com/mini/framework/sjs)。
+
 ```javascript
 // util.sjs
 export default {
   message: 'hello alipay',
   getMsg: x => x,
 };
 ```
+
 ```html
 <!-- page.axml -->
 <import-sjs name="util" from="./util.sjs"/>
 <view> 使用变量 {{util.message}}</view>
 <view> 使用函数 {{util.getMsg(msg)}}</view>
 ```
 
-通过 `<import-sjs />` 标签，只能使用 SJS 通过 `export` 语法导出的符号。并遵循如下规则。
-## 默认导出
-通过 `export default` 导出的 **默认导出** 符号，必须通过 `<import-sjs name="module"/>` 来引入。<br />`import-sjs` 功能标签的 `name` 属性必须是一个合法的标识符 `/^[A-Za-z_][A-Za-z0-9_]*$/`。
+通过 `<import-sjs />` 标签，只能使用 SJS 通过 `export` 语法导出的符号。并遵循以下规则：
 
+## 默认导出
+通过 `export default` 导出的**默认导出**符号，必须通过 `<import-sjs name="module"/>` 来引入。`import-sjs` 功能标签的 `name` 属性必须是一个合法（满足 `/^[A-Za-z_][A-Za-z0-9_]*$/` 正则规则）的标识符。
 
 ## 具名导出
-通过 `export const a` 导出的 **具名** 符号，必须通过 `<import-sjs name="{ a }"/>` 来引入。<br />`import-sjs` 功能标签的 `name` 属性满足以下规则
+通过 `export const a` 导出的**具名**符号，必须通过 `<import-sjs name="{ a }"/>` 来引入。`import-sjs` 功能标签的 `name` 属性满足以下规则：
 
-- 是一个 `Object` 字面量表达式
-- `Object` 的 `key` 和 `value` 均是一个 **标识符**
+- 是一个 `Object` 字面量表达式。
+- `Object` 的 `key` 和 `value` 均是一个**标识符**。
 
 以下是一个复杂示例：
+
 ```javascript
 // helper.sjs
 export const a = 1;
 export function b() { return 2 }
 ```
+
 ```html
 <!-- page.axml -->
-<import-sjs from="./helper.sjs"  name="{ a, b: c }"/>
+<import-sjs from="./helper.sjs" name="{ a, b: c }"/>
 <view>{{ c() }}:{{a}}:{{ b }}</view>
 <!-- 等价于 -->
 <view>{{ 2 }}:{{ 1 }}:{{ undefined }}</view>
 ```
 
-需要注意：
+需要注意的是：
 
-- 如果 `name` 出现 **默认导出** 的同名，会在编译期直接覆盖（即不论 `<import-sjs>` 标签的顺序，被覆盖的 _默认导出_ 符号在整个 AXML 中均不可访问）。
-- 如果 `name` 出现 **具名导出** 的同名，会直接抛出编译异常。
+- 如果 `name` 出现**默认导出**的同名，会在编译期直接覆盖（即`<import-sjs>` 标签的顺序无关紧要，被覆盖的*默认导出*符号在整个 AXML 中均不可访问）。
+- 如果 `name` 出现**具名导出**的同名，会直接抛出编译异常。