Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
提交 3035f58a 编写于 作者: L luoying_ace 提交者： Gitee
浏览文件
操作

Merge branch 'OpenHarmony-3.1-Release' of gitee.com:openharmony/docs into ly810

上级 d0e30231 56b80c95
隐藏空白更改
内联 并排
Showing with 5294 addition and 406 deletion
en/application-dev/database/database-relational-guidelines.md
浏览文件 @ 3035f58a
......@@ -2,7 +2,7 @@
## When to Use
A relational database (RDB) store allows you to operate data with or without native SQL statements based on the SQLite database.
A relational database (RDB) store allows you to operate local data with or without native SQL statements based on SQLite.
## Available APIs
......@@ -130,8 +130,8 @@ A result set can be regarded as a row of data in the queried results. It allows
| ResultSet | goToPreviousRow(): boolean | Moves the result set to the previous row.|
| ResultSet | getColumnIndex(columnName: string): number | Obtains the column index based on the specified column name.|
| ResultSet | getColumnName(columnIndex: number): string | Obtains the column name based on the specified column index.|
| ResultSet | goToFirstRow(): boolean | Checks whether the result set is located in the first row.|
| ResultSet | goToLastRow(): boolean | Checks whether the result set is located in the last row.|
| ResultSet | goToFirstRow(): boolean | Moves to the first row of the result set.|
| ResultSet | goToLastRow(): boolean | Moves to the last row of the result set.|
| ResultSet | getString(columnIndex: number): string | Obtains the value in the specified column of the current row, in a string.|
| ResultSet | getBlob(columnIndex: number): Uint8Array | Obtains the values in the specified column of the current row, in a byte array.|
| ResultSet | getDouble(columnIndex: number): number | Obtains the values in the specified column of the current row, in double.|
......@@ -307,8 +307,4 @@ You can obtain the distributed table name for a remote device based on the local
let tableName = rdbStore.obtainDistributedTableName(deviceId, "test");
let resultSet = rdbStore.querySql("SELECT * FROM " + tableName)
```
## Samples
The following samples are provided for you to better understand the RDB development:
- [`Rdb`: eTS RDB (API8)](https://gitee.com/openharmony/app_samples/tree/master/data/Rdb)
- [`DistributedRdb`: eTS Distributed Relational Database (API8)](https://gitee.com/openharmony/app_samples/tree/master/data/DistributedRdb)
- [Relational Database](https://gitee.com/openharmony/codelabs/tree/master/Data/JSRelationshipData)
zh-cn/application-dev/reference/apis/js-apis-bundle-AbilityInfo.md
浏览文件 @ 3035f58a
......@@ -4,39 +4,39 @@
> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> API9 当前为Canary版本，仅供试用，不保证接口可稳定调用。
Ability信息
Ability信息，未做特殊说明的属性，均通过GET_BUNDLE_DEFAULT获取
## AbilityInfo
**系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework
| 名称 | 类型 | 可读 | 可写 | 说明 |
| --------------------- | -------------------------------------------------------- | ---- | ---- | ----------------------------------------- |
| bundleName | string | 是 | 否 | 应用包名 |
| name | string | 是 | 否 | Ability名称 |
| label | string | 是 | 否 | Ability对用户显示的名称 |
| description | string | 是 | 否 | Ability的描述 |
| icon | string | 是 | 否 | Ability的图标资源文件索引 |
| descriptionId | number | 是 | 否 | Ability的描述id |
| iconId | number | 是 | 否 | Ability的图标id |
| moduleName | string | 是 | 否 | Ability所属的HAP包的名称 |
| process | string | 是 | 否 | Ability的进程，如果不设置，默认为包的名称 |
| targetAbility | string | 是 | 否 | 当前Ability重用的目标Ability |
| backgroundModes | number | 是 | 否 | 表示后台服务的类型 |
| isVisible | boolean | 是 | 否 | 判断Ability是否可以被其他应用调用 |
| formEnabled | boolean | 是 | 否 | 判断Ability是否提供卡片能力 |
| type | AbilityType | 是 | 否 | Ability类型 |
| orientation | DisplayOrientation | 是 | 否 | Ability的显示模式 |
| launchMode | LaunchMode | 是 | 否 | Ability的启动模式 |
| permissions | Array\<string> | 是 | 否 | 被其他应用Ability调用时需要申请的权限集合 |
| deviceTypes | Array\<string> | 是 | 否 | Ability支持的设备类型 |
| deviceCapabilities | Array\<string> | 是 | 否 | Ability需要的设备能力 |
| readPermission | string | 是 | 否 | 读取Ability数据所需的权限 |
| writePermission | string | 是 | 否 | 向Ability写数据所需的权限 |
| applicationInfo | ApplicationInfo | 是 | 否 | 应用程序的配置信息 |
| uri | string | 是 | 否 | 获取Ability的统一资源标识符（URI） |
| labelId | number | 是 | 否 | Ability的标签id |
| subType | AbilitySubType | 是 | 否 | Ability中枚举使用的模板的子类型 |
| metaData<sup>8+</sup> | Array\<[CustomizeData](js-apis-bundle-CustomizeData.md)> | 是 | 否 | ability的自定义信息 |
| metadata<sup>9+</sup> | Array\<[Metadata](js-apis-bundle-Metadata.md)> | 是 | 否 | ability的元信息 |
| enabled<sup>8+</sup> | boolean | 是 | 否 | ability是否可用 |
\ No newline at end of file
| 名称 | 类型 | 可读 | 可写 | 说明 |
| --------------------- | -------------------------------------------------------- | ---- | ---- | ------------------------------------------------------------ |
| bundleName | string | 是 | 否 | 应用包名 |
| name | string | 是 | 否 | Ability名称 |
| label | string | 是 | 否 | Ability对用户显示的名称 |
| description | string | 是 | 否 | Ability的描述 |
| icon | string | 是 | 否 | Ability的图标资源文件索引 |
| descriptionId | number | 是 | 否 | Ability的描述id |
| iconId | number | 是 | 否 | Ability的图标id |
| moduleName | string | 是 | 否 | Ability所属的HAP包的名称 |
| process | string | 是 | 否 | Ability的进程，如果不设置，默认为包的名称 |
| targetAbility | string | 是 | 否 | 当前Ability重用的目标Ability |
| backgroundModes | number | 是 | 否 | 表示后台服务的类型 |
| isVisible | boolean | 是 | 否 | 判断Ability是否可以被其他应用调用 |
| formEnabled | boolean | 是 | 否 | 判断Ability是否提供卡片能力 |
| type | AbilityType | 是 | 否 | Ability类型 |
| orientation | DisplayOrientation | 是 | 否 | Ability的显示模式 |
| launchMode | LaunchMode | 是 | 否 | Ability的启动模式 |
| permissions | Array\<string> | 是 | 否 | 被其他应用Ability调用时需要申请的权限集合<br />通过传入GET_ABILITY_INFO_WITH_PERMISSION获取 |
| deviceTypes | Array\<string> | 是 | 否 | Ability支持的设备类型 |
| deviceCapabilities | Array\<string> | 是 | 否 | Ability需要的设备能力 |
| readPermission | string | 是 | 否 | 读取Ability数据所需的权限 |
| writePermission | string | 是 | 否 | 向Ability写数据所需的权限 |
| applicationInfo | ApplicationInfo | 是 | 否 | 应用程序的配置信息<br />通过传入GET_ABILITY_INFO_WITH_APPLICATION获取 |
| uri | string | 是 | 否 | 获取Ability的统一资源标识符（URI） |
| labelId | number | 是 | 否 | Ability的标签id |
| subType | AbilitySubType | 是 | 否 | Ability中枚举使用的模板的子类型 |
| metaData<sup>8+</sup> | Array\<[CustomizeData](js-apis-bundle-CustomizeData.md)> | 是 | 否 | ability的自定义信息<br />通过传入GET_ABILITY_INFO_WITH_METADATA获取 |
| metadata<sup>9+</sup> | Array\<[Metadata](js-apis-bundle-Metadata.md)> | 是 | 否 | ability的元信息<br />通过传入GET_ABILITY_INFO_WITH_METADATA获取 |
| enabled<sup>8+</sup> | boolean | 是 | 否 | ability是否可用 |
\ No newline at end of file
zh-cn/application-dev/reference/apis/js-apis-bundle-ApplicationInfo.md
浏览文件 @ 3035f58a
......@@ -4,33 +4,33 @@
> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> API9 当前为Canary版本，仅供试用，不保证接口可稳定调用。
应用程序信息
应用程序信息，未做特殊说明的属性，均通过GET_BUNDLE_DEFAULT获取
## ApplicationInfo
**系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework
| 名称 | 类型 | 可读 | 可写 | 说明 |
| -------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------ |
| name | string | 是 | 否 | 应用程序的名称 |
| description | string | 是 | 否 | 应用程序的描述 |
| descriptionId | number | 是 | 否 | 应用程序的描述id |
| systemApp | boolean | 是 | 否 | 判断是否为系统应用程序，默认为false |
| enabled | boolean | 是 | 否 | 判断应用程序是否可以使用，默认为true |
| label | string | 是 | 否 | 应用程序的标签 |
| labelId | string | 是 | 否 | 应用程序的标签id |
| icon | string | 是 | 否 | 应用程序的图标 |
| iconId | string | 是 | 否 | 应用程序的图标id |
| process | string | 是 | 否 | 应用程序的进程，如果不设置，默认为包的名称 |
| supportedModes | number | 是 | 否 | 应用程序支持的运行模式 |
| moduleSourceDirs | Array\<string> | 是 | 否 | 应用程序的资源存放的相对路径 |
| permissions | Array\<string> | 是 | 否 | 访问应用程序所需的权限 |
| moduleInfos | Array\<[ModuleInfo](js-apis-bundle-ModuleInfo.md)> | 是 | 否 | 应用程序的模块信息 |
| entryDir | string | 是 | 否 | 应用程序的文件保存路径 |
| codePath<sup>8+</sup> | string | 是 | 否 | 应用程序的安装目录 |
| metaData<sup>8+</sup> | Map\<string, Array\<[CustomizeData](js-apis-bundle-CustomizeData.md)>> | 是 | 否 | 应用程序的自定义元信息 |
| metadata<sup>9+</sup> | Map\<string, Array\<[Metadata](js-apis-bundle-Metadata.md)>> | 是 | 否 | 应用程序的元信息 |
| removable<sup>8+</sup> | boolean | 是 | 否 | 应用程序是否可以被移除 |
| accessTokenId<sup>8+</sup> | number | 是 | 否 | 应用程序的accessTokenId |
| uid<sup>8+</sup> | number | 是 | 否 | 应用程序的uid |
| entityType<sup>8+</sup> | string | 是 | 否 | 应用程序的实体类型 |
| 名称 | 类型 | 可读 | 可写 | 说明 |
| -------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ |
| name | string | 是 | 否 | 应用程序的名称 |
| description | string | 是 | 否 | 应用程序的描述 |
| descriptionId | number | 是 | 否 | 应用程序的描述id |
| systemApp | boolean | 是 | 否 | 判断是否为系统应用程序，默认为false |
| enabled | boolean | 是 | 否 | 判断应用程序是否可以使用，默认为true |
| label | string | 是 | 否 | 应用程序的标签 |
| labelId | string | 是 | 否 | 应用程序的标签id |
| icon | string | 是 | 否 | 应用程序的图标 |
| iconId | string | 是 | 否 | 应用程序的图标id |
| process | string | 是 | 否 | 应用程序的进程，如果不设置，默认为包的名称 |
| supportedModes | number | 是 | 否 | 应用程序支持的运行模式 |
| moduleSourceDirs | Array\<string> | 是 | 否 | 应用程序的资源存放的相对路径 |
| permissions | Array\<string> | 是 | 否 | 访问应用程序所需的权限<br />通过传入GET_APPLICATION_INFO_WITH_PERMISSION获取 |
| moduleInfos | Array\<[ModuleInfo](js-apis-bundle-ModuleInfo.md)> | 是 | 否 | 应用程序的模块信息 |
| entryDir | string | 是 | 否 | 应用程序的文件保存路径 |
| codePath<sup>8+</sup> | string | 是 | 否 | 应用程序的安装目录 |
| metaData<sup>8+</sup> | Map\<string, Array\<[CustomizeData](js-apis-bundle-CustomizeData.md)>> | 是 | 否 | 应用程序的自定义元信息<br />通过传入GET_APPLICATION_INFO_WITH_METADATA获取 |
| metadata<sup>9+</sup> | Map\<string, Array\<[Metadata](js-apis-bundle-Metadata.md)>> | 是 | 否 | 应用程序的元信息<br />通过传入GET_APPLICATION_INFO_WITH_METADATA获取 |
| removable<sup>8+</sup> | boolean | 是 | 否 | 应用程序是否可以被移除 |
| accessTokenId<sup>8+</sup> | number | 是 | 否 | 应用程序的accessTokenId |
| uid<sup>8+</sup> | number | 是 | 否 | 应用程序的uid |
| entityType<sup>8+</sup> | string | 是 | 否 | 应用程序的实体类型 |
zh-cn/application-dev/reference/apis/js-apis-bundle-BundleInfo.md
浏览文件 @ 3035f58a
......@@ -4,38 +4,38 @@
> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> API9 当前为Canary版本，仅供试用，不保证接口可稳定调用。
应用包的信息
应用包的信息，未做特殊说明的属性，均通过GET_BUNDLE_DEFAULT获取
## BundleInfo
**系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework
| 名称 | 类型 | 可读 | 可写 | 说明 |
| --------------------------------- | ---------------------------- | ---- | ---- | --------------------- |
| name | string | 是 | 否 | 应用包的名称 |
| type | string | 是 | 否 | 应用包类型 |
| appId | string | 是 | 否 | 应用包里应用程序的id |
| uid | number | 是 | 否 | 应用包里应用程序的uid |
| installTime | number | 是 | 否 | HAP包安装时间 |
| updateTime | number | 是 | 否 | HAP包更新时间 |
| appInfo | ApplicationInfo | 是 | 否 | 应用程序的配置信息 |
| abilityInfos | Array\<[AbilityInfo](js-apis-bundle-AbilityInfo.md)> | 是 | 否 | Ability的配置信息 |
| reqPermissions | Array\<string> | 是 | 否 | 应用运行时需向系统申请的权限集合 |
| reqPermissionDetails | Array\<[ReqPermissionDetail](#reqpermissiondetail)> | 是 | 否 | 应用运行时需向系统申请的权限集合的详细信息 |
| vendor | string | 是 | 否 | 应用包的供应商 |
| versionCode | number | 是 | 否 | 应用包的版本号 |
| versionName | string | 是 | 否 | 应用包的版本文本描述信息 |
| compatibleVersion | number | 是 | 否 | 运行应用包所需要最低的SDK版本号 |
| targetVersion | number | 是 | 否 | 运行应用包所需要最高SDK版本号 |
| isCompressNativeLibs | boolean | 是 | 否 | 是否压缩应用包的本地库，默认为true |
| hapModuleInfos | Array\<[HapModuleInfo](js-apis-bundle-HapModuleInfo.md)> | 是 | 否 | 模块的配置信息 |
| entryModuleName | string | 是 | 否 | Entry的模块名称 |
| cpuAbi | string | 是 | 否 | 应用包的cpuAbi信息 |
| isSilentInstallation | string | 是 | 否 | 是否通过静默安装 |
| minCompatibleVersionCode | number | 是 | 否 | 分布式场景下的应用包兼容的最低版本 |
| entryInstallationFree | boolean | 是 | 否 | Entry是否支持免安装 |
| reqPermissionStates<sup>8+</sup> | Array\<number> | 是 | 否 | 申请权限的授予状态 |
| extensionAbilityInfo<sup>9+</sup> | Array\<[ExtensionAbilityInfo](js-apis-bundle-ExtensionAbilityInfo.md)> | 是 | 否 | ability的可扩展信息 |
| 名称 | 类型 | 可读 | 可写 | 说明 |
| --------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ |
| name | string | 是 | 否 | 应用包的名称 |
| type | string | 是 | 否 | 应用包类型 |
| appId | string | 是 | 否 | 应用包里应用程序的id |
| uid | number | 是 | 否 | 应用包里应用程序的uid |
| installTime | number | 是 | 否 | HAP包安装时间 |
| updateTime | number | 是 | 否 | HAP包更新时间 |
| appInfo | ApplicationInfo | 是 | 否 | 应用程序的配置信息 |
| abilityInfos | Array\<[AbilityInfo](js-apis-bundle-AbilityInfo.md)> | 是 | 否 | Ability的配置信息<br />通过传入GET_BUNDLE_WITH_ABILITIES获取 |
| reqPermissions | Array\<string> | 是 | 否 | 应用运行时需向系统申请的权限集合<br />通过传入GET_BUNDLE_WITH_REQUESTED_PERMISSION获取 |
| reqPermissionDetails | Array\<[ReqPermissionDetail](#reqpermissiondetail)> | 是 | 否 | 应用运行时需向系统申请的权限集合的详细信息<br />通过传入GET_BUNDLE_WITH_REQUESTED_PERMISSION获取 |
| vendor | string | 是 | 否 | 应用包的供应商 |
| versionCode | number | 是 | 否 | 应用包的版本号 |
| versionName | string | 是 | 否 | 应用包的版本文本描述信息 |
| compatibleVersion | number | 是 | 否 | 运行应用包所需要最低的SDK版本号 |
| targetVersion | number | 是 | 否 | 运行应用包所需要最高SDK版本号 |
| isCompressNativeLibs | boolean | 是 | 否 | 是否压缩应用包的本地库，默认为true |
| hapModuleInfos | Array\<[HapModuleInfo](js-apis-bundle-HapModuleInfo.md)> | 是 | 否 | 模块的配置信息 |
| entryModuleName | string | 是 | 否 | Entry的模块名称 |
| cpuAbi | string | 是 | 否 | 应用包的cpuAbi信息 |
| isSilentInstallation | string | 是 | 否 | 是否通过静默安装 |
| minCompatibleVersionCode | number | 是 | 否 | 分布式场景下的应用包兼容的最低版本 |
| entryInstallationFree | boolean | 是 | 否 | Entry是否支持免安装 |
| reqPermissionStates<sup>8+</sup> | Array\<number> | 是 | 否 | 申请权限的授予状态 |
| extensionAbilityInfo<sup>9+</sup> | Array\<[ExtensionAbilityInfo](js-apis-bundle-ExtensionAbilityInfo.md)> | 是 | 否 | ability的可扩展信息<br />通过传入GET_BUNDLE_WITH_EXTENSION_ABILITY获取 |
## ReqPermissionDetail
......
zh-cn/application-dev/reference/apis/js-apis-bundle-ExtensionAbilityInfo.md
浏览文件 @ 3035f58a
......@@ -4,7 +4,7 @@
> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> API9 当前为Canary版本，仅供试用，不保证接口可稳定调用。
ExtensionAbility信息
ExtensionAbility信息，未做特殊说明的属性，均通过GET_BUNDLE_DEFAULT获取
## ExtensionAbilityInfo
......
zh-cn/application-dev/reference/apis/js-apis-bundle-HapModuleInfo.md
浏览文件 @ 3035f58a
......@@ -4,7 +4,7 @@
> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> API9 当前为Canary版本，仅供试用，不保证接口可稳定调用。
Hap模块信息
Hap模块信息，未做特殊说明的属性，均通过GET_BUNDLE_DEFAULT获取
## HapModuleInfo
......
zh-cn/application-dev/reference/apis/js-apis-display.md
浏览文件 @ 3035f58a
......@@ -61,22 +61,24 @@ getDefaultDisplay(callback: AsyncCallback&lt;Display&gt;): void
**系统能力：** SystemCapability.WindowManager.WindowManager.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[Display](#display)&gt; | 是 | 回调函数。返回当前默认的display对象。 |
**示例：**
```js
var displayClass = null;
display.getDefaultDisplay((err, data) => {
if (err.code) {
console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data));
displayClass = data;
});
```
```js
var displayClass = null;
display.getDefaultDisplay((err, data) => {
if (err.code) {
console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data));
displayClass = data;
});
```
## display.getDefaultDisplay
......@@ -94,14 +96,16 @@ getDefaultDisplay(): Promise&lt;Display&gt;
**示例：**
```js
let promise = display.getDefaultDisplay();
promise.then(() => {
console.log('getDefaultDisplay success');
}).catch((err) => {
console.log('getDefaultDisplay fail: ' + JSON.stringify(err));
});
```
```js
var displayClass = null;
let promise = display.getDefaultDisplay();
promise.then((data) => {
displayClass = data;
console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data));
}).catch((err) => {
console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(err));
});
```
## display.getAllDisplay
......@@ -119,15 +123,15 @@ getAllDisplay(callback: AsyncCallback&lt;Array&lt;Display&gt;&gt;): void
**示例：**
```js
display.getAllDisplay((err, data) => {
if (err.code) {
console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data))
});
```
```js
display.getAllDisplay((err, data) => {
if (err.code) {
console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data));
});
```
## display.getAllDisplay
......@@ -145,14 +149,14 @@ getAllDisplay(): Promise&lt;Array&lt;Display&gt;&gt;
**示例：**
```js
let promise = display.getAllDisplay();
promise.then(() => {
console.log('getAllDisplay success');
}).catch((err) => {
console.log('getAllDisplay fail: ' + JSON.stringify(err));
});
```
```js
let promise = display.getAllDisplay();
promise.then((data) => {
console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err));
}).catch((err) => {
console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data));
});
```
## display.on('add'|'remove'|'change')
......@@ -163,19 +167,20 @@ on(type: 'add'|'remove'|'change', callback: Callback&lt;number&gt;): void
**系统能力：** SystemCapability.WindowManager.WindowManager.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 设置监听类型。<br/>-&nbsp;type为"add"，表示监听增加显示设备。<br/>-&nbsp;type为"remove"，表示监听移除显示设备。<br/>-&nbsp;type为"change"，表示监听改变显示设备。 |
| callback | Callback&lt;number&gt; | 是 | 回调函数。返回监听到的显示设备的id。 |
**示例：**
```js
var callback = (data) => {
console.info('Listening enabled. Data: ' + JSON.stringify(data))
}
display.on("add", callback);
```
```js
var callback = (data) => {
console.info('Listening enabled. Data: ' + JSON.stringify(data))
}
display.on("add", callback);
```
## display.off('add'|'remove'|'change')
......@@ -186,12 +191,13 @@ off(type: 'add'|'remove'|'change', callback?: Callback&lt;number&gt;): void
**系统能力：** SystemCapability.WindowManager.WindowManager.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 设置监听类型。<br/>-&nbsp;type为"add"，表示监听增加显示设备。<br/>-&nbsp;type为"remove"，表示监听移除显示设备。<br/>-&nbsp;type为"change"，表示监听改变显示设备。 |
| callback | Callback&lt;number&gt; | 否 | 回调函数。返回监听到的显示设备的id。 |
**示例：**
```js
display.off("remove");
```
```js
display.off("remove");
```
zh-cn/application-dev/reference/apis/js-apis-window.md
浏览文件 @ 3035f58a
......@@ -44,7 +44,7 @@ import window from '@ohos.window';
窗口模式枚举。
此接口为系统接口，三方应用不支持调用。
**系统接口：** 此接口为系统接口，三方应用不支持调用。
**系统能力：** SystemCapability.WindowManager.WindowManager.Core
......@@ -75,7 +75,7 @@ import window from '@ohos.window';
单个导航栏或状态栏回调信息。
此接口为系统接口，三方应用不支持调用。
**系统接口：** 此接口为系统接口，三方应用不支持调用。
**系统能力：** SystemCapability.WindowManager.WindowManager.Core
......@@ -91,7 +91,7 @@ import window from '@ohos.window';
当前系统栏回调信息集合。
此接口为系统接口，三方应用不支持调用。
**系统接口：** 此接口为系统接口，三方应用不支持调用。
**系统能力：** SystemCapability.WindowManager.WindowManager.Core
......@@ -486,7 +486,7 @@ on(type: 'systemBarTintChange', callback: Callback&lt;SystemBarTintState&gt;): v
开启状态栏、导航栏属性变化的监听。
此接口为系统接口，三方应用不支持调用。
**系统接口：** 此接口为系统接口，三方应用不支持调用。
**系统能力：** SystemCapability.WindowManager.WindowManager.Core
......@@ -511,7 +511,7 @@ off(type: 'systemBarTintChange', callback?: Callback&lt;SystemBarTintState &gt;)
关闭状态栏、导航栏属性变化的监听。
此接口为系统接口，三方应用不支持调用。
**系统接口：** 此接口为系统接口，三方应用不支持调用。
**系统能力：** SystemCapability.WindowManager.WindowManager.Core
......@@ -540,7 +540,7 @@ hide (callback: AsyncCallback&lt;void&gt;): void
隐藏当前窗口，使用callback异步回调。
此接口为系统接口，三方应用不支持调用。
**系统接口：** 此接口为系统接口，三方应用不支持调用。
**系统能力：** SystemCapability.WindowManager.WindowManager.Core
......@@ -568,7 +568,7 @@ hide(): Promise&lt;void&gt;
隐藏当前窗口，使用Promise异步回调。
此接口为系统接口，三方应用不支持调用。
**系统接口：** 此接口为系统接口，三方应用不支持调用。
**系统能力：** SystemCapability.WindowManager.WindowManager.Core
......@@ -818,7 +818,7 @@ setWindowType(type: WindowType, callback: AsyncCallback&lt;void&gt;): void
设置窗口类型，使用callback异步回调。
此接口为系统接口，三方应用不支持调用。
**系统接口：** 此接口为系统接口，三方应用不支持调用。
**系统能力：** SystemCapability.WindowManager.WindowManager.Core
......@@ -848,7 +848,7 @@ setWindowType(type: WindowType): Promise&lt;void&gt;
设置窗口类型，使用Promise异步回调。
此接口为系统接口，三方应用不支持调用。
**系统接口：** 此接口为系统接口，三方应用不支持调用。
**系统能力：** SystemCapability.WindowManager.WindowManager.Core
......
zh-cn/application-dev/reference/arkui-ts/ts-basic-components-web.md
浏览文件 @ 3035f58a
......@@ -19,11 +19,27 @@ Web(options: { src: ResourceStr, controller: WebController })
表1 options参数说明
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---------- | ------------------------------- | ---- | ---- | ------- |
| src | [ResourceStr](../../ui/ts-types.md) | 是 | - | 网页资源地址。 |
| controller | [WebController](#webcontroller) | 否 | - | 控制器。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
}
}
}
```
> **说明：**
>
> - 不支持转场动画；
......@@ -32,22 +48,405 @@ Web(options: { src: ResourceStr, controller: WebController })
## 属性
| 名称 | 参数类型 | 默认值 | 描述 |
| ------------------ | ---------------------------------------- | ----------------- | ---------------------------------------- |
| domStorageAccess | boolean | false | 设置是否开启文档对象模型存储接口（DOM Storage API）权限，默认未开启。 |
| fileAccess | boolean | false | 设置是否开启通过[$rawfile(filepath/filename)](../../ui/ts-application-resource-access.md#资源引用)访问应用中rawfile路径的文件， 默认启用。 |
| fileFromUrlAccess | boolean | true | 设置是否允许通过网页中的JavaScript脚本访问[$rawfile(filepath/filename)](../../ui/ts-application-resource-access.md#资源引用)的内容，默认未启用。 |
| imageAccess | boolean | true | 设置是否允许自动加载图片资源，默认允许。 |
| javaScriptProxy | { <br> object: object, <br/> name: string, <br/> methodList: Array\<string\>, <br/> controller: WebController <br>} | - | 注入JavaScript对象到window对象中，并在window对象中调用该对象的方法。所有参数不支持更新。 <br/>- object: 参与注册的对象。只能声明方法，不能声明属性 。其中方法的参数和返回类型只能为string，number，boolean。<br/>- name: 注册对象的名称，与window中调用的对象名一致。注册后window对象可以通过此名字访问应用侧JavaScript对象。<br/>- methodList: 参与注册的应用侧JavaScript对象的方法。<br/>- controller: 控制器。 |
| javaScriptAccess | boolean | true | 设置是否允许执行JavaScript脚本，默认允许执行。 |
| mixedMode | [MixedMode](#mixedmode枚举说明) | MixedMode.None | 设置是否允许加载超文本传输协议（HTTP）和超文本传输安全协议（HTTPS）混合内容，默认不允许加载HTTP和HTTPS混合内容。 |
| onlineImageAccess | boolean | true | 设置是否允许从网络加载图片资源（通过HTTP和HTTPS访问的资源），默认允许访问。 |
| zoomAccess | boolean | true | 设置是否支持手势进行缩放，默认允许执行缩放。 |
| overviewModeAccess | boolean | true | 设置是否使用概览模式加载网页，默认使用该方式。 |
| databaseAccess | boolean | false | 设置是否开启数据库存储API权限，默认不开启。 |
| cacheMode | [CacheMode](#cachemode枚举说明) | CacheMode.Default | 设置缓存模式。 |
| textZoomAtio | number | 100 | 设置页面的文本缩放百分比，默认为100%。 |
| userAgent | string | - | 设置用户代理。 |
web组件的网络属性。
### domStorageAccess
domStorageAccess(domStorageAccess: boolean)
设置是否开启文档对象模型存储接口（DOM Storage API）权限，默认未开启。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---------------- | ------- | ---- | ---- | ------------------------------------ |
| domStorageAccess | boolean | 是 | false | 设置是否开启文档对象模型存储接口（DOM Storage API）权限。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.domStorageAccess(true)
}
}
}
```
### fileAccess
fileAccess(fileAccess: boolean)
设置是否开启通过[$rawfile(filepath/filename)](../../ui/ts-resource-access.md)访问应用中rawfile路径的文件， 默认启用。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---------- | ------- | ---- | ---- | ---------------------------------------- |
| fileAccess | boolean | 是 | true | 设置是否开启通过[$rawfile(filepath/filename)](../../ui/ts-resource-access.md)访问应用中rawfile路径的文件，默认启用。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.fileAccess(true)
}
}
}
```
### imageAccess
imageAccess(imageAccess: boolean)
设置是否允许自动加载图片资源，默认允许。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ----------- | ------- | ---- | ---- | --------------- |
| imageAccess | boolean | 是 | true | 设置是否允许自动加载图片资源。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.imageAccess(true)
}
}
}
```
### javaScriptProxy
javaScriptProxy(javaScriptProxy: { object: object, name: string, methodList: Array\<string\>,
controller: WebController })
注入JavaScript对象到window对象中，并在window对象中调用该对象的方法。所有参数不支持更新。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---------- | --------------- | ---- | ---- | ------------------------- |
| object | object | 是 | - | 参与注册的对象。只能声明方法，不能声明属性。 |
| name | string | 是 | - | 注册对象的名称，与window中调用的对象名一致。 |
| methodList | Array\<string\> | 是 | - | 参与注册的应用侧JavaScript对象的方法。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
testObj = {
test: (data1, data2, data3) => {
console.log("data1:" + data1);
console.log("data2:" + data2);
console.log("data3:" + data3);
return "AceString";
},
toString: () => {
console.log('toString' + "interface instead.");
}
}
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.javaScriptAccess(true)
.javaScriptProxy({
object: this.testObj,
name: "objName",
methodList: ["test", "toString"],
controller: this.controller,
})
}
}
}
```
### javaScriptAccess
javaScriptAccess(javaScriptAccess: boolean)
设置是否允许执行JavaScript脚本，默认允许执行。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---------------- | ------- | ---- | ---- | ------------------- |
| javaScriptAccess | boolean | 是 | true | 是否允许执行JavaScript脚本。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.javaScriptAccess(true)
}
}
}
```
### mixedMode
mixedMode(mixedMode: MixedMode)
设置是否允许加载超文本传输协议（HTTP）和超文本传输安全协议（HTTPS）混合内容，默认不允许加载HTTP和HTTPS混合内容。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| --------- | --------------------------- | ---- | ---- | --------- |
| mixedMode | [MixedMode](#mixedmode枚举说明) | 是 | None | 要设置的混合内容。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
@State mode:MixedMode = MixedMode.All;
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.mixedMode(this.mode)
}
}
}
```
onlineImageAccess(onlineImageAccess: boolean)
设置是否允许从网络加载图片资源（通过HTTP和HTTPS访问的资源），默认允许访问。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ----------------- | ------- | ---- | ---- | ---------------- |
| onlineImageAccess | boolean | 是 | true | 设置是否允许从网络加载图片资源。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.onlineImageAccess(true)
}
}
}
```
### zoomAccess
zoomAccess(zoomAccess: boolean)
设置是否支持手势进行缩放，默认允许执行缩放。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---------- | ------- | ---- | ---- | ------------- |
| zoomAccess | boolean | 是 | true | 设置是否支持手势进行缩放。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.zoomAccess(true)
}
}
}
```
### overviewModeAccess
overviewModeAccess(overviewModeAccess: boolean)
设置是否使用概览模式加载网页，默认使用该方式。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ------------------ | ------- | ---- | ---- | --------------- |
| overviewModeAccess | boolean | 是 | true | 设置是否使用概览模式加载网页。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.overviewModeAccess(true)
}
}
}
```
### databaseAccess
databaseAccess(databaseAccess: boolean)
设置是否开启数据库存储API权限，默认不开启。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| -------------- | ------- | ---- | ---- | ----------------- |
| databaseAccess | boolean | 是 | false | 设置是否开启数据库存储API权限。 |
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.databaseAccess(true)
}
}
}
```
### geolocationAccess
geolocationAccess(geolocationAccess: boolean)
设置是否开启获取地理位置权限，默认开启。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| -------------- | ------- | ---- | ---- | ----------------- |
| geolocationAccess | boolean | 是 | true | 设置是否开启获取地理位置权限。 |
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.geolocationAccess(true)
}
}
}
```
### cacheMode
cacheMode(cacheMode: CacheMode)
设置缓存模式。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| --------- | --------------------------- | ---- | ---- | --------- |
| cacheMode | [CacheMode](#cachemode枚举说明) | 是 | - | 要设置的缓存模式。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
@State mode:CacheMode = CacheMode.None;
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.cacheMode(this.mode)
}
}
}
```
### textZoomAtio
textZoomAtio(textZoomAtio: number)
设置页面的文本缩放百分比，默认为100%。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ------------ | ------ | ---- | ---- | --------------- |
| textZoomAtio | number | 是 | 100 | 要设置的页面的文本缩放百分比。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
@State atio:number = 150;
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.textZoomAtio(this.atio)
}
}
}
```
### userAgent
userAgent(userAgent: string)
设置用户代理。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| --------- | ------ | ---- | ---- | --------- |
| userAgent | string | 是 | - | 要设置的用户代理。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
@State userAgent:string = 'Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36';
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.userAgent(this.userAgent)
}
}
}
```
> **说明：**
>
......@@ -57,140 +456,729 @@ Web(options: { src: ResourceStr, controller: WebController })
不支持通用事件。
| 名称 | 功能描述 |
| ---------------------------------------- | ---------------------------------------- |
| onAlert(callback: (event?: { url: string; message: string; result: [JsResult](#jsresult对象说明) }) => boolean) | <p>网页触发alert()告警弹窗时触发回调。<br />当回调返回false时，触发默认弹窗。当回调返回true时，系统应用可以调用系统弹窗能力（只有确认场景），并且根据用户的确认操作调用JsResult通知Web组件。<br />- url：当前显示弹窗所在网页的URL。<br />- message：弹窗中显示的信息。<br />- result：通知Web组件用户操作行为。</p> |
| onBeforeUnload(callback: (event?: { url: string; message: string; result: [JsResult](#jsresult对象说明) }) => boolean) | <p>刷新或关闭场景下，在即将离开当前页面时触发此回调。<br />当回调返回false时，触发默认弹窗。当回调返回true时，系统应用可以调用系统弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。<br />- url：当前显示弹窗所在网页的URL。<br />- message：弹窗中显示的信息。<br />- result：通知Web组件用户操作行为。</p> |
| onConfirm(callback: (event?: { url: string; message: string; result: [JsResult](#jsresult对象说明) }) => boolean) | <p>网页调用confirm()告警时触发此回调。<br />当回调返回false时，触发默认弹窗。当回调返回true时，系统应用可以调用系统弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件。<br />- url：当前显示弹窗所在网页的URL。<br />- message：弹窗中显示的信息。<br />- result：通知Web组件用户操作行为。</p> |
| onConsole(callback: (event?: { message: [ConsoleMessage](#consolemessage对象说明) }) => boolean) | <p>通知宿主应用JavaScript console消息。<br/>- message：触发的控制台信息。</p> |
| onDownloadStart(callback: (event?: { url: string, userAgent: string, contentDisposition: string, mimetype: string, contentLength: number }) => void) | <p>网页的下载任务开始时触发该回调。<br />- url：文件下载的URL。<br />- userAgent：下载的用户代理（UA）名称。<br />- contentDisposition：服务器返回的 Content-Disposition响应头，可能为空。<br />- mimetype：服务器返回内容媒体类型（MIME）信息。<br />- contentLength：服务器返回文件的长度。</p> |
| onErrorReceive(callback: (event?: { request: [WebResourceRequest](#webresourceerror对象说明), error: [WebResourceError](#webresourceerror对象说明) }) => void) | <p>网页加载遇到错误时触发该回调。<br/>出于性能考虑，建议此回调中尽量执行简单逻辑。<br/>- request：网页请求的封装信息。<br/>- error：网页加载资源错误的封装信息 。</p> |
| onHttpErrorReceive(callback: (event?: { request: [WebResourceRequest](#webresourceerror对象说明), response: [WebResourceResponse](#webresourceresponse对象说明) }) => void) | <p>网页加载资源遇到的HTTP错误（响应码>=400)时触发该回调。<br/>- request：网页请求的封装信息。<br/>- response：网页响应的封装信息</p> |
| onPageBegin(callback: (event?: { url: string }) => void) | <p>网页开始加载时触发该回调，且只在主frame触发，iframe或者frameset的内容加载时不会触发此回调。<br/>- url：页面的URL地址。</p> |
| onPageEnd(callback: (event?: { url: string }) => void) | <p>网页加载完成时触发该回调，且只在主frame触发。<br/>- url：页面的URL地址。</p> |
| onProgressChange(callback: (event?: { newProgress: number }) => void) | <p>网页加载进度变化时触发该回调。<br/>- newProgress：新的加载进度，取值范围为0到100的整数。</p> |
| onTitleReceive(callback: (event?: { title: string }) => void) | <p>网页document标题更改时触发该回调。<br/>- title：document标题内容。</p> |
| onRefreshAccessedHistory(callback: (event?: { url: string, isRefreshed: boolean }) => void) | <p>加载网页页面完成时触发该回调，用于应用更新其访问的历史链接。<br/>- url：访问的url。<br/>- isRefreshed：true表示该页面是被重新加载的，false表示该页面是新加载的。</p> |
| onRenderExited(callback: (event?: { renderExitReason: [RenderExitReason](#renderexitreason枚举说明) }) => void) | <p>应用渲染进程异常退出时触发该回调。<br/>- renderExitReason：渲染进程进程异常退出的具体原因。</p> |
| onFileSelectorShow(callback: (event?: { result: [FileSelectorResult](#fileselectorresult对象说明), fileSelector: [FileSelectorParam](#fileselectorparam对象说明) }) => void) | <p>调用此函数以处理具有“文件”输入类型的HTML表单，以响应用户按下的“选择文件”按钮<br/>- result：用于通知Web组件文件选择的结果。<br/>- fileSelector：文件选择器的相关信息。</p> |
| onUrlLoadIntercept(callback: (event?: { data:string \| [WebResourceRequest](#webresourcerequest对象说明) }) => boolean) | <p>当Web组件加载url之前触发该回调，用于是否阻止此次访问。callback返回true表示阻止此次加载，否则允许此次加载。<br/>- data：url的相关信息。</p> |
## ConsoleMessage对象说明
| 接口名称 | 功能描述 |
| ---------------------------------------- | ---------------------- |
| getLineNumber(): number | 获取ConsoleMessage的行数。 |
| getMessage(): string | 获取ConsoleMessage的日志信息。 |
| getMessageLevel(): [MessageLevel](#messagelevel枚举说明) | 获取ConsoleMessage的信息级别。 |
| getSourceId(): string | 获取网页源文件路径和名字。 |
### onAlert
onAlert(callback: (event?: { url: string; message: string; result: JsResult }) => boolean)
网页触发alert()告警弹窗时触发回调。
**参数：**
| 参数名 | 参数类型 | 参数描述 |
| ------- | --------------------- | --------------- |
| url | string | 当前显示弹窗所在网页的URL。 |
| message | string | 弹窗中显示的信息。 |
| result | [JsResult](#jsresult) | 通知Web组件用户操作行为。 |
**返回值：**
| 类型 | 说明 |
| ------- | ---------------------------------------- |
| boolean | 当回调返回false时，触发默认弹窗。当回调返回true时，系统应用可以调用系统弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController();
build() {
Column() {
Web({ src:'www.example.com', controller:this.controller })
.onAlert((event) => {
AlertDialog.show({
title: 'title',
message: 'text',
confirm: {
value: 'onAlert',
action: () => {
event.result.handleConfirm()
}
},
cancel: () => {
event.result.handleCancel()
}
})
return true;
})
}
}
}
```
### onBeforeUnload
onBeforeUnload(callback: (event?: { url: string; message: string; result: JsResult }) => boolean)
刷新或关闭场景下，在即将离开当前页面时触发此回调。
**参数：**
| 参数名 | 参数类型 | 参数描述 |
| ------- | --------------------- | --------------- |
| url | string | 当前显示弹窗所在网页的URL。 |
| message | string | 弹窗中显示的信息。 |
| result | [JsResult](#jsresult) | 通知Web组件用户操作行为。 |
**返回值：**
| 类型 | 说明 |
| ------- | ---------------------------------------- |
| boolean | 当回调返回false时，触发默认弹窗。当回调返回true时，系统应用可以调用系统弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.onBeforeUnload((event) => {
console.log("event.url:" + event.url);
console.log("event.message:" + event.message);
console.log("event.result:" + event.result);
return false;
})
}
}
}
```
### onConfirm
onConfirm(callback: (event?: { url: string; message: string; result: JsResult }) => boolean)
网页调用confirm()告警时触发此回调。
**参数：**
| 参数名 | 参数类型 | 参数描述 |
| ------- | --------------------- | --------------- |
| url | string | 当前显示弹窗所在网页的URL。 |
| message | string | 弹窗中显示的信息。 |
| result | [JsResult](#jsresult) | 通知Web组件用户操作行为。 |
**返回值：**
| 类型 | 说明 |
| ------- | ---------------------------------------- |
| boolean | 当回调返回false时，触发默认弹窗。当回调返回true时，系统应用可以调用系统弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.onConfirm((event) => {
console.log("event.url:" + event.url);
console.log("event.message:" + event.message);
console.log("event.result:" + event.result);
AlertDialog.show({
title: 'title',
message: 'text',
confirm: {
value: 'onConfirm',
action: () => {
event.result.handleConfirm()
}
},
cancel: () => {
event.result.handleCancel()
}
})
return true;
})
}
}
}
```
### onConsole
onConsole(callback: (event?: { message: ConsoleMessage }) => boolean)
通知宿主应用JavaScript console消息。
**参数：**
| 参数名 | 参数类型 | 参数描述 |
| ------- | --------------------------------- | --------- |
| message | [ConsoleMessage](#consolemessage) | 触发的控制台信息。 |
**返回值：**
| 类型 | 说明 |
| ------- | ----------------------------------- |
| boolean | 当返回true时，该条消息将不会再打印至控制台，反之仍会打印至控制台。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.onConsole((event) => {
console.log('getMessage:' + event.message.getMessage());
console.log('getSourceId:' + event.message.getSourceId());
console.log('getLineNumber:' + event.message.getLineNumber());
console.log('getMessageLevel:' + event.message.getMessageLevel());
return false;
})
}
}
}
```
### onDownloadStart
onDownloadStart(callback: (event?: { url: string, userAgent: string, contentDisposition: string, mimetype: string, contentLength: number }) => void)
**参数：**
| 参数名 | 参数类型 | 参数描述 |
| ------------------ | ------------- | ----------------------------------- |
| url | string | 文件下载的URL。 |
| contentDisposition | string | 服务器返回的 Content-Disposition响应头，可能为空。 |
| mimetype | string | 服务器返回内容媒体类型（MIME）信息。 |
| contentLength | contentLength | 服务器返回文件的长度。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.onDownloadStart((event) => {
console.log('url:' + event.url);
console.log('userAgent:' + event.userAgent);
console.log('contentDisposition:' + event.contentDisposition);
console.log('contentLength:' + event.contentLength);
console.log('mimetype:' + event.mimetype);
})
}
}
}
```
### onErrorReceive
onErrorReceive(callback: (event?: { request: WebResourceRequest, error: WebResourceError }) => void)
网页加载遇到错误时触发该回调。出于性能考虑，建议此回调中尽量执行简单逻辑。
**参数：**
| 参数名 | 参数类型 | 参数描述 |
| ------- | ---------------------------------------- | --------------- |
| request | [WebResourceRequest](#webresourcerequest) | 网页请求的封装信息。 |
| error | [WebResourceError](#webresourceerror) | 网页加载资源错误的封装信息 。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.onErrorReceive((event) => {
console.log('getErrorInfo:' + event.error.getErrorInfo());
console.log('getErrorCode:' + event.error.getErrorCode());
console.log('url:' + event.request.getRequestUrl());
console.log('isMainFrame:' + event.request.isMainFrame());
console.log('isRedirect:' + event.request.isRedirect());
console.log('isRequestGesture:' + event.request.isRequestGesture());
console.log('getRequestHeader_headerKey:' + event.request.getRequestHeader().toString());
let result = event.request.getRequestHeader();
console.log('The request header result size is ' + result.length);
for (let i of result) {
console.log('The request header key is : ' + i.headerKey + ', value is : ' + i.headerValue);
}
})
}
}
}
```
### onHttpErrorReceive
onHttpErrorReceive(callback: (event?: { request: WebResourceRequest, response: WebResourceResponse }) => void)
网页加载资源遇到的HTTP错误（响应码>=400)时触发该回调。
**参数：**
| 参数名 | 参数类型 | 参数描述 |
| ------- | ---------------------------------------- | --------------- |
| request | [WebResourceRequest](#webresourcerequest) | 网页请求的封装信息。 |
| error | [WebResourceError](#webresourceerror) | 网页加载资源错误的封装信息 。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.onHttpErrorReceive((event) => {
console.log('url:' + event.request.getRequestUrl());
console.log('isMainFrame:' + event.request.isMainFrame());
console.log('isRedirect:' + event.request.isRedirect());
console.log('isRequestGesture:' + event.request.isRequestGesture());
console.log('getResponseData:' + event.response.getResponseData());
console.log('getResponseEncoding:' + event.response.getResponseEncoding());
console.log('getResponseMimeType:' + event.response.getResponseMimeType());
console.log('getResponseCode:' + event.response.getResponseCode());
console.log('getReasonMessage:' + event.response.getReasonMessage());
let result = event.request.getRequestHeader();
console.log('The request header result size is ' + result.length);
for (let i of result) {
console.log('The request header key is : ' + i.headerKey + ' , value is : ' + i.headerValue);
}
let resph = event.response.getResponseHeader();
console.log('The response header result size is ' + resph.length);
for (let i of resph) {
console.log('The response header key is : ' + i.headerKey + ' , value is : ' + i.headerValue);
}
})
}
}
}
```
### onPageBegin
onPageBegin(callback: (event?: { url: string }) => void)
网页开始加载时触发该回调，且只在主frame触发，iframe或者frameset的内容加载时不会触发此回调。
**参数：**
| 参数名 | 参数类型 | 参数描述 |
| ---- | ------ | --------- |
| url | string | 页面的URL地址。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.onPageBegin((event) => {
console.log('url:' + event.url);
})
}
}
}
```
### onPageEnd
onPageEnd(callback: (event?: { url: string }) => void)
网页加载完成时触发该回调，且只在主frame触发。
**参数：**
| 参数名 | 参数类型 | 参数描述 |
| ---- | ------ | --------- |
| url | string | 页面的URL地址。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.onPageEnd((event) => {
console.log('url:' + event.url);
})
}
}
}
```
### onProgressChange
onProgressChange(callback: (event?: { newProgress: number }) => void)
网页加载进度变化时触发该回调。
**参数：**
| 参数名 | 参数类型 | 参数描述 |
| ----------- | ------ | --------------------- |
| newProgress | number | 新的加载进度，取值范围为0到100的整数。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.onProgressChange((event) => {
console.log('newProgress:' + event.newProgress)
})
}
}
}
```
### onTitleReceive
onTitleReceive(callback: (event?: { title: string }) => void)
网页document标题更改时触发该回调。
**参数：**
| 参数名 | 参数类型 | 参数描述 |
| ----- | ------ | ------------- |
| title | string | document标题内容。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.onTitleReceive((event) => {
console.log('title:' + event.title)
})
}
}
}
```
### onRefreshAccessedHistory
onRefreshAccessedHistory(callback: (event?: { url: string, refreshed: boolean }) => void)
加载网页页面完成时触发该回调，用于应用更新其访问的历史链接。
**参数：**
| 参数名 | 参数类型 | 参数描述 |
| ----------- | ------- | --------------------------------- |
| url | string | 访问的url。 |
| refreshed | boolean | true表示该页面是被重新加载的，false表示该页面是新加载的。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.onRefreshAccessedHistory((event) => {
console.log('url:' + event.url + ' isReload:' + event.refreshed);
})
}
}
}
```
### onUrlLoadIntercept
onUrlLoadIntercept(callback: (event?: { data:string | WebResourceRequest }) => boolean)
当Web组件加载url之前触发该回调，用于是否阻止此次访问。
**参数：**
| 参数名 | 参数类型 | 参数描述 |
| ---- | ---------------------------------------- | --------- |
| data | string / [WebResourceRequest](#webresourcerequest) | url的相关信息。 |
**返回值：**
| 类型 | 说明 |
| ------- | ------------------------ |
| boolean | 返回true表示阻止此次加载，否则允许此次加载。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Web({ src: 'www.example.com', controller: this.controller })
.onUrlLoadIntercept((event) => {
console.log('onUrlLoadIntercept ' + event.data.toString())
return true;
})
}
}
}
```
## MessageLevel枚举说明
## ConsoleMessage
| 名称 | 描述 |
| ----- | :---- |
| Debug | 调试级别。 |
| Error | 错误级别。 |
| Info | 消息级别。 |
| Log | 日志级别。 |
| Warn | 警告级别。 |
Web组件获取控制台信息对象。示例代码参考[onConsole事件](#onconsole)。
### getLineNumber
getLineNumber(): number
获取ConsoleMessage的行数。
**返回值：**
| 类型 | 说明 |
| ------ | -------------------- |
| number | 返回ConsoleMessage的行数。 |
### getMessage
getMessage(): string
获取ConsoleMessage的日志信息。
**返回值：**
| 类型 | 说明 |
| ------ | ---------------------- |
| string | 返回ConsoleMessage的日志信息。 |
### getMessageLevel
getMessageLevel(): MessageLevel
获取ConsoleMessage的信息级别。
**返回值：**
| 类型 | 说明 |
| --------------------------------- | ---------------------- |
| [MessageLevel](#messagelevel枚举说明) | 返回ConsoleMessage的信息级别。 |
### getSourceId
getSourceId(): string
获取网页源文件路径和名字。
**返回值：**
| 类型 | 说明 |
| ------ | ------------- |
| string | 返回网页源文件路径和名字。 |
## JsResult
Web组件返回的弹窗确认或弹窗取消功能对象。示例代码参考[onAlert事件](#onalert)。
### handleCancel
handleCancel(): void
通知Web组件用户取消弹窗操作。
### handleConfirm
handleConfirm(): void
通知Web组件用户确认弹窗操作。
## WebResourceError
web组件资源管理错误信息对象。示例代码参考[onErrorReceive事件](#onerrorreceive)。
### getErrorCode
getErrorCode(): number
获取加载资源的错误码。
**返回值：**
| 类型 | 说明 |
| ------ | ----------- |
| number | 返回加载资源的错误码。 |
### getErrorInfo
getErrorInfo(): string
获取加载资源的错误信息。
**返回值：**
| 类型 | 说明 |
| ------ | ------------ |
| string | 返回加载资源的错误信息。 |
## WebResourceRequest
web组件获取资源请求对象。示例代码参考[onErrorReceive事件](#onerrorreceive)。
### getRequestHeader
getResponseHeader() : Array\<Header\>
获取资源请求头信息。
**返回值：**
| 类型 | 说明 |
| -------------------------- | ---------- |
| Array\<[Header](#header)\> | 返回资源请求头信息。 |
### getRequestUrl
getRequestUrl(): string
获取资源请求的URL信息。
**返回值：**
| 类型 | 说明 |
| ------ | ------------- |
| string | 返回资源请求的URL信息。 |
### isMainFrame
isMainFrame(): boolean
判断资源请求是否为主frame。
**返回值：**
| 类型 | 说明 |
| ------- | ---------------- |
| boolean | 返回资源请求是否为主frame。 |
## JsResult对象说明
### isRedirect
Web组件返回的弹窗确认或弹窗取消功能对象。
isRedirect(): boolean
| 接口名称 | 功能描述 |
| --------------------- | ----------------------- |
| handleCancel(): void | <p>通知Web组件用户取消弹窗操作。</p> |
| handleConfirm(): void | <p>通知Web组件用户确认弹窗操作。</p> |
判断资源请求是否被服务端重定向。
## WebResourceError对象说明
**返回值：**
| 类型 | 说明 |
| ------- | ---------------- |
| boolean | 返回资源请求是否被服务端重定向。 |
| 接口名称 | 功能描述 |
| ---------------------- | ------------ |
| getErrorCode(): number | 获取加载资源的错误码。 |
| getErrorInfo(): string | 获取加载资源的错误信息。 |
### isRequestGesture
## WebResourceRequest对象说明
isRequestGesture(): boolean
| 接口名称 | 功能描述 |
| ---------------------------------------- | -------------------- |
| getRequestHeader(): Array\<[Header](#header对象说明)\> | 获取资源请求头信息。 |
| getRequestUrl(): string | 获取资源请求的URL信息。 |
| isMainFrame(): boolean | 判断资源请求是否为主frame。 |
| isRedirect(): boolean | 判断资源请求是否被服务端重定向。 |
| isRequestGesture(): boolean | 获取资源请求是否与手势（如点击）相关联。 |
获取资源请求是否与手势（如点击）相关联。
## Header对象说明
**返回值：**
| 类型 | 说明 |
| ------- | -------------------- |
| boolean | 返回资源请求是否与手势（如点击）相关联。 |
## Header
Web组件返回的请求/响应头对象。
| 参数名称 | 参数类型 | 参数描述 |
| 名称 | 类型 | 描述 |
| ----------- | ------ | ------------- |
| headerKey | string | 请求/响应头的key。 |
| headerValue | string | 请求/响应头的value。 |
## WebResourceResponse
## WebResourceResponse对象说明
web组件资源响应对象。示例代码参考[onHttpErrorReceive事件](#onhttperrorreceive)。
| 接口名称 | 功能描述 |
| ---------------------------------------- | ------------------ |
| getReasonMessage(): string | 获取资源响应的状态码描述。 |
| getResponseCode(): number | 获取资源响应的状态码。 |
| getResponseData(): string | 获取资源响应数据。 |
| getResponseEncoding(): string | 获取资源响应的编码。 |
| getResponseHeader(): Array\<[Header](#header对象说明)\> | 获取资源响应头。 |
| getResponseMimeType(): string | 获取资源响应的媒体（MIME）类型。 |
### getReasonMessage
## RenderExitReason枚举说明
getReasonMessage(): string
onRenderExited接口返回的渲染进程退出的具体原因。
获取资源响应的状态码描述。
| 名称 | 描述 |
| ---------------------------- | ----------------- |
| PROCESS_ABNORMAL_TERMINATION | 渲染进程异常退出。 |
| PROCESS_WAS_KILLED | 收到SIGKILL，或被手动终止。 |
| PROCESS_CRASHED | 渲染进程崩溃退出，如段错误。 |
| PROCESS_OOM | 程序内存不足。 |
| PROCESS_EXIT_UNKNOWN | 其他原因。 |
**返回值：**
| 类型 | 说明 |
| ------ | ------------- |
| string | 返回资源响应的状态码描述。 |
## MixedMode枚举说明
### getResponseCode
| 名称 | 描述 |
| ---------- | ---------------------------------- |
| All | 允许加载HTTP和HTTPS混合内容。所有不安全的内容都可以被加载。 |
| Compatible | 混合内容兼容性模式，部分不安全的内容可能被加载。 |
| None | 不允许加载HTTP和HTTPS混合内容。 |
getResponseCode(): number
## CacheMode枚举说明
| 名称 | 描述 |
| ------- | ------------------------------------ |
| Default | 使用未过期的cache加载资源，如果cache中无该资源则从网络中获取。 |
| None | 加载资源使用cache，如果cache中无该资源则从网络中获取。 |
| Online | 加载资源不使用cache，全部从网络中获取。 |
| Only | 只从cache中加载资源。 |
获取资源响应的状态码。
**返回值：**
| 类型 | 说明 |
| ------ | ----------- |
| number | 返回资源响应的状态码。 |
### getResponseData
## FileSelectorResult对象说明
通知Web组件的文件选择结果。
| 接口名称 | 功能描述 |
| ---------------------------------------- | -------------------------------------- |
| handleFileList(fileList: Array\<string>): void | 通知Web组件进行文件选择操作。fileList: 需要进行操作的文件列表。 |
## FileSelectorParam对象说明
| 接口名称 | 功能描述 |
| ----------------------------- | ------------ |
| title(): string | 获取文件选择器标题。 |
| mode(): FileSelectorMode | 获取文件选择器的模式。 |
| accpetType(): Array\<string\> | 获取文件过滤类型。 |
| isCapture(): boolean | 获取是否调用多媒体能力。 |
## FileSelectorMode枚举说明
| 名称 | 描述 |
| ----------------------- | ---------- |
| FILE_OPEN_MODE | 打开上传单个文件。 |
| FILE_OPEN_MULTIPLE_MODE | 打开上传多个文件。 |
| FILE_OPEN_FOLDER_MODE | 打开上传文件夹模式。 |
| FILE_SAVE_MODE | 文件保存模式。 |
getResponseData(): string
获取资源响应数据。
**返回值：**
| 类型 | 说明 |
| ------ | --------- |
| string | 返回资源响应数据。 |
### getResponseEncoding
getResponseEncoding(): string
获取资源响应的编码。
**返回值：**
| 类型 | 说明 |
| ------ | ---------- |
| string | 返回资源响应的编码。 |
### getResponseHeader
getResponseHeader() : Array\<Header\>
获取资源响应头。
**返回值：**
| 类型 | 说明 |
| -------------------------- | -------- |
| Array\<[Header](#header)\> | 返回资源响应头。 |
### getResponseMimeType
getResponseMimeType(): string
获取资源响应的媒体（MIME）类型。
**返回值：**
| 类型 | 说明 |
| ------ | ------------------ |
| string | 返回资源响应的媒体（MIME）类型。 |
## WebController
......@@ -208,29 +1196,102 @@ accessBackward(): boolean
当前页面是否可后退，即当前页面是否有返回历史记录。
**返回值：**
| 类型 | 说明 |
| ------- | --------------------- |
| boolean | 可以后退返回true,否则返回false。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('accessBackward')
.onClick(() => {
let result = this.controller.accessBackward();
console.log('result:' + result);
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### accessForward
accessForward(): boolean
当前页面是否可前进，即当前页面是否有前进历史记录。
**返回值：**
| 类型 | 说明 |
| ------- | --------------------- |
| boolean | 可以前进返回true,否则返回false。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('accessForward')
.onClick(() => {
let result = this.controller.accessForward();
console.log('result:' + result);
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### accessStep
accessStep(step: number): boolean
当前页面是否可前进或者后退给定的step步。
- 参数
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---- | ------ | ---- | ---- | --------------------- |
| step | number | 是 | - | 要跳转的步数，正数代表前进，负数代表后退。 |
- 返回值
| 参数类型 | 说明 |
| ------- | --------- |
| boolean | 页面是否前进或后退 |
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---- | ------ | ---- | ---- | --------------------- |
| step | number | 是 | - | 要跳转的步数，正数代表前进，负数代表后退。 |
**返回值：**
| 类型 | 说明 |
| ------- | --------- |
| boolean | 页面是否前进或后退 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
@State steps: number = 2;
build() {
Column() {
Button('accessStep')
.onClick(() => {
let result = this.controller.accessStep(this.steps);
console.log('result:' + result);
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### backward
......@@ -238,23 +1299,83 @@ backward(): void
按照历史栈，后退一个页面。一般结合accessBackward一起使用。
### deleteJavaScriptRegister
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('backward')
.onClick(() => {
this.controller.backward();
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
deleteJavaScriptRegister(name: string): void
### forward
删除通过registerJavaScriptProxy注册到window上的指定name的应用侧JavaScript对象。
forward(): void
- 参数
按照历史栈，前进一个页面。一般结合accessForward一起使用。
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---- | ------ | ---- | ---- | ---------------------------------------- |
| name | string | 是 | - | 注册对象的名称，可在网页侧JavaScript中通过此名称调用应用侧JavaScript对象。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('forward')
.onClick(() => {
this.controller.forward();
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### forward
### deleteJavaScriptRegister
forward(): void
deleteJavaScriptRegister(name: string)
按照历史栈，前进一个页面。一般结合accessForward一起使用。
删除通过registerJavaScriptProxy注册到window上的指定name的应用侧JavaScript对象。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---- | ------ | ---- | ---- | ---------------------------------------- |
| name | string | 是 | - | 注册对象的名称，可在网页侧JavaScript中通过此名称调用应用侧JavaScript对象。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
@State name: string = 'Object';
build() {
Column() {
Button('deleteJavaScriptRegister')
.onClick(() => {
this.controller.deleteJavaScriptRegister(this.name);
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### getHitTest
......@@ -262,21 +1383,61 @@ getHitTest(): HitTestType
获取当前被点击区域的元素类型。
- HitTestType枚举说明
| 名称 | 描述 |
| ------------- | ------------------------ |
| EditText | 可编辑的区域。 |
| Email | 电子邮件地址。 |
| HttpAnchor | 超链接。其src为http。 |
| HttpAnchorImg | 带有超链接的图片，其中超链接的src为http。 |
| Img | HTML::img标签。 |
| Map | 地理地址。 |
| Unknown | 未知内容。 |
**返回值：**
| 类型 | 说明 |
| ------------------------------- | ----------- |
| [HitTestType](#hittesttype枚举说明) | 被点击区域的元素类型。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('getHitTest')
.onClick(() => {
let hitType = this.controller.getHitTest();
console.log("hitType: " + hitType);
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### requestFocus
requestFocus()
使当前web页面获取焦点。
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('requestFocus')
.onClick(() => {
this.controller.requestFocus();
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### loadData
loadData(options: { data: string, mimeType: string, encoding: string, baseUrl?: string, historyUrl?: string }): void
loadData(options: { data: string, mimeType: string, encoding: string, baseUrl?: string, historyUrl?: string })
baseUrl为空时，通过”data“协议加载指定的一段字符串。
......@@ -284,19 +1445,42 @@ baseUrl为空时，通过”data“协议加载指定的一段字符串。
当baseUrl为“http/https"协议时，编码后的data字符串将被Web组件以类似loadUrl的方式以非编码字符串处理。
- options参数说明
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---------- | ------ | ---- | ---- | ---------------------------------------- |
| data | string | 是 | - | 按照”Base64“或者”URL"编码后的一段字符串。 |
| mimeType | string | 是 | - | 媒体类型（MIME）。 |
| encoding | string | 是 | - | 编码类型，具体为“Base64"或者”URL编码。 |
| baseUrl | string | 否 | - | 指定的一个URL路径（“http”/“https”/"data"协议），并由Web组件赋值给window.origin。 |
| historyUrl | string | 否 | - | 历史记录URL。非空时，可被历史记录管理，实现前后后退功能。当baseUrl为空时，此属性无效。 |
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---------- | ------ | ---- | ---- | ---------------------------------------- |
| data | string | 是 | - | 按照”Base64“或者”URL"编码后的一段字符串。 |
| mimeType | string | 是 | - | 媒体类型（MIME）。 |
| encoding | string | 是 | - | 编码类型，具体为“Base64"或者”URL编码。 |
| baseUrl | string | 否 | - | 指定的一个URL路径（“http”/“https”/"data"协议），并由Web组件赋值给window.origin。 |
| historyUrl | string | 否 | - | 历史记录URL。非空时，可被历史记录管理，实现前后后退功能。当baseUrl为空时，此属性无效。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('loadData')
.onClick(() => {
this.controller.loadData({
data: "<html><body bgcolor=\"white\">Source:<pre>source</pre></body></html>",
mimeType: "text/html",
encoding: "UTF-8"
});
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### loadUrl
loadUrl(options:{ url: string, headers?: Array\<Header\> }): void
loadUrl(options: { url: string | Resource, headers?: Array\<Header\> })
使用指定的http头加载指定的URL。
......@@ -304,12 +1488,31 @@ loadUrl(options:{ url: string, headers?: Array\<Header\> }): void
而通过registerJavaScriptProxy注入的对象，在loadUrl导航到新的页面也会有效。
- options参数说明
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ------- | ------------------------------ | ---- | ---- | -------------- |
| url | string | 是 | - | 需要加载的 URL。 |
| headers | Array\<[Header](#header对象说明)\> | 否 | [] | URL的附加HTTP请求头。 |
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ------- | -------------------------- | ---- | ---- | -------------- |
| url | string | 是 | - | 需要加载的 URL。 |
| headers | Array\<[Header](#header)\> | 否 | [] | URL的附加HTTP请求头。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('loadUrl')
.onClick(() => {
this.controller.loadUrl({ url: 'www.example.com' });
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### onActive
......@@ -317,130 +1520,304 @@ onActive(): void
调用此接口通知Web组件进入前台激活状态。
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('onActive')
.onClick(() => {
this.controller.onActive();
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### onInactive
onInactive(): void
调用此接口通知Web组件进入未激活状态。
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('onInactive')
.onClick(() => {
this.controller.onInactive();
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### refresh
refresh(): void
refresh()
调用此接口通知Web组件刷新网页。
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('refresh')
.onClick(() => {
this.controller.refresh();
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### registerJavaScriptProxy
registerJavaScriptProxy(options: { object: object, name: string, methodList: Array\<string\> }): void
registerJavaScriptProxy(options: { object: object, name: string, methodList: Array\<string\> })
注入JavaScript对象到window对象中，并在window对象中调用该对象的方法。注册后，须调用refresh接口生效。
- options 参数说明
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---------- | --------------- | ---- | ---- | ---------------------------------------- |
| object | object | 是 | - | 参与注册的应用侧JavaScript对象。只能声明方法，不能声明属性 。其中方法的参数和返回类型只能为string，number，boolean |
| name | string | 是 | - | 注册对象的名称，与window中调用的对象名一致。注册后window对象可以通过此名字访问应用侧JavaScript对象。 |
| methodList | Array\<string\> | 是 | - | 参与注册的应用侧JavaScript对象的方法。 |
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---------- | --------------- | ---- | ---- | ---------------------------------------- |
| object | object | 是 | - | 参与注册的应用侧JavaScript对象。只能声明方法，不能声明属性 。其中方法的参数和返回类型只能为string，number，boolean |
| name | string | 是 | - | 注册对象的名称，与window中调用的对象名一致。注册后window对象可以通过此名字访问应用侧JavaScript对象。 |
| methodList | Array\<string\> | 是 | - | 参与注册的应用侧JavaScript对象的方法。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct Index {
controller: WebController = new WebController()
testObj = {
test: (data) => {
return "ArkUI Web Component";
},
toString: () => {
console.log('Web Component toString');
}
}
build() {
Column() {
Row() {
Button('Register JavaScript To Window').onClick(() => {
this.controller.registerJavaScriptProxy({
object: this.testObj,
name: "objName",
methodList: ["test", "toString"],
});
})
}
Web({ src: $rawfile('index.html'), controller: this.controller })
.javaScriptAccess(true)
}
}
}
```
```html
<!-- index.html -->
<!DOCTYPE html>
<html>
<meta charset="utf-8">
<body>
Hello world!
</body>
<script type="text/javascript">
function htmlTest() {
str = objName.test("test function");
console.log('objName.test result:'+ str);
}
</script>
</html>
```
### runJavaScript
runJavaScript(options: { script: string, callback?: (result: string) => void }): void
runJavaScript(options: { script: string, callback?: (result: string) => void })
异步执行JavaScript脚本，并通过回调方式返回脚本执行的结果。runJavaScript需要在loadUrl完成后，比如onPageEnd中调用。
- options参数说明
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| -------- | ------------------------ | ---- | ---- | ---------------------------------------- |
| script | string | 是 | - | JavaScript脚本。 |
| callback | (result: string) => void | 否 | - | 回调执行JavaScript脚本结果。JavaScript脚本若执行失败或无返回值时，返回null。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
@State webResult: string = ''
build() {
Column() {
Text(this.webResult).fontSize(20)
Web({ src: $rawfile('index.html'), controller: this.controller })
.javaScriptAccess(true)
.onPageEnd(e => {
this.controller.runJavaScript({
script: 'test()',
callback: (result: string)=> {
this.webResult = result
console.info(`The test() return value is: ${result}`)
}});
console.info('url: ', e.url);
})
}
}
}
```
```html
<!-- index.html -->
<!DOCTYPE html>
<html>
<meta charset="utf-8">
<body>
Hello world!
</body>
<script type="text/javascript">
function test() {
console.log('Ark WebComponent');
return "This value is from index.html"
}
</script>
</html>
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| -------- | ------------------------ | ---- | ---- | ---------------------------------------- |
| script | string | 是 | - | JavaScript脚本。 |
| callback | (result: string) => void | 否 | - | 回调执行JavaScript脚本结果。JavaScript脚本若执行失败或无返回值时，返回null。 |
```
### stop
stop(): void
stop()
停止页面加载。
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('stop')
.onClick(() => {
this.controller.stop();
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### zoom
zoom(factor: number): void
调整当前网页的缩放比例。
**参数：**
| 参数名 | 参数类型 | 必填 | 参数描述 |
| ------ | ------ | ---- | ------------------------------ |
| factor | number | 是 | 基于当前网页所需调整的相对缩放比例，正值为放大，负值为缩小。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
@State factor: number = 1;
build() {
Column() {
Button('zoom')
.onClick(() => {
this.controller.zoom(this.factor);
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### clearHistory
clearHistory(): void
删除所有前进后退记录。
### getCookieManager
getCookieManager(): WebCookie
获取web组件cookie管理对象。
- 返回值
| 参数类型 | 说明 |
| --------- | ---------------------------------------- |
| WebCookie | web组件cookie管理对象，参考[WebCookie](#webcookie)定义。 |
## WebCookie
通过WebCookie可以控制Web组件中的cookie的各种行为，其中每个应用中的所有web组件共享一个WebCookie。通过controller方法中的getCookieManager方法可以获取WebCookie对象，进行后续的cookie管理操作。
### setCookie
setCookie(url: string, value: string): boolean
设置cookie，该方法为同步方法。设置成功返回true，否则返回false。
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('clearHistory')
.onClick(() => {
this.controller.clearHistory();
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
- 参数说明
## MessageLevel枚举说明
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ----- | ------ | ---- | ---- | ----------------- |
| url | string | 是 | - | 要设置的cookie所属的url。 |
| value | string | 是 | - | cookie的值。 |
- 返回值
| 参数类型 | 说明 |
| ------- | ------------- |
| boolean | 设置cookie是否成功。 |
| 名称 | 描述 |
| ----- | :---- |
| Debug | 调试级别。 |
| Error | 错误级别。 |
| Info | 消息级别。 |
| Log | 日志级别。 |
| Warn | 警告级别。 |
### saveCookieSync
saveCookieSync(): boolean
## MixedMode枚举说明
将当前存在内存中的cookie同步到磁盘中，该方法为同步方法。
- 返回值
| 参数类型 | 说明 |
| ------- | -------------------- |
| boolean | 同步内存cookie到磁盘操作是否成功。 |
## 示例
| 名称 | 描述 |
| ---------- | ---------------------------------- |
| All | 允许加载HTTP和HTTPS混合内容。所有不安全的内容都可以被加载。 |
| Compatible | 混合内容兼容性模式，部分不安全的内容可能被加载。 |
| None | 不允许加载HTTP和HTTPS混合内容。 |
```
// webComponent.ets
@Entry
@Component
struct WebComponent {
@State javaScriptAccess: boolean = true;
@State fileAccess: boolean = true;
controller: WebController = new WebController();
build() {
Column() {
Web({ src: $rawfile('index.html'), controller: this.controller })
.javaScriptAccess(this.javaScriptAccess)
.fileAccess(this.fileAccess)
.onPageEnd(e => {
// test() 在 index.html 中已定义
this.controller.runJavaScript({ script: 'test()' });
console.log("url: ", e.url);
})
}
}
}
```
```
<!-- index.html -->
<!DOCTYPE html>
<html>
<meta charset="utf-8">
<body>
Hello world!
</body>
<script type="text/javascript">
function test() {
console.log('Ark WebComponent');
}
</script>
</html>
```
![](figures/Web.png)
\ No newline at end of file
## CacheMode枚举说明
| 名称 | 描述 |
| ------- | ------------------------------------ |
| None | 加载资源使用cache，如果cache中无该资源则从网络中获取。 |
| Online | 加载资源不使用cache，全部从网络中获取。 |
| Only | 只从cache中加载资源。 |
zh-cn/application-dev/reference/js-service-widget-ui/Readme-CN.md 0 → 100644
浏览文件 @ 3035f58a
# JS服务卡片页面开发
- JS服务卡片页面框架说明
- [文件组织](js-service-widget-file.md)
- [配置文件](js-service-widget-config-file.md)
- 语法
- [HML语法参考](js-service-widget-syntax-hml.md)
- [CSS语法参考](js-service-widget-syntax-css.md)
- [配置数据和事件](js-service-widget-configuration.md)
- [多语言支持](js-service-widget-multiple-languages.md)
- [低版本兼容](js-service-widget-version-compatibility.md)
- 组件
- 通用
- [通用属性](js-service-widget-common-attributes.md)
- [通用样式](js-service-widget-common-styles.md)
- [通用事件](js-service-widget-common-events.md)
- [渐变样式](js-service-widget-common-gradient.md)
- [媒体查询](js-service-widget-common-mediaquery.md)
- [自定义字体样式](js-service-widget-common-customizing-font.md)
- [无障碍](js-service-widget-common-accessibility.md)
- [原子布局](js-service-widget-common-atomic-layout.md)
- 容器组件
- [div](js-service-widget-container-div.md)
- [list](js-service-widget-container-list.md)
- [list-item](js-service-widget-container-list-item.md)
- [stack](js-service-widget-container-stack.md)
- [swiper](js-service-widget-container-swiper.md)
- 基础组件
- [button](js-service-widget-basic-button.md)
- [calendar](js-service-widget-basic-calendar.md)
- [chart](js-service-widget-basic-chart.md)
- [clock](js-service-widget-basic-clock.md)
- [divider](js-service-widget-basic-divider.md)
- [image](js-service-widget-basic-image.md)
- [input](js-service-widget-basic-input.md)
- [progress](js-service-widget-basic-progress.md)
- [span](js-service-widget-basic-span.md)
- [text](js-service-widget-basic-text.md)
- 自定义组件
- [自定义组件基本用法](js-service-widget-custom-basic-usage.md)
- [自定义事件](js-service-widget-custom-events.md)
- [Props](js-service-widget-custom-props.md)
- [数据类型说明](js-service-widget-appendix-types.md)
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-appendix-types.md 0 → 100644
浏览文件 @ 3035f58a
# 数据类型说明
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 长度类型
| 名称 | 类型定义 | 描述 |
| -------- | -------- | -------- |
| length | string&nbsp;\|&nbsp;number | 用于描述尺寸单位，输入为number类型时，使用px单位。输入为string类型时，需要显式指定像素单位，当前支持的像素单位有：<br/>-&nbsp;px：逻辑尺寸单位。<br/>-&nbsp;fp：字体尺寸单位，随系统字体大小设置发生变化，仅支持文本类组件设置相应的字体大小。 |
| percentage | string | 百分比尺寸单位，如“50%”。 |
## 颜色类型
| 名称 | 类型定义 | 描述 |
| -------- | -------- | -------- |
| color | string&nbsp;\|颜色枚举 | 用于描述颜色信息。<br/>&nbsp;&nbsp;字符串格式如下：<br/>-&nbsp;'rgb(255,&nbsp;255,&nbsp;255)'。<br/>-&nbsp;'rgba(255,&nbsp;255,&nbsp;255,&nbsp;1.0)'。<br/>-&nbsp;HEX格式：'\#rrggbb'，'\#aarrggbb'。<br/>-&nbsp;枚举格式：'black'，'white'。<br/>JS脚本中不支持颜色枚举格式。 |
**表1** 当前支持的颜色枚举
| 枚举名称 | 对应颜色 | 颜色 |
| -------- | -------- | -------- |
| aliceblue | \#f0f8ff | ![aliceblue](figures/aliceblue.png) |
| antiquewhite | \#faebd7 | ![antiquewhite](figures/antiquewhite.png) |
| aqua | \#00ffff | ![aqua](figures/aqua.png) |
| aquamarine | \#7fffd4 | ![aquamarine](figures/aquamarine.png) |
| azure | \#f0ffff | ![azure](figures/azure.png) |
| beige | \#f5f5dc | ![beige](figures/beige.png) |
| bisque | \#ffe4c4 | ![bisque](figures/bisque.png) |
| black | \#000000 | ![#000000](figures/#000000.png) |
| blanchedalmond | \#ffebcd | ![blanchedalmond](figures/blanchedalmond.png) |
| blue | \#0000ff | ![blue](figures/blue.png) |
| blueviolet | \#8a2be2 | ![blueviolet](figures/blueviolet.png) |
| brown | \#a52a2a | ![brown](figures/brown.png) |
| burlywood | \#deB887 | ![burlywood](figures/burlywood.png) |
| cadetblue | \#5f9ea0 | ![cadetblue](figures/cadetblue.png) |
| chartreuse | \#7fff00 | ![chartreuse](figures/chartreuse.png) |
| chocolate | \#d2691e | ![chocolate](figures/chocolate.png) |
| coral | \#ff7f50 | ![coral](figures/coral.png) |
| cornflowerblue | \#6495ed | ![cornflowerblue](figures/cornflowerblue.png) |
| cornsilk | \#fff8dc | ![cornsilk](figures/cornsilk.png) |
| crimson | \#dc143c | ![crimson](figures/crimson.png) |
| cyan | \#00ffff | ![cyan](figures/cyan.png) |
| darkblue | \#00008b | ![darkblue](figures/darkblue.png) |
| darkcyan | \#008b8b | ![darkcyan](figures/darkcyan.png) |
| darkgoldenrod | \#b8860b | ![darkgoldenrod](figures/darkgoldenrod.png) |
| darkgray | \#a9a9a9 | ![darkgray](figures/darkgray.png) |
| darkgreen | \#006400 | ![darkgreen](figures/darkgreen.png) |
| darkgrey | \#a9a9a9 | ![darkgrey](figures/darkgrey.png) |
| darkkhaki | \#bdb76b | ![darkkhaki](figures/darkkhaki.png) |
| darkmagenta | \#8b008b | ![darkmagenta](figures/darkmagenta.png) |
| darkolivegreen | \#556b2f | ![darkolivegreen](figures/darkolivegreen.png) |
| darkorange | \#ff8c00 | ![darkorange](figures/darkorange.png) |
| darkorchid | \#9932cc | ![darkorchid](figures/darkorchid.png) |
| darkred | \#8b0000 | ![darkred](figures/darkred.png) |
| darksalmon | \#e9967a | ![darksalmon](figures/darksalmon.png) |
| darkseagreen | \#8fbc8f | ![darkseagreen](figures/darkseagreen.png) |
| darkslateblue | \#483d8b | ![darkslateblue](figures/darkslateblue.png) |
| darkslategray | \#2f4f4f | ![darkslategray](figures/darkslategray.png) |
| darkslategrey | \#2f4f4f | ![darkslategrey](figures/darkslategrey.png) |
| darkturquoise | \#00ced1 | ![darkturquoise](figures/darkturquoise.png) |
| darkviolet | \#9400d3 | ![darkviolet](figures/darkviolet.png) |
| deeppink | \#ff1493 | ![deeppink](figures/deeppink.png) |
| deepskyblue | \#00bfff | ![deepskyblue](figures/deepskyblue.png) |
| dimgray | \#696969 | ![dimgray](figures/dimgray.png) |
| dimgrey | \#696969 | ![dimgrey](figures/dimgrey.png) |
| dodgerblue | \#1e90ff | ![dodgerblue](figures/dodgerblue.png) |
| firebrick | \#b22222 | ![firebrick](figures/firebrick.png) |
| floralwhite | \#fffaf0 | ![floralwhite](figures/floralwhite.png) |
| forestgreen | \#228b22 | ![forestgreen](figures/forestgreen.png) |
| fuchsia | \#ff00ff | ![fuchsia](figures/fuchsia.png) |
| gainsboro | \#dcdcdc | ![gainsboro](figures/gainsboro.png) |
| ghostwhite | \#f8f8ff | ![ghostwhite](figures/ghostwhite.png) |
| gold | \#ffd700 | ![gold](figures/gold.png) |
| goldenrod | \#daa520 | ![goldenrod](figures/goldenrod.png) |
| gray | \#808080 | ![gray](figures/gray.png) |
| green | \#008000 | ![green](figures/green.png) |
| greenyellow | \#adff2f | ![greenyellow](figures/greenyellow.png) |
| grey | \#808080 | ![grey](figures/grey.png) |
| honeydew | \#f0fff0 | ![honeydew](figures/honeydew.png) |
| hotpink | \#ff69b4 | ![hotpink](figures/hotpink.png) |
| indianred | \#cd5c5c | ![indianred](figures/indianred.png) |
| indigo | \#4b0082 | ![indigo](figures/indigo.png) |
| ivory | \#fffff0 | ![ivory](figures/ivory.png) |
| khaki | \#f0e68c | ![khaki](figures/khaki.png) |
| lavender | \#e6e6fa | ![lavender](figures/lavender.png) |
| lavenderblush | \#fff0f5 | ![lavenderblush](figures/lavenderblush.png) |
| lawngreen | \#7cfc00 | ![lawngreen](figures/lawngreen.png) |
| lemonchiffon | \#fffacd | ![lemonchiffon](figures/lemonchiffon.png) |
| lightblue | \#add8e6 | ![lightblue](figures/lightblue.png) |
| lightcoral | \#f08080 | ![lightcoral](figures/lightcoral.png) |
| lightcyan | \#e0ffff | ![lightcyan](figures/lightcyan.png) |
| lightgoldenrodyellow | \#fafad2 | ![lightgoldenrodyellow](figures/lightgoldenrodyellow.png) |
| lightgray | \#d3d3d3 | ![lightgray](figures/lightgray.png) |
| lightgreen | \#90ee90 | ![lightgreen](figures/lightgreen.png) |
| lightpink | \#ffb6c1 | ![lightpink](figures/lightpink.png) |
| lightsalmon | \#ffa07a | ![lightsalmon](figures/lightsalmon.png) |
| lightseagreen | \#20b2aa | ![lightseagreen](figures/lightseagreen.png) |
| lightskyblue | \#87cefa | ![lightskyblue](figures/lightskyblue.png) |
| lightslategray | \#778899 | ![lightslategray](figures/lightslategray.png) |
| lightslategrey | \#778899 | ![lightslategrey](figures/lightslategrey.png) |
| lightsteelblue | \#b0c4de | ![lightsteelblue](figures/lightsteelblue.png) |
| lightyellow | \#ffffe0 | ![lightyellow](figures/lightyellow.png) |
| lime | \#00ff00 | ![lime](figures/lime.png) |
| limegreen | \#32cd32 | ![limegreen](figures/limegreen.png) |
| linen | \#faf0e6 | ![linen](figures/linen.png) |
| magenta | \#ff00ff | ![magenta](figures/magenta.png) |
| maroon | \#800000 | ![maroon](figures/maroon.png) |
| mediumaquamarine | \#66cdaa | ![mediumaquamarine](figures/mediumaquamarine.png) |
| mediumblue | \#0000cd | ![mediumblue](figures/mediumblue.png) |
| mediumorchid | \#ba55d3 | ![mediumorchid](figures/mediumorchid.png) |
| mediumpurple | \#9370db | ![mediumpurple](figures/mediumpurple.png) |
| mediumseagreen | \#3cb371 | ![mediumseagreen](figures/mediumseagreen.png) |
| mediumslateblue | \#7b68ee | ![mediumslateblue](figures/mediumslateblue.png) |
| mediumspringgreen | \#00fa9a | ![mediumspringgreen](figures/mediumspringgreen.png) |
| mediumturquoise | \#48d1cc | ![mediumturquoise](figures/mediumturquoise.png) |
| mediumvioletred | \#c71585 | ![mediumvioletred](figures/mediumvioletred.png) |
| midnightblue | \#191970 | ![midnightblue](figures/midnightblue.png) |
| mintcream | \#f5fffa | ![mintcream](figures/mintcream.png) |
| mistyrose | \#ffe4e1 | ![mistyrose](figures/mistyrose.png) |
| moccasin | \#ffe4b5 | ![moccasin](figures/moccasin.png) |
| navajowhite | \#ffdead | ![navajowhite](figures/navajowhite.png) |
| navy | \#000080 | ![navy](figures/navy.png) |
| oldlace | \#fdf5e6 | ![oldlace](figures/oldlace.png) |
| olive | \#808000 | ![olive](figures/olive.png) |
| olivedrab | \#6b8e23 | ![olivedrab](figures/olivedrab.png) |
| orange | \#ffa500 | ![orange](figures/orange.png) |
| orangered | \#ff4500 | ![orangered](figures/orangered.png) |
| orchid | \#da70d6 | ![orchid](figures/orchid.png) |
| palegoldenrod | \#eee8aa | ![palegoldenrod](figures/palegoldenrod.png) |
| palegreen | \#98fb98 | ![palegreen](figures/palegreen.png) |
| paleturquoise | \#afeeee | ![paleturquoise](figures/paleturquoise.png) |
| palevioletred | \#db7093 | ![palevioletred](figures/palevioletred.png) |
| papayawhip | \#ffefd5 | ![papayawhip](figures/papayawhip.png) |
| peachpuff | \#ffdab9 | ![peachpuff](figures/peachpuff.png) |
| peru | \#cd853f | ![peru](figures/peru.png) |
| pink | \#ffc0cb | ![pink](figures/pink.png) |
| plum | \#dda0dd | ![plum](figures/plum.png) |
| powderblue | \#b0e0e6 | ![powderblue](figures/powderblue.png) |
| purple | \#800080 | ![purple](figures/purple.png) |
| rebeccapurple | \#663399 | ![rebeccapurple](figures/rebeccapurple.png) |
| red | \#ff0000 | ![red](figures/red.png) |
| rosybrown | \#bc8f8f | ![rosybrown](figures/rosybrown.png) |
| royalblue | \#4169e1 | ![royalblue](figures/royalblue.png) |
| saddlebrown | \#8b4513 | ![saddlebrown](figures/saddlebrown.png) |
| salmon | \#fa8072 | ![salmon](figures/salmon.png) |
| sandybrown | \#f4a460 | ![sandybrown](figures/sandybrown.png) |
| seagreen | \#2e8b57 | ![seagreen](figures/seagreen.png) |
| seashell | \#fff5ee | ![seashell](figures/seashell.png) |
| sienna | \#a0522d | ![sienna](figures/sienna.png) |
| silver | \#c0c0c0 | ![silver](figures/silver.png) |
| skyblue | \#87ceeb | ![skyblue](figures/skyblue.png) |
| slateblue | \#6a5acd | ![slateblue](figures/slateblue.png) |
| slategray | \#708090 | ![slategray](figures/slategray.png) |
| slategrey | \#708090 | ![slategray](figures/slategray.png) |
| snow | \#fffafa | ![snow](figures/snow.png) |
| springgreen | \#00ff7f | ![springgreen](figures/springgreen.png) |
| steelblue | \#4682b4 | ![steelblue](figures/steelblue.png) |
| tan | \#d2b48c | ![tan](figures/tan.png) |
| teal | \#008080 | ![teal](figures/teal.png) |
| thistle | \#d8Bfd8 | ![thistle](figures/thistle.png) |
| tomato | \#ff6347 | ![tomato](figures/tomato.png) |
| turquoise | \#40e0d0 | ![turquoise](figures/turquoise.png) |
| violet | \#ee82ee | ![violet](figures/violet.png) |
| wheat | \#f5deb3 | ![wheat](figures/wheat.png) |
| white | \#ffffff | ![white](figures/white.png) |
| whitesmoke | \#f5f5f5 | ![whitesmoke](figures/whitesmoke.png) |
| yellow | \#ffff00 | ![yellow](figures/yellow.png) |
| yellowgreen | \#9acd32 | ![yellowgreen](figures/yellowgreen.png) |
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-button.md 0 → 100644
浏览文件 @ 3035f58a
# button
按钮组件，包括胶囊按钮、圆形按钮和文本按钮。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| type | string | - | 否 | 不支持动态修改。如果该属性缺省，展示类胶囊型按钮，不同于胶囊类型，四边圆角可以通过border-radius分别指定，如果需要设置该属性，可选值如下：<br/>-&nbsp;"capsule"：胶囊型按钮，带圆角按钮，有背景色和文本。<br/>-&nbsp;"circle"：圆形按钮，支持放置图标。<br/>-&nbsp;"text"：文本按钮，仅包含文本显示。 |
| value | string | - | 否 | button的文本值，circle类型不生效。 |
| icon | string | - | 否 | button的图标路径，图标格式为jpg，png和svg。 |
| placement | string | end | 否 | 仅在type属性为缺省时生效，设置图标位于文本的位置，可选值为：<br/>-&nbsp;"start"：图标位于文本起始处。<br/>-&nbsp;"end"：图标位于文本结束处。<br/>-&nbsp;"top"：图标位于文本上方。<br/>-&nbsp;"bottom"：图标位于文本下方。 |
| waiting | boolean | false | 否 | 是否处于waiting状态，值为true时展现等待中转圈效果，位于文本左侧。 |
## 事件
支持[通用事件](js-service-widget-common-events.md)。
## 样式
除支持[通用样式](js-service-widget-common-styles.md)外，还支持如下样式：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| text-color | &lt;color&gt; | - | 否 | 按钮的文本颜色。 |
| font-size | &lt;length&gt; | - | 否 | 按钮的文本尺寸。 |
| font-style | string | normal | 否 | 按钮的字体样式。 |
| font-weight | number&nbsp;\|&nbsp;string | normal | 否 | 按钮的字体粗细，见[text组件font-weight的样式属性](js-service-widget-basic-text.md#样式)。 |
| font-family | &lt;string&gt; | sans-serif | 否 | 按钮的字体列表，用逗号分隔，每个字体用字体名或者字体族名设置。列表中第一个系统中存在的或者通过[自定义字体](js-service-widget-common-customizing-font.md)指定的字体，会被选中作为文本的字体。 |
| icon-width | &lt;length&gt; | - | 否 | 设置圆形按钮内部图标的宽，默认填满整个圆形按钮。<br/>icon使用svg图源时必须设置该样式。 |
| icon-height | &lt;length&gt; | - | 否 | 设置圆形按钮内部图标的高，默认填满整个圆形按钮。<br/>icon使用svg图源时必须设置该样式。 |
| radius | &lt;length&gt; | - | 否 | 圆形按钮半径或者胶囊按钮圆角半径。在圆形按钮类型下该样式优先于通用样式的width和height样式。 |
> **说明：**
> - 胶囊按钮（type=capsule）时，不支持border相关样式。
>
> - 圆形按钮（type=circle）时，不支持文本相关样式。
>
> - 文本按钮（type=text）时，自适应文本大小，不支持尺寸设置（radius，width，height），背景透明不支持background-color样式。
## 示例
```html
<!-- xxx.hml -->
<div class="div-button">
<button class="button" type="capsule" value="Capsule button"></button>
<button class="button circle" type="circle" icon="common/ic_add_default.png"></button>
<button class="button text" type="text">Text button</button>
</div>
```
```css
/* xxx.css */
.div-button {
flex-direction: column;
align-items: center;
}
.button {
margin-top: 15px;
}
.circle {
background-color: #007dff;
radius: 72px;
icon-width: 72px;
icon-height: 72px;
}
.text {
text-color: red;
font-size: 40px;
font-weight: 900;
font-family: sans-serif;
font-style: normal;
}
```
**4*4卡片**
![button](figures/button.jpg)
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-calendar.md 0 → 100644
浏览文件 @ 3035f58a
# calendar
日历组件，用于呈现日历界面。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| date | string | 当前日期 | 否 | 当前页面选中的日期，默认是当前日期，格式为年-月-日，如"2019-11-22"。 |
| cardcalendar | bool | false | 否 | 标识当前日历是否为卡片日历。 |
| startdayofweek | int | 6 | 否 | 标识卡片显示的起始天，默认是星期天（取值范围：0-6）。 |
| offdays | string | 5，6 | 否 | 标识卡片显示的休息日，默认是星期六、星期天（取值范围：0-6）。 |
| calendardata | string | - | 是 | 卡片需要显示的月视图数据信息，包括5\*7或者6\*7格的日数据信息，格式为JSON字符串。"data"标签属性信息见**表1** calendardata的日属性。 |
| showholiday | bool | true | 否 | 标识当前是否显示节假日信息。 |
**表1** calendardata的日属性
| 名称 | 类型 | 描述 |
| -------- | -------- | -------- |
| index | int | 数据的索引，表示第几个日期。 |
| day | int | 表示具体哪一天。 |
| month | int | 表示月份。 |
| year | int | 表示年份。 |
| isFirstOfLuanr | bool | 表示是否是农历的第一天，在农历第一天的数据下绘制横线。 |
| hasSchedule | bool | 表示是否有日程，在有日程的日期数据上绘制圆。 |
| markLunarDay | bool | 表示节假日，农历数据会变成蓝色。 |
| lunarDay | string | 农历日期。 |
| lunarMonth | string | 农历月份。 |
| dayMark | string | 表示工作日。<br>- “work”：工作日。<br>- “off”：休息日。 |
| dayMarkValue | string | 表示具体需要显示的“班”、“休”信息。 |
calendardata示例：
```json
{
"year":2021,
"month":1,
"data": [{
"index": 0,
"lunarMonth": "十一",
"lunarDay": "十三",
"year": 2020,
"month ": 12,
"day": 27,
"dayMark": "work",
"dayMarkValue": "班",
"isFirstOfLunar": true,
"hasSchedule": true,
"markLunarDay": true
}, {
"index": 1,
"lunarMonth": "十一",
"lunarDay": "十四",
"year": 2020,
"month ": 12,
"day": 28,
"dayMark": "work",
"dayMarkValue": "班",
"isFirstOfLunar": true,
"hasSchedule": true,
"markLunarDay": true
}, {
"index": 2,
"lunarMonth": "十一",
"lunarDay": "十五",
"year": 2020,
"month ": 12,
"day": 29,
"dayMark": "work",
"dayMarkValue": "班",
"isFirstOfLunar": true,
"hasSchedule": true,
"markLunarDay": true
},
...
]
}
```
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| selectedchange | changeEvent | 在点击日期和上下月跳转时触发。 |
| requestdata | requestEvent | 请求日期时触发。 |
**表2** changeEvent
| 名称 | 类型 | 描述 |
| -------- | -------- | -------- |
| $event.day | string | 选择的日期。 |
| $event.month | string | 选择的月份。 |
| $event.year | string | 选择的年份。 |
**表3** requestEvent
| 名称 | 类型 | 描述 |
| -------- | -------- | -------- |
| $event.month | string | 请求的月份。 |
| $event.year | string | 请求的年份。 |
| $event.currentYear | string | 当前显示的年份。 |
| $event.currentMonth | string | 当前显示的月份。 |
## 示例
```html
<!-- xxx.hml -->
<div class="container">
<calendar class="container_test"
cardcalendar="true"
onselectedchange="clickOneDay"
onrequestdata="messageEventData"
date="{{currentDate}}"
offdays="{{offDays}}"
showholiday="{{showHoliday}}"
startdayofweek="{{startDayOfWeek}}"
calendardata="{{calendarData}}">
</calendar>
</div>
```
```css
/* xxx.css */
.container {
flex-direction:column;
width: 100%;
height: 100%;
align-items:center;
padding-start: 4px;
padding-end: 4px;
}
.container_test {
background-color: white;
}
```
```json
// xxx.json
{
"data": {
"currentDate": "",
"offDays": "",
"startDayOfWeek": 6,
"showHoliday": true,
"calendarData": ""
},
"actions": {
"clickOneDay": {
"action": "router",
"bundleName": "com.example.calendar",
"abilityName": "com.example.calendar.MainAbility",
"params": {
"action": "click_month_view_event",
"day": "$event.day",
"month": "$event.month",
"year": "$event.year"
}
},
"messageEventData": {
"action": "message",
"params": {
"month": "$event.month",
"year": "$event.year",
"currentMonth": "$event.currentMonth",
"currentYear": "$event.currentYear"
}
}
}
}
```
**4*4卡片**
![zh-cn_image_0000001231452477](figures/zh-cn_image_0000001231452477.png)
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-chart.md 0 → 100644
浏览文件 @ 3035f58a
# chart
图表组件，用于呈现线形图、柱状图、量规图界面。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| type | string | line | 否 | 设置图表类型（不支持动态修改），可选项有：<br/>-&nbsp;bar：柱状图。<br/>-&nbsp;line：线形图。<br/>-&nbsp;gauge：量规图。<br/>-&nbsp;progress：进度类圆形图表。<br/>-&nbsp;loading：加载类圆形图表。<br/>-&nbsp;rainbow：占比类圆形图表。 |
| options | ChartOptions | - | 否 | 图表参数设置，柱状图和线形图必须设置参数设置，量规图不生效。可以设置x轴、y轴的最小值、最大值、刻度数、是否显示，线条宽度、是否平滑等。（不支持动态修改） |
| datasets | Array\<ChartDataset> | - | 否 | 数据集合，柱状图和线形图必须设置数据集合，量规图不生效。可以设置多条数据集及其背景色。 |
| segments | DataSegment \| Array\<DataSegment> | | 否 | 进度类、加载类和占比类圆形图表使用的数据结构。<br/>DataSegment针对进度类和加载类圆形图表使用，Array\<DataSegment>针对占比类图标使用，DataSegment最多9个。 |
| effects | boolean | true | 否 | 是否开启占比类、进度类圆形图表特效。 |
| animationduration | number | 3000 | 否 | 设置占比类圆形图表展开动画时长，单位为ms。 |
**表1** ChartOptions
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| xAxis | ChartAxis | - | 是 | x轴参数设置。可以设置x轴最小值、最大值、刻度数以及是否显示。 |
| yAxis | ChartAxis | - | 是 | y轴参数设置。可以设置y轴最小值、最大值、刻度数以及是否显示。 |
| series | ChartAxis | - | 否 | 数据序列参数设置，仅线形图支持。可以设置：<br>- 线的样式，如线宽、是否平滑。<br>- 线最前端位置白点的样式和大小。 |
**表2** ChartDataset
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| strokeColor | &lt;color&gt; | \#ff6384 | 否 | 线条颜色，仅线形图支持。 |
| fillColor | &lt;color&gt; | \#ff6384 | 否 | 填充颜色，线形图表示填充的渐变颜色。 |
| data | Array&lt;number&gt;&nbsp;\|&nbsp;Array\<Point&gt; | - | 是 | 设置绘制线或柱中的点集。 |
| gradient | boolean | false | 否 | 设置是否显示填充渐变颜色，仅线形图支持。 |
**表3** ChartAxis
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| min | number | 0 | 否 | 轴的最小值，不支持负数，仅线形图支持。 |
| max | number | 100 | 否 | 轴的最大值，不支持负数，仅线形图支持。 |
| axisTick | number | 10 | 否 | 轴显示的刻度数量。<br/>仅支持1~20，且具体显示的效果与如下计算值有关（图的宽度所占的像素/（max-min））。在柱状图中，每组数据显示的柱子数量与刻度数量一致，且柱子显示在刻度处。 |
| display | boolean | false | 否 | 是否显示轴。 |
| color | &lt;color&gt; | \#c0c0c0 | 否 | 轴颜色。 |
**表4** ChartSeries
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| lineStyle | ChartLineStyle | - | 否 | 线样式设置，如线宽、是否平滑。 |
| headPoint | PointStyle | - | 否 | 线最前端位置白点的样式和大小。 |
| topPoint | PointStyle | - | 否 | 最高点的样式和大小。 |
| bottomPoint | PointStyle | - | 否 | 最低点的样式和大小。 |
| loop | ChartLoop | - | 否 | 设置屏幕显示满时，是否需要重头开始绘制。 |
**表5** ChartLineStyle
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| width | &lt;length&gt; | 1px | 否 | 线宽设置。 |
| smooth | boolean | false | 否 | 是否平滑。 |
**表6** PointStyle
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| shape | string | circle | 否 | 高亮点的形状。可选值为：<br/>-&nbsp;circle：圆形。<br/>-&nbsp;square：方形。<br/>-&nbsp;triangle：三角形。 |
| size | &lt;length&gt; | 5px | 否 | 高亮点的大小。 |
| strokeWidth | &lt;length&gt; | 1px | 否 | 边框宽度。 |
| strokeColor | &lt;color&gt; | \#ff0000 | 否 | 边框颜色。 |
| fillColor | &lt;color&gt; | \#ff0000 | 否 | 填充颜色。 |
**表7** ChartLoop
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| margin | &lt;length&gt; | 1 | 否 | 擦除点的个数（最新绘制的点与最老的点之间的横向距离）。<br>margin和topPoint/bottomPoint/headPoint同时使用时，有概率出现point正好位于擦除区域的情况，导致point不可见，因此不建议同时使用。 |
| gradient | boolean | false | 否 | 是否需要渐变擦除。 |
**表8** Point
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| value | number | 0 | 是 | 表示绘制点的Y轴坐标。 |
| pointStyle | PointStyle | - | 否 | 表示当前数据点的绘制样式。 |
| description | string | - | 否 | 表示当前点的注释内容。 |
| textLocation | string | - | 否 | 可选值为：<br>- "top"：注释的绘制位置位于点的上方。<br>- "bottom"：注释的绘制位置位于点的下方。<br>- "none"：不绘制。 |
| textColor | &lt;color&gt; | \#000000 | 否 | 表示注释文字的颜色。 |
| lineDash | string | solid | 否 | 表示绘制当前线段虚线的样式。<br>- "dashed，&nbsp;5，&nbsp;5"：表示纯虚线，绘制5px的实线后留5px的空白。<br>- “solid”：表示绘制实线。 |
| lineColor | &lt;color&gt; | \#000000 | 否 | 表示绘制当前线段的颜色。此颜色不设置会默认使用整体的strokeColor。 |
**表9** DataSegment
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| startColor | Color | - | 否 | 起始位置的颜色，设置startColor必须设置endColor。不设置startColor时，会使用系统默认预置的颜色数组，具体颜色值见下表。 |
| endColor | Color | - | 否 | 终止位置的颜色，设置endColor必须设置startColor。<br/>不设置startColor时，会使用系统默认预置的颜色数组。 |
| value | number | 0 | 是 | 占比数据的所占份额，最大100。 |
| name | string | - | 否 | 此类数据的名称。 |
| 数据组 | 主题 | 深色主题 |
| -------- | -------- | -------- |
| 0 | 起始颜色：\#f7ce00，结束颜色：\#f99b11 | 起始颜色：\#d1a738，结束颜色：\#eb933d |
| 1 | 起始颜色：\#f76223，结束颜色：\#f2400a | 起始颜色：\#e67d50，结束颜色：\#d9542b |
| 2 | 起始颜色：\#f772ac，结束颜色：\#e65392 | 起始颜色：\#d5749e，结束颜色：\#d6568d |
| 3 | 起始颜色：\#a575eb，结束颜色：\#a12df7 | 起始颜色：\#9973d1，结束颜色：\#5552d9 |
| 4 | 起始颜色：\#7b79f7，结束颜色：\#4b48f7 | 起始颜色：\#7977d9，结束颜色：\#f99b11 |
| 5 | 起始颜色：\#4b8af3，结束颜色：\#007dff | 起始颜色：\#4c81d9，结束颜色：\#217bd9 |
| 6 | 起始颜色：\#73c1e6，结束颜色：\#4fb4e3 | 起始颜色：\#5ea6d1，结束颜色：\#4895c2 |
| 7 | 起始颜色：\#a5d61d，结束颜色：\#69d14f | 起始颜色：\#91c23a，结束颜色：\#70ba5d |
| 8 | 起始颜色：\#a2a2b0，结束颜色：\#8e8e93 | 起始颜色：\#8c8c99，结束颜色：\#6b6b76 |
当类型为量规图时，还支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| percent | number | 0 | 否 | 当前值占整体的百分比，取值范围为0-100。 |
## 样式
除支持[通用样式](js-service-widget-common-styles.md)外，还支持如下样式：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| stroke-width | &lt;length&gt; | 32px（量规）<br/>24px（占比类圆形图表） | 否 | 量规、占比类圆形图表组件刻度条的宽度。 |
| start-angle | &lt;deg&gt; | 240（量规）<br/>0（占比类圆形图表） | 否 | 量规、占比类圆形图表组件刻度条起始角度，以时钟0点为基线。范围为0到360。 |
| total-angle | &lt;deg&gt; | 240（量规）<br/>360（占比类圆形图表） | 否 | 量规、占比类圆形图表组件刻度条总长度，范围为-360到360，负数标识起点到终点为逆时针。 |
| center-x | &lt;length&gt; | - | 否 | 量规组件刻度条中心位置，该样式优先于通用样式的position样式，仅量规图支持。<br>该样式需要和center-y和radius一起配置才能生效。 |
| center-y | &lt;length&gt; | - | 否 | 量规组件刻度条中心位置，该样式优先于通用样式的position样式，仅量规图支持。<br>该样式需要和center-x和radius一起配置才能生效。 |
| radius | &lt;length&gt; | - | 否 | 量规组件刻度条半径，该样式优先于通用样式的width和height样式，仅量规图支持。<br>该样式需要和center-x和center-y一起配置才能生效。 |
| colors | Array | - | 否 | 量规组件刻度条每一个区段的颜色，仅量规图支持。<br/>如：colors:&nbsp;\#ff0000,&nbsp;\#00ff00。 |
| weights | Array | - | 否 | 量规组件刻度条每一个区段的权重，仅量规图支持。<br/>如：weights:&nbsp;2,&nbsp;2。 |
| font-family | Array | - | 否 | 表示绘制注释的字体样式，支持[自定义字体](js-service-widget-common-customizing-font.md)。 |
| font-size | &lt;length&gt; | - | 否 | 表示绘制注释的字体的大小。 |
## 事件
支持[通用事件](js-service-widget-common-events.md)。
## 示例
1. 线形图
```html
<!-- xxx.hml -->
<div class="container">
<stack class="chart-region">
<image class="chart-background" src="common/background.png"></image>
<chart class="chart-data" type="line" ref="linechart" options="{{lineOps}}" datasets="{{lineData}}"></chart>
</stack>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
}
.chart-region {
height: 400px;
width: 700px;
}
.chart-background {
object-fit: fill;
}
.chart-data {
width: 700px;
height: 600px;
}
```
```json
// xxx.json
{
"data": {
"lineData": [
{
"strokeColor": "#0081ff",
"fillColor": "#cce5ff",
"data": [
763,
550,
551,
554,
731,
654,
525,
696,
595,
628,
791,
505,
613,
575,
475,
553,
491,
680,
657,
716
],
"gradient": true
}
],
"lineOps": {
"xAxis": {
"min": 0,
"max": 20,
"display": false
},
"yAxis": {
"min": 0,
"max": 1000,
"display": false
},
"series": {
"lineStyle": {
"width": "5px",
"smooth": true
},
"headPoint": {
"shape": "circle",
"size": 20,
"strokeWidth": 5,
"fillColor": "#ffffff",
"strokeColor": "#007aff",
"display": true
},
"loop": {
"margin": 2,
"gradient": true
}
}
}
}
}
```
**4*4卡片**
![zh-cn_image_0000001185652902](figures/zh-cn_image_0000001185652902.png)
2. 柱状图
```html
<!-- xxx.hml -->
<div class="container">
<stack class="data-region">
<image class="data-background" src="common/background.png"></image>
<chart class="data-bar" type="bar" id="bar-chart" options="{{barOps}}" datasets="{{barData}}"></chart>
</stack>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
}
.data-region {
height: 400px;
width: 700px;
}
.data-background {
object-fit: fill;
}
.data-bar {
width: 700px;
height: 400px;
}
```
```json
// xxx.json
{
"data": {
"barData": [
{
"fillColor": "#f07826",
"data": [763, 550, 551, 554, 731, 654, 525, 696, 595, 628]
},
{
"fillColor": "#cce5ff",
"data": [535, 776, 615, 444, 694, 785, 677, 609, 562, 410]
},
{
"fillColor": "#ff88bb",
"data": [673, 500, 574, 483, 702, 583, 437, 506, 693, 657]
}
],
"barOps": {
"xAxis": {
"min": 0,
"max": 20,
"display": false,
"axisTick": 10
},
"yAxis": {
"min": 0,
"max": 1000,
"display": false
}
}
}
}
```
**4*4卡片**
![barchart](figures/barchart.PNG)
3. 量规图
```html
<!-- xxx.hml -->
<div class="container">
<div class="gauge-region">
<chart class="data-gauge" type="gauge" percent = "50"></chart>
</div>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
}
.gauge-region {
height: 400px;
width: 400px;
}
.data-gauge {
colors: #83f115, #fd3636, #3bf8ff;
weights: 4, 2, 1;
}
```
**4*4卡片**
![gauge](figures/gauge.PNG)
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-clock.md 0 → 100644
浏览文件 @ 3035f58a
# clock
时钟组件，用于提供时钟表盘界面。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本
## 子组件
不支持。
## 属性
除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| clockconfig | ClockConfig | - | 是 | Clock的图片资源和样式设置，包括日间时段（6:00-18:00）和夜间时段（18:00-次日6:00）两套资源和样式设置。<br/>其中每套资源和样式包括表盘资源、时针指针资源、分针指针资源、秒针指针资源四张图和相应时间段的表盘数字颜色。<br/>日间资源为必填项。夜间资源可不填，不填时默认会复用日间资源用作夜间时段的显示。<br/>仅支持动态更新整个Object，不支持动态更新Object里的内容。<br/>建议使用PNG资源作为Clock组件的图片资源。<br/>不支持使用SVG资源作为Clock组件的图片资源。 |
| showdigit | boolean | true | 否 | 是否由Clock组件绘制表盘数字。<br/>该属性为true时，请留意clockconfig中digitRadiusRatio和digitSizeRatio参数与表盘的匹配情况。<br/>由Clock组件绘制的表盘数字支持国际化。 |
| hourswest | number | - | 否 | 时钟的时区偏移值，时区为标准时区减去hourswest。<br/>有效范围为[-12,&nbsp;12]，其中负值范围表示东时区，比如东八区对应的是-8。不设置默认采用系统时间所在的时区。 |
**表1** ClockConfig
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| face | &lt;string&gt; | - | 是 | 日间时段的表盘资源路径。<br/>表盘资源须为包含时钟刻度的正方形图片，表盘区域（圆形）为该图片的内切圆或内切圆的同心圆。如果表盘区域为表盘资源内切圆的同心圆的话，请相应调整digitRadiusRatio和digitSizeRatio参数。 |
| hourHand | &lt;string&gt; | - | 是 | 日间时段的时针资源路径。<br/>- 时针图片的高度须与表盘资源高度相同。<br/>- 时针图片的宽高比建议在0.062。<br/>- 时针图片上指针的旋转中心须处于时针图片的中心（对角线交点）。<br/>- 夜间时段的时针资源请调整hourHandNight参数。 |
| minuteHand | &lt;string&gt; | - | 是 | 日间时段的分针资源路径。<br/>- 分针图片的高度须与表盘资源高度相同。<br/>- 分针图片的宽高比建议在0.062。<br/>- 分针图片上指针的旋转中心须处于分针图片的中心（对角线交点）。<br/>-&nbsp;夜间时段的分针资源请调整minuteHandNight参数。 |
| secondHand | &lt;string&gt; | - | 是 | 日间时段的秒针资源路径。<br/>- &nbsp;秒针图片的高度须与表盘资源高度相同。<br/>-&nbsp;秒针图片的宽高比建议在0.062。<br/>-&nbsp;秒针图片上指针的旋转中心须处于秒针图片的中心（对角线交点）。<br/>- 夜间时段的秒针资源请调整secondHandNightSrc参数。 |
| digitColor | &lt;color&gt; | \#FF000000 | 否 | 日间时段（6:00-18:00）的表盘文本颜色。 |
| digitColorNight | &lt;color&gt; | 与digitColor保持一致 | 否 | 夜间时段（18:00-次日6:00）的表盘文本颜色。<br/>- 该属性未设置时，取digitColor的值作为digitColorNight的值（digitColor被设置时，取digitColor被设置的值）。<br/>- 请注意缺省状态下使用digitClor的值作为digitColorNight的值时，夜间时段表盘文本颜色与夜间时段表盘背景（faceNight）的颜色配合问题。 |
| faceNight | &lt;string&gt; | - | 否 | 夜间时段的表盘资源路径。<br/>未设置时使用face的资源路径作为夜间时段的表盘资源路径。 |
| hourHandNight | &lt;string&gt; | - | 否 | 夜间时段的时针资源路径。<br/>未设置时使用hourHand的资源路径作为夜间时段的时针资源路径。 |
| minuteHandNight | &lt;string&gt; | - | 否 | 夜间时段的分针资源路径。<br/>设置时使用minuteHand的资源路径作为夜间时段的分针资源路径。 |
| secondHandNight | &lt;string&gt; | - | 否 | 夜间时段的秒针资源路径。<br/>未设置时使用secondHand的资源路径作为夜间时段的秒针资源路径。 |
| digitRadiusRatio | number | 0.7 | 否 | 表盘数字中心到表盘中心距离&nbsp;/&nbsp;表盘资源边长的一半。<br/>- 有效范围为(0,&nbsp;1]。<br/>- 该参数用于计算表盘数字在表盘上距离圆心的位置。<br/>- 该参数可以保证同一套表盘资源在不同组件尺寸下都有同样的相对位置，而不需要针对每个组件尺寸都重新调整数字位置。<br/>- 该参数设为1时数字会有部分区域超出表盘，建议结合表盘区域合理设置digitRadiusRatio。 |
| digitSizeRatio | number | 0.08 | 否 | 表盘数字尺寸/表盘资源边长。<br/>- 有效范围为(0,&nbsp;0.142]。<br/>- 该参数用于计算表盘数字相对表盘尺寸的大小。<br/>- 该参数可以保证同一套表盘资源在不同组件尺寸下都有同样的相对大小，而不需要针对每个组件尺寸都重新调整字号。 |
![clock](figures/clock.png)
## 样式
除支持[通用样式](js-service-widget-common-styles.md)之外，还支持如下样式：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| font-family | &lt;string&gt; | sans-serif | 否 | 表盘数字的字体列表，用逗号分隔，每个字体用字体名或者字体族名设置。列表中第一个系统中存在的或者通过2.1.6&nbsp;自定义字体样式指定的字体，会被选中作为文本的字体。 |
> **说明：**
>
> clock组件会保持显示区域的宽高比为1，最终正方形显示区域的边长为min(width, height)，在width \* height的组件区域中居中显示。
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| hour | {hour:&nbsp;number} | 每个整点触发该事件 |
## 示例
```html
<!-- xxx.hml -->
<div class="container">
<div class="row">
<clock class="clk" style="font-family:Courier;" hourswest="-8" clockconfig="{{clockconfig}}">
</clock>
<clock class="clk" style="font-family:Courier;" hourswest="4" clockconfig="{{clockconfig}}">
</clock>
</div>
</div>
```
```css
/* xxx.css */
.container {
flex-direction:column;
align-items:center;
}
.clk {
width:350px;
height:350px;
}
.row {
flex-direction:row;
align-items:center;
justify-content: space-around;
border-radius: 40px;
padding-top: 20px;
padding-bottom: 20px;
background-color: #4169E1;
}
```
```json
// xxx.json
{
"data": {
"clockconfig": {
"digitRadiusRatio": 0.7,
"digitSizeRatio": 0.08,
"face": "common/clock_widget.png",
"hourHand": "common/clock_widget_hour.png",
"minuteHand": "common/clock_widget_minute.png",
"secondHand": "common/clock_widget_second.png",
"faceNight": "common/black_clock_widget.png",
"hourHandNight": "common/black_clock_widget_hour.png",
"minuteHandNight": "common/black_clock_widget_minute.png",
"digitColor": "#000000",
"digitColorNight": "#FFFFFF"
}
}
}
```
**2*4卡片**
![clockshow](figures/clockshow.png)
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-divider.md 0 → 100644
浏览文件 @ 3035f58a
# divider
分隔器组件，分隔不同内容块/内容元素。可用于列表或界面布局。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 属性
除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| vertical | boolean | false | 否 | 使用水平分割线还是垂直分割线，默认水平分割线。 |
## 样式
仅支持如下样式：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| margin | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的外边距属性，该属性可以有1到4个值。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 使用简写属性设置左、上、右、下外边距属性，类型length，单位px，默认值0。 |
| color | &lt;color&gt; | - | 否 | 设置分割线颜色。 |
| stroke-width | &lt;length&gt; | 1 | 否 | 设置分割线宽度。 |
| display | string | flex | 否 | 确定分割线所产生的框的类型。值flex/none，默认值flex。 |
| visibility | string | visible | 否 | 是否显示分割线，不可见的框会占用布局。visible代表显示元素，hidden代表不显示元素。 |
| line-cap | string | butt | 否 | 设置分割线条的端点样式，默认为butt，可选值为：<br/>-&nbsp;"butt"：分割线两端为平行线。<br/>-&nbsp;"round"：分割线两端额外添加半圆。<br/>-&nbsp;"square"：分割线两端额外添加半方形。<br/>"round"和"square"会额外增加一个线宽的分割线长度。 |
| flex | number | - | 否 | 规定了分割线如何适应父组件中的可用空间。作为一个简写属性，用来设置组件的flex-grow。<br/>仅父容器为&lt;div&gt;、&lt;list-item&gt;、&lt;tabs&gt;时生效。 |
| flex-grow | number | 0 | 否 | 设置分割线的伸展因子，指定父组件容器主轴方向上剩余空间（容器本身大小减去所有flex项加起来的大小）的分配系数。0为不伸展。<br/>仅父容器为&lt;div&gt;、&lt;list-item&gt;、&lt;tabs&gt;时生效。 |
| flex-shrink | number | 1 | 否 | 设置分割线的收缩因子，flex元素仅在默认宽度之和大于容器的时候才会发生收缩，0为不收缩。<br/>仅父容器为&lt;div&gt;、&lt;list-item&gt;、&lt;tabs&gt;时生效。 |
| flex-basis | &lt;length&gt; | - | 否 | 设置分割线在主轴方向上的初始大小。<br/>仅父容器为&lt;div&gt;、&lt;list-item&gt;、&lt;tabs&gt;时生效。 |
## 事件
不支持。
## 示例
```html
<!-- xxx.hml -->
<div class="container">
<div class="content">
<divider class="divider" vertical="false"></divider>
</div>
</div>
```
```css
/* xxx.css */
.container {
margin: 20px;
flex-direction:column;
width:100%;
height:100%;
align-items:center;
}
.content{
width:80%;
height:40%;
margin-top:100px;
border:1px solid #000000;
align-items: center;
justify-content: center;
flex-direction:column;
}
.divider {
margin: 10px;
color: #ff0000ff;
stroke-width: 3px;
line-cap: round;
}
```
**4*4卡片**
![卡片divider](figures/divider.png)
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-image.md 0 → 100644
浏览文件 @ 3035f58a
# image
图片组件，用来渲染展示图片。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| src | string | - | 否 | 图片的路径。<br/>-&nbsp;支持本地路径，图片格式包括png,&nbsp;jpg,&nbsp;bmp,&nbsp;svg和gif。<br/>-&nbsp;支持内存图片读取，scheme格式为memory://。 |
| alt | string | - | 否 | 占位图，当指定图片在加载中时显示。 |
## 样式
除支持[通用样式](js-service-widget-common-styles.md)外，还支持如下样式：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| object-fit | string | cover | 否 | 设置图片的缩放类型，可选值类型说明请见object-fit 类型说明，svg格式不支持。 |
| match-text-direction | boolean | false | 否 | 图片是否跟随文字方向，svg格式不支持。 |
| fit-original-size | boolean | false | 否 | image组件在未设置宽高的情况下是否适应图源尺寸，该属性为true时object-fit属性不生效，svg类型图源不支持该属性。 |
**表1** object-fit 类型说明
| 类型 | 描述 |
| -------- | -------- |
| cover | 保持宽高比进行缩小或者放大，使得图片两边都大于或等于显示边界，居中显示。 |
| contain | 保持宽高比进行缩小或者放大，使得图片完全显示在显示边界内，居中显示。 |
| fill | 不保持宽高比进行放大缩小，使得图片填充满显示边界。 |
| none | 保持原有尺寸进行居中显示。 |
| scale-down | 保持宽高比居中显示，图片缩小或者保持不变。 |
> **说明：**
> 使用svg图片资源时：
>
> - 建议设置image组件的长宽，否则在父组件的长或宽为无穷大的场景下，svg资源将不会绘制。
>
> - 如果svg描述中未指定相应的长宽，则svg将会填满image组件区域。
>
> - 如果svg描述中指定了相应的长宽，和image组件本身的长宽效果如下：
>
> - 如果image组件本身的长宽小于svg中的长宽，svg会被裁切，仅显示左上角部分。
>
> - 如果image组件本身的长宽大于svg中的长宽，svg会被放置在image组件的左上角，image组件其他部分显示空白。
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| click | - | 点击动作触发该事件。 |
| complete | - | 图片成功加载时触发该回调。 |
| error | - | 图片加载出现异常时触发该回调。 |
## 示例
```html
<!-- xxx.hml -->
<stack class="content">
<image src="/common/bg3.jpg" class="img"></image>
</stack>
```
```css
/* xxx.css */
.img{
object-fit: contain
}
```
**4*4卡片**
![卡片image.jpg](figures/image.jpg)
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-input.md 0 → 100644
浏览文件 @ 3035f58a
# input
交互式组件，提供单选框功能。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 属性
除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| type | string | radio | 是 | input组件类型，当前仅支持radio类型：<br/>-&nbsp;"radio"：定义单选按钮，允许在多个拥有相同name值的选项中选中其中一个； |
| checked | boolean | false | 否 | 当前组件是否选中。 |
| name | string | - | 否 | input组件的名称。 |
| value | string | - | 否 | input组件的value值，类型为radio时必填且相同name值的选项该值唯一。 |
## 样式
支持[通用样式](js-service-widget-common-styles.md)。
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| change | $event.checkedItem | radio单选框的checked状态发生变化时触发该事件，返回选中的组件value值。 |
| click | - | 点击动作触发该事件。 |
## 示例
```html
<!-- xxx.hml -->
<div class="content">
<input type="radio" checked='true' name="radioSample" value="radio1" onchange="onRadioChange"></input>
<input type="radio" checked='false' name="radioSample" value="radio2" onchange="onRadioChange"></input>
<input type="radio" checked='false' name="radioSample" value="radio3" onchange="onRadioChange"></input>
</div>
```
```css
/* xxx.css */
.content{
width: 100%;
height: 200px;
justify-content: center;
align-items: center;
}
```
```json
// xxx.json
{
"actions": {
"onRadioChange":{
"action": "message",
"params": {
"checkedRadio": "$event.checkedItem"
}
}
}
}
```
**4*4卡片**
![卡片input](figures/input.gif)
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-progress.md 0 → 100644
浏览文件 @ 3035f58a
# progress
进度条，用于显示内容加载或操作的处理进度。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| type | string | horizontal | 否 | 设置进度条的类型，该属性不支持动态修改，可选值为：<br/>-&nbsp;horizontal：线性进度条。<br/>-&nbsp;circular：loading样式进度条。<br/>-&nbsp;ring：圆环形进度条。<br/>-&nbsp;scale-ring：带刻度圆环形进度条。<br/>-&nbsp;arc：弧形进度条。<br/>-&nbsp;eclipse：圆形进度条，展现类似月圆月缺的进度展示效果。 |
不同类型的进度条还支持不同的属性：
- 类型为horizontal、ring、scale-ring时，支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| percent | number | 0 | 否 | 当前进度。取值范围为0-100。 |
| secondarypercent(Rich) | number | 0 | 否 | 次级进度。取值范围为0-100。 |
- 类型为ring、scale-ring时，支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| clockwise | boolean | true | 否 | 圆环形进度条是否采用顺时针。 |
- 类型为arc、eclipse时，支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| percent | number | 0 | 否 | 当前进度。取值范围为0-100。 |
## 样式
除支持[通用样式](js-service-widget-common-styles.md)外，还支持如下样式：
type=horizontal
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | \#ff007dff | 否 | 设置进度条的颜色。 |
| stroke-width | &lt;length&gt; | 4px | 否 | 设置进度条的宽度。 |
| background-color | &lt;color&gt; | - | 否 | 设置进度条的背景色。 |
| secondary-color | &lt;color&gt; | - | 否 | 设置次级进度条的颜色。 |
type=circular
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | - | 否 | loading进度条上的圆点颜色。 |
type=ring, scale-ring
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt;&nbsp;\|&nbsp;&lt;linear-gradient&gt; | - | 否 | 环形进度条的颜色，ring类型支持线性渐变色设置。<br/>线性渐变色仅支持两个颜色参数设置格式，如color&nbsp;=&nbsp;linear-gradient(\#ff0000,&nbsp;\#00ff00)。 |
| background-color | &lt;color&gt; | - | 否 | 环形进度条的背景色。 |
| secondary-color | &lt;color&gt; | - | 否 | 环形次级进度条的颜色。 |
| stroke-width | &lt;length&gt; | 10px | 否 | 环形进度条的宽度。 |
| scale-width | &lt;length&gt; | - | 否 | 带刻度的环形进度条的刻度粗细，类型为scale-ring生效。 |
| scale-number | number | 120 | 否 | 带刻度的环形进度条的刻度数量，类型为scale-ring生效。 |
type=arc
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | - | 否 | 弧形进度条的颜色。 |
| background-color | &lt;color&gt; | - | 否 | 弧形进度条的背景色。 |
| stroke-width | &lt;length&gt; | - | 否 | 弧形进度条的宽度。<br/>进度条宽度越大，进度条越靠近圆心。即进度条始终在半径区域内。 |
| start-angle | &lt;deg&gt; | 240 | 否 | 弧形进度条起始角度，以时钟0点为基线。范围为0到360（顺时针）。 |
| total-angle | &lt;deg&gt; | 240 | 否 | 弧形进度条总长度，范围为-360到360，负数标识起点到终点为逆时针。 |
| center-x | &lt;length&gt; | - | 否 | 弧形进度条中心位置，（坐标原点为组件左上角顶点）。该样式需要和center-y和radius一起。 |
| center-y | &lt;length&gt; | - | 否 | 弧形进度条中心位置，（坐标原点为组件左上角顶点）。该样式需要和center-x和radius一起。 |
| radius | &lt;length&gt; | - | 否 | 弧形进度条半径，该样式需要和center-x和center-y一起。 |
## 事件
支持[通用事件](js-service-widget-common-events.md)。
## 示例
```html
<!--xxx.hml -->
<div class="container">
<progress class="min-progress" type="scale-ring" percent= "10" secondarypercent="50"></progress>
<progress class="min-progress" type="horizontal" percent= "10" secondarypercent="50"></progress>
<progress class="min-progress" type="arc" percent= "10"></progress>
<progress class="min-progress" type="ring" percent= "10" secondarypercent="50"></progress>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
height: 100%;
width: 100%;
align-items: center;
}
.min-progress {
width: 300px;
height: 300px;
}
```
**4*4卡片**
![progress](figures/progress.png)
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-span.md 0 → 100644
浏览文件 @ 3035f58a
# span
作为&lt;[text](js-service-widget-basic-text.md)&gt;子组件提供文本修饰能力。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 子组件
支持子组件[\<span>](js-service-widget-basic-span.md)。
## 属性
支持[通用属性](js-service-widget-common-attributes.md)。
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | - | 否 | 设置文本段落的文本颜色。 |
| font-size | &lt;length&gt; | 30px | 否 | 设置文本段落的文本尺寸。 |
| font-style | string | normal | 否 | 设置文本段落的字体样式，见[text组件font-style的样式属性](js-service-widget-basic-text.md#样式)。 |
| font-weight | number&nbsp;\|&nbsp;string | normal | 否 | 设置文本段落的字体粗细，见[text组件font-weight的样式属性](js-service-widget-basic-text.md#样式)。 |
| text-decoration | string | none | 否 | 设置文本段落的文本修饰，见[text组件text-decoration样式属性](js-service-widget-basic-text.md#样式)。 |
| font-family | string | sans-serif | 否 | 设置文本段落的字体列表，用逗号分隔，每个字体用字体名或者字体族名设置。列表中第一个系统中存在的或者通过[自定义字体](js-service-widget-common-customizing-font.md)指定的字体，会被选中作为文本的字体。 |
## 事件
不支持。
## 示例
详见[text示例](js-service-widget-basic-text.md#示例)。
\ No newline at end of file
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-text.md 0 → 100644
浏览文件 @ 3035f58a
# text
文本，用于呈现一段信息。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 子组件
支持&lt;[span](js-service-widget-basic-span.md)&gt;。
## 属性
支持[通用属性](js-service-widget-common-attributes.md)。
## 样式
除支持[通用样式](js-service-widget-common-styles.md)外，还支持如下样式：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | - | 否 | 设置文本的颜色。 |
| font-size | &lt;length&gt; | 30px | 否 | 设置文本的尺寸。 |
| letter-spacing | &lt;length&gt; | 0px | 否 | 设置文本的字符间距。 |
| font-style | string | normal | 否 | 设置文本的字体样式，可选值为：<br/>-&nbsp;normal：标准的字体样式；<br/>-&nbsp;italic：斜体的字体样式。 |
| font-weight | number&nbsp;\|&nbsp;string | normal | 否 | 设置文本的字体粗细，number类型取值[100,&nbsp;900]，默认为400，取值越大，字体越粗。<br/>-&nbsp;number取值必须为100的整数倍。<br/>- string类型取值支持如下四个值：lighter、normal、bold、bolder。 |
| text-decoration | string | none | 否 | 设置文本的文本修饰，可选值为：<br/>-&nbsp;underline：文字下划线修饰；<br/>-&nbsp;line-through：穿过文本的修饰线n<br/>-&nbsp;none：标准文本。 |
| text-align | string | start | 否 | 设置文本的文本对齐方式，可选值为：<br/>-&nbsp;left：文本左对齐；<br/>-&nbsp;center：文本居中对齐；<br/>-&nbsp;right：文本右对齐；<br/>-&nbsp;start：根据文字书写相同的方向对齐；<br/>-&nbsp;end：根据文字书写相反的方向对齐。<br/>&nbsp;如文本宽度未指定大小，文本的宽度和父容器的宽度大小相等的情况下，对齐效果可能会不明显。 |
| line-height | &lt;length&gt; | 0px | 否 | 设置文本的文本行高，设置为0px时，不限制文本行高，自适应字体大小。 |
| text-overflow | string | clip | 否 | 在设置了最大行数的情况下生效，可选值为：<br/>-&nbsp;clip：将文本根据父容器大小进行裁剪显示；<br/>-&nbsp;ellipsis：根据父容器大小显示，显示不下的文本用省略号代替。需配合max-lines使用。 |
| font-family | string | sans-serif<br/><br/> | 否 | 设置文本的字体列表，用逗号分隔，每个字体用字体名或者字体族名设置。列表中第一个系统中存在的或者通过[自定义字体](js-service-widget-common-customizing-font.md)指定的字体，会被选中作为文本的字体。 |
| max-lines | number | - | 否 | 设置文本的最大行数。 |
| min-font-size | &lt;length&gt; | - | 否 | 文本最小字号，需要和文本最大字号同时设置，支持文本字号动态变化。设置最大最小字体样式后，font-size不生效。 |
| max-font-size | &lt;length&gt; | - | 否 | 文本最大字号，需要和文本最小字号同时设置，支持文本字号动态变化。设置最大最小字体样式后，font-size不生效。 |
| font-size-step | &lt;length&gt; | 1px | 否 | 文本动态调整字号时的步长，需要设置最小，最大字号样式生效。 |
| prefer-font-sizes | &lt;array&gt; | - | 否 | 预设的字号集合，在动态尺寸调整时，优先使用预设字号集合中的字号匹配设置的最大行数，如果预设字号集合未设置，则使用最大最小和步长调整字号。针对仍然无法满足最大行数要求的情况，使用text-overflow设置项进行截断，设置预设尺寸集后，font-size、max-font-size、min-font-size和font-size-step不生效。<br/>如：prefer-font-sizes:&nbsp;12px,14px,16px |
| word-break | string | normal | 否 | 设置文本折行模式，可选值为：<br/>-&nbsp;normal：默认换行规则，依据各自语言的规则，允许在字间发生换行。<br/>-&nbsp;break-all：对于非中文/日文/韩文的文本，可在任意字符间断行。<br/>-&nbsp;break-word：与break-all相同，不同的地方在于它要求一个没有断行破发点的词必须保持为一个整体单位。 |
> **说明：**
> - 字体动态缩放：预设尺寸集合和最小最大字号调节基于是否满足最大行数要求，预设尺寸集合会按照从左到右顺序查看是否满足最大行数要求，最小最大字号调节则基于从大到小顺序查看是否满足最大行数要求。
>
> - 文本换行：文本可以通过转义字符\r\n进行换行。
>
> - 文本标签内支持以下转义字符：\a，\b，\f，\n，\r，\t，\v，\'，\"，\0。
>
> - 当使用子组件span组成文本段落时，如果span属性样式异常，将导致text段落无法显示。
>
> - letter-spacing、text-align、line-height、text-overflow和max-lines样式作用于text及其子组件（span）组成的文本内容。
>
> - text组件说明：不支持text内同时存在文本内容和span子组件。（如果同时存在，只显示span内的内容)
## 事件
支持[通用事件](js-service-widget-common-events.md)。
## 示例
```html
<div class="container">
<text class="line_height">
<span>这是设置了行高的文本。</span>
</text>
<text class="letter_spacing">这是设置了字符间距的文本。</text>
<text class="font_style">这是设置为斜体的文本。</text>
<text class="text_decoration_style">这是添加了下划线的文本。</text>
<text class="text_over_flow">文本过长可省略，省略文本。</text>
</div>
```
```css
.container{
flex-direction: column;
width: 100%;
height: 100%;
margin-top: 10px;
margin-left: 30px;
}
.line_height{
font-size: 20px;
line-height: 40px;
}
.letter_spacing{
font-size: 20px;
letter-spacing: 5px;
}
.font_style{
font-size: 20px;
font-style: italic;
}
.text_decoration_style{
font-size: 20px;
text-decoration: underline;
text-decoration-color: red;
}
.text_over_flow{
font-size: 20px;
width: 40%;
max-lines: 1;
text-overflow: ellipsis;
}
```
**4*4卡片**
![progress](figures/text.png)
\ No newline at end of file
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-common-accessibility.md 0 → 100644
浏览文件 @ 3035f58a
# 无障碍
组件可以设置相应的无障碍属性和事件来更好地使用无障碍能力。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 无障碍属性
| 名称 | 类型 | 默认值 | 描述 |
| -------- | -------- | -------- | -------- |
| accessibilitygroup | boolean | false | 无障碍组，设置为true时表示该组件及其所有子组件为一整个可以选中的组件，无障碍服务将不再关注其子组件内容。 |
| accessibilitytext | string | - | 无障碍文本，当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。若组件既拥有文本属性，又拥有无障碍文本属性，则组件被选中时，仅播报无障碍文本内容。 |
| accessibilitydescription | string | - | 无障碍说明，用于为用户进一步说明当前组件，如帮助用户理解将要执行的操作可能导致什么后果，尤其是当这些后果无法从组件本身属性与无障碍文本中了解到时。开发人员可为组件的该属性设置相对较详细的解释文本，帮助用户理解将要执行的操作。若组件既拥有文本属性又拥有无障碍说明属性，则组件被选中时，先播报组件的文本属性，再播报无障碍说明属性的内容。 |
| accessibilityimportance | string | auto | 无障碍重要性，用于控制某个组件是否可被无障碍辅助服务所识别。具体值可以设置为auto，yes，no和no-hide-descendants（最后一个值会使屏幕朗读忽略当前组件及其所有子组件）。若设置为yes，当前组件对无障碍辅助服务而言可选中；若设置为no，则当前组件对无障碍辅助服务来说是不可选中的。 |
- accessibilitygroup
```html
<div accessibilitygroup="true">
<text>text1</text>
<text>text2</text>
</div>
```
- accessibilitytext
```html
<image src="common/image/barrierfree.jpg" accessibilitytext="这是一张风景图"></image>
```
- accessibilitydescription
```html
<button accessibilitydescription="点击此按键会弹出一个对话框" onclick="DialogShow">按键</button>
```
- accessibilityimportance
此情况下，div和text都不会被无障碍框选中。若想让某些默认不会被无障碍框选中的组件可以被选中，则给该组件增加一个accessibilityimportance="yes"即可。
```html
<div accessibilityimportance="no-hide-descendants">
<text>text</text>
</div>
```
## 无障碍事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| accessibility | AbilityEvent | 无障碍服务下发的事件。 |
**表1**AbilityEvent属性列表
| 属性 | 类型 | 说明 |
| -------- | -------- | -------- |
| eventType | number | 事件类型：<br/>-&nbsp;0：custom&nbsp;event<br/>-&nbsp;1：accessibility&nbsp;focus<br/>-&nbsp;2：clear&nbsp;accessibility&nbsp;focus<br/>无障碍系统下发的非焦点相关的事件为0，无障碍系统下发的获焦事件为1，无障碍系统下发的失焦事件为2。 |
| param | Object | 无障碍辅助应用发送自定义事件时需传入对应参数。 |
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-common-atomic-layout.md 0 → 100644
浏览文件 @ 3035f58a
# 原子布局
在屏幕形态和规格不同等情况下，布局效果需要实现自适应，因此系统提供了面向不同屏幕尺寸界面自适应适配的布局能力，称为原子布局。设计师可以考虑使用原子能力，定义元素在不同形态的尺寸界面上体现的自适应规则。开发者可以使用原子布局能力，快速实现让应用在多形态屏幕上有与设计效果相匹配的自适应效果。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 隐藏能力
在非折行flex布局基础上，增加了显示优先级标记，可以调整组件内元素水平/垂直方向的显示优先级，根据当前组件容器的可用空间来显示内容。
| 样式 | 类型 | 默认值 | 说明 |
| -------- | -------- | -------- | -------- |
| display-index | number | 0 | 适用于div等支持flex布局的容器组件中的子组件上，当容器组件在flex主轴上尺寸不足以显示全部内容时，按照display-index值从小到大的顺序进行隐藏，具有相同display-index值的组件同时隐藏，默认值为0，表示隐藏。 |
## 占比能力
在非折行的flex布局中，定义了占比能力的组件，保证指定元素始终在容器的某一个比例空间中进行布局。
| 样式 | 类型 | 默认值 | 说明 |
| -------- | -------- | -------- | -------- |
| flex-weight | number | - | 指明当前元素在flex主轴方向上尺寸权值，当且仅当容器组件中所有节点均设置此属性时生效，当前元素尺寸为：&nbsp;容器主轴尺寸&nbsp;\*&nbsp;当前权值&nbsp;/&nbsp;所有子元素权值和。 |
## 固定比例
定义了组件固定比例调整尺寸的能力。
| 样式 | 类型 | 默认值 | 说明 |
| -------- | -------- | -------- | -------- |
| aspect-ratio | number | - | &nbsp;接受任意大于0的浮点值，定义为该节点的宽度与高度比，设置该属性后，该元素尺寸宽高比按照此属性值进行调整。<br/>&nbsp;遵守最大值与最小值的限制。<br/>&nbsp;在flex布局中，主轴尺寸先进行调整，后根据该尺寸调整交叉轴。 |
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-common-attributes.md 0 → 100644
浏览文件 @ 3035f58a
# 通用属性
> **说明：**
>
>从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 常规属性
常规属性指的是组件普遍支持的用来设置组件基本标识和外观显示特征的属性。
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类，用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素或子组件的引用信息，该引用将注册到父组件的$refs&nbsp;属性对象上。 |
| disabled | boolean | false | 否 | 当前组件是否被禁用，在禁用场景下，组件将无法响应用户交互。 |
| dir | string | auto | 否 | 设置元素布局模式，支持设置rtl、ltr和auto三种属性值：<br/>-&nbsp;"rtl"：使用从右往左布局模式。<br/>-&nbsp;"ltr"：使用从左往右布局模式。<br/>-&nbsp;"auto"：跟随系统语言环境。 |
## 渲染属性
组件普遍支持的用来设置组件是否渲染的属性。
| 名称 | 类型 | 默认值 | 描述 |
| -------- | -------- | -------- | -------- |
| for | Array | - | 根据设置的数据列表，展开当前元素。 |
| if | boolean | - | 根据设置的boolean值，添加或移除当前元素。 |
| show | boolean | - | 根据设置的boolean值，显示或隐藏当前元素。 |
> **说明：**
> 属性和样式不能混用，不能在属性字段中进行样式设置。
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-common-customizing-font.md 0 → 100644
浏览文件 @ 3035f58a
# 自定义字体样式
font-face用于定义字体样式。应用可以在style中定义font-face来指定相应的字体名和字体资源，然后在font-family样式中引用该字体。
自定义字体可以是从项目中的字体文件或网络字体文件中加载的字体。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
>
> 字体格式支持ttf和otf。
## 定义font-face
```css
@font-face {
font-family: HWfont;
src: url('/common/HWfont.ttf');
}
```
**font-family：** 自定义字体的名称。
**src：** 自定义字体的来源，支持如下类别。
- 项目中的字体文件：通过url指定项目中的字体文件路径(只支持绝对路径，详见[文件组织](js-service-widget-file.md))。
- 网络字体文件：通过url指定网络字体的地址。
- 不支持设置多个src。
## 使用font-face
可以在style中定义font-face，然后在font-family样式中指定该font-face的名称，从而应用font-face定义的字体。示例如下：
- 页面布局
```html
<div>
<text class="demo-text">测试自定义字体</text>
</div>
```
- 页面样式
```css
@font-face {
font-family: HWfont;
src: url("/common/HWfont.ttf");
}
.demo-text {
font-family: HWfont;
}
```
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-common-events.md 0 → 100644
浏览文件 @ 3035f58a
# 通用事件
相对于私有事件，大部分组件都可以绑定如下事件。(如果需要响应键盘的回车和空格发生Key Up事件，需要在最外层的控件上添加click事件)
> **说明：**
>
>从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| click | - | 点击动作触发该事件。 |
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-common-gradient.md 0 → 100644
浏览文件 @ 3035f58a
# 渐变样式
组件普遍支持的在style或css中设置的 可以平稳过渡两个或多个指定的颜色。
> **说明：**
>
>从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
开发框架支持线性渐变 (linear-gradient)和重复线性渐变 (repeating-linear-gradient)两种渐变效果。
## 线性渐变/重复线性渐变
使用渐变样式，需要定义过渡方向和过渡颜色。
### 过渡方向
通过direction或者angle指定过渡方向。
- direction：进行方向渐变。
- angle：进行角度渐变。
```css
background: linear-gradient(direction/angle, color, color, ...);
background: repeating-linear-gradient(direction/angle, color, color, ...);
```
### 过渡颜色
支持以下四种方式：\#ff0000、\#ffff0000、rgb(255, 0, 0)、rgba(255, 0, 0, 1)，需要指定至少两种颜色。
- 参数
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| direction | to&nbsp;&lt;side-or-corner&gt;&nbsp;&nbsp;&lt;side-or-corner&gt;&nbsp;=&nbsp;[left&nbsp;\|&nbsp;right]&nbsp;\|\|&nbsp;[top&nbsp;\|&nbsp;bottom] | to&nbsp;bottom&nbsp;(由上到下渐变) | 否 | 指定过渡方向，如：to&nbsp;left&nbsp;(从右向左渐变)&nbsp;&nbsp;，或者to&nbsp;bottom&nbsp;right&nbsp;(从左上角到右下角)。 |
| angle | &lt;deg&gt; | 180deg | 否 | 指定过渡方向，以元素几何中心为坐标原点，水平方向为X轴，angle指定了渐变线与Y轴的夹角(顺时针方向)。 |
| color | &lt;color&gt;&nbsp;[&lt;length&gt;\|&lt;percentage&gt;] | - | 是 | 定义使用渐变样式区域内颜色的渐变效果。 |
- 示例
1. 默认渐变方向为从上向下渐变。
```css
#gradient {
height: 300px;
width: 600px;
/* 从顶部开始向底部由红色向绿色渐变 */
background: linear-gradient(red, #00ff00);
}
```
![111](figures/111.PNG)
2. 45度夹角渐变。
```css
/* 45度夹角，从红色渐变到绿色 */
background: linear-gradient(45deg, rgb(255,0,0),rgb(0, 255, 0));
```
![222](figures/222.PNG)
3. 设置方向从左向右渐变。
```css
/* 从左向右渐变，在距离左边90px和距离左边360px (600*0.6) 之间270px宽度形成渐变 */
background: linear-gradient(to right, rgb(255,0,0) 90px, rgb(0, 255, 0) 60%);
```
![333](figures/333.PNG)
4. 重复渐变。
```css
/* 从左向右重复渐变，重复渐变区域30px（60-30）透明度0.5 */
background: repeating-linear-gradient(to right, rgba(255, 255, 0, 1) 30px,rgba(0, 0, 255, .5) 60px);
```
![444](figures/444.PNG)
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-common-mediaquery.md 0 → 100644
浏览文件 @ 3035f58a
# 媒体查询
媒体查询（Media Query）在移动设备上应用十分广泛，开发者经常需要根据设备的大致类型或者特定的特征和设备参数（例如屏幕分辨率）来修改应用的样式。为此媒体查询提供了如下功能：
1. 针对设备和应用的属性信息，可以设计出相匹配的布局样式。
2. 当屏幕发生动态改变时（比如分屏、横竖屏切换），应用页面布局同步更新。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
>
> media属性值默认为设备的真实尺寸大小、物理像素和真实的屏幕分辨率。请勿与以720px为基准的项目配置宽度px混淆。
## CSS语法规则
使用\@media来引入查询语句，具体规则如下：
```css
@media [media-type] [and|not|only] [(media-feature)] {
CSS-Code;
}
```
例子：
\@media screen and (round-screen: true) { … } // 当设备屏幕是圆形时条件成立
\@media (max-height: 800) { … } // 范围查询，CSS level 3 写法
\@media (height &lt;= 800) { … } // 范围查询，CSS level 4 写法，与CSS level3写法等价
\@media screen and (device-type: tv) or (resolution &lt; 2) { … } // 同时包含媒体类型和多个媒体特征的多条件复杂语句查询
## 页面中引用资源
通过\@import方式引入媒体查询，具体使用方法如下：
```
@import url [media-type] [and|not|only] [(media-feature)];
```
例如：
```
@import '../common/style.css' screen and (min-width: 600) and (max-width: 1200);
```
## 媒体类型
| 类型 | 说明 |
| -------- | -------- |
| screen | 按屏幕相关参数进行媒体查询。 |
## 媒体逻辑操作
媒体逻辑操作符：and、or、not、only用于构成复杂媒体查询，也可以通过comma（,）将其组合起来，详细解释说明如下表。
**表1** 媒体逻辑操作符
| 类型 | 说明 |
| -------- | -------- |
| and | 将多个媒体特征（Media&nbsp;Feature）以“与”的方式连接成一个媒体查询，只有当所有媒体特征都为true，查询条件成立。另外，它还可以将媒体类型和媒体功能结合起来。<br/>例如：screen&nbsp;and&nbsp;(device-type:&nbsp;wearable)&nbsp;and&nbsp;(max-height:&nbsp;600)&nbsp;表示当设备类型是智能穿戴同时应用的最大高度小于等于600个像素单位时成立。 |
| not | 取反媒体查询结果，媒体查询结果不成立时返回true，否则返回false。在媒体查询列表中应用not，则not仅取反应用它的媒体查询。<br/>例如：not&nbsp;screen&nbsp;and&nbsp;(min-height:&nbsp;50)&nbsp;and&nbsp;(max-height:&nbsp;600)&nbsp;表示当应用高度小于50个像素单位或者大于600个像素单位时成立。<br/>使用not运算符时必须指定媒体类型。 |
| only | 当整个表达式都匹配时，才会应用选择的样式，可以应用在防止某些较早的版本的浏览器上产生歧义的场景。一些较早版本的浏览器对于同时包含了媒体类型和媒体特征的语句会产生歧义，比如：<br/>screen&nbsp;and&nbsp;(min-height:&nbsp;50)<br/>老版本浏览器会将这句话理解成screen，从而导致仅仅匹配到媒体类型（screen），就应用了指定样式，使用only可以很好地规避这种情况。<br/>使用only时必须指定媒体类型。 |
| ,(comma) | 将多个媒体特征以“或”的方式连接成一个媒体查询，如果存在结果为true的媒体特征，则查询条件成立。其效果等同于or运算符。<br/>例如：screen&nbsp;and&nbsp;(min-height:&nbsp;1000),&nbsp;&nbsp;（round-screen：true）&nbsp;表示当应用高度大于等于1000个像素单位或者设备屏幕是圆形时，条件成立。 |
| or | 将多个媒体特征以“或”的方式连接成一个媒体查询，如果存在结果为true的媒体特征，则查询条件成立。<br/>例如：screen&nbsp;and&nbsp;(max-height:&nbsp;1000)&nbsp;or&nbsp;&nbsp;（round-screen：true）表示当应用高度小于等于1000个像素单位或者设备屏幕是圆形时，条件成立。 |
在MediaQuery Level 4中引入了范围查询，使其能够使用max-，min-的同时，也支持了&lt;=，&gt;=，&lt;，&gt;操作符。
**表2** 媒体逻辑范围操作符
| 类型 | 说明 |
| -------- | -------- |
| &lt;= | 小于等于，例如：screen&nbsp;and&nbsp;(height&nbsp;&lt;=&nbsp;50)。 |
| &gt;= | 大于等于，例如：screen&nbsp;and&nbsp;(height&nbsp;&gt;=&nbsp;600)。 |
| &lt; | 小于，例如：screen&nbsp;and&nbsp;(height&nbsp;&lt;&nbsp;50)。 |
| &gt; | 大于，例如：screen&nbsp;and&nbsp;(height&nbsp;&gt;&nbsp;600)。 |
## 媒体特征
| 类型 | 说明 |
| -------- | -------- |
| height | 应用页面显示区域的高度。 |
| min-height | 应用页面显示区域的最小高度。 |
| max-height | 应用页面显示区域的最大高度。 |
| width | 应用页面显示区域的宽度。 |
| min-width | 应用页面显示区域的最小宽度。 |
| max-width | 应用页面显示区域的最大宽度。 |
| resolution | 设备的分辨率，支持dpi，dppx和dpcm单位。其中：<br/>-&nbsp;dpi表示每英寸中物理像素个数，1dpi≈0.39dpcm；<br/>-&nbsp;dpcm表示每厘米上的物理像素个数，1dpcm&nbsp;≈&nbsp;2.54dpi；<br/>-&nbsp;dppx表示每个px中的物理像素数（此单位按96px=1英寸为基准，与页面中的px单位计算方式不同），1dppx&nbsp;=&nbsp;96dpi。 |
| min-resolution | 设备的最小分辨率。 |
| max-resolution | 设备的最大分辨率。 |
| orientation | 屏幕的方向。<br/>可选值：<br/>-&nbsp;orientation:&nbsp;portrait（设备竖屏）<br/>-&nbsp;orientation:&nbsp;landscape（设备横屏） |
| aspect-ratio | 应用页面显示区域的宽度与高度的比值。<br/>例如：aspect-ratio:1/2 |
| min-aspect-ratio | 应用页面显示区域的宽度与高度的最小比值。 |
| max-aspect-ratio | 应用页面显示区域的宽度与高度的最大比值。 |
| device-height | 设备的高度。 |
| min-device-height | 设备的最小高度。 |
| max-device-height | 设备的最大高度。 |
| device-width | 设备的宽度。 |
| min-device-width | 设备的最小宽度。 |
| max-device-width | 设备的最大宽度。 |
| round-screen | 屏幕类型，圆形屏幕为true，&nbsp;非圆形屏幕为&nbsp;false。 |
| dark-mode<sup>6+</sup> | 系统为深色模式时为true，否则为false。 |
## 示例代码
```html
<!-- xxx.hml -->
<div>
<div class="container">
<text class="title">Hello World</text>
</div>
</div>
```
```css
/* xxx.css */
.container {
width: 300px;
height: 600px;
background-color: #008000;
}
@media (device-type: wearable) {
.container-inner {
justify-content: center;
align-items: center;
padding: 40px 26px;
}
.title {
text-align: center;
}
.detail_text {
max-lines: 2;
text-align: center;
}
}
@media (device-type: tv) {
.title {
font-size: 16px;
}
.detail_text {
font-size: 12px;
}
}
@media (device-type: car) {
.title {
font-size: 12px;
color: #FFFFFF;
font-family: @id_text_font_family_medium;
}
.detail_text {
font-size: 12px;
margin-top: 2px;
font-family: @id_text_font_family_regular;
color: #FFFFFF;
}
}
```
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-common-styles.md 0 → 100644
浏览文件 @ 3035f58a
# 通用样式
组件普遍支持的可以在style或css中设置组件外观样式，均不是必填项。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
| 名称 | 类型 | 默认值 | 描述 |
| -------- | -------- | -------- | -------- |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | - | 设置组件自身的宽度。<br/>缺省时使用元素自身内容需要的宽度。<br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | - | 设置组件自身的高度。<br/>缺省时使用元素自身内容需要的高度。<br/>未设置时组件高度默认为0。 |
| min-width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | 0 | 设置元素的最小宽度。 |
| min-height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | 0 | 设置元素的最小高度。 |
| max-width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | - | 设置元素的最大宽度。默认无限制。 |
| max-height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | - | 设置元素的最大高度。默认无限制。 |
| padding | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | 0 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值：<br/>-&nbsp;指定一个值时，该值指定四个边的内边距。<br/>-&nbsp;指定两个值时，第一个值指定上下两边的内边距，第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时，第一个指定上边的内边距，第二个指定左右两边的内边距，第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距（顺时针顺序）。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | 0 | 设置左、上、右、下内边距属性。 |
| padding-[start\|end] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | 0 | 设置起始和末端内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | 0 | 使用简写属性设置所有的外边距属性，该属性可以有1到4个值。<br/>-&nbsp;只有一个值时，这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时，第一个值被匹配给上和下，第二个值被匹配给左和右。<br/>-&nbsp;三个值时，第一个值被匹配给上,&nbsp;第二个值被匹配给左和右，第三个值被匹配给下。<br/>-&nbsp;四个值时，会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | 0 | 设置左、上、右、下外边距属性。 |
| margin-[start\|end] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | 0 | 设置起始和末端外边距属性。 |
| border | - | 0 | 使用简写属性设置所有的边框属性，包含边框的宽度，样式，颜色属性，顺序设置为border-width、border-style、border-color，不设置时，各属性值为默认值。 |
| border-style | string | solid | 使用简写属性设置所有边框的样式，可选值为：<br/>-&nbsp;dotted：显示为一系列圆点，圆点半径为border-width的一半。<br/>-&nbsp;dashed：显示为一系列短的方形虚线。<br/>-&nbsp;solid：显示为一条实线。 |
| border-[left\|top\|right\|bottom]-style | string | solid | 分别设置左、上、右、下四个边框的样式，可选值为dotted、dashed、solid。 |
| border-[left\|top\|right\|bottom] | - | - | 使用简写属性设置对应位置的边框属性，包含边框的宽度，样式，颜色属性，顺序设置为border-width、border-style、border-color，不设置的值为默认值。 |
| border-width | &lt;length&gt; | 0 | 使用简写属性设置元素的所有边框宽度，或者单独为各边边框设置宽度。 |
| border-[left\|top\|right\|bottom]-width | &lt;length&gt; | 0 | 分别设置左、上、右、下四个边框的宽度。 |
| border-color | &lt;color&gt; | black | 使用简写属性设置元素的所有边框颜色，或者单独为各边边框设置颜色。 |
| border-[left\|top\|right\|bottom]-color | &lt;color&gt; | black | 分别设置左、上、右、下四个边框的颜色。 |
| border-radius | &lt;length&gt; | - | border-radius属性设置元素的外边框圆角半径。设置border-radius时不能单独设置某一个方向的border-[left\|top\|right\|bottom]-width，border-[left\|top\|right\|bottom]-color&nbsp;，border-[left\|top\|right\|bottom]-style，如果要设置color、width和style，需要将四个方向一起设置（border-width、border-color、border-style）。 |
| border-[top\|bottom]-[left\|right]-radius | &lt;length&gt; | - | 分别设置左上，右上，右下和左下四个角的圆角半径。 |
| background | &lt;linear-gradient&gt; | - | 仅支持设置[渐变样式](js-service-widget-common-gradient.md)，与background-color、background-image不兼容。 |
| background-color | &lt;color&gt; | - | 设置背景颜色。 |
| background-image | string | - | 设置背景图片。与background-color、background不兼容，支持本地图片资源地址。<br/>示例：<br/>-&nbsp;background-image:&nbsp;url("/common/background.png")<br/>不支持svg格式图片。 |
| background-size | -&nbsp;string<br/>-&nbsp;&lt;length&gt;&nbsp;&lt;length&gt;<br/>-&nbsp;&lt;percentage&gt;&nbsp;&lt;percentage&gt; | auto | 设置背景图片的大小。<br/>-&nbsp;string可选值：<br/>&nbsp;&nbsp;-&nbsp;contain：把图片扩展至最大尺寸，以使其高度和宽度完全适用内容区域。<br/>&nbsp;&nbsp;-&nbsp;cover：把背景图片扩展至足够大，以使背景图片完全覆盖背景区域；背景图片的某些部分也许无法显示在背景定位区域中。<br/>&nbsp;&nbsp;-&nbsp;auto：保持原图的比例不变。<br/>-&nbsp;length值参数方式：<br/>&nbsp;&nbsp;设置背景图片的高度和宽度。第一个值设置宽度，第二个值设置高度。如果只设置一个值，则第二个值会被设置为&nbsp;"auto"。<br/>-&nbsp;百分比参数方式：<br/>&nbsp;&nbsp;以父元素的百分比来设置背景图片的宽度和高度。第一个值设置宽度，第二个值设置高度。如果只设置一个值，则第二个值会被设置为&nbsp;"auto"。 |
| background-repeat | string | repeat | 针对重复背景图片样式进行设置，背景图片默认在水平和垂直方向上重复。<br/>-&nbsp;repeat：在水平轴和竖直轴上同时重复绘制图片。<br/>-&nbsp;repeat-x：只在水平轴上重复绘制图片。<br/>-&nbsp;repeat-y：只在竖直轴上重复绘制图片。<br/>-&nbsp;no-repeat：不会重复绘制图片。 |
| background-position | -&nbsp;string&nbsp;string<br/>-&nbsp;&lt;length&gt;&nbsp;&lt;length&gt;<br/>-&nbsp;&lt;percentage&gt;&nbsp;&lt;percentage&gt; | 0px&nbsp;0px | -&nbsp;关键词方式：如果仅规定了一个关键词，那么第二个值为"center"。两个值分别定义水平方向位置和竖直方向位置。<br/>&nbsp;&nbsp;-&nbsp;left：水平方向上最左侧。<br/>&nbsp;&nbsp;-&nbsp;right：水平方向上最右侧。<br/>&nbsp;&nbsp;-&nbsp;top：竖直方向上最顶部。<br/>&nbsp;&nbsp;-&nbsp;bottom：竖直方向上最底部。<br/>&nbsp;&nbsp;-&nbsp;center：水平方向或竖直方向上中间位置。<br/>-&nbsp;length值参数方式：第一个值是水平位置，第二个值是垂直位置。&nbsp;左上角是&nbsp;0&nbsp;0。单位是像素&nbsp;(0px&nbsp;0px)&nbsp;&nbsp;。如果仅规定了一个值，另外一个值将是50%。<br/>-&nbsp;百分比参数方式：第一个值是水平位置，第二个值是垂直位置。左上角是&nbsp;0%&nbsp;0%。右下角是&nbsp;100%&nbsp;100%。如果仅规定了一个值，另外一个值为50%。<br/>-&nbsp;可以混合使用&lt;percentage&gt;和&lt;length&gt;。 |
| box-shadow | string | 0 | 语法：box-shadow:&nbsp;h-shadow&nbsp;v-shadow&nbsp;blur&nbsp;spread&nbsp;color<br/>通过这个样式可以设置当前组件的阴影样式，包括水平位置(必填)、垂直位置(必填)、模糊半径(可选，默认值为0)、阴影延展距离(可选，默认值为0)、阴影颜色(可选，默认值为黑色)。<br/>示例：<br/>-&nbsp;box-shadow&nbsp;:10px&nbsp;20px&nbsp;5px&nbsp;10px&nbsp;\#888888<br/>-&nbsp;box-shadow&nbsp;:100px&nbsp;100px&nbsp;30px&nbsp;red<br/>-&nbsp;box-shadow&nbsp;:-100px&nbsp;-100px&nbsp;0px&nbsp;40px |
| filter | string | - | 语法：filter:&nbsp;blur(px)<br/>通过这个样式可以设置当前组件布局范围的内容模糊，参数用于指定模糊半径，如果没有设置值，则默认是0(不模糊)，不支持百分比。<br/>示例：filter:&nbsp;blur(10px) |
| backdrop-filter | string | - | 语法：backdrop-filter:&nbsp;blur(px)<br/>通过这个样式可以设置当前组件布局范围的背景模糊，参数用于指定模糊半径，如果没有设置值，则默认是0(不模糊)，不支持百分比。<br/>示例：backdrop-filter:&nbsp;blur(10px) |
| opacity | number | 1 | 元素的透明度，取值范围为0到1，1表示为不透明，0表示为完全透明。 |
| display | string | flex | 确定一个元素所产生的框的类型，可选值为：<br/>-&nbsp;flex：弹性布局。<br/>-&nbsp;none：不渲染此元素。 |
| visibility | string | visible | 是否显示元素所产生的框。不可见的框会占用布局（将'display'属性设置为'none'来完全去除框），可选值为：<br/>-&nbsp;visible：元素正常显示。<br/>-&nbsp;hidden：隐藏元素，但是其他元素的布局不改变，相当于此元素变成透明<br/>visibility和display样式都设置时，仅display生效。 |
| flex | number&nbsp;\|&nbsp;string | - | 规定当前组件如何适应父组件中的可用空间。<br/>flex可以指定1个、2个或3个值。<br/>单值语法：<br/>-&nbsp;一个无单位数：用来设置组件的flex-grow。<br/>-&nbsp;一个有效的宽度值：用来设置组件的flex-basis。<br/>双值语法：<br/>第一个值必须是无单位数，用来设置组件的flex-grow。第二个值是以下之一：<br/>-&nbsp;一个无单位数：用来设置组件的flex-shrink。<br/>-&nbsp;一个有效的宽度值：用来设置组件的flex-basis。<br/>三值语法：<br/>第一个值必须是无单位数，用来设置组件的flex-grow；第二个值必须是无单位数，用来设置组件的flex-shrink；第三个值必须是一个有效的宽度值，用来设置组件的flex-basis。<br/>仅父容器为&lt;div&gt;、&lt;list-item&gt;时生效。 |
| flex-grow | number | 0 | 设置组件的拉伸样式，指定父组件容器主轴方向上剩余空间（容器本身大小减去所有flex子元素占用的大小）的分配权重。0为不伸展。<br/>仅父容器为&lt;div&gt;、&lt;list-item&gt;时生效。 |
| flex-shrink | number | 1 | 设置组件的收缩样式，元素仅在默认宽度之和大于容器的时候才会发生收缩，0为不收缩。<br/>仅父容器为&lt;div&gt;、&lt;list-item&gt;时生效。 |
| flex-basis | &lt;length&gt; | - | 设置组件在主轴方向上的初始大小。<br/>仅父容器为&lt;div&gt;、&lt;list-item&gt;时生效。 |
| align-self | string | - | 设置自身在父元素交叉轴上的对齐方式，该样式会覆盖父元素的align-items样式，仅在父容器为div、list。可选值为：<br/>-&nbsp;stretch&nbsp;弹性元素被在交叉轴方向被拉伸到与容器相同的高度或宽度。<br/>-&nbsp;flex-start&nbsp;元素向交叉轴起点对齐。<br/>-&nbsp;flex-end&nbsp;元素向交叉轴终点对齐。<br/>-&nbsp;center&nbsp;元素在交叉轴居中。<br/>-&nbsp;baseline&nbsp;元素在交叉轴基线对齐。 |
| position | string | relative | 设置元素的定位类型，不支持动态变更。<br/>-&nbsp;fixed：相对与整个界面进行定位。<br/>-&nbsp;absolute：相对于父元素进行定位。<br/>-&nbsp;relative：相对于其正常位置进行定位。<br/>absolute属性仅在父容器为&lt;div&gt;时生效。 |
| [left\|top\|right\|bottom | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | - | left\|top\|right\|bottom需要配合position样式使用，来确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。<br/>-&nbsp;right属性规定元素的右边缘。该属性定义了定位元素右外边距边界与其包含块右边界之间的偏移。<br/>-&nbsp;bottom属性规定元素的底部边缘。该属性定义了一个定位元素的下外边距边界与其包含块下边界之间的偏移。 |
| [start&nbsp;\|&nbsp;end] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | - | start&nbsp;\|&nbsp;end需要配合position样式使用，来确定元素的偏移位置。<br/>-&nbsp;start属性规定元素的起始边缘。该属性定义了定位元素起始外边距边界与其包含块起始边界之间的偏移。<br/>-&nbsp;end属性规定元素的结尾边缘。该属性定义了一个定位元素的结尾边距边界与其包含块结尾边界之间的偏移。 |
| z-index | number | - | 表示对于同一父节点其子节点的渲染顺序。数值越大，渲染数据越靠后。<br/>z-index不支持auto，并且opacity等其他样式不会影响z-index的渲染顺序。 |
| image-fill | &lt;color&gt; | - | 为svg图片填充颜色，支持组件范围（与设置图片资源的属性）：button（icon属性）、image（src属性）。<br/>svg图片文件内的fill属性颜色值在渲染时将被替换为image-fill所配的颜色值，且仅对svg图片内显示声明的fill属性生效。 |
| clip-path | [&nbsp;&lt;geometry-box&gt;&nbsp;\|&lt;basic-shape&gt;&nbsp;]&nbsp;\|&nbsp;none | - | 设置组件的裁剪区域。区域内的部分显示，区域外的不显示。<br/>&lt;geometry-box&gt;：表示裁剪区域的作用范围，默认为border-box。可选值为：<br/>-&nbsp;margin-box：margin计算入长宽尺寸内。<br/>-&nbsp;border-box：border计算入长宽尺寸内。<br/>-&nbsp;padding-box：padding计算入长宽尺寸内。<br/>-&nbsp;content-box：margin/border/padding不计算入长宽尺寸内。<br/>&lt;basic-shape&gt;：表示裁剪的形状。包含以下类型：<br/>-&nbsp;inset，格式为：inset(&nbsp;&lt;percentage&gt;{1,4}&nbsp;[&nbsp;round&nbsp;&lt;'border-radius'&gt;&nbsp;]?&nbsp;)。<br/>-&nbsp;circle，格式为：circle(&nbsp;[&nbsp;&lt;percentage&gt;&nbsp;]?&nbsp;[&nbsp;at&nbsp;&lt;percentage&gt;&nbsp;&lt;percentage&gt;&nbsp;]?&nbsp;)。<br/>-&nbsp;ellipse，格式为：ellipse(&nbsp;[&nbsp;&lt;percentage&gt;{2}&nbsp;]?&nbsp;[&nbsp;at&nbsp;&lt;percentage&gt;&nbsp;&lt;percentage&gt;&nbsp;]?&nbsp;)。<br/>-&nbsp;polygon，格式为：polygon(&nbsp;[&nbsp;&lt;percentage&gt;&nbsp;&lt;percentage&gt;&nbsp;]\#&nbsp;)。<br/>-&nbsp;path，格式为：path(&nbsp;&lt;string&gt;&nbsp;)。 |
| mask-image | -&nbsp;&lt;linear-gradient&gt;<br/>-&nbsp;string | - | 设置渐变色遮罩或本地图片设置。<br/>设置渐变色遮罩，示例：linear-gradient(to&nbsp;left,&nbsp;black,&nbsp;white)<br/>设置纯色遮罩，示例：linear-gradient(to&nbsp;right,&nbsp;grey&nbsp;,&nbsp;grey)<br/>设置本地svg图片为遮罩，示例：url(common/mask.svg) |
| mask-size | -&nbsp;string<br/>-&nbsp;&lt;length&gt;&lt;length&gt;<br/>-&nbsp;&lt;percentage&gt;&nbsp;&lt;percentage&gt; | auto | 设置遮罩图片显示大小，仅当mask-image为图片资源时有效。<br/>string可选值：<br/>-&nbsp;contain：把图像扩展至最大尺寸，以使其高度和宽度完全适用内容区域。<br/>-&nbsp;cover：把图像扩展至足够大，以使背景图像完全覆盖背景区域；背景图像的某些部分也许无法显示在背景定位区域中。<br/>-&nbsp;auto：保持原图的比例不变。<br/>length值参数方式：设置图像的高度和宽度。第一个值设置宽度，第二个值设置高度。如果只设置一个值，则第二个值会被设置为&nbsp;"auto"。<br/>百分比参数方式：以原图宽高的百分比来设置图像的宽度和高度。第一个值设置宽度，第二个值设置高度。如果只设置一个值，则第二个值会被设置为&nbsp;"auto"。 |
| mask-position | -&nbsp;string&nbsp;string<br/>-&nbsp;&lt;length&gt;&nbsp;&lt;length&gt;<br/>-&nbsp;&lt;percentage&gt;&nbsp;&lt;percentage&gt; | 0px&nbsp;0px | 设置遮罩图片显示位置，仅当mask-image为图片资源时有效。关键词方式：如果仅规定了一个关键词，那么第二个值为"center"。两个值分别定义水平方向位置和竖直方向位置。<br/>string可选值：<br/>-&nbsp;left：水平方向上最左侧。<br/>-&nbsp;right：水平方向上最右侧。<br/>-&nbsp;top：竖直方向上最顶部。<br/>-&nbsp;bottom：竖直方向上最底部。<br/>-&nbsp;center：水平方向或竖直方向上中间位置。<br/>length值参数方式：第一个值是水平位置，第二个值是垂直位置。&nbsp;左上角是&nbsp;0&nbsp;0。单位是像素&nbsp;(0px&nbsp;0px)&nbsp;&nbsp;。如果仅规定了一个值，另外一个值将是50%。<br/>百分比参数方式：第一个值是水平位置，第二个值是垂直位置。左上角是&nbsp;0%&nbsp;0%。右下角是&nbsp;100%&nbsp;100%。如果仅规定了一个值，另外一个值为50%。<br/>可以混合使用&lt;percentage&gt;和&lt;length&gt;。 |
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-config-file.md 0 → 100644
浏览文件 @ 3035f58a
# 配置文件
js标签中包含了实例名称、窗口样式和卡片页面信息。
| 标签 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| name | String | default | 是 | 标识JS实例的名字。 |
| pages | Array | - | 是 | 路由信息，详见“[pages](#pages)”。 |
| window | Object | - | 否 | 窗口信息，详见“[window](#window)”。 |
> **说明：**
> name、pages、window等标签配置需在[配置文件]()中的“js”标签中完成设置。
## pages
定义卡片页面信息，由卡片页面路径和卡片页面名组成，卡片仅包含一个页面。比如：
```
{
...
"src": "./js/widget/pages/index/index" //卡片仅包含一个页面
...
}
```
> **说明：**
> - pages列表中仅包含一个页面。
>
> - 页面文件名不能使用组件名称，比如：text.hml、button.hml等。
## window
window用于定义与显示窗口相关的配置。对于卡片尺寸适配问题，有2种配置方法，建议使用autoDesignWidth：
- 指定卡片designWidth 150px（2×2），所有与大小相关的样式（例如width、font-size）均以designWidth和实际卡片宽度的比例进行缩放，例如在designWidth为150时，如果设置width为100px时，在卡片实际宽度为300物理像素时，width实际渲染像素为200物理像素。
- 设置autoDesignWidth为true，此时designWidth字段将会被忽略，渲染组件和布局时按屏幕密度进行缩放。屏幕逻辑宽度由设备宽度和屏幕密度自动计算得出，在不同设备上可能不同，请使用相对布局来适配多种设备。例如：在466\*466分辨率，320dpi的设备上，屏幕密度为2（以160dpi为基准），1px等于渲染出的2物理像素。
> **说明：**
> - 组件样式中&lt;length&gt;类型的默认值，按屏幕密度进行计算和绘制，如：在屏幕密度为2（以160dpi为基准）的设备上，默认&lt;length&gt;为1px时，设备上实际渲染出2物理像素。
>
> - autoDesignWidth、designWidth的设置不影响默认值计算方式和绘制结果。
| 属性 | 类型 | 必填 | 默认值 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| designWidth | number | 否 | 150px | 页面显示设计时的参考值，实际显示效果基于设备宽度与参考值之间的比例进行缩放。 |
| autoDesignWidth | boolean | 否 | false | 页面设计基准宽度是否自动计算，当设为true时，designWidth将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出。 |
示例如下：
```
{
...
"window": {
"autoDesignWidth": true
}
...
}
```
## 示例
```json
{
"forms": [
{
"name": "widget",
"description": "This is a service widget.",
"src": "./js/widget/pages/index/index",
"window": {
"designWidth": 720,
"autoDesignWidth": true
},
"colorMode": "auto",
"isDefault": true,
"updateEnabled": true,
"scheduledUpdateTime": "10:30",
"updateDuration": 1,
"defaultDimension": "2*2",
"supportDimensions": [
"1*2","2*2","2*4","4*4"
],
"formConfigAbility": "ability://xxxxx"
}
]
}
```
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-configuration.md 0 → 100644
浏览文件 @ 3035f58a
# 配置数据和事件
卡片使用json文件配置卡片使用的变量和事件，变量的声明在data字段下，事件的声明在actions字段下。
示例：
```json
{
"data": {
"temperature": "35°C",
"city": "hangzhou"
},
"actions": {
"routerEventName": {
"action": "router",
"abilityName": "com.example.myapplication.FormAbility",
"params": {
"message": "weather",
"temperature": "{{temperature}}"
}
},
"messageEventName": {
"action": "message",
"params": {
"message": "weather update"
}
}
}
}
```
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-container-div.md 0 → 100644
浏览文件 @ 3035f58a
# div
基础容器，用作页面结构的根节点或将内容进行分组。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 子组件
支持。
## 属性
支持[通用属性](js-service-widget-common-attributes.md)。
## 样式
除支持[通用样式](js-service-widget-common-styles.md)外，还支持如下样式：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| flex-direction | string | row | 否 | flex容器主轴方向。可选项有：<br/>-&nbsp;column：垂直方向从上到下。<br/>-&nbsp;row：水平方向从左到右。 |
| flex-wrap | string | nowrap | 否 | flex容器是单行还是多行显示，该值暂不支持动态修改。可选项有：<br/>-&nbsp;nowrap：不换行，单行显示。<br/>-&nbsp;wrap：换行，多行显示。 |
| justify-content | string | flex-start | 否 | flex容器当前行的主轴对齐格式。可选项有：<br/>-&nbsp;flex-start：项目位于容器的开头。<br/>-&nbsp;flex-end：项目位于容器的结尾。<br/>-&nbsp;center：项目位于容器的中心。<br/>-&nbsp;space-between：项目位于各行之间留有空白的容器内。<br/>-&nbsp;space-around：项目位于各行之前、之间、之后都留有空白的容器内。<br/>-&nbsp;space-evenly<sup>5+</sup>:&nbsp;&nbsp;均匀排列每个元素，每个元素之间的间隔相等。 |
| align-items | string | stretch | 否 | flex容器当前行的交叉轴对齐格式，可选值为：<br/>-&nbsp;stretch：弹性元素在交叉轴方向被拉伸到与容器相同的高度或宽度。<br/>-&nbsp;flex-start：元素向交叉轴起点对齐。<br/>-&nbsp;flex-end：元素向交叉轴终点对齐。<br/>-&nbsp;center：元素在交叉轴居中。 |
| align-content | string | flex-start | 否 | 交叉轴中有额外的空间时，多行内容对齐格式，可选值为：<br/>-&nbsp;flex-start：所有行从交叉轴起点开始填充。第一行的交叉轴起点边和容器的交叉轴起点边对齐。接下来的每一行紧跟前一行。<br/>-&nbsp;flex-end：所有行从交叉轴末尾开始填充。最后一行的交叉轴终点和容器的交叉轴终点对齐。同时所有后续行与前一个对齐。<br/>-&nbsp;center：所有行朝向容器的中心填充。每行互相紧挨，相对于容器居中对齐。容器的交叉轴起点边和第一行的距离相等于容器的交叉轴终点边和最后一行的距离。<br/>-&nbsp;space-between：所有行在容器中平均分布。相邻两行间距相等。容器的交叉轴起点边和终点边分别与第一行和最后一行的边对齐。<br/>-&nbsp;space-around：所有行在容器中平均分布，相邻两行间距相等。容器的交叉轴起点边和终点边分别与第一行和最后一行的距离是相邻两行间距的一半。 |
| display | string | flex | 否 | 确定该元素视图框的类型，该值暂不支持动态修改。可选值为：<br/>-&nbsp;flex：弹性布局<br/>-&nbsp;none：不渲染此元素 |
| grid-template-[columns\|rows] | string | 1行1列 | 否 | 用于设置当前网格布局行和列的数量，不设置时默认1行1列，仅当display为grid时生效。<br/>示例：如设置grid-template-columns为：<br/>-&nbsp;50px&nbsp;100px&nbsp;60px：分三列，第一列50px，第二列100px，第三列60px。<br/>-&nbsp;1fr&nbsp;1fr&nbsp;2fr：分三列，将父组件允许的宽分为4等份，第一列占1份，第二列占一份，第三列占2份。<br/>-&nbsp;30%&nbsp;20%&nbsp;50%：分三列，将父组件允许的宽为基准，第一列占30%，第二列占20%，第三列占50%。<br/>-&nbsp;repeat(2,100px)：分两列，第一列100px，第二列100px。<br/>-&nbsp;repeat(auto-fill,100px)<sup>5+</sup>：按照每列100px的大小和交叉轴大小计算最大正整数重复次数，按照该重复次数布满交叉轴。<br/>-&nbsp;auto&nbsp;1fr&nbsp;1fr：分三列，第一列自适应内部子组件所需宽度，剩余空间分为两等份，第二列占一份，第三列占一份。 |
| grid-[columns\|rows]-gap | &lt;length&gt; | 0 | 否 | 用于设置行与行的间距或者列与列的间距，也可以支持通过grid-gap设置相同的行列间距，仅当display为grid时生效。 |
| grid-row-[start\|end] | number | - | 否 | 用于设置当前元素在网格布局中的起止行号，仅当父组件display样式为grid时生效（仅div支持display样式设置为grid）。 |
| grid-column-[start\|end] | number | - | 否 | 用于设置当前元素在网格布局中的起止列号，仅当父组件display样式为grid时生效（仅div支持display样式设置为grid）。 |
| grid-auto-flow | string | - | 否 | 使用框架自动布局算法进行网格的布局，可选值为：<br/>-&nbsp;row：逐行填充元素，如果行空间不够，则新增行。<br/>-&nbsp;column：逐列填充元素，如果列空间不够，则新增列。 |
| align-items | string | - | 否 | 设置容器中元素交叉轴上的对齐方式：<br/>-&nbsp;stretch：Flex容器内容在交叉轴方向被拉伸到与容器相同的高度或宽度。<br/>-&nbsp;flex-start：Flex布局容器内元素向交叉轴起点对齐。<br/>-&nbsp;flex-end：Flex布局容器内元素向交叉轴终点对齐。<br/>-&nbsp;center：Flex布局容器内元素在交叉轴居中对齐。<br/>-&nbsp;baseline：如Flex布局纵向排列，则该值与'flex-start'等效。横向布局时，内容元素存在文本时按照文本基线对齐，否则底部对齐。 |
## 事件
支持[通用事件](js-service-widget-common-events.md)。
## 示例
1. Flex样式
```html
<!-- xxx.hml -->
<div class="container">
<div class="flex-box">
<div class="flex-item color-primary"></div>
<div class="flex-item color-warning"></div>
<div class="flex-item color-success"></div>
</div>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
width: 454px;
height: 454px;
}
.flex-box {
justify-content: space-around;
align-items: center;
width: 400px;
height: 140px;
background-color: #ffffff;
}
.flex-item {
width: 120px;
height: 120px;
border-radius: 16px;
}
.color-primary {
background-color: #007dff;
}
.color-warning {
background-color: #ff7500;
}
.color-success {
background-color: #41ba41;
}
```
**2*4卡片**
![zh-cn_image_0000001231610863](figures/zh-cn_image_0000001231610863.png)
2. Flex Wrap样式
```html
<!-- xxx.hml -->
<div class="container">
<div class="flex-box">
<div class="flex-item color-primary"></div>
<div class="flex-item color-warning"></div>
<div class="flex-item color-success"></div>
</div>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
width: 454px;
height: 454px;
}
.flex-box {
justify-content: space-around;
align-items: center;
flex-wrap: wrap;
width: 300px;
height: 250px;
background-color: #ffffff;
}
.flex-item {
width: 120px;
height: 120px;
border-radius: 16px;
}
.color-primary {
background-color: #007dff;
}
.color-warning {
background-color: #ff7500;
}
.color-success {
background-color: #41ba41;
}
```
**4*4卡片**
![zh-cn_image_0000001186131150](figures/zh-cn_image_0000001186131150.png)
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-container-list-item.md 0 → 100644
浏览文件 @ 3035f58a
# list-item
&lt;[list](js-service-widget-container-list.md)&gt;的子组件，用来展示列表具体item。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
> - 由于父元素list组件的align-items默认样式为stretch，该组件宽度默认充满list组件。设置父元素list组件的align-items样式为非stretch来生效自定义宽度。
>
> - list-item组件开发避免长按和拖动操作。
## 子组件
支持。
## 属性
除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| type | string | default | 否 | list-item类型，默认值为default，同一list中可以包含多种type的list-item，相同type的list-item需要确保渲染后的视图布局也相同，如果type固定，则使用show属性代替if属性，确保视图布局不变。 |
| section | string | - | 否 | 当前item的匹配字符串，如不设置则为空。不支持动态修改。group内只有主item设置有效。 |
| sticky | string | none | 否 | 设置当前item是否为吸顶item以及其吸顶消失的效果，当前仅支持纵向list，group内部的item不可吸顶，设置该属性无效。<br/>-&nbsp;none：当前item不吸顶。<br/>-&nbsp;normal：当前item吸顶，消失效果滑动消失。<br/>-&nbsp;opacity：当前item吸顶，消失效果渐隐消失，仅在智能穿戴上支持。 |
| clickeffect | boolean | true | 否 | 设置当前item是否有点击动效。<br/>-&nbsp;false：item点击时无点击动效。<br/>-&nbsp;true：item点击时有点击动效。 |
## 样式
除支持[通用样式](js-service-widget-common-styles.md)外，还支持如下样式：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| column-span | &lt;number&gt; | 1 | 否 | 当前的list-item需要在list中占据的列的数量，默认占一列，仅在list为多列时生效。 |
| click-color | &lt;color&gt; | - | 否 | 设置列表项按压点击时的背板颜色。 |
## 事件
支持[通用事件](js-service-widget-common-events.md)。
## 示例
详见[list示例](js-service-widget-container-list.md#示例)。
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-container-list.md 0 → 100644
浏览文件 @ 3035f58a
# list
列表包含一系列相同宽度的列表项。适合连续、多行呈现同类数据，例如图片和文本。
> **说明：**
>
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
>
> 针对卡片场景，建议开发者控制list中的子节点list-item的数量（建议30条以内）以便获取更好的卡片交互体验。
## 子组件
仅支持&lt;[list-item](js-service-widget-container-list-item.md)&gt;子组件。
## 属性
除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| cachedcount | number | 0 | 否 | 长列表延迟加载时list-item最少缓存数量。 |
| scrollbar | string | off | 否 | 侧边滑动栏的显示模式（当前只支持纵向）：<br/>-&nbsp;off：不显示。<br/>-&nbsp;auto：按需显示(触摸时显示，2s后消失)。<br/>-&nbsp;on：常驻显示。 |
| scrolleffect | string | spring | 否 | 滑动效果，目前支持如下滑动效果：<br/>-&nbsp;spring：弹性物理动效，滑动到边缘后可以根据初始速度或通过触摸事件继续滑动一段距离，松手后回弹。<br/>-&nbsp;fade：渐隐物理动效，滑动到边缘后展示一个波浪形的渐隐，根据速度和滑动距离的变化渐隐也会发送一定的变化。<br/>-&nbsp;no：滑动到边缘后无效果。 |
| divider | boolean | false | 否 | item是否自带分隔线。<br/>其样式参考[样式列表](#样式)的divider-color、divider-height、divider-length、divider-origin。 |
| shapemode | string | default | 否 | 侧边滑动栏的形状类型。<br/>-&nbsp;default：不指定，跟随主题。<br/>-&nbsp;rect：矩形。<br/>-&nbsp;round：圆形。 |
| updateeffect | boolean | false | 否 | 用于设置当list内部的item发生删除或新增时是否支持动效。<br/>-&nbsp;false：新增删除item时无过渡动效。<br/>-&nbsp;true：新增删除item时播放过程动效。 |
| initialindex | number | 0 | 否 | 用于设置当前List初次加载时视口起始位置显示的item，默认为0，即显示第一个item，如设置的序号超过了最后一个item的序号，则设置不生效，当同时设置了initialoffset属性时，当前属性不生效。 |
| initialoffset | &lt;length&gt; | 0 | 否 | 用于设置当前List初次加载时视口的起始偏移量，偏移量无法超过当前List可滑动的范围，如果超过会被截断为可滑动范围的极限值。 |
| selected | string | - | 否 | 指定当前列表中被选中激活的项，可选值为list-item的section属性值。 |
## 样式
除支持[通用样式](js-service-widget-common-styles.md)外，还支持如下样式：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| divider-color | &lt;color&gt; | transparent | 否 | item分隔线颜色，仅当list的divider属性为true时生效。 |
| divider-height | &lt;length&gt; | 1 | 否 | item分隔线高度，仅当list的divider属性为true时生效。 |
| divider-length | &lt;length&gt; | 主轴宽度 | 否 | item分隔线长度，不设置时最大长度为主轴宽度，具体长度取决于divider-origin，仅当list的divider属性为true时生效。 |
| divider-origin | &lt;length&gt; | 0 | 否 | item分隔线相对于item主轴起点位置的偏移量，仅当list的divider属性为true时生效。 |
| flex-direction | string | column | 否 | 设置flex容器主轴的方向，指定flex项如何放置在flex容器中，可选值为：<br/>-&nbsp;column：主轴为纵向。<br/>-&nbsp;row：主轴为横向。<br/>其他组件默认值为row，在list组件中默认值为column。 |
| columns | number | 1 | 否 | list交叉轴方向的显示列数，默认为1列。<br/>设置多列时，在list交叉轴上进行均分，每一列大小相同。 |
| align-items | string | stretch | 否 | list每一列交叉轴上的对齐格式，可选值为：<br/>-&nbsp;stretch：弹性元素被在交叉轴方向被拉伸到与容器相同的高度或宽度。<br/>-&nbsp;flex-start：元素向交叉轴起点对齐。<br/>-&nbsp;flex-end：元素向交叉轴终点对齐。<br/>-&nbsp;center：元素在交叉轴居中。<br/>&nbsp;align-items样式作用在每一列的子元素上，列与列之间采用均分方式布局。 |
| item-extent | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | - | 否 | 设置内部item为固定大小，设置为百分比格式时，指相对于list的视口主轴方向长度的百分比。 |
| fade-color | &lt;color&gt; | grey | 否 | 设置渐隐物理动效的颜色。当滑动效果设置为渐隐物理动效时生效。 |
| scrollbar-color | &lt;color&gt; | - | 否 | 设置滚动条的颜色。 |
| scrollbar-width | &lt;length&gt; | - | 否 | 设置滚动条的宽度。 |
| scrollbar-offset | &lt;length&gt; | 0 | 否 | 设置滚动条距离List默认位置的偏移量，只支持正数，默认位置在List右边缘，可以通过这个偏移量调整滚动条的水平位置，如果滚动条绘制在list外部，而list父组件有裁剪，会导致滚动条被裁剪。 |
## 事件
支持[通用事件](js-service-widget-common-events.md)。
## 示例
```html
<!-- index.hml -->
<div class="container">
<list class="todo-wraper">
<list-item for="{{todolist}}" class="todo-item">
<text class="todo-title">{{$item.title}}</text>
<text class="todo-title">{{$item.date}}</text>
</list-item>
</list>
</div>
```
```json
// xxx.json
{
"data": {
"todolist": [{
"title": "work",
"date": "2021-12-31 10:00:00"
}, {
"title": "watch movie",
"date": "2021-12-31 20:00:00"
}]
}
}
```
```css
/* index.css */
.container {
display: flex;
justify-content: center;
align-items: center;
left: 0px;
top: 0px;
width: 454px;
height: 454px;
}
.todo-wraper {
width: 454px;
height: 300px;
}
.todo-item {
width: 454px;
height: 80px;
flex-direction: column;
}
.todo-title {
width: 454px;
height: 40px;
text-align: center;
}
```
**4*4卡片**
![zh-cn_image_0000001231370803](figures/zh-cn_image_0000001231370803.png)
\ No newline at end of file
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-container-stack.md 0 → 100644
浏览文件 @ 3035f58a
# stack
堆叠容器，子组件按照顺序依次入栈，后一个子组件覆盖前一个子组件。
> **说明：**
>
>从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 子组件
支持。
## 属性
支持[通用属性](js-service-widget-common-attributes.md)。
## 样式
支持[通用样式](js-service-widget-common-styles.md)。
## 事件
支持[通用事件](js-service-widget-common-events.md)。
## 示例
```html
<!-- xxx.hml -->
<stack class="stack-parent">
<div class="back-child bd-radius"></div>
<div class="positioned-child bd-radius"></div>
<div class="front-child bd-radius"></div>
</stack>
```
```css
/* xxx.css */
.stack-parent {
width: 400px;
height: 400px;
margin: 50px;
background-color: #ffffff;
border-width: 1px;
border-style: solid;
}
.back-child {
width: 300px;
height: 300px;
background-color: #3f56ea;
}
.front-child {
width: 100px;
height: 100px;
background-color: #00bfc9;
}
.positioned-child {
width: 100px;
height: 100px;
left: 50px;
top: 50px;
background-color: #47cc47;
}
.bd-radius {
border-radius: 16px;
}
```
**4*4卡片**
![卡片 stack](figures/stack.PNG)
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-container-swiper.md 0 → 100644
浏览文件 @ 3035f58a
# swiper
滑动容器，提供切换子组件显示的能力。
> **说明：**
>
>从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 属性
除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| index | number | 0 | 否 | 当前在容器中显示的子组件的索引值。 |
| indicator | boolean | true | 否 | 是否启用导航点指示器，默认true。 |
| digital | boolean | false | 否 | 是否启用数字导航点，默认为false。<br/>必须设置indicator时才能生效数字导航点。 |
| loop | boolean | true | 否 | 是否开启循环滑动。 |
| duration | number | - | 否 | 子组件切换的动画时长。 |
| vertical | boolean | false | 否 | 是否为纵向滑动，纵向滑动时采用纵向的指示器。 |
## 样式
除支持[通用样式](js-service-widget-common-styles.md)外，还支持如下样式：
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| indicator-color | &lt;color&gt; | - | 否 | 导航点指示器的填充颜色。 |
| indicator-selected-color | &lt;color&gt; | - | 否 | 导航点指示器选中的颜色。 |
| indicator-size | &lt;length&gt; | 4px | 否 | 导航点指示器的直径大小。 |
| indicator-top\|left\|right\|bottom | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt; | - | 否 | 导航点指示器在swiper中的相对位置。 |
## 事件
支持[通用事件](js-service-widget-common-events.md)。
## 示例
```html
<!-- xxx.hml -->
<swiper class="container" index="{{index}}">
<div class="swiper-item primary-item">
<text>1</text>
</div>
<div class="swiper-item warning-item">
<text>2</text>
</div>
<div class="swiper-item success-item">
<text>3</text>
</div>
</swiper>
```
```css
/* xxx.css */
.container {
left: 0px;
top: 0px;
width: 454px;
height: 454px;
}
.swiper-item {
width: 454px;
height: 454px;
justify-content: center;
align-items: center;
}
.primary-item {
background-color: #007dff;
}
.warning-item {
background-color: #ff7500;
}
.success-item {
background-color: #41ba41;
}
```
```json
// xxx.json
{
"data": {
"index": 1
}
}
```
**4*4卡片**
![卡片swiper](figures/swiper.png)
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-custom-basic-usage.md 0 → 100644
浏览文件 @ 3035f58a
# 自定义组件基本用法
> **说明：**
> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
自定义组件是用户根据业务需求，将已有的组件组合，封装成的新组件，可以在工程中多次调用，提高代码的可读性。自定义组件通过element引入到宿主页面，使用方法：
```html
<element name='comp' src='../../common/component/comp.hml'></element>
<div>
<comp prop1='xxxx' @child1="bindParentVmMethod"></comp>
</div>
```
- name属性指自定义组件名称(非必填)，组件名称对大小写不敏感，默认使用小写。src属性指自定义组件hml文件路径(必填)，若没有设置name属性，则默认使用hml文件名作为组件名。
- 事件绑定：自定义组件中绑定子组件事件使用(on|\@)child1语法，子组件中通过{action:"proxy", method: "eventName"}触发事件并进行传值，父组件执行bindParentVmMethod方法并接收子组件传递的参数。
## 自定义组件配置文件标签
| 属性 | 类型 | 描述 |
| -------- | -------- | -------- |
| data | Object | 页面的数据模型，类型是对象。属性名不能以$或_开头，不要使用保留字for,&nbsp;if,&nbsp;show,&nbsp;tid。 |
| props | Array/Object | props用于组件之间的通信，可以通过&lt;tag&nbsp;xxxx='value'&gt;方式传递给组件；props名称必须用小写，不能以$或_开头，不要使用保留字for,&nbsp;if,&nbsp;show,&nbsp;tid。目前props的数据类型不支持Function。 |
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-custom-events.md 0 → 100644
浏览文件 @ 3035f58a
# 自定义事件
自定义组件内支持自定义事件，该事件的标识需要action类型指定为proxy，事件名则通过method指定。使用该自定义组件的卡片页面可以通过该事件名注册相应的事件回调，当自定义组件内该自定义事件触发时，会触发卡片页面上注册的回调事件。
> **说明：**
>
> 事件名不支持大写字母。
## 子组件comp示例：
```html
<!-- comp.hml -->
<div class="container">
<div class="row-3" if="true">
<button onclick="buttonClicked" value="click"></button>
</div>
</div>
```
```css
/* comp.css */
.container {
flex-direction:column;
background-color: green;
width: 100%;
height: 100%;
}
.row-3 {
width: 100%;
height: 50px;
background-color: orange;
font-size:15px;
}
```
```json
// comp.json
{
"data": {
},
"actions": {
"buttonClicked": {
"action": "proxy",
"method":"event_1"
}
}
}
```
## 卡片页面示例
```html
<!-- xxx.hml -->
<element name='comp' src='../../common/customComponent/customComponent.hml'></element>
<div class="container">
<comp @event_1="click"></comp>
<button value="parentClick" @click="buttonClick"></button>
</div>
```
```css
/* xxx.css */
.container {
background-color: red;
height: 500px;
width: 500px;
}
```
```json
// xxx.json
{
"data": {
},
"actions": {
"click": {
"action": "message",
"params": {
"message": "click event"
}
},
"buttonClick": {
"action": "message",
"params": {
"message": "click event 2"
}
}
}
}
```
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-custom-props.md 0 → 100644
浏览文件 @ 3035f58a
# Props
自定义组件可以通过props声明属性，父组件通过设置属性向子组件传递参数。通过父组件向下传递参数的示例如下：
## 添加默认值
子组件可以通过固定值default设置默认值，当父组件没有设置该属性时，将使用其默认值。此情况下props属性必须为对象形式，不能用数组形式，示例如下：
```html
<!-- comp.hml -->
<div class="container">
<div class="row-1">
<div class="box-1">
<text>xiaoziti</text>
</div>
<div class="box-2">
<text>{{text}}</text>
</div>
<div class="box-3">
<text>{{textdata[0]}}</text>
</div>
</div>
<div class="row-2" if="true">
<button value="{{progress}}"></button>
</div>
<div class="row-3" if="true">
<button onclick="buttonClicked" value="click"></button>
</div>
</div>
```
```json
// comp.json
{
"data": {
"progress": {
"default": "80"
}
},
"props": {
"textdata": {
"default": ["a","b"]
},
"progress": {
"default": 60
},
"text": {
"default": "ha"
}
},
"actions": {
"buttonClicked": {
"action": "proxy",
"method": "event_1"
}
}
}
```
```html
<!-- xxx.hml -->
<element name='comp' src='../../common/customComponent/customComponent.hml'></element>
<div class="container">
<comp progress="{{clicknow}}" textdata="{{texts}}" if="false" @event_1="click"></comp>
</div>
```
## 数据单向性
父子组件之间数据的传递是单向的，只能从父组件传递给子组件，子组件不能直接修改父组件传递下来的值，可以将props传入的值用data接收后作为默认值，再对data的值进行修改。
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-file.md 0 → 100644
浏览文件 @ 3035f58a
# 文件组织
## 目录结构
JS服务卡片(entry/src/main/js/Widget)的典型开发目录结构如下：
```
├─widget
│ ├─common
│ │ └─widget.png
│ ├─i18n
│ │ ├─en-US.json
│ │ └─zh-CN.json
│ └─pages
│ └─index
│ ├─index.css
│ ├─index.hml
│ └─index.json
```
目录结构中文件分类如下：
- .hml结尾的HML模板文件，这个文件用来描述卡片页面的模板布局结构。
- .css结尾的CSS样式文件，这个文件用于描述页面样式。
- .json结尾的JSON文件，这个文件用于配置卡片中使用的变量action事件。
各个文件夹的作用：
- pages目录用于存放卡片模板页面。
- common目录用于存放公共资源文件，比如：图片资源。
- i18n目录用于配置不同语言场景资源内容，比如应用文本词条，图片路径等资源。
## 文件访问规则
应用资源可通过绝对路径或相对路径的方式进行访问，本开发框架中绝对路径以"/"开头，相对路径以"./"或"../"。具体访问规则如下：
- 引用代码文件，需使用相对路径，比如：../common/style.css。
- 引用资源文件，推荐使用绝对路径。比如：/common/xxx.png。
- 公共代码文件和资源文件推荐放在common下，通过规则1和规则2进行访问。
- CSS样式文件中通过url()函数创建&lt;url&gt;数据类型，如：url(/common/xxx.png)。
> **说明：**
> 当代码文件A需要引用代码文件B时：
>
> - 如果代码文件A和文件B位于同一目录，则代码文件B引用资源文件时可使用相对路径，也可使用绝对路径。
>
> - 如果代码文件A和文件B位于不同目录，则代码文件B引用资源文件时必须使用绝对路径。因为Webpack打包时，代码文件B的目录会发生变化。
>
> - 在json文件中定义的数据为资源文件路径时，需使用绝对路径。
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-multiple-languages.md 0 → 100644
浏览文件 @ 3035f58a
# 多语言支持
基于开发框架的应用会覆盖多个国家和地区，开发框架支持多语言能力后，可以让应用开发者无需开发多个不同语言的版本，就可以同时支持多种语言的切换，为项目维护带来便利。
开发者仅需要通过[定义资源文件](#定义资源文件)和[引用资源](#引用资源)两个步骤，就可以使用开发框架的多语言能力。
## 定义资源文件
资源文件用于存放应用在多种语言场景下的资源内容，开发框架使用JSON文件保存资源定义。
在[文件组织](js-service-widget-file.md)中指定的i18n文件夹内放置每个语言地区下的资源定义文件即可，资源文件命名为“语言-地区.json”格式，例如英文（美国）的资源文件命名为en-US.json。当开发框架无法在应用中找到系统语言的资源文件时，默认使用en-US.json中的资源内容。
由于不同语言针对单复数有不同的匹配规则，在资源文件中的使用“zero”“one”“two”“few”“many”“other”定义不同单复数场景下的词条内容。例如中文不区分单复数仅存在“other”场景；英文存在“one”、“other”场景；阿拉伯语存在上述6种场景。
以en-US.json和ar-AE.json为例，资源文件内容格式如下：
```json
{
"strings": {
"hello": "Hello world!",
"symbol": "@#$%^&*()_+-={}[]\\|:;\"'<>,./?",
"plurals": {
"one": "one person",
"other": "other people"
}
},
"files": {
"image": "image/en_picture.PNG"
}
}
```
```json
{
"strings": {
"plurals": {
"zero": "لا أحد",
"one": "وحده",
"two": "اثنان",
"few": "ستة اشخاص",
"many": "خمسون شخص",
"other": "مائة شخص"
}
}
}
```
## 引用资源
在应用开发的页面中使用多语言的语法，包含简单格式化和单复数格式化两种，都可以在hml或js中使用。
- 简单格式化方法
在应用中使用$t方法引用资源，$t既可以在hml中使用，也可以在js中使用。系统将根据当前语言环境和指定的资源路径（通过$t的path参数设置），显示对应语言的资源文件中的内容。
**表1** 简单格式化
| 属性 | 类型 | 参数 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| $t | Function | 请见$t参数说明 | 是 | 根据系统语言完成简单的替换：this.$t('strings.hello') |
**表2** $t参数说明
| 参数 | 类型 | 必填 | 描述 |
| -------- | -------- | -------- | -------- |
| path | string | 是 | 资源路径 |
- 简单格式化示例代码
```html
<!-- xxx.hml -->
<div>
<text>{{ $t('strings.hello') }}</text>
<image src="{{ $t('files.image') }}" class="image"></image>
</div>
```
- 单复数格式化方法
**表3** 单复数格式化
| 属性 | 类型 | 参数 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| $tc | Function | 请见$tc参数说明 | 是 | 根据系统语言完成单复数替换：this.$tc('strings.plurals')<br/>定义资源的内容通过json格式的key为“zero”、“one”、“two”、“few”、“many”和“other”区分。 |
**表4** $tc参数说明
| 参数 | 类型 | 必填 | 描述 |
| -------- | -------- | -------- | -------- |
| path | string | 是 | 资源路径 |
| count | number | 是 | 要表达的值 |
- 单复数格式化示例代码
```html
<!--xxx.hml-->
<div>
<!-- 传递数值为0时： "0 people" 阿拉伯语中此处匹配key为zero的词条-->
<text>{{ $tc('strings.plurals', 0) }}</text>
<!-- 传递数值为1时： "one person" 阿拉伯语中此处匹配key为one的词条-->
<text>{{ $tc('strings.plurals', 1) }}</text>
<!-- 传递数值为2时： "2 people" 阿拉伯语中此处匹配key为two的词条-->
<text>{{ $tc('strings.plurals', 2) }}</text>
<!-- 传递数值为6时： "6 people" 阿拉伯语中此处匹配key为few的词条-->
<text>{{ $tc('strings.plurals', 6) }}</text>
<!-- 传递数值为50时： "50 people" 阿拉伯语中此处匹配key为many的词条-->
<text>{{ $tc('strings.plurals', 50) }}</text>
<!-- 传递数值为100时： "100 people" 阿拉伯语中此处匹配key为other的词条-->
<text>{{ $tc('strings.plurals', 100) }}</text>
</div>
```
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-syntax-css.md 0 → 100644
浏览文件 @ 3035f58a
# CSS语法参考
CSS是描述HML页面结构的样式语言。所有组件均存在系统默认样式，也可在页面CSS样式文件中对组件、页面自定义不同的样式。
## 尺寸单位
1. 逻辑像素px（文档中以&lt;length&gt;表示）：
1. 默认卡片具有的逻辑宽度为150px（配置见[配置文件](js-service-widget-config-file.md#window)中的window小节），实际显示时会将页面布局缩放至屏幕实际宽度，如100px在宽度为300的卡片上，实际渲染为200物理像素（从150px向300物理像素，所有尺寸放大2倍）。
2. 额外配置autoDesignWidth为true时（配置见[配置文件](js-service-widget-config-file.md#window)中的window小节），逻辑像素px将按照屏幕密度进行缩放，如100px在屏幕密度为3的设备上，实际渲染为300物理像素。应用需要适配多种设备时，建议采用此方法。
2. 百分比（文档中以&lt;percentage&gt;表示）：表示该组件占父组件尺寸的百分比，如组件的width设置为50%，代表其宽度为父组件的50%。
## 样式导入
为了模块化管理和代码复用，CSS样式文件支持 \@import 语句，导入 CSS 文件。
## 声明样式
每个页面目录下存在一个与布局hml文件同名的css文件，用来描述该hml页面中组件的样式，决定组件应该如何显示。
1. 内部样式，支持使用style、class属性来控制组件的样式。例如：
```html
<!-- index.hml -->
<div class="container">
<text style="color: red">Hello World</text>
</div>
```
```css
/* index.css */
.container {
justify-content: center;
}
```
2. 文件导入，合并外部样式文件。例如，在common目录中定义样式文件style.css，并在index.css中进行导入：
```css
/* style.css */
.title {
font-size: 50px;
}
```
```css
/* index.css */
@import '../../common/style.css';
.container {
justify-content: center;
}
```
## 选择器
css选择器用于选择需要添加样式的元素，支持的选择器如下表所示：
| 选择器 | 样例 | 样例描述 |
| -------- | -------- | -------- |
| .class | .container | 用于选择class="container"的组件。 |
| \#id | \#titleId | 用于选择id="titleId"的组件。 |
示例：
```html
<!-- 页面布局xxx.hml -->
<div id="containerId" class="container">
<text id="titleId" class="title">标题</text>
<div class="content">
<text id="contentId">内容</text>
</div>
</div>
```
```css
/* 页面样式xxx.css */
/* 对class="title"的组件设置样式 */
.title {
font-size: 30px;
}
/* 对id="contentId"的组件设置样式 */
#contentId {
font-size: 20px;
}
```
## 选择器优先级
选择器的优先级计算规则与w3c规则保持一致（只支持：内联样式，id，class），其中内联样式为在元素style属性中声明的样式。
当多条选择器声明匹配到同一元素时，各类选择器优先级由高到低顺序为：内联样式 &gt; id &gt; class 。
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-syntax-hml.md 0 → 100644
浏览文件 @ 3035f58a
# HML语法参考
HML（OpenHarmony Markup Language）是一套类HTML的标记语言，通过组件，事件构建出页面的内容。页面具备数据绑定、事件绑定、条件渲染和逻辑控制等高级能力。
## 页面结构
```html
<!-- xxx.hml -->
<div class="item-container">
<text class="item-title">Image Show</text>
<div class="item-content">
<image src="/common/xxx.png" class="image"></image>
</div>
</div>
```
## 数据绑定
```html
<!-- xxx.hml -->
<div class="item-container">
<text>{{content}} </text> <!-- 输出：Hello World！-->
<text>{{key1}} {{key2}}</text> <!-- 输出：Hello World6+-->
<text>key1 {{key1}}</text> <!-- 输出：key1 Hello 6+-->
<text>{{flag1 && flag2}}</text> <!-- 输出：false 6+-->
<text>{{flag1 || flag2}}</text> <!-- 输出：true 6+-->
<text>{{!flag1}}</text> <!-- 输出：false 6+-->
</div>
```
```json
// xxx.json
{
"data": {
"content": "Hello World!",
"key1": "Hello",
"key2": "World",
"flag1": true,
"flag2": false
}
}
```
> **说明：**
> - key值支持对象操作符和数组操作符，如{{key.value}}、{{key[0]}}。
>
> - 从 API Version 6 开始支持字符串拼接、逻辑运算和三元表达式。
> - 字符串拼接：
> - 支持变量跟变量：{{key1}}{{key2}}等
> - 支持常量跟变量： "my name is {{name}}， i am from {{city}}." "key1 {{key1}}"
> - 逻辑运算：
> - 与：{{flag1 &amp;&amp; flag2}}（仅支持两个boolean变量间的与）
> - 或：{{flag1 || flag2}} （仅支持两个boolean变量间的或）
> - 非：{{!flag1}} （仅支持boolean变量的非运行）
> - 三元表达式
> - {{flag? key1:key2}}（flag为boolean变量，key1和key2可以是变量，也可以是常量）
> - 注意事项
> - 非boolean类型值进行bool运算默认为false
> - 以上所有变量解析跟运算解析均不支持嵌套
## 事件绑定
卡片仅支持click通用事件，事件的定义只能是直接命令式，事件定义必须包含action字段，用以说明事件类型。卡片支持两种事件类型：跳转事件(router)和消息事件(message)。跳转事件可以跳转到卡片提供方的OpenHarmony应用，消息事件可以将开发者自定义信息传递给卡片提供方。事件参数支持变量，变量以"{{}}"修饰。跳转事件中若定义了params字段，则在被拉起应用的onStart的intent中，可用"params"作为key将跳转事件定义的params字段的值取到。
- 跳转事件格式
通过定义ability名称和携带的参数字段params直接跳转，可用"params"作为key提取到跳转事件定义的params字段值。
| 选择器 | 样例 | 默认值 | 样例描述 |
| -------- | -------- | -------- | -------- |
| action | string | "router" | 事件类型。<br/>- "router"：用于应用跳转。<br/>- "message"：自定义点击事件。 |
| abilityName | string | - | 跳转ability名。 |
| params | Object | - | 跳转应用携带的额外参数。 |
```json
// xxx.json
{
"data": {
"mainAbility": "xxx.xxx.xxx"
},
"actions": {
"routerEvent": {
"action": "router",
"abilityName": "{{mainAbility}}",
"params":{}
}
}
}
```
也可以使用want格式绑定参数跳转到目标应用，want定义了ability名称、包名、携带的参数字段等。
| 选择器 | 类型 | 默认值 | 样例描述 |
| ------ | ------ | -------- | ------------------------------------------------------------ |
| action | string | "router" | 事件类型。<br>- "router"：用于应用跳转。<br>- "message"：自定义点击事件。 |
| want | Object | - | 跳转目标应用的信息，参考want格式表。 |
**表1** want格式
| 选择器 | 类型 | 默认值 | 样例描述 |
| ----------- | -------------------- | ------------ | ------------------------------------------------------------ |
| bundleName | string | - | 表示包描述。如果在Want中同时指定了BundleName和AbilityName，则Want可以直接匹配到指定的Ability。 |
| abilityName | string | - | 表示待启动的Ability名称。 |
| action | string | - | 表示action选项描述。 |
| uri | string | - | 表示Uri描述。如果在Want中指定了Uri，则Want将匹配指定的Uri信息，包括scheme, schemeSpecificPart, authority和path信息。 |
| type | string | "text/plain" | 表示MIME type类型描述，比如："text/plain" 、 "image/*"等。 |
| flags | number | - | 表示处理Want的方式。默认传数字，具体参考[flags说明](../apis/js-apis-featureAbility.md#flags说明)。 |
| entities | Array\<string> | - | 类别，用于指定Intent的操作类别。 |
| parameters | {[key: string]: any} | - | 表示WantParams描述。 |
```json
// xxx.json
{
"data": {
"mainAbility": "xxx.xxx.xxx"
},
"actions": {
"routerEventName1": {
"action": "router",
"want": {
"bundleName": "com.example.myapplication",
"abilityName": "com.example.entry.MainAbility"
}
},
"routerEventName2": {
"action": "router",
"want": {
"action": "xxx.intent.action.DIAL",
"uri": "tel:12345678"
}
}
}
}
```
在API Version 8，want参数需要在app.js或app.ets文件的onCreate方法中调用[featureAbility.getWant](../apis/js-apis-featureAbility.md#featureabilitygetwant-1)接口接收相关参数。
- 消息事件格式
| 选择器 | 样例 | 默认值 | 样例描述 |
| -------- | -------- | -------- | -------- |
| action | string | message | 表示事件类型。 |
| params | Object | - | 跳转应用携带的额外参数。 |
```json
// xxx.json
{
"actions": {
"activeEvent": {
"action": "message",
"params": {}
}
}
}
```
- 绑定路由事件和消息事件
```html
<!-- xxx.hml -->
<div>
<!-- 正常格式 -->
<div onclick="activeEvent"></div>
<!-- 缩写 -->
<div @click="activeEvent"></div>
</div>
```
## 列表渲染
```html
<!-- xxx.hml -->
<div class="array-container">
<!-- div列表渲染 -->
<!-- 默认$item代表数组中的元素, $idx代表数组中的元素索引 -->
<div for="{{array}}" tid="id">
<text>{{$item.name}}</text>
</div>
<!-- 自定义元素变量名称 -->
<div for="{{value in array}}" tid="id">
<text>{{value.name}}</text>
</div>
<!-- 自定义元素变量、索引名称 -->
<div for="{{(index, value) in array}}" tid="id">
<text>{{value.name}}</text>
</div>
</div>
```
```json
// xxx.json
{
"data": {
"array": [
{"id": 1, "name": "jack", "age": 18},
{"id": 2, "name": "tony", "age": 18}
]
}
}
```
tid属性主要用来加速for循环的重渲染，旨在列表中的数据有变更时，提高重新渲染的效率。tid属性是用来指定数组中每个元素的唯一标识，如果未指定，数组中每个元素的索引为该元素的唯一id。例如上述tid="id"表示数组中的每个元素的id属性为该元素的唯一标识。for循环支持的写法如下：
- for="array"：其中array为数组对象，array的元素变量默认为$item。
- for="v in array"：其中v为自定义的元素变量，元素索引默认为$idx。
- for="(i, v) in array"：其中元素索引为i，元素变量为v，遍历数组对象array。
> **说明：**
> - 数组中的每个元素必须存在tid指定的数据属性，否则运行时可能会导致异常。
>
> - 数组中被tid指定的属性要保证唯一性，如果不是则会造成性能损耗。比如，示例中只有id和name可以作为tid字段，因为它们属于唯一字段。
>
> - tid不支持表达式。
>
> - 不支持for嵌套使用。
>
> - for对应的变量数组，当前要求数组中的object是相同类型，不支持多种object类型混合写在一个数组中。
## 条件渲染
条件渲染分为2种：if/elif/else和show。
当使用if/elif/else写法时，节点必须是兄弟节点，否则编译无法通过。实例如下：
```html
<!-- xxx.hml -->
<div>
<text if="{{show}}"> Hello-TV </text>
<text elif="{{display}}"> Hello-Wearable </text>
<text else> Hello-World </text>
</div>
```
```json
// xxx.json
{
"data": {
"show": false,
"display": true
}
}
```
当show为真时，节点正常渲染；当show为假时，节点不渲染，效果等同display样式为none。
```html
<!-- xxx.hml -->
<text show="{{visible}}"> Hello World </text>
```
```json
// xxx.json
{
"data": {
"visible": false
}
}
```
## 逻辑控制块
&lt;block&gt;控制块使得循环渲染和条件渲染变得更加灵活；block在构建时不会被当作真实的节点编译。block标签只支持if属性。
```html
<!-- xxx.hml -->
<div>
<block if="{{show}}">
<text>Hello</text>
<text>World</text>
</block>
</div>
```
```json
// xxx.json
{
"data": {
"show": true
}
}
```
zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-version-compatibility.md 0 → 100644
浏览文件 @ 3035f58a
# 低版本兼容
卡片特性不断增加，使用了新特性的卡片，在不支持这些新特性的老系统上可能显示异常。可以在卡片工程中指定最小SDK版本，防止使用新特性的卡片推送安装在老的系统上。也可以参考本章节的内容，在卡片开发阶段做前向兼容适配。
> **说明：**
> 低版本兼容能力从 API Version 6 开始支持。
开发者可以通过JSON配置文件配置前向兼容能力。该文件提供了apiVersion属性用于兼容版本，该字段和卡片配置文件的数据字段data、事件字段actions同级。在apiVersion标签下定义的内容会基于当前运行版本信息，覆盖原始的data标签内容。
示例如下：
假设JS服务卡片框架从API Version 6开始，支持引用系统内置资源颜色，从API Version 7开始支持slider组件（仅用于举例，不代表实际情况），则可以按照如下的方式，做前向兼容。
```html
<!-- xxx.hml -->
<div style="background-color: {{myBackgroundColor}}">
<text>hello world</text>
<slider if="{{canUseSlider}}" min="0" max="100"></slider>
</div>
```
xxx.json配置文件：
```json
{
"data": {
"myBackgroundColor": "#87ceeb",
"canUseSlider": "false"
},
"apiVersion": {
"6": {
"myBackgroundColor": "@sys.color.fa_background"
},
"7": {
"canUseSlider": "true"
}
}
}
```
JS服务卡片开发框架会根据应用中的配置及当前系统运行版本，选取最合适的数据。
假设系统运行版本在5及以下，则实际解析的myBackgroundColor值为\#87ceeb，canUseSlider值为false；
假设系统运行版本为6，则实际解析的myBackgroundColor值为\@sys.color.fa_background，canUseSlider值为false；
假设系统运行版本为7及以上，则实际解析的际解析的myBackgroundColor值为\@sys.color.fa_background，canUseSlider值为true。
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或