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..1a54b09b3 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,24 @@ -ACSS 是一套样式语言，用于描述 AXML 的组件样式，决定 AXML 的组件的显示效果。 +ACSS 是一种样式语言，用于定义 AXML 组件的样式，从而决定组件的显示效果。 -为适应广大前端开发者，ACSS 和 CSS 规则完全一致，100% 可以用。同时为更适合开发小程序，对 CSS 进行了扩充，ACSS 支持 px，rpx，vh，vw 等单位。 +ACSS 与传统的 CSS 规则完全兼容，前端开发者可以无缝使用。为了更好地适应小程序开发，ACSS 还扩展了 CSS，支持 `px`、`rpx`、`vh`、`vw` 等单位。 -ACSS 已经帮开发者做了不同手机端的样式兼容性处理。 +ACSS 也处理了不同手机端的样式兼容性问题，简化了开发者的工作。 # rpx -rpx（responsive pixel）可以根据屏幕宽度进行自适应，规定屏幕宽为 750rpx。以 Apple iPhone6 为例，屏幕宽度为 375px，共有 750 个物理像素，则 750 rpx = 375 px = 750 物理像素，1rpx = 0.5 px = 1 物理像素。 +`rpx`（responsive pixel）是一种尺寸单位，它能根据屏幕宽度自动进行适配。在小程序中，规定屏幕宽为 750 rpx。以 iPhone6 为例，其屏幕宽度为 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 的换算关系： + +| 设备 | 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` 语句，可以在 ACSS 文件中导入外部样式表。在 `@import` 语句后面，需要指定外联样式表的相对路径，并以分号 `;` 结束该声明。 **示例代码**： @@ -35,64 +37,68 @@ rpx（responsive pixel）可以根据屏幕宽度进行自适应，规定屏幕 } ``` -导入路径支持从 node_modules 目录载入第三方模块，例如 page.acss。 +ACSS 支持从 `node_modules` 目录导入第三方模块的样式文件，例如在 `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` 属性来控制样式。 +在 ACSS 中，可以使用 `style` 和 `class` 属性来控制组件的样式。 ## style 属性 -用于接收动态样式，样式在运行时会进行解析。行内样式不支持 `!important` 优先级规则。 +`style` 属性用于设置动态样式，这些样式将在运行时被解析。注意，行内样式不支持使用 `!important` 来提升优先级。 + +**示例代码**： ```html - + ``` ## class 属性 -用于接收静态样式，属性值是样式规则中类选择器名（样式类名）的集合，样式类名不需要带上`.`，多个类名间以空格分隔。请静态样式写进 class 中，避免将静态样式写进 style 中，以免影响渲染速度。 +`class` 属性用于应用静态样式，其值是一个或多个样式类名的集合。类名不需要包含点号 `.` 前缀，并且多个类名之间应以空格分隔。建议将静态样式放在 `class` 中，以避免将静态样式写入 `style` 属性，这样可以提高渲染效率。 + +**示例代码**： ```html - + ``` - # 选择器 -同 CSS3 保持一致。 +ACSS 选择器的使用方式与 CSS3 保持一致，提供了丰富的选择器用于定位和样式化页面中的元素。 **注意**： -- `.a-`，`.am-` 开头的类选择器为系统组件占用，不可使用。 -- 不支持属性选择器。 +- 类选择器以 `.a-` 或 `.am-` 开头的是系统组件保留的，开发者应避免使用这些前缀以免发生冲突。 +- ACSS 不支持属性选择器。 # 全局样式与局部样式 -- 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 等，造成样式之间相互影响、样式污染怎么办？ +## 一个 axml 引用多个自定义组件或 template 模板、include 等，造成样式之间相互影响、样式污染怎么办？ -A：对于基础库小于 2.7.2 的小程序，可使用 class 命名空间处理样式隔离。从基础库版本 2.7.2 开始，可以在自定义组件的 JSON 文件中配置 styleIsolation，避免页面的样式影响到外部。例如： +对于基础库版本小于 2.7.2 的小程序，建议使用类命名空间来处理样式隔离，避免样式冲突。从基础库版本 2.7.2 开始，自定义组件的 JSON 文件中可以配置 `styleIsolation` 选项，这有助于防止页面样式相互影响。 ```json { @@ -100,15 +106,15 @@ A：对于基础库小于 2.7.2 的小程序，可使用 class 命名空间处 } ``` -该选项支持以下取值： +`styleIsolation` 支持的选项包括： -- apply-shared 表示 app.acss 样式以及其他（设置了 shared 的页面和其他自定义组件）的样式将影响到自定义组件，但自定义组件 ACSS 中指定的样式不会影响外部。 -- shared（默认）表示 app.acss 样式以及其他（设置了 shared 的页面和其他自定义组件）的样式将影响到页面，自定义组件 ACSS 中指定的样式也会影响到外部。 +- `apply-shared`：表示自定义组件将受到 app.acss 样式以及其他设置了 shared 的页面和自定义组件的样式影响，但自定义组件内部的样式不会影响外部。 +- `shared`（默认值）：表示自定义组件的样式既会受到 app.acss 的影响，也可能会影响外部的样式。 -## Q：设置页面高度 100% 为什么没用？ +## 设置页面高度 100% 没有效果怎么办？ -A：设置 100%，需要依赖父容器的高度，父容器没有高度那么 100% 就是 0。或者添加绝对定位也可解决，如不添加，会自适应页面的内容。 +如果设置元素高度为 100% 没有效果，可能是因为其父容器没有设置高度，导致 100% 实际上等于 0。解决方法是确保父容器有明确的高度，或者给元素设置绝对定位。 # 相关文档 -[小程序全局配置介绍](https://opendocs.alipay.com/mini/framework/app) +更多关于小程序开发的详细信息，请参考[小程序全局配置介绍](https://opendocs.alipay.com/mini/framework/app)。 \ No newline at end of file diff --git "a/mini/framework/SJS \350\257\255\346\263\225\345\217\202\350\200\203/SJS \344\273\213\347\273\215.md" "b/mini/framework/SJS \350\257\255\346\263\225\345\217\202\350\200\203/SJS \344\273\213\347\273\215.md" index 914af11a8..6c9c29007 100644 --- "a/mini/framework/SJS \350\257\255\346\263\225\345\217\202\350\200\203/SJS \344\273\213\347\273\215.md" +++ "b/mini/framework/SJS \350\257\255\346\263\225\345\217\202\350\200\203/SJS \344\273\213\347\273\215.md" @@ -1,29 +1,39 @@ -SJS（Safe/Subset JavaScript）是小程序定义的一套脚本语言，由它导出的变量/函数可以 [在 `AXML` 中使用](https://opendocs.alipay.com/mini/framework/import-sjs)。 +SJS (Safe/Subset JavaScript) 是专为小程序设计的脚本语言。作为 JavaScript 的子集，它支持 JavaScript 的部分功能，但不是全部。它的主要特点是变量和函数可以直接在小程序的 AXML 中使用，提高了开发效率和安全性。 -## 语言概述 +## 详细特性 + +### 语法规则与特性 + +SJS 遵从 JavaScript 的基本语法，但作为子集，并非支持 JavaScript 的所有特性。详细信息可参考以下链接： -**语法定义** -SJS 是 JavaScript 语言的子集，并不等同于 JavaScript。具体可参考： - [变量](https://opendocs.alipay.com/mini/framework/sjs-variable) - [数据类型](https://opendocs.alipay.com/mini/framework/datatype) - [运算符](https://opendocs.alipay.com/mini/framework/operator) - [语句](https://opendocs.alipay.com/mini/framework/sjs-statement) - [基础类库](https://opendocs.alipay.com/mini/framework/basic-library) -**模块管理** -- SJS 文件的扩展名必须为 `.sjs`，每个 .sjs 文件为一个模块，使用 export 导出变量和函数，使用 import 引入依赖的其他 SJS 模块。 -- SJS 也可引用 npm 包，但只能引用其中的 .sjs 文件。 +### 模块化特性 + +- **文件格式**：`.sjs` 文件，每个文件是一个模块。 +- **导入导出**：使用 `export` 导出变量和函数，通过 `import` 引入其他 SJS 模块。 +- **对 npm 支持**：SJS 支持引用 npm 包中的 `.sjs` 文件。 + +### 运行环境 -**运行环境** -- SJS 运行在小程序渲染层，与小程序的 JavaScript 运行环境（逻辑层）隔离，因而不能调用 JS 文件中定义的函数，也不能调用小程序提供的 API。 -- SJS 中定义的函数可用于响应基础组件的事件以避免逻辑层和渲染层的频繁通信，但有一定的限制，详见 [SJS 响应事件](https://opendocs.alipay.com/mini/01og7z)。 +SJS 在小程序的渲染层中运行，与逻辑层的 JavaScript 环境隔离。具体来说： +- SJS 不能调用 JS 文件中定义的函数或小程序提供的 API。 +- SJS 可用于处理基础组件的事件响应，减少逻辑层和渲染层间的通信。 +- 使用 SJS 有一定限制，详见：[SJS 响应事件](https://opendocs.alipay.com/mini/01og7z)。 ## 使用示例 +以下是 SJS 的基本使用示例，展示了如何定义和使用 SJS 脚本。 + +### 定义 SJS 模块 + ```javascript // pages/index/foo.sjs - const message = 'hello sjs'; const format = num => num.toFixed(2); const five = 5; @@ -34,17 +44,19 @@ export default { }; ``` +### 引入和使用其他 SJS 模块 + ```javascript // pages/index/bar.sjs - import { five } from './foo.sjs'; export const x = 3; export const y = 4 + five; ``` +### 小程序页面的 JavaScript 部分 + ```javascript // pages/index/index.js - Page({ data: { message: 'hello javascript', @@ -53,21 +65,21 @@ Page({ }); ``` +### 小程序页面的 AXML 部分 + ```html - - js message: {{message}} sjs message: {{m.message}} formatted value: {{m.format(value)}} - x: {{x}} z: {{z}} ``` -**页面渲染结果：** +### 页面渲染结果 + ```text js message: hello javascript sjs message: hello sjs diff --git "a/mini/framework/\345\260\217\347\250\213\345\272\217\345\205\250\345\261\200\351\205\215\347\275\256/app.json \345\272\224\347\224\250\351\205\215\347\275\256.md" "b/mini/framework/\345\260\217\347\250\213\345\272\217\345\205\250\345\261\200\351\205\215\347\275\256/app.json \345\272\224\347\224\250\351\205\215\347\275\256.md" index 38bbbb3be..a6a60b930 100644 --- "a/mini/framework/\345\260\217\347\250\213\345\272\217\345\205\250\345\261\200\351\205\215\347\275\256/app.json \345\272\224\347\224\250\351\205\215\347\275\256.md" +++ "b/mini/framework/\345\260\217\347\250\213\345\272\217\345\205\250\345\261\200\351\205\215\347\275\256/app.json \345\272\224\347\224\250\351\205\215\347\275\256.md" @@ -1,6 +1,6 @@ -[openvideo-应用配置](https://gw.alipayobjects.com/mdn/rms_aefee5/afts/file/A*rfoRSI3JCrMAAAAAAAAAAAAAARQnAQ) `app.json` 用于对小程序进行全局配置，设置页面文件的路径、窗口表现、多 tab、分包、插件等。 +[openvideo-应用配置](https://gw.alipayobjects.com/mdn/rms_aefee5/afts/file/A*rfoRSI3JCrMAAAAAAAAAAAAAARQnAQ) `app.json` 用于对小程序进行全局配置，可以设置页面文件的路径、窗口表现、多 tab、分包、插件等。 -以下是一个基本配置示例： +以下是一个基本配置的示例： ```json { @@ -13,53 +13,50 @@ 完整配置项如下： -| **属性** | **类型** | **必填** | **描述** | -| ------------------- | -------- | -------- | ------------------------------ | -| entryPagePath | String | 否 | 小程序默认启动首页。 | -| pages | Array | 是 | 设置页面路径。 | -| window | Object | 否 | 设置默认页面的窗口表现。 | -| tabBar | Object | 否 | 设置底部 tabbar 的表现。 | -| subPackages | Object[] | 否 | 分包结构描述。 | -| preloadRule | Object | 否 | 分包预加载规则。 | -| plugins | Object | 否 | 静态插件配置规则。 | -| useDynamicPlugins | Boolean | 否 | 动态插件配置规则。 | -| usingComponents | Array | 否 | 设置全局自定义组件声明。 | -| lazyCodeLoading | String | 否 | 是否开启代码按需执行。 | -| permission | Object | 否 | 小程序接口权限相关配置。 | -| behavior | Object | 否 | 修改小程序运行行为的相关设置。 | -| workers | Array | 否 | 设置 Worker 代码文件列表。 | +| **属性** | **类型** | **必填** | **描述** | +| ------------------- | --------- | -------- | ------------------------------ | +| entryPagePath | String | 否 | 小程序默认启动首页。 | +| pages | Array | 是 | 设置页面路径。 | +| window | Object | 否 | 设置默认页面的窗口表现。 | +| tabBar | Object | 否 | 设置底部 tabbar 的表现。 | +| subPackages | Object[] | 否 | 分包结构描述。 | +| preloadRule | Object | 否 | 分包预加载规则。 | +| plugins | Object | 否 | 静态插件配置规则。 | +| useDynamicPlugins | Boolean | 否 | 动态插件配置规则。 | +| usingComponents | Array | 否 | 设置全局自定义组件声明。 | +| lazyCodeLoading | String | 否 | 是否开启代码按需执行。 | +| permission | Object | 否 | 小程序接口权限相关配置。 | +| workers | Array | 否 | 设置 Worker 代码文件列表。 | +| behavior | Object | 否 | 修改小程序运行行为的相关设置。 | # entryPagePath -指定小程序的默认启动路径（首页）。如果不填，将默认为 pages 列表的第一项。不支持带页面路径参数。 +指定小程序的默认启动路径（首页）。如果不填，默认为 `pages` 数组的第一项。不支持带页面路径参数。 -**注意**：此特性从基础库 [2.7.20](https://opendocs.alipay.com/mini/framework/lib-upgrade-v2)，[IDE 3.1.2](https://opendocs.alipay.com/mini/ide/download) 开始支持。若强依赖此特性，建议设置最低基础库版本号为 2.7.20。否则，在低版本的基础库，会因为无法识别正确的首页而导致渲染出 **返回首页** 图标。 +**注意**：此特性从基础库 [2.7.20](https://opendocs.alipay.com/mini/framework/lib-upgrade-v2) 和 [IDE 3.1.2](https://opendocs.alipay.com/mini/ide/download) 开始支持。如果您的小程序强依赖此特性，请设置最低基础库版本号为 2.7.20。在低于此版本的基础库中，小程序可能无法识别正确的首页，导致渲染出 **返回首页** 图标。 # pages -`app.json` 中的 `pages` 为数组属性，数组中每一项都是字符串，用于指定小程序的页面。在小程序中新增或删除页面，都需要对 `pages` 数组进行修改。 +`app.json` 中的 `pages` 属性是一个数组，其中每一项都是一个字符串，用于指定小程序的页面路径。在小程序中新增或删除页面时，都需要更新 `pages` 数组。 -`pages` 数组的每一项代表对应页面的路径信息，其中，第一项代表小程序的首页。 - -页面路径不需要写任何后缀，框架会自动去加载同名的 `.json`、`.js`、`.axml`、`.acss` 文件。举例来说，如果开发目录为： - -```javascript +数组中的每一项代表对应页面的路径信息，第一项是小程序的首页。页面路径不需要写文件扩展名，框架会自动加载同名的 `.json`、`.js`、`.axml`、`.acss` 文件。例如，如果项目结构如下： +```plaintext ├── pages -│ ├──index -│ │ ├── index.json -│ │ ├── index.js -│ │ ├── index.axml -│ │ └── index.acss -│ ├──logs -│ │ ├── logs.json -│ │ ├── logs.js -│ │ └── logs.axml +│ ├── index +│ │ ├── index.json +│ │ ├── index.js +│ │ ├── index.axml +│ │ └── index.acss +│ ├── logs +│ │ ├── logs.json +│ │ ├── logs.js +│ │ └── logs.axml ├── app.json ├── app.js └── app.acss ``` -`app.json` 中应当如下配置： +则 `app.json` 应配置为： ```json { @@ -69,7 +66,7 @@ # usingComponents -在 app.json 中声明的自定义组件将会认为成全局自定义组件，在小程序各页面或自定义组件中可以直接使用无需额外声明。 +在 `app.json` 中声明的自定义组件将被视为全局自定义组件，在小程序的各个页面或自定义组件中可以直接使用，无需额外声明。 ```json { @@ -80,11 +77,11 @@ } ``` -**注意**：[IDE3.1.2](https://opendocs.alipay.com/mini/ide/download) 及以上开始支持。该功能声明的组件将要被所有页面和组件依赖，可能会影响性能，且会占用主包大小，建议开启 app.lazyCodeLoading。 +**注意**：从 [IDE 3.1.2](https://opendocs.alipay.com/mini/ide/download) 开始支持。声明为全局自定义组件的组件将被所有页面和组件依赖，可能会影响性能，并占用主包大小。建议开启 `app.lazyCodeLoading`。 # window -`window` 用于设置小程序的状态栏、导航条、标题、窗口背景色等。示例代码： +`window` 配置用于设置小程序的状态栏、导航条、标题、窗口背景色等。以下是一个示例： ```json { @@ -94,46 +91,48 @@ } ``` +各属性说明如下： + | **属性** | **类型** | **必填** | **描述** | **最低版本** | | --- | --- | --- | --- | --- | -| allowsBounceVertical | String | 否 | 是否允许向下拉拽。默认 `YES`, 支持 `YES` / `NO` | - | -| backgroundColor | HexColor | 否 | 窗口的背景色。例：白色 "#FFFFFF"。 | - | -| backgroundImageColor | HexColor | 否 | 下拉露出显示背景图的底色。例：白色 "#FFFFFF"。**仅安卓下有效，iOS 下页面背景图底色会使用 backgroundColor 的值** | - | -| backgroundImageUrl | String | 否 | 下拉露出显示背景图的链接。 | - | +| allowsBounceVertical | String | 否 | 是否允许向下拉拽。默认为 `YES`，支持 `YES` / `NO`。 | - | +| backgroundColor | HexColor | 否 | 窗口的背景色，如白色 `#FFFFFF`。 | - | +| backgroundImageColor | HexColor | 否 | 下拉露出时显示背景图的底色，如白色 `#FFFFFF`。**仅安卓下有效，iOS 下页面背景图底色会使用 backgroundColor 的值**。 | - | +| backgroundImageUrl | String | 否 | 下拉露出时显示的背景图链接。 | - | | defaultTitle | String | 否 | 页面默认标题。 | - | -| enableScrollBar | String | 否 | 仅支持 Android，是否显示 `WebView` 滚动条。默认 `YES`，支持 `YES` / `NO`。 | - | -| gestureBack | String | 否 | 仅支持 iOS，是否支持手势返回。默认 `YES`，支持 `YES` / `NO`。 | - | -| onReachBottomDistance | Number | 否 | 页面上拉触底时触发时距离页面底部的距离，单位为 `px`，详情可查看 [页面事件处理函数](https://opendocs.alipay.com/mini/framework/page-detail#%E9%A1%B5%E9%9D%A2%E4%BA%8B%E4%BB%B6%E5%A4%84%E7%90%86%E5%87%BD%E6%95%B0)。 | [1.19.0](https://opendocs.alipay.com/mini/framework/compatibility) ，目前`iOS`在`page.json`下设置无效，只能全局设置。 | -| pullRefresh | Boolean | 否 | 是否允许下拉刷新，默认 `false`。
**说明：**
1.下拉刷新生效的前提是 allowsBounceVertical 值为 YES。
2.window 全局配置后全局生效，但是如果单个页面配置了该参数，以页面的配置为准。 | - | -| responsive | Boolean | 否 | `rpx` 单位是否宽度自适应 ，默认 true，当设置为 `false` 时，2 rpx 将恒等于 1 px，不再根据屏幕宽度进行自适应，注意，此时 750 rpx 将不再等于 100% 宽度。 | [1.23.0](https://opendocs.alipay.com/mini/framework/compatibility) | -| showTitleLoading | String | 否 | 是否进入时显示导航栏的 loading。默认 `NO`，支持 `YES` / `NO`。 | - | -| transparentTitle | String | 否 | 导航栏透明设置。默认 `none`，支持 `always` 一直透明 / `auto` 滑动自适应 / `none` 不透明。 | - | -| titlePenetrate | String | 否 | 是否允许导航栏点击穿透。默认 `NO`，支持 `YES` / `NO`。 | - | +| enableScrollBar | String | 否 | 仅支持 Android，是否显示 `WebView` 滚动条。默认为 `YES`，支持 `YES` / `NO`。 | - | +| gestureBack | String | 否 | 仅支持 iOS，是否支持手势返回。默认为 `YES`，支持 `YES` / `NO`。 | - | +| onReachBottomDistance | Number | 否 | 页面上拉触底时触发的距离，单位为 `px`。详情见 [页面事件处理函数](https://opendocs.alipay.com/mini/framework/page-detail#%E9%A1%B5%E9%9D%A2%E4%BA%8B%E4%BB%B6%E5%A4%84%E7%90%86%E5%87%BD%E6%95%B0)。 | [1.19.0](https://opendocs.alipay.com/mini/framework/compatibility) ，目前 `iOS` 在 `page.json` 下设置无效，只能全局设置。 | +| pullRefresh | Boolean | 否 | 是否允许下拉刷新，默认为 `false`。
**说明：**
1. 下拉刷新生效的前提是 allowsBounceVertical 值为 `YES`。
2. 全局配置后全局生效，单个页面配置该参数时，以页面配置为准。 | - | +| responsive | Boolean | 否 | `rpx` 单位是否宽度自适应，默认为 `true`。设置为 `false` 时，2 `rpx` 将恒等于 1 `px`，不再根据屏幕宽度自适应。此时 750 `rpx` 将不等于 100% 宽度。 | [1.23.0](https://opendocs.alipay.com/mini/framework/compatibility) | +| showTitleLoading | String | 否 | 是否进入页面时显示导航栏的 loading。默认为 `NO`，支持 `YES` / `NO`。 | - | +| transparentTitle | String | 否 | 导航栏透明设置。默认为 `none`，支持 `always` 一直透明 / `auto` 滑动自适应 / `none` 不透明。 | - | +| titlePenetrate | String | 否 | 是否允许导航栏点击穿透。默认为 `NO`，支持 `YES` / `NO`。 | - | | titleImage | String | 否 | 导航栏图片地址。 | - | -| titleBarColor | HexColor | 否 | 导航栏背景色。例：白色 "#FFFFFF"。 | - | -| navigationBarFrontColor | "black"/"white" | 否 | 导航栏前景色。只支持配置黑色或者白色。 | [支付宝客户端 10.5.30](https://opendocs.alipay.com/mini/framework/compatibility) | +| titleBarColor | HexColor | 否 | 导航栏背景色，如白色 `#FFFFFF`。 | - | +| navigationBarFrontColor | "black"/"white" | 否 | 导航栏前景色，只支持黑色或白色。 | [支付宝客户端 10.5.30](https://opendocs.alipay.com/mini/framework/compatibility) | # tabBar -如果开发的小程序是一个多 tab 应用（客户端窗口的底部栏可以切换页面），那么可以通过 `tabBar` 配置项指定 tab 栏的表现，以及 tab 切换时显示的对应页面。 `tabBar` 与 `pages`、 `window` 配置同级，配置项如下： +如果小程序是一个多 tab 应用（客户端窗口底部的栏可以切换页面），可以通过 `tabBar` 配置项指定 tab 栏的表现，以及 tab 切换时显示的对应页面。`tabBar` 与 `pages`、`window` 配置项同级。以下是 `tabBar` 的配置项： | **属性** | **类型** | **必填** | **描述** | | --------------- | -------- | -------- | --------------- | -| textColor | HexColor | 否 | 文字颜色。 | -| selectedColor | HexColor | 否 | 选中文字颜色。 | -| backgroundColor | HexColor | 否 | 背景色。 | -| items | Array | 是 | 每个 tab 配置。 | +| textColor | HexColor | 否 | tab 的文字颜色。 | +| selectedColor | HexColor | 否 | 选中 tab 的文字颜色。 | +| backgroundColor | HexColor | 否 | tab 的背景色。 | +| items | Array | 是 | tab 的配置数组。 | -每个 item 配置： +每个 item 的配置项如下： | **属性** | **类型** | **必填** | **描述** | | ---------- | -------- | -------- | ---------------------------- | -| pagePath | String | 是 | 设置页面路径。 | -| name | String | 是 | 名称。 | -| icon | String | 否 | 平常图标路径（非选中状态）。 | -| activeIcon | String | 否 | 高亮图标路径（选中状态）。 | +| pagePath | String | 是 | 页面路径。 | +| name | String | 是 | tab 显示的名称。 | +| icon | String | 否 | 默认状态下的图标路径。 | +| activeIcon | String | 否 | 选中状态下的图标路径。 | -icon 图标推荐大小为 81px \* 81px，系统会对传入的非推荐尺寸的图片进行非等比拉伸或缩放。带有 `tabBar` 的 `app.json` 示例如下： +推荐的 icon 图标大小为 81px \* 81px。非推荐尺寸的图片会被系统非等比拉伸或缩放。带有 `tabBar` 的 `app.json` 配置示例如下： ```json { @@ -148,79 +147,83 @@ icon 图标推荐大小为 81px \* 81px，系统会对传入的非推荐尺寸 "items": [ { "pagePath": "pages/index/index", - "name": "首页" + "name": "首页", + "icon": "path/to/icon.png", + "activeIcon": "path/to/activeIcon.png" }, { "pagePath": "pages/logs/logs", - "name": "日志" + "name": "日志", + "icon": "path/to/icon.png", + "activeIcon": "path/to/activeIcon.png" } ] } } ``` -代码中，开发者可通过 [my.setTabBarItem](https://opendocs.alipay.com/mini/api/zu37bk) 动态设置 `tabBar` 中指定 `item` 的内容。 +开发者可以通过 [my.setTabBarItem](https://opendocs.alipay.com/mini/api/zu37bk) 动态设置 `tabBar` 中指定 `item` 的内容。 # networkTimeout -各类网络请求的超时时间，单位均为毫秒。 -| **属性** | **类型** | **必填** | **默认值** | **说明** | -| --------------- | -------- | -------- | ---------------| --------------- | -| request | number | 否 | 30000 | [my.request](https://opendocs.alipay.com/mini/api/owycmh) 的超时时间，单位：毫秒。 | -| connectSocket | number | 否 | 30000 | [my.connectSocket](https://opendocs.alipay.com/mini/api/vx19c3) 的超时时间，单位：毫秒。 | -| uploadFile | number | 否 | 60000 | [my.uploadFile](https://opendocs.alipay.com/mini/api/kmq4hc) 的超时时间，单位：毫秒。 | -| downloadFile | number | 否 | 60000 | [my.downloadFile](https://opendocs.alipay.com/mini/api/xr054r) 的超时时间，单位：毫秒。 | +设置各类网络请求的超时时间，单位为毫秒。 +| **属性** | **类型** | **必填** | **默认值** | **说明** | +| -------------- | -------- | -------- | ---------- | -------- | +| request | Number | 否 | 30000 | [my.request](https://opendocs.alipay.com/mini/api/owycmh) 的超时时间。 | +| connectSocket | Number | 否 | 30000 | [my.connectSocket](https://opendocs.alipay.com/mini/api/vx19c3) 的超时时间。 | +| uploadFile | Number | 否 | 60000 | [my.uploadFile](https://opendocs.alipay.com/mini/api/kmq4hc) 的超时时间。 | +| downloadFile | Number | 否 | 60000 | [my.downloadFile](https://opendocs.alipay.com/mini/api/xr054r) 的超时时间。 | # subPackages -启用 [分包加载](https://opendocs.alipay.com/mini/framework/subpackages) 时，声明项目分包结构。 +启用 [分包加载](https://opendocs.alipay.com/mini/framework/subpackages) 时，用于声明项目的分包结构。 # preloadRule -声明 [分包预下载](https://opendocs.alipay.com/mini/framework/subpackages#%E5%88%86%E5%8C%85%E9%A2%84%E4%B8%8B%E8%BD%BD) 的规则。 +用于声明 [分包预下载](https://opendocs.alipay.com/mini/framework/subpackages#%E5%88%86%E5%8C%85%E9%A2%84%E4%B8%8B%E8%BD%BD) 规则。 # plugins -基础库 1.22.4 及以上，支付宝客户端 10.1.85 及以上开始支持。声明小程序需要使用的 [静态插件](https://opendocs.alipay.com/mini/plugin/plugin-usage#%E9%9D%99%E6%80%81%E5%A3%B0%E6%98%8E)。 +基础库 1.22.4 及以上版本，支付宝客户端 10.1.85 及以上版本开始支持。用于声明小程序需要使用的 [静态插件](https://opendocs.alipay.com/mini/plugin/plugin-usage#%E9%9D%99%E6%80%81%E5%A3%B0%E6%98%8E)。 # useDynamicPlugins -基础库 1.22.4 及以上，支付宝客户端 10.1.85 及以上开始支持。声明小程序需要使用 [动态插件](https://opendocs.alipay.com/mini/plugin/plugin-usage#%E5%8A%A8%E6%80%81%E5%8A%A0%E8%BD%BD)。 +基础库 1.22.4 及以上版本，支付宝客户端 10.1.85 及以上版本开始支持。用于声明小程序需要使用的 [动态插件](https://opendocs.alipay.com/mini/plugin/plugin-usage#%E5%8A%A8%E6%80%81%E5%8A%A0%E8%BD%BD)。 # lazyCodeLoading -小程序应用的启动过程中，除了下载阶段以外，默认会执行所有代码（包括当前页面未使用到的所有页面、自定义组件），会对启动耗时有一定影响。基础库 2.7.0 及以上 ，支持配置以下 lazyCodeLoading 参数，仅执行当前页面所必须的页面脚本和自定义组件脚本，其他脚本则不会被执行。 +小程序应用的启动过程中，除了下载阶段以外，默认会执行所有代码（包括当前页面未使用到的所有页面和自定义组件的代码），这可能会影响启动耗时。基础库 2.7.0 及以上版本支持配置以下 `lazyCodeLoading` 参数，仅执行当前页面所必须的页面脚本和自定义组件脚本，其他脚本则不会被执行。 -```javascript +```json { "lazyCodeLoading": "requiredComponents" } ``` -**注意：** 由于开启该配置后，当前页面未使用到的代码将不会被执行，可能对某些依赖默认脚本执行先后顺序的逻辑产生影响。 +**注意**：开启该配置后，当前页面未使用到的代码将不会被执行，这可能会影响依赖默认脚本执行顺序的逻辑。 # workers -使用 [Worker](https://opendocs.alipay.com/mini/api/createworker) 处理多线程任务时，设置 Worker 代码文件列表。如： +使用 [Worker](https://opendocs.alipay.com/mini/api/createworker) 处理多线程任务时，设置 Worker 代码文件列表，例如： ```json -"workers": [ - "workers/index.js" -] +{ + "workers": ["workers/index.js"] +} ``` - + # permission -小程序接口权限相关设置。字段类型为 Object，结构为： +小程序接口权限相关设置。字段类型为 Object，结构如下： -| **属性** | **类型** | **必填** | **描述** | -| --- | --- | --- | --- | -| scope.album | PermissionObject | 否 | 相册（访问）相关权限声明，相关 API：[my.chooseImage](https://opendocs.alipay.com/mini/api/media/image/my.chooseimage)、[my.chooseVideo](https://opendocs.alipay.com/mini/api/media/video/my.choosevideo)（sourceType 包含 album）。 | -| scope.writePhotosAlbum | PermissionObject | 否 | 相册（保存）相关权限声明，相关 API：[my.saveImage](https://opendocs.alipay.com/mini/api/media/image/my.saveimage)、[my.saveImageToPhotosAlbum](https://opendocs.alipay.com/mini/api/media/image/my.saveImagetophotosalbum)、[my.saveVideoToPhotosAlbum](https://opendocs.alipay.com/mini/api/media/video/my.savevideotophotosalbum)。 | -| scope.camera | PermissionObject | 否 | 相机相关权限声明，相关 API：[my.chooseImage](https://opendocs.alipay.com/mini/api/media/image/my.chooseimage)、[my.chooseVideo](https://opendocs.alipay.com/mini/api/media/video/my.choosevideo)（sourceType 包含 camera）。 | -| scope.record | PermissionObject | 否 | 麦克风相关权限声明，相关 API：[my.getRecorderManager](https://opendocs.alipay.com/mini/api/getrecordermanager)。 | -| scope.userLocation | PermissionObject | 否 | 位置相关权限声明，相关 API：[my.getLocation](https://opendocs.alipay.com/mini/api/mkxuqd)。 | +| **属性** | **类型** | **必填** | **描述** | +| ---------------------- | ------------------ | -------- | -------- | +| scope.album | PermissionObject | 否 | 相册（访问）相关权限声明，相关 API：[my.chooseImage](https://opendocs.alipay.com/mini/api/media/image/my.chooseimage)、[my.chooseVideo](https://opendocs.alipay.com/mini/api/media/video/my.choosevideo)（`sourceType` 包含 `album`）。 | +| scope.writePhotosAlbum | PermissionObject | 否 | 相册（保存）相关权限声明，相关 API：[my.saveImage](https://opendocs.alipay.com/mini/api/media/image/my.saveimage)、[my.saveImageToPhotosAlbum](https://opendocs.alipay.com/mini/api/media/image/my.saveImagetophotosalbum)、[my.saveVideoToPhotosAlbum](https://opendocs.alipay.com/mini/api/media/video/my.savevideotophotosalbum)。 | +| scope.camera | PermissionObject | 否 | 相机相关权限声明，相关 API：[my.chooseImage](https://opendocs.alipay.com/mini/api/media/image/my.chooseimage)、[my.chooseVideo](https://opendocs.alipay.com/mini/api/media/video/my.choosevideo)（`sourceType` 包含 `camera`）。 | +| scope.record | PermissionObject | 否 | 麦克风相关权限声明，相关 API：[my.getRecorderManager](https://opendocs.alipay.com/mini/api/getrecordermanager)。 | +| scope.userLocation | PermissionObject | 否 | 位置相关权限声明，相关 API：[my.getLocation](https://opendocs.alipay.com/mini/api/mkxuqd)。 | ## PermissionObject 结构 @@ -230,23 +233,23 @@ icon 图标推荐大小为 81px \* 81px，系统会对传入的非推荐尺寸 ### 使用示例 -```JSON +```json { "permission": { "scope.album": { "desc": "读取照片用于提供美颜服务" }, - "scope.camera" : { - "desc" : "访问你的摄像头，用于扫描二维码" + "scope.camera": { + "desc": "访问你的摄像头，用于扫描二维码" }, - "scope.record" : { - "desc" : "访问你的麦克风，用于识别歌曲" + "scope.record": { + "desc": "访问你的麦克风，用于识别歌曲" }, "scope.userLocation": { - "desc": "你的位置信息将用于匹配您的服务城市" + "desc": "你的位置信息将用于匹配你的服务城市" }, - "scope.writePhotosAlbum" : { - "desc" : "用于保存美颜后的照片" + "scope.writePhotosAlbum": { + "desc": "用于保存美颜后的照片" } } } @@ -256,28 +259,28 @@ icon 图标推荐大小为 81px \* 81px，系统会对传入的非推荐尺寸 # behavior -用于改变小程序若干运行行为。字段类型为 Object，结构请见下方说明。 +用于改变小程序若干运行行为的设置。字段类型为 Object，结构如下： -| **属性** | **类型** | **必填** | **描述** | -| --- | --- | --- | --- | -| shareAppMessage | String | 否 | **可选值**：appendQuery。
使用小程序默认分享功能时（即不显式设置 [Page.onShareAppMessage]()），当设置此字段后，会使客户端生成的用于分享的 `scheme` 带上当前用户打开的页面所携带的 query 参数。
基础库 [2.7.10](https://opendocs.alipay.com/mini/framework/lib-upgrade-v2) 及以上开始支持，同时需使用 [IDE 2.7.0](https://opendocs.alipay.com/mini/ide/download) 及以上版本进行构建。 | -| decodeQuery | String | 否 | **可选值**：disable。
小程序在解析全局参数、页面参数时默认会对键/值做 `encodeURIComponent`。当设置为 `disable` 后，则不再对键/值做`encodeURIComponent`，解析规则详情可查看 [小程序全局/页面参数设置以及解析细节](https://opendocs.alipay.com/mini/03durs)，基础库 [2.7.19](https://opendocs.alipay.com/mini/framework/lib-upgrade-v2) 及以上开始支持，同时需使用 [IDE 3.0.0](https://opendocs.alipay.com/mini/ide/download) 及以上版本进行构建。 | +| **属性** | **类型** | **必填** | **描述** | +| ----------------- | -------- | -------- | -------- | +| shareAppMessage | String | 否 | 可选值：`appendQuery`。使用小程序默认分享功能时，若设置此字段，客户端生成的用于分享的 `scheme` 会带上当前用户打开的页面所携带的 query 参数。基础库 [2.7.10](https://opendocs.alipay.com/mini/framework/lib-upgrade-v2) 及以上版本支持，同时需使用 [IDE 2.7.0](https://opendocs.alipay.com/mini/ide/download) 及以上版本构建。 | +| decodeQuery | String | 否 | 可选值：`disable`。小程序解析全局参数、页面参数时，默认会对键/值进行 `encodeURIComponent`。设置为 `disable` 后，不再对键/值进行 `encodeURIComponent`。解析规则详见 [小程序全局/页面参数设置以及解析细节](https://opendocs.alipay.com/mini/03durs)，基础库 [2.7.19](https://opendocs.alipay.com/mini/framework/lib-upgrade-v2) 及以上版本支持，同时需使用 [IDE 3.0.0](https://opendocs.alipay.com/mini/ide/download) 及以上版本构建。 | ## 使用示例 -```JSON +```json { "behavior": { - "shareAppMessage": "appendQuery", // 通过此配置，可选择默认分享功能是否带上 query 参数。 - "decodeQuery": "disable" // 设置为disable后，基础库不再对全局/页面参数的键/值做 encodeURIComponent + "shareAppMessage": "appendQuery", + "decodeQuery": "disable" } } ``` # 常见问题 -## Q：A 页面（列表页）设置允许下拉刷新，B 页面（详情页）设置禁止下拉 `allowsBounceVertical: NO`, A 页面跳转 B 页面后再点左上角返回 A 页面，此时 A 页面无法下拉刷新。 +## Q：A 页面（列表页）设置允许下拉刷新，B 页面（详情页）设置禁止下拉 `allowsBounceVertical: NO`，A 页面跳转 B 页面后再点左上角返回 A 页面，此时 A 页面无法下拉刷新。 -A：A 页面设置下拉刷新的同时设置 `allowsBounceVertical: YES`,即可解决该问题。 +A：在 A 页面设置允许下拉刷新的同时，设置 `allowsBounceVertical: YES` 即可解决该问题。 -**注意**：设置下拉刷新的时候一定要设置允许下拉。 +**注意**：设置下拉刷新时，一定要设置允许下拉。 \ No newline at end of file diff --git "a/mini/framework/\346\241\206\346\236\266\346\246\202\350\277\260.md" "b/mini/framework/\346\241\206\346\236\266\346\246\202\350\277\260.md" index 8a675a90e..b3ec9f18a 100644 --- "a/mini/framework/\346\241\206\346\236\266\346\246\202\350\277\260.md" +++ "b/mini/framework/\346\241\206\346\236\266\346\246\202\350\277\260.md" @@ -1,8 +1,8 @@ # 文件结构 -小程序分为 `app` 和 `page` 两层。`app` 用来描述整个应用，`page` 用来描述各个页面，此外还有关于整个 `project` 的配置描述（可选）。 +小程序分为 `app` 和 `page` 两层结构。`app` 描述整个应用程序，而 `page` 描述各个独立页面。此外，还有描述整个 `project` 的配置（可选项）。 -`app` 由三个文件组成，必须放在项目的根目录。 +`app` 由以下三个文件组成，这些文件必须放置在项目的根目录中： | **文件** | **必填** | **作用** | | -------- | -------- | ---------------- | @@ -10,20 +10,20 @@ | app.json | 是 | 小程序全局设置 | | app.acss | 否 | 小程序全局样式表 | -`page` 由四个文件组成，分别是： +每个 `page` 由四个文件组成，具体如下： | **文件类型** | **必填** | **作用** | | ------------ | -------- | ---------- | -| js | 是 | 页面逻辑 | -| axml | 是 | 页面结构 | -| json | 是 | 页面配置 | -| acss | 否 | 页面样式表 | +| .js | 是 | 页面逻辑 | +| .axml | 是 | 页面结构 | +| .json | 是 | 页面配置 | +| .acss | 否 | 页面样式表 | -**注意：** 为了方便开发者，支付宝小程序规定这四个文件必须具有相同的路径与文件名。 `project` 特指 `mini.project.json` 文件，必须放在项目的根目录，其中的具体配置可查看 [小程序项目配置介绍](https://opendocs.alipay.com/mini/framework/project)。开发者写的所有代码最终将会打包成一份 JavaScript 脚本，在小程序启动的时候运行，在小程序结束运行时销毁。 +**注意**：为了便于开发者管理，支付宝小程序要求这四个文件必须具有相同的路径和文件名。关于 `project` 的配置，指的是 `mini.project.json` 文件，它也必须放在项目的根目录。你可以在[小程序项目配置介绍](https://opendocs.alipay.com/mini/framework/project)中查看具体的配置选项。所有开发者编写的代码最终将打包成一个 JavaScript 脚本，在小程序启动时运行，并在小程序结束时销毁。 # 逻辑结构 -小程序的核心是一个响应式的数据绑定系统，分为视图层和逻辑层。这两层始终保持同步，只要在逻辑层修改数据，视图层就会相应的更新。示例代码： +小程序的核心功能是响应式数据绑定，它由视图层和逻辑层组成。这两层保持实时同步，当逻辑层的数据变化时，视图层会自动更新以反映这些变化。下面是一个典型的示例： ```html @@ -36,11 +36,11 @@ var initialData = { name: 'taobao', }; -// 注册一个页面 +// 页面注册 Page({ data: initialData, changeName(e) { - // 改变数据 + // 更新数据 this.setData({ name: 'alipay', }); @@ -48,43 +48,59 @@ Page({ }); ``` -上面代码中，框架自动将逻辑层数据中的 `name` 与视图层的 `name` 进行了绑定，所以在页面一打开的时候会显示 `Hello taobao!`。用户点击按钮的时候，视图层会发送 `changeName` 的事件给逻辑层，逻辑层找到对应的事件处理函数。逻辑层执行了 `setData` 的操作，将 `name` 从 `taobao` 变为 `alipay` ，因为该数据和视图层已经绑定了，从而视图层会自动改变为 `Hello alipay!`。 **注意：** 由于框架并非运行在浏览器中，所以 JavaScript 在 web 中的一些能力都无法使用，如 `document`、`window` 等对象。逻辑层 js 可以用 ES2015 模块化语法组织代码： +在这段代码中，当页面初次加载时，用户会看到文本 `Hello taobao!`。当用户点击按钮时，视图层触发 `changeName` 事件，逻辑层响应并执行 `setData` 方法来更新数据。由于 `name` 已与视图层绑定，数据变更后视图层自动更新文本为 `Hello alipay!`。 + +**注意**：小程序不在传统的浏览器环境下运行，因此无法使用某些 Web 特有的 JavaScript 对象，比如 `document` 和 `window`。在逻辑层，你可以使用 ES2015 的模块化语法来组织代码，这有助于提高项目的结构化和代码的可维护性： ```javascript -import util from './util'; // 载入相对路径 -import absolute from '/absolute'; // 载入项目根路径文件 +import util from './util'; // 导入模块，使用相对路径 +import absolute from '/absolute'; // 导入模块，使用项目根路径 ``` ## 模块名的保留字 -小程序中将浏览器部分内置对象名（如 window、document）作保留字使用，以应对未来的不时之需。 保留字有：**globalThis**、**global**、**AlipayJSBridge**、**fetch**、**self**、**window**、**document**、**location**、**XMLHttpRequest**。请勿使用保留字做模块名，否则框架会出现无法正常访问模块的现象。如： +在小程序中，某些浏览器内置对象的名称（如 `window`、`document`）被作为保留字使用，以备将来可能的需求。以下是保留字列表： + +- **globalThis** +- **global** +- **AlipayJSBridge** +- **fetch** +- **self** +- **window** +- **document** +- **location** +- **XMLHttpRequest** + +请避免使用这些保留字作为模块名，否则可能导致无法正常访问模块。例如： ```javascript import { window } from './myWindow'; -console.log(window); // undefined +console.log(window); // 结果为 undefined ``` -上述代码中，因为使用了保留字做模块名，使得引入的模块变成了 undefined 。正确的方法是不使用保留字命名模块，或者在引入模块的时候使用 as 关键字给模块重新命名，例如： +正确的做法是避免使用保留字命名模块，因为在小程序的 JavaScript 环境中，这些保留字可能与系统内置对象或功能关联，使用它们作为模块名可能会导致冲突，从而使得模块无法被正确引用。如果确实需要使用这些名称，可以通过 `as` 关键字在引入时给模块重新命名，这样可以避免潜在的命名冲突。例如： ```javascript import { window as myWindow } from './myWindow'; -console.log(myWindow); +console.log(myWindow); // 正确显示模块内容 ``` +在上述代码中，通过 `as` 关键字将 `window` 模块重命名为 `myWindow`，这样就可以避免与小程序环境中的 `window` 保留字冲突，并且能够正确地引用和使用模块。 + # 第三方 NPM 模块 -小程序支持引入第三方模块，需先在小程序根目录下执行如下命令安装该模块： +小程序支持引入第三方 NPM 模块。要安装第三方模块，请在小程序根目录下执行以下命令： -```javascript -$ npm install query-string --save +```bash +npm install query-string --save ``` -引入后即可在逻辑层中直接使用： +安装完成后，你可以在逻辑层中直接使用该模块： ```javascript -import queryString from 'query-string'; // 载入第三方 npm 模块 +import queryString from 'query-string'; // 导入第三方 NPM 模块 ``` -有关 NPM 的详细介绍，可查看 [NPM 包管理](https://opendocs.alipay.com/mini/ide/npm-manage)。 +更多关于 NPM 的信息，请参阅[小程序 NPM 包管理](https://opendocs.alipay.com/mini/ide/npm-manage)文档。 -**注意：** 由于 `node_modules` 里第三方模块代码不会经过转换器，为了确保各个终端兼容，`node_modules` 下的代码需要转成 ES5 格式再引用，模块格式推荐使用 ES2015 的 import/export。同时，浏览器相关 web 能力同样无法使用。 +**注意**：由于 `node_modules` 目录下的第三方模块代码不会经过转换器处理，为确保各终端的兼容性，建议将 `node_modules` 下的代码转换为 ES5 格式后再引用。同时，推荐使用 ES2015 的 `import/export` 模块格式。另外，由于小程序不运行在浏览器环境中，浏览器相关的 Web 能力无法使用。 \ No newline at end of file diff --git "a/mini/framework/\350\207\252\345\256\232\344\271\211\347\273\204\344\273\266/\347\273\204\344\273\266\346\250\241\346\235\277\345\222\214\346\240\267\345\274\217.md" "b/mini/framework/\350\207\252\345\256\232\344\271\211\347\273\204\344\273\266/\347\273\204\344\273\266\346\250\241\346\235\277\345\222\214\346\240\267\345\274\217.md" index 2418751e5..7e506fb9e 100644 --- "a/mini/framework/\350\207\252\345\256\232\344\271\211\347\273\204\344\273\266/\347\273\204\344\273\266\346\250\241\346\235\277\345\222\214\346\240\267\345\274\217.md" +++ "b/mini/framework/\350\207\252\345\256\232\344\271\211\347\273\204\344\273\266/\347\273\204\344\273\266\346\250\241\346\235\277\345\222\214\346\240\267\345\274\217.md" @@ -1,10 +1,10 @@ -与页面类似，自定义组件可以有自己的 AXML 模板和 ACSS 样式。 +自定义组件和页面具有类似的特性，它们都可以具备独立的 AXML 模板和 ACSS 样式。 # 示例代码 ## .axml 示例代码 -AXML 是自定义组件必选部分： +自定义组件的核心部分是 AXML 模板。以下是一个 .axml 文件的示例代码： ```html @@ -13,6 +13,8 @@ AXML 是自定义组件必选部分： ## .js 示例代码 +自定义组件的行为定义在 .js 文件中。以下是相应的示例代码： + ```javascript // /components/index/index.js Component({ @@ -24,15 +26,15 @@ Component({ }); ``` -**注意**：与页面不同，用户自定义事件需要放到 methods 里面。 +**注意**：与页面不同，自定义组件中的用户定义事件需要放入 `methods` 对象中。 # 插槽 slot -通过在组件 JS 中支持 props，自定义组件可以和外部调用者交互，接受外部调用者传来的数据，同时可以调用外部调用者传来的函数，通知外部调用者组件内部的变化。但是这样还不够，自定义组件还不够灵活。除了数据的处理与通知，小程序提供的 slot 使得自定义组件的 AXML 结构可以使用外部调用者传来的 AXML 组装。外部调用者可以传递 AXML 给自定义组件，自定义组件使用其组装出最终的组件 AXML 结构。 +自定义组件通过支持 `props` 来与外部调用者交互，接收数据并通知外部调用者组件内部的变化。除了数据处理和通知外，小程序的 `slot` 机制允许自定义组件的 AXML 结构接受外部传入的 AXML，实现更灵活的组件设计。 ## 默认插槽 default slot -示例代码： +下面是关于默认插槽的示例代码： ```html @@ -44,7 +46,7 @@ Component({ ``` -调用者不传递 axml，示例如下： +当调用者不传递任何 AXML 时，组件会渲染默认插槽的内容。例如： ```javascript // /pages/index/index.json @@ -60,14 +62,14 @@ Component({ ``` -页面输出： +页面将输出以下内容： -```javascript +```plain default slot & default value other ``` -调用者传递 axml，示例如下： +如果调用者传递了 AXML，它会替代默认插槽内容。例如： ```html @@ -77,7 +79,7 @@ other ``` -页面输出： +页面将输出以下内容： ```plain header @@ -85,17 +87,13 @@ footer other ``` -可以将 slot 理解为插槽，default slot 就是默认插槽，如果调用者在组件标签 `` 之间不传递 AXML，则渲染的是默认插槽。而如果调用者在组件标签 `` 之间传递有 AXML，则使用其替代默认插槽，进而组装出最终的 AXML 以供渲染。 +默认插槽（default slot）可以理解为组件的默认内容展示区域，当调用者未提供特定 AXML 时，组件将展示这些默认内容。 ## 具名插槽 named slot -default slot 只能传递一份 AXML。 - -复杂的组件需要在不同位置渲染不同的 AXML，即需要传递多个 AXML，此时需要 named slot。 使用 named slot 后，外部调用者可以在自定义组件标签的子标签中指定要将哪一部分的 AXML 放入到自定义组件的哪个具名插槽中，而自定义组件标签的子标签中没有指定具名插槽的部分则会放入到默认插槽上。 - -如果仅传递了具名插槽，则默认插槽不会被覆盖。 +为了在组件的不同部位渲染不同的 AXML，可以使用具名插槽（named slot）。具名插槽允许在组件标签内部指定特定的 AXML 片段放入不同的插槽中。未指定具名插槽的 AXML 片段将放入默认插槽。 -示例代码： +如果仅传递了具名插槽，则默认插槽的内容不会被覆盖。以下是具名插槽的示例代码： ```html @@ -109,7 +107,7 @@ default slot 只能传递一份 AXML。 ``` -只传递具名插槽，示例如下： +只传递具名插槽时的示例： ```html @@ -119,18 +117,18 @@ default slot 只能传递一份 AXML。 ``` -页面输出： +页面将输出以下内容： -```javascript +```plain default slot & default value header body footer ``` -传递具名插槽与默认插槽，示例如下： +同时传递具名插槽和默认插槽时的示例： -```HTML +```html this is to default slot @@ -139,7 +137,7 @@ footer ``` -页面输出： +页面将输出以下内容： ```plain this is to default slot @@ -148,11 +146,13 @@ body footer ``` +具名插槽提供了在自定义组件的不同位置插入特定内容的能力，增强了组件的灵活性和可重用性。 + ## 作用域插槽 slot-scope -通过使用 named slot ，自定义组件的 AXML 要么使用自定义组件的 AXML，要么使用外部调用者（例如页面）的 AXML。 使用自定义组件的 AXML，可以访问组件内部的数据，同时通过 props 属性，可以访问外部调用者的数据。 +作用域插槽允许插槽内容访问自定义组件内的数据。在使用 named slot 时，自定义组件的 AXML 可以使用自定义组件的数据，或者通过 props 属性访问外部调用者的数据。 -示例代码： +以下是作用域插槽的示例代码： ```javascript // /components/index/index.js @@ -184,16 +184,14 @@ Page({ ``` -页面输出： +页面将输出以下内容： -```javascript +```plain component data: 1 page data: 2 ``` -自定义组件通过 slot 使用外部调用者（例如页面）的 axml 时，却只能访问外部调用者的数据。 - -示例代码： +当使用自定义组件的 AXML 时，可以访问组件内部的数据，而使用外部调用者的 AXML 时，只能访问外部调用者的数据。例如： ```html @@ -219,15 +217,13 @@ Page({ ``` -页面输出： +页面将输出以下内容： ```html page data: 2 body ``` -slot scope 使得插槽内容可以访问到组件内部的数据。 - -示例代码： +使用 slot scope，插槽内容可以访问到组件内部的数据。下面是 slot scope 的使用示例： ```javascript // /components/index/index.js @@ -265,7 +261,7 @@ Page({ ``` -页面输出： +页面将输出以下内容： ```plain component data: 1 @@ -273,15 +269,17 @@ page data: 2 body ``` -如上所示，自定义组件通过定义 slot 属性的方式暴露组件内部数据，页面使用组件时，通过 slot-scope 申明为作用域插槽，属性值定义临时变量名 props，即可访问到组件内部数据。 +在上述示例中，自定义组件通过定义 slot 属性的方式暴露了组件内部数据。页面使用组件时，通过 slot-scope 声明作用域插槽，通过 props 变量即可访问到组件内部的数据。 # ACSS -和页面一样，自定义组件也可以定义自己的 ACSS 样式。ACSS 会自动被引入使用组件的页面，不需要页面手动引入。可查看 [acss 语法](https://opendocs.alipay.com/mini/framework/acss)。 +自定义组件可以定义自己的 ACSS 样式，类似于页面样式。这些样式会自动应用到使用该组件的页面中，无需手动引入。更多关于 ACSS 的语法信息，请参阅 [ACSS 语法文档](https://opendocs.alipay.com/mini/framework/acss)。 # 自定义组件样式隔离 -默认情况下，自定义组件的样式将对外产生影响。从基础库版本 [2.7.2](https://opendocs.alipay.com/mini/framework/lib-upgrade-v2) 开始，可以在自定义组件的 JSON 文件中配置 styleIsolation，避免页面的样式影响到外部。例如： +默认情况下，自定义组件的样式对外部环境具有影响。为避免这种情况，从基础库版本 [2.7.2](https://opendocs.alipay.com/mini/framework/lib-upgrade-v2) 起，可以在组件的 JSON 文件中配置 `styleIsolation`，以实现样式隔离。样式隔离有助于确保组件的样式不会影响到外部环境。 + +以下是样式隔离的配置示例： ```json { @@ -289,68 +287,76 @@ body } ``` -该选项支持以下取值： - -- `apply-shared` 表示 app.acss 样式以及其它（设置了 `shared` 的页面和其它自定义组件）的样式将影响到自定义组件，但自定义组件 acss 中指定的样式不会影响外部。 -- `shared`（默认）表示 app.acss 样式以及其它（设置了 `shared` 的页面和其它自定义组件）的样式将影响到页面，自定义组件 acss 中指定的样式也会影响到外部。 +`styleIsolation` 支持的取值有： +- `apply-shared`：表示 `app.acss` 和其他设置了 `shared` 的页面或组件的样式将影响到自定义组件，但组件自身的 ACSS 不会影响外部。 +- `shared`（默认）：表示 `app.acss` 和其他设置了 `shared` 的页面或组件的样式将影响到页面，且组件自身的 ACSS 也会影响外部。 # 非虚拟化组件节点 -默认情况下，自定义组件是“虚拟的”，即会展示自定义组件内部的第一层节点。但有些时候，开发者希望这个节点是一个“非虚拟化的”，使用时可以在这个节点设置 `id`、`class`、`style`，就如同一个基础组件。
这个时候，可以将该自定义组件设置为“非虚拟化”。支持基础库 2.8.0、IDE 3.2.3 及以上版本。 + +在默认情况下，自定义组件被视为“虚拟的”，即只显示自定义组件内部的第一层节点。然而，某些情况下，开发者可能希望组件节点是“非虚拟化的”，即能够像基础组件一样在节点上设置 `id`、`class`、`style` 等属性。此时，可以将自定义组件配置为“非虚拟化”。该功能支持基础库 2.8.0、IDE 3.2.3 及以上版本。 ## 配置示例 -支持两种方式配置，同时 **js 的优先级高于 json**。 + +自定义组件可以通过两种方式配置为“非虚拟化”，且需要注意，`js` 文件的配置优先级高于 `json` 文件。 + ```javascript +// JavaScript 配置 Component({ - mixins: [], options: { virtualHost: false, }, data: {}, -}) +}); ``` + ```json +// JSON 配置 { "component": true, "virtualHost": false, "usingComponents": {} } ``` + +以下是在页面中使用非虚拟化自定义组件的示例： + ```html - 字体是蓝色的 + 字体是蓝色的 ``` ## :host 选择器 -当开启 `virtualHost: false` 时，自定义组件可以使用 `:host` 选择器来指定该自定义组件的默认样式。支持基础库 2.8.0、IDE 3.2.3 及以上版本。 + +当启用 `virtualHost: false` 时，可以使用 `:host` 选择器为自定义组件指定默认样式。该选择器仅在启用了非虚拟化节点的情况下生效。 + ```css :host { color: red; } ``` + +以下是使用 `:host` 选择器的示例： + ```html - 字体是红色的 + 字体是红色的 ``` # 外部样式类 -有时，组件希望接受外部传入的样式类。此时可以在 `Component` 中用 `externalClasses` 定义段定义若干个外部样式类。 - -基础库 [2.8.5](https://opendocs.alipay.com/mini/framework/lib-upgrade-v2) 开始支持外部样式类。 - -这个特性可以用于实现类似于 `view` 组件的 `hover-class` 属性：页面可以提供一个样式类，赋予 `view` 的 `hover-class`，这个样式类本身写在页面中而非 `view` 组件的实现中。 +在某些情况下，组件可能需要接受从外部传入的样式类。这可以通过在 `Component` 构造器中定义 `externalClasses` 来实现。从基础库 [2.8.5](https://opendocs.alipay.com/mini/framework/lib-upgrade-v2) 起，外部样式类得到支持。此功能有助于实现更灵活的样式自定义，例如，可以用于实现类似于 `view` 组件的 `hover-class` 属性。 ## 开启外部样式类 -由于开发者在开发跨平台小程序时可能已经设置了 `externalClasses` 字段，但其实之前会无效（在其它平台会生效）。 - -为了避免产生非预期行为，故需要开发者显式开启外部样式类功能。 -通过 Component 构造器的 `options` 配置项设置 `externalClasses: true` 开启。该功能仅在开启了[样式隔离](https://opendocs.alipay.com/mini/framework/component-template#%E8%87%AA%E5%AE%9A%E4%B9%89%E7%BB%84%E4%BB%B6%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB)的自定义组件当中生效。 +为避免非预期行为，开发者需要显式开启外部样式类功能。这是因为在开发跨平台小程序时，开发者可能已经设置了 `externalClasses` 字段，但在其它平台可能不生效。该功能仅在开启了[样式隔离](https://opendocs.alipay.com/mini/framework/component-template#%E8%87%AA%E5%AE%9A%E4%B9%89%E7%BB%84%E4%BB%B6%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB)的自定义组件中生效。 ### 示例代码 + +以下是开启外部样式类功能的示例： + ```javascript /* 组件 custom-component.js */ Component({ @@ -359,7 +365,7 @@ Component({ externalClasses: true, }, externalClasses: ['my-class'] -}) +}); ``` ```html @@ -367,7 +373,7 @@ Component({ 这段文本的颜色由组件外的 class 决定 ``` -这样，组件的使用者可以指定这个样式类对应的 class，就像使用普通属性一样。 +组件的使用者可以指定这个样式类对应的 class，就像使用普通属性一样： ```html @@ -387,10 +393,11 @@ Component({ # 使用示例 -下面通过一个示例演示 component2 的使用，具体代码可查看 [component2-demo](https://github.com/ant-mini-program/component2-demo)。 +以下是通过一个具体示例来演示 `component2` 的使用，您可以在 [component2-demo](https://github.com/ant-mini-program/component2-demo) 查看完整的代码。 ```javascript // /pages/complex/complex.js +// 页面的 JavaScript 代码 Page({ data: { count: 2, @@ -405,19 +412,15 @@ Page({ ```html - + {{item}} - + {{c.value}} count: {{count}} @@ -427,6 +430,7 @@ Page({ ```javascript // /components/complex/i1.js +// 自定义组件的 JavaScript 代码 Component({ data: { o: { @@ -438,7 +442,7 @@ Component({ console.log('i1 onInit', this.props, this.data); }, deriveDataFromProps(nextProps) { - // 组件创建时触发或更新时触发 + // 组件创建或更新时触发 console.log('i1 deriveDataFromProps', nextProps, this.props, this.data); }, didMount() { @@ -463,6 +467,7 @@ Component({ ```javascript // /components/complex/f.sjs +// SJS 脚本 export default function addOne(value) { return ++value; } @@ -470,54 +475,46 @@ export default function addOne(value) { ```html - + - + - + - + default - + ``` -本示例在 page 中 使用自定义组件 i1，并使用了小程序框架提供的如下关键技术： +本示例在页面中使用自定义组件 `i1`，展示了小程序框架提供的关键技术，包括： - 自定义组件体系 component2。 -- axml 支持灵活的使用 slot。 -- axml 中使用 sjs。 +- AXML 支持灵活使用 slot。 +- AXML 中使用 SJS。 本示例初始渲染内容如下： -![](https://gw.alipayobjects.com/zos/skylark-tools/public/files/971a55d7c409082c17ed5f1cc2f8cdcd.png#align=left&display=inline&height=370&margin=%5Bobject%20Object%5D&originHeight=370&originWidth=508&status=done&style=none&width=508) 控制台会依次打印： +![](https://gw.alipayobjects.com/zos/skylark-tools/public/files/971a55d7c409082c17ed5f1cc2f8cdcd.png#align=left&display=inline&height=370&margin=%5Bobject%20Object%5D&originHeight=370&originWidth=508&status=done&style=none&width=508) + +控制台会依次打印： ```plain i1 onInit @@ -525,9 +522,9 @@ i1 deriveDataFromProps i1 didMount ``` -**说明**：自定义组件创建阶段依次触发: `onInit`、`deriveDataFromProps`、`didMount` 生命周期。 +**说明**：自定义组件创建阶段依次触发：`onInit`、`deriveDataFromProps`、`didMount` 生命周期。 -当点击 `count+` button 的时候，页面渲染如下： +当点击 `count+` 按钮时，页面渲染如下： ![](https://gw.alipayobjects.com/zos/skylark-tools/public/files/6895abb3a0fc11724aa3882f255c9405.png#align=left&display=inline&height=500&margin=%5Bobject%20Object%5D&originHeight=500&originWidth=510&status=done&style=none&width=510) @@ -538,10 +535,10 @@ i1 deriveDataFromProps i1 didUpdate ``` -**说明：** +**说明**： -- 自定义组件更新阶段依次触发: deriveDataFromProps、didUpdate 生命周期。 -- 外部 props 变化会触发 deriveDataFromProps。 +- 自定义组件更新阶段依次触发：`deriveDataFromProps`、`didUpdate` 生命周期。 +- 外部 `props` 变化会触发 `deriveDataFromProps`。 点击 **change scope slot value** 按钮时，页面渲染如下： @@ -554,9 +551,9 @@ i1 deriveDataFromProps i1 didUpdate ``` -**说明**：自定义组件 data 变化也会触发 `deriveDataFromProps`。 +**说明**：自定义组件的 `data` 变化也会触发 `deriveDataFromProps`。 # 相关文档 - [acss 语法](https://opendocs.alipay.com/mini/framework/acss) -- [component2 Demo](https://github.com/ant-mini-program/component2-demo) +- [component2 Demo](https://github.com/ant-mini-program/component2-demo) \ No newline at end of file