diff --git "a/mini/framework/ACSS \350\257\255\346\263\225\345\217\202\350\200\203.md" "b/mini/framework/ACSS \350\257\255\346\263\225\345\217\202\350\200\203.md" index 6f09cc93c..461f723d3 100644 --- "a/mini/framework/ACSS \350\257\255\346\263\225\345\217\202\350\200\203.md" +++ "b/mini/framework/ACSS \350\257\255\346\263\225\345\217\202\350\200\203.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 - + ``` ## class 属性 -用于接收静态样式，属性值是样式规则中类选择器名（样式类名）的集合，样式类名不需要带上`.`，多个类名间以空格分隔。请静态样式写进 class 中，避免将静态样式写进 style 中，以免影响渲染速度。 +用于接收静态样式，属性值是样式规则中类选择器名（样式类名）的集合，样式类名不需要带上 `.`，多个类名间以空格分隔。请将静态样式写进 class 中，避免将静态样式写进 style 中，以免影响渲染速度。 ```html @@ -69,17 +68,17 @@ rpx（responsive pixel）可以根据屏幕宽度进行自适应，规定屏幕 **注意**： -- `.a-`，`.am-` 开头的类选择器为系统组件占用，不可使用。 +- `.a-`、`.am-` 开头的类选择器为系统组件占用，不可使用。 - 不支持属性选择器。 # 全局样式与局部样式 -- app.acss 中的样式为全局样式，作用于每一个页面。 -- 页面文件夹内的 .acss 文件中定义的样式为局部样式，只作用在对应的页面，并会覆盖 app.acss 中相同的选择器。 +- `app.acss` 中的样式为全局样式，作用于每一个页面。 +- 页面文件夹内的 `.acss` 文件中定义的样式为局部样式，只作用在对应的页面，并会覆盖 `app.acss` 中相同的选择器。 # 本地资源引用 -ACSS 文件里的本地资源引用请使用绝对路径的方式，不支持相对路径引用，例如下方示例。 +ACSS 文件里的本地资源引用请使用绝对路径的方式，不支持相对路径引用。例如下方示例。 ```css /* 支持 */ @@ -87,12 +86,11 @@ 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`。另外，也可以通过添加绝对定位解决问题。如果不添加绝对定位，页面的高度将会自适应内容的大小。 # 相关文档 diff --git "a/mini/framework/AXML/AXML\344\273\213\347\273\215.md" "b/mini/framework/AXML/AXML\344\273\213\347\273\215.md" index 160984db0..3842f327d 100644 --- "a/mini/framework/AXML/AXML\344\273\213\347\273\215.md" +++ "b/mini/framework/AXML/AXML\344\273\213\347\273\215.md" @@ -1,6 +1,6 @@ [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)。 # 数据绑定 @@ -8,7 +8,7 @@ AXML 是小程序框架设计的一套标签语言，结合基础组件、事件 ```html - {{ message }} +{{ message }} ``` ## .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 - {{ item }} +{{item}} ``` ## .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', }, }, diff --git "a/mini/framework/AXML/\345\210\227\350\241\250\346\270\262\346\237\223.md" "b/mini/framework/AXML/\345\210\227\350\241\250\346\270\262\346\237\223.md" index cef398206..db0f29629 100644 --- "a/mini/framework/AXML/\345\210\227\350\241\250\346\270\262\346\237\223.md" +++ "b/mini/framework/AXML/\345\210\227\350\241\250\346\270\262\346\237\223.md" @@ -1,6 +1,6 @@ # a:for -在组件上使用 `a:for` 属性可以绑定一个数组，即可使用数组中各项的数据重复渲染该组件。数组当前项的下标变量名默认为 `index`，数组当前项的变量名默认为 `item`。 +在组件上使用 `a:for` 属性可以绑定一个数组，以此使用数组中各项的数据来重复渲染该组件。数组当前项的下标变量名默认为 `index`，数组当前项的变量名默认为 `item`。 ```html {{index}}: {{item.message}} @@ -21,7 +21,7 @@ Page({ }); ``` -使用 `a:for-item` 可以指定数组当前元素的变量名。使用 `a:for-index` 可以指定数组当前下标的变量名。 +通过 `a:for-item` 可以自定义数组当前元素的变量名，`a:for-index` 允许指定数组当前下标的变量名。 ```html @@ -29,7 +29,7 @@ Page({ ``` -`a:for` 支持嵌套。 以下是九九乘法表的嵌套示例代码。 +`a:for` 属性支持嵌套使用。下列代码示例展示了一个九九乘法表的嵌套 `a:for` 应用。 ```html @@ -38,7 +38,6 @@ Page({ ``` - # block a:for 与 `block a:if` 类似，可以将 `a:for` 用在 `` 标签上，以渲染一个包含多节点的结构块。 @@ -49,18 +48,17 @@ Page({ {{item}} ``` +# `a:key` -# a:key - -如果列表项位置会动态改变或者有新项目添加到列表中，同时希望列表项保持特征和状态（例如 `` 中的输入内容，`` 的选中状态），需要使用 `a:key` 来指定列表项的唯一标识。 `a:key` 的值以两种形式来提供： +如果列表项位置会动态改变或者有新项目添加到列表中，同时希望列表项保持特征和状态（例如 `` 中的输入内容，`` 的选中状态），需要使用 `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 diff --git "a/mini/framework/AXML/\345\274\225\345\205\245 SJS.md" "b/mini/framework/AXML/\345\274\225\345\205\245 SJS.md" index 844c6a989..02a690a7a 100644 --- "a/mini/framework/AXML/\345\274\225\345\205\245 SJS.md" +++ "b/mini/framework/AXML/\345\274\225\345\205\245 SJS.md" @@ -1,4 +1,5 @@ -`import-sjs` 标签用于将 SJS 脚本文件定义的符号引入当前 AXML 文件，并在表达式中使用。更多关于 SJS 的介绍可查看 [SJS 介绍](https://opendocs.alipay.com/mini/framework/sjs)。 +`` 标签用于将 SJS 脚本文件定义的符号引入当前 AXML 文件，并在表达式中使用。了解更多关于 SJS 的信息，请访问 [SJS 介绍](https://opendocs.alipay.com/mini/framework/sjs)。 + ```javascript // util.sjs export default { @@ -6,6 +7,7 @@ export default { getMsg: x => x, }; ``` + ```html @@ -13,32 +15,34 @@ export default { 使用函数 {{util.getMsg(msg)}} ``` -通过 `` 标签，只能使用 SJS 通过 `export` 语法导出的符号。并遵循如下规则。 -## 默认导出 -通过 `export default` 导出的 **默认导出** 符号，必须通过 `` 来引入。
`import-sjs` 功能标签的 `name` 属性必须是一个合法的标识符 `/^[A-Za-z_][A-Za-z0-9_]*$/`。 +通过 `` 标签，只能使用 SJS 通过 `export` 语法导出的符号。并遵循以下规则： +## 默认导出 +通过 `export default` 导出的**默认导出**符号，必须通过 `` 来引入。`import-sjs` 功能标签的 `name` 属性必须是一个合法（满足 `/^[A-Za-z_][A-Za-z0-9_]*$/` 正则规则）的标识符。 ## 具名导出 -通过 `export const a` 导出的 **具名** 符号，必须通过 `` 来引入。
`import-sjs` 功能标签的 `name` 属性满足以下规则 +通过 `export const 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 - + {{ c() }}:{{a}}:{{ b }} {{ 2 }}:{{ 1 }}:{{ undefined }} ``` -需要注意： +需要注意的是： -- 如果 `name` 出现 **默认导出** 的同名，会在编译期直接覆盖（即不论 `` 标签的顺序，被覆盖的 _默认导出_ 符号在整个 AXML 中均不可访问）。 -- 如果 `name` 出现 **具名导出** 的同名，会直接抛出编译异常。 +- 如果 `name` 出现**默认导出**的同名，会在编译期直接覆盖（即`` 标签的顺序无关紧要，被覆盖的*默认导出*符号在整个 AXML 中均不可访问）。 +- 如果 `name` 出现**具名导出**的同名，会直接抛出编译异常。 diff --git "a/mini/framework/AXML/\345\274\225\347\224\250.md" "b/mini/framework/AXML/\345\274\225\347\224\250.md" index d537d2994..730300581 100644 --- "a/mini/framework/AXML/\345\274\225\347\224\250.md" +++ "b/mini/framework/AXML/\345\274\225\347\224\250.md" @@ -1,5 +1,4 @@ AXML 提供两种文件引用方式 `import` 和 `include`。 - # import `import` 可以加载已经定义好的 `template`。 @@ -13,20 +12,21 @@ AXML 提供两种文件引用方式 `import` 和 `include`。 ``` -在 index.axml 中引用 item.axml，就可以使用 `item` 模板。 +在 index.axml 中引用 item.axml 后，可以使用 `item` 模板。 ```html -