diff --git a/en/application-dev/ability/ability-brief.md b/en/application-dev/ability/ability-brief.md index 187064a1c67d7bd21c823a945cca79366428d3f8..0d2303bf4f84c2ddc6f34a13d28b02a3762893b0 100644 --- a/en/application-dev/ability/ability-brief.md +++ b/en/application-dev/ability/ability-brief.md @@ -2,19 +2,19 @@ An ability is the abstraction of a functionality that an application can provide. It is the minimum unit for the system to schedule applications. An application can contain one or more `Ability` instances. -The ability framework model has two forms. +The ability framework model has two forms: -- FA model, which applies to application development using API version 8 and earlier versions. In the FA model, there are Feature Ability (FA) and Particle Ability (PA). The FA supports Page abilities, and the PA supports Service, Data, and Form abilities. -- Stage model, which is introduced since API version 9. In the stage model, there are Ability and ExtensionAbility. The ExtensionAbility is further extended to ServiceExtensionAbility, FormExtensionAbility, DataShareExtensionAbility, and more. +- FA model, which applies to application development using API version 8 and earlier versions. In the FA model, there is Feature Ability (FA) and Particle Ability (PA). The FA supports Page abilities, and the PA supports Service, Data, and Form abilities. +- Stage model, which is introduced since API version 9. In the stage model, there is `Ability` and `ExtensionAbility`. `ExtensionAbility` is further extended to `ServiceExtensionAbility`, `FormExtensionAbility`, `DataShareExtensionAbility`, and more. The stage model is designed to make it easier to develop complex applications in the distributed environment. The table below lists the design differences between the two models. | Item | FA Model | Stage Model | | -------------- | ------------------------------------------------------------ | -------------------------------------------------------- | -| Development mode | Web-like APIs are provided. The UI development is the same as that of the stage model. | Object-oriented development mode is provided. The UI development is the same as that of the FA model. | +| Development mode | Web-like APIs are provided. The UI development is the same as that of the stage model. | Object-oriented development mode is provided. The UI development is the same as that of the FA model. | | Engine instance | Each ability in a process exclusively uses a JS VM engine instance. | Multiple abilities in a process share one JS VM engine instance. | | Intra-process object sharing| Not supported. | Supported. | -| Bundle description file | The `config.json` file is used to describe the HAP and component information. Each component must use a fixed file name.| The `module.json` file is used to describe the HAP and component information. The entry file name can be specified.| +| Bundle description file | The `config.json` file is used to describe the HAP and component information. Each component must use a fixed file name.| The `module.json5` file is used to describe the HAP and component information. The entry file name can be specified.| | Component | Four types of components are provided: Page ability (used for UI page display), Service ability (used to provide services), Data ability (used for data sharing), and Form ability (used to provide widgets).| Two types of components are provided: Ability (used for UI page display) and Extension (scenario-based service extension). | In addition, the following differences exist in the development process: @@ -27,5 +27,4 @@ In addition, the following differences exist in the development process: ![lifecycle](figures/lifecycle.png) - For details about the two models, see [FA Model Overview](fa-brief.md) and [Stage Model Overview](stage-brief.md). diff --git a/en/application-dev/ability/stage-ability.md b/en/application-dev/ability/stage-ability.md index 7f08aa3d19d29d1857e36791e7ca28ea99e62bce..19c43dcc322e08fad315341396fabfad9d99d0a1 100644 --- a/en/application-dev/ability/stage-ability.md +++ b/en/application-dev/ability/stage-ability.md @@ -1,6 +1,6 @@ # Ability Development ## When to Use -Ability development in the [stage model](stage-brief.md) is significantly different from that in the FA model. The stage model requires you to declare the application package structure in the `module.json` and `app.json` files during application development. For details about the configuration file, see [Application Package Structure Configuration File](../quick-start/stage-structure.md). To develop an ability based on the stage model, implement the following logic: +Ability development in the [stage model](stage-brief.md) is significantly different from that in the FA model. The stage model requires you to declare the application package structure in the `module.json5` and `app.json5` files during application development. For details about the configuration file, see [Application Package Structure Configuration File](../quick-start/stage-structure.md). To develop an ability based on the stage model, implement the following logic: - Create an ability that supports screen viewing and human-machine interaction. You must implement the following scenarios: ability lifecycle callbacks, obtaining ability configuration, requesting permissions, and notifying environment changes. - Start an ability. You need to implement ability startup on the same device, on a remote device, or with a specified UI page. - Call abilities. For details, see [Call Development](stage-call.md). @@ -8,7 +8,7 @@ Ability development in the [stage model](stage-brief.md) is significantly differ - Continue the ability on another device. For details, see [Ability Continuation Development](stage-ability-continuation.md). ### Launch Type -An ability can be launched in the **standard**, **singleton**, or **specified** mode, as configured by `launchType` in the `module.json` file. Depending on the launch type, the action performed when the ability is started differs, as described below. +An ability can be launched in the **standard**, **singleton**, or **specified** mode, as configured by `launchType` in the `module.json5` file. Depending on the launch type, the action performed when the ability is started differs, as described below. | Launch Type | Description |Action | | ----------- | ------- |---------------- | @@ -16,7 +16,7 @@ An ability can be launched in the **standard**, **singleton**, or **specified** | singleton | Singleton | The ability has only one instance in the system. If an instance already exists when an ability is started, that instance is reused.| | specified | Instance-specific| The internal service of an ability determines whether to create multiple instances during running.| -By default, the singleton mode is used. The following is an example of the `module.json` file: +By default, the singleton mode is used. The following is an example of the `module.json5` file: ```json { "module": { @@ -42,6 +42,7 @@ The table below describes the APIs provided by the `AbilityStage` class, which h The table below describes the APIs provided by the `Ability` class. For details about the APIs, see [Ability](../reference/apis/js-apis-application-ability.md). **Table 2** Ability APIs + |API|Description| |:------|:------| |onCreate(want: Want, param: AbilityConstant.LaunchParam): void|Called when an ability is created.| @@ -107,7 +108,10 @@ To create Page abilities for an application in the stage model, you must impleme } ``` ### Obtaining AbilityStage and Ability Configurations -Both the `AbilityStage` and `Ability` classes have the `context` attribute. An application can obtain the context of an `Ability` instance through `this.context` to obtain the configuration details. The following example shows how an application obtains the bundle code directory, HAP file name, ability name, and system language through the `context` attribute in the `AbilityStage` class. The sample code is as follows: +Both the `AbilityStage` and `Ability` classes have the `context` attribute. An application can obtain the context of an `Ability` instance through `this.context` to obtain the configuration details. + +The following example shows how an application obtains the bundle code directory, HAP file name, ability name, and system language through the `context` attribute in the `AbilityStage` class. The sample code is as follows: + ```ts import AbilityStage from "@ohos.application.AbilityStage" export default class MyAbilityStage extends AbilityStage { @@ -145,9 +149,9 @@ export default class MainAbility extends Ability { } ``` ### Requesting Permissions -If an application needs to obtain user privacy information or use system capabilities, for example, obtaining location information or using the camera to take photos or record videos, it must request the respective permission from consumers. During application development, you need to specify the involved sensitive permissions, declare the required permissions in `module.json`, and use the `requestPermissionsFromUser` API to request the permission from consumers in the form of a dialog box. The following uses the permission for calendar access as an example. +If an application needs to obtain user privacy information or use system capabilities, for example, obtaining location information or using the camera to take photos or record videos, it must request the respective permission from consumers. During application development, you need to specify the involved sensitive permissions, declare the required permissions in `module.json5`, and use the `requestPermissionsFromUser` API to request the permission from consumers in the form of a dialog box. The following uses the permission for calendar access as an example. -Declare the required permission in the `module.json` file. +Declare the required permission in the `module.json5` file. ```json "requestPermissions": [ { @@ -269,7 +273,7 @@ function getRemoteDeviceId() { ``` Request the permission `ohos.permission.DISTRIBUTED_DATASYNC` from consumers. This permission is used for data synchronization. For details about the sample code for requesting the permission, see [Requesting Permissions](##requesting-permissions). ### Starting an Ability with the Specified Page -If the launch type of an ability is set to `singleton` and the ability has been started, the `onNewWant` callback rather than the `onCreate` callback is triggered when the ability is started again. You can pass start options through the `want`. For example, to start an ability with the specified page, use the `uri` or `parameters` parameter in the `want` to pass the page information. Currently, the ability in the stage model cannot directly use the `router` capability. You must pass the start options to the custom component and invoke the `router` method to display the specified page during the custom component lifecycle management. The sample code is as follows: +If the launch type of an ability is set to `singleton` and the ability has been started, the `onNewWant` callback is triggered when the ability is started again. You can pass start options through the `want`. For example, to start an ability with the specified page, use the `uri` or `parameters` parameter in the `want` to pass the page information. Currently, the ability in the stage model cannot directly use the `router` capability. You must pass the start options to the custom component and invoke the `router` method to display the specified page during the custom component lifecycle management. The sample code is as follows: When using `startAbility` to start an ability again, use the `uri` parameter in the `want` to pass the page information. ```ts diff --git a/en/application-dev/ability/stage-serviceextension.md b/en/application-dev/ability/stage-serviceextension.md index b6fc349d0902889502e10502ca850af295b2ecc0..6f83c084a783856c871848171af24e430611356d 100644 --- a/en/application-dev/ability/stage-serviceextension.md +++ b/en/application-dev/ability/stage-serviceextension.md @@ -61,9 +61,9 @@ OpenHarmony does not support creation of a Service Extension ability for third-p 2. Register the Service Extension ability. - Declare the Service Extension ability in the **module.json** file by setting its **type** attribute to **service**. + Declare the Service Extension ability in the **module.json5** file by setting its **type** attribute to **service**. - **module.json configuration example** + **module.json5 configuration example** ```json "extensionAbilities":[{ diff --git a/en/application-dev/database/database-mdds-overview.md b/en/application-dev/database/database-mdds-overview.md index 2262558e38e892854b4de12cf124a88569cabf84..26efa7491805e871017db3593f5fa50d947717f5 100644 --- a/en/application-dev/database/database-mdds-overview.md +++ b/en/application-dev/database/database-mdds-overview.md @@ -1,8 +1,12 @@ -# Distributed Data Service Overview +# Distributed Data Service Overview -The distributed data service \(DDS\) implements distributed database collaboration across devices for applications. Applications save data to distributed databases by calling the DDS APIs. The DDS isolates data of different applications based on a triplet of account, application, and database to ensure secure data access. The DDS synchronizes application data between trusted devices to provide users with consistent data access experience on different devices. +The distributed data service (DDS) implements distributed database collaboration across devices for applications. -## Basic Concepts +Applications save data to distributed databases by calling the DDS APIs. The DDS isolates data of different applications based on a triplet of account, application, and database to ensure secure data access. The DDS synchronizes application data between trusted devices to provide users with consistent data access experience on different devices. + +You do not need to care about the implementation of the database locking mechanism. + +## Basic Concepts - **KV data model** @@ -54,7 +58,7 @@ The distributed data service \(DDS\) implements distributed database collaborati The DDS provides the database backup capability. You can set **backup** to **true** to enable daily backup. If a distributed database is damaged, the DDS deletes the database and restores the most recent data from the backup database. If no backup database is available, the DDS creates one. The DDS can also back up encrypted databases. -## Working Principles +## Working Principles The DDS supports distributed management of application database data in the OpenHarmony system. Data can be synchronized between multiple devices with the same account, delivering a consistent user experience across devices. The DDS consists of the following: @@ -86,7 +90,7 @@ Applications call the DDS APIs to create, access, and subscribe to distributed d ![](figures/en-us_image_0000001183386164.png) -## Constraints +## Constraints - The DDS supports the KV data model only. It does not support foreign keys or triggers of the relational database. - The KV data model specifications supported by the DDS are as follows: diff --git a/en/application-dev/database/database-relational-guidelines.md b/en/application-dev/database/database-relational-guidelines.md index c8ff6bc64eeccb90c131d5ac4e799b09e6293b9c..688835122445f6800d83a76fa0633b0be64f385c 100644 --- a/en/application-dev/database/database-relational-guidelines.md +++ b/en/application-dev/database/database-relational-guidelines.md @@ -2,7 +2,7 @@ ## When to Use -A relational database (RDB) store allows you to operate local data with or without native SQL statements based on SQLite. +A relational database (RDB) store allows you to manage local data with or without native SQL statements based on SQLite. ## Available APIs @@ -21,11 +21,11 @@ The table below describes the APIs available for creating and deleting an RDB st ### Managing Data in an RDB Store -The RDB provides APIs for inserting, deleting, updating, and querying data in the local RDB store. +The **RDB** module provides APIs for inserting, deleting, updating, and querying data in a local RDB store. - **Inserting Data** - The RDB provides APIs for inserting data through a **ValuesBucket** in a data table. If the data is inserted, the row ID of the data inserted will be returned; otherwise, **-1** will be returned. + The **RDB** module provides APIs for inserting data through a **ValuesBucket** in a data table. If the data is inserted, the row ID of the data inserted will be returned; otherwise, **-1** will be returned. **Table 2** API for inserting data @@ -41,7 +41,7 @@ The RDB provides APIs for inserting, deleting, updating, and querying data in th | Class| API| Description| | -------- | -------- | -------- | - | RdbStore | update(values:ValuesBucket,rdbPredicates:RdbPredicates):Promise\ | Updates data based on the specified **RdbPredicates** object. This API uses a promise to return the result.
Return value: number of rows updated.
- **values**: data to update, which is stored in **ValuesBucket**.
- **rdbPredicates**: conditions for updating data. | + | RdbStore | update(values:ValuesBucket,rdbPredicates:RdbPredicates):Promise\ | Updates data based on the specified **RdbPredicates** object. This API uses a promise to return the result.
Return value: number of rows updated.
- **values**: data to update, which is stored in **ValuesBucket**.
- **rdbPredicates**: conditions for updating data.| - **Deleting Data** @@ -51,7 +51,7 @@ The RDB provides APIs for inserting, deleting, updating, and querying data in th | Class| API| Description| | -------- | -------- | -------- | - | RdbStore | delete(rdbPredicates:RdbPredicates):Promise\ | Deletes data from the RDB store based on the specified **RdbPredicates** object. This API uses a promise to return the result.
Return value: number of rows updated.
- **rdbPredicates**: conditions for deleting data. | + | RdbStore | delete(rdbPredicates:RdbPredicates):Promise\ | Deletes data from the RDB store based on the specified **RdbPredicates** object. This API uses a promise to return the result.
Return value: number of rows updated.
- **rdbPredicates**: conditions for deleting data.| - **Querying data** @@ -69,19 +69,19 @@ The RDB provides APIs for inserting, deleting, updating, and querying data in th ### Using Predicates -The RDB provides **RdbPredicates** for you to set database operation conditions. +The **RDB** module provides **RdbPredicates** for you to set database operation conditions. -The following lists common predicates. For more information about predicates, see [**RdbPredicates**](../reference/apis/js-apis-data-rdb.md#rdbpredicates). +The table below lists common predicates. For more information about predicates, see [**RdbPredicates**](../reference/apis/js-apis-data-rdb.md#rdbpredicates). **Table 6** APIs for using RDB store predicates | Class| API| Description| | -------- | -------- | -------- | -| RdbPredicates | equalTo(field:string,value:ValueType):RdbPredicates | Sets an **RdbPredicates** to match the field with data type **ValueType** and value equal to the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object that matches the specified field. | -| RdbPredicates | notEqualTo(field:string,value:ValueType):RdbPredicates | Sets an **RdbPredicates** to match the field with data type **ValueType** and value not equal to the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object that matches the specified field. | -| RdbPredicates | or():RdbPredicates | Adds the OR condition to the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** with the OR condition.| -| RdbPredicates | and():RdbPredicates | Adds the AND condition to the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** with the AND condition.| -| RdbPredicates | contains(field:string,value:string):RdbPredicats | Sets an **RdbPredicates** to match a string that contains the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object that matches the specified field. | +| RdbPredicates | equalTo(field:string,value:ValueType):RdbPredicates | Sets an **RdbPredicates** object to match the field with data type **ValueType** and value equal to the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object created.| +| RdbPredicates | notEqualTo(field:string,value:ValueType):RdbPredicates | Sets an **RdbPredicates** object to match the field with data type **ValueType** and value not equal to the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object created.| +| RdbPredicates | or():RdbPredicates | Adds the OR condition to the **RdbPredicates** object.
- **RdbPredicates**: **RdbPredicates** with the OR condition.| +| RdbPredicates | and():RdbPredicates | Adds the AND condition to the **RdbPredicates** object.
- **RdbPredicates**: **RdbPredicates** with the AND condition.| +| RdbPredicates | contains(field:string,value:string):RdbPredicats | Sets an **RdbPredicates** object to match a string that contains the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object created.| ### Using the Result Set diff --git a/en/application-dev/database/database-relational-overview.md b/en/application-dev/database/database-relational-overview.md index cd675b9701e9e22147833d1fb7b471f420af2f12..c78034c76f63fe1f6e8bd338f9595206f8c5eea0 100644 --- a/en/application-dev/database/database-relational-overview.md +++ b/en/application-dev/database/database-relational-overview.md @@ -1,42 +1,43 @@ -# RDB Overview +# RDB Overview -The relational database \(RDB\) manages data based on relational models. With the underlying SQLite database, the RDB provides a complete mechanism for managing local databases. To satisfy different needs in complicated scenarios, the RDB offers a series of methods for performing operations such as adding, deleting, modifying, and querying data, and supports direct execution of SQL statements. +The relational database (RDB) manages data based on relational models. With the underlying SQLite database, the RDB provides a complete mechanism for managing local databases. To satisfy different needs in complicated scenarios, the RDB offers a series of methods for performing operations such as adding, deleting, modifying, and querying data, and supports direct execution of SQL statements. -## Basic Concepts +You do not need to care about the implementation of the database locking mechanism. -- **RDB** +## Basic concepts - A type of database based on the relational model of data. The RDB stores data in rows and columns. An RDB is also called RDB store. +- **RDB** -- **Predicate** + A type of database created on the basis of relational models. The RDB stores data in rows and columns. A RDB is also called RDB store. - A representation of the property or feature of a data entity, or the relationship between data entities. It is mainly used to define operation conditions. +- **Predicate** -- **Result set** + A representation of the property or feature of a data entity, or the relationship between data entities. It is mainly used to define operation conditions. - A set of query results used to access the data. You can access the required data in a result set in flexible modes. +- **Result set** -- **SQLite database** + A set of query results used to access data. You can access the required data in a result set in flexible modes. - A lightweight open-source relational database management system that complies with Atomicity, Consistency, Isolation, and Durability \(ACID\). +- **SQLite database** + A lightweight open-source relational database management system that complies with Atomicity, Consistency, Isolation, and Durability (ACID). -## Working Principles +## Working Principles -The RDB provides a common operation interface for external systems. It uses the SQLite as the underlying persistent storage engine, which supports all SQLite database features. +The RDB provides common operation APIs for external systems. It uses the SQLite as the underlying persistent storage engine, which supports all SQLite database features. -**Figure 1** How RDB works -![](figures/how-rdb-works.png "how-rdb-works") +**Figure 1** How RDB works -## Default Settings +![how-rdb-works](figures/how-rdb-works.png) -- The default database logging mode is write-ahead logging \(WAL\). -- The default database flush mode is Full mode. -- The default shared memory used by the OpenHarmony database is 2 MB. +## Default Settings -## Constraints +- The default RDB logging mode is Write Ahead Log (WAL). +- The default data flushing mode is **FULL** mode. +- The default size of the shared memory used by an OpenHarmony database is 2 MB. -- A maximum of four connection pools can be connected to an RDB to manage read and write operations. +## Constraints -- To ensure data accuracy, the RDB supports only one write operation at a time. +- A maximum of four connection pools can be connected to an RDB to manage read and write operations. +- To ensure data accuracy, the RDB supports only one write operation at a time. diff --git a/en/application-dev/database/database-storage-overview.md b/en/application-dev/database/database-storage-overview.md index 45639c75e8ad5d1b3f68c79da90fbc598af7e840..6bf3acda7d8eb9efac54b38474eeea5b2c35c4fd 100644 --- a/en/application-dev/database/database-storage-overview.md +++ b/en/application-dev/database/database-storage-overview.md @@ -1,31 +1,32 @@ -# Lightweight Data Store Overview +# Lightweight Data Store Overview -Lightweight data store is applicable to access and persistence operations on the data in key-value pairs. When an application accesses a lightweight **Storage** instance, data in the **Storage** instance will be cached in the memory for faster access. The cached data can also be written back to the text file for persistent storage. Since file read and write consume system resources, you are advised to minimize the frequency of reading and writing persistent files. +The lightweight data store is applicable to access and persistence of data in the key-value structure. -## Basic Concepts +After an application obtains a lightweight store instance, the data in the instance will be cached in the memory for faster access. The cached data can also be written back to the text file for persistent storage. Since file read and write consume system resources, you are advised to minimize the frequency of reading and writing persistent files. -- **Key-Value data structure** +You do not need to care about the implementation of the database lock mechanism. - A type of data structure. The key is the unique identifier for a piece of data, and the value is the specific data being identified. +## Basic Concepts -- **Non-relational database** +- **Key-value structure** - A database not in compliance with the atomicity, consistency, isolation, and durability \(ACID\) database management properties of relational data transactions. The data in a non-relational database is independent. + A type of data structure. The key is the unique identifier for a piece of data, and the value is the specific data being identified. +- **Non-relational database** -## Working Principles + A database not in compliance with the atomicity, consistency, isolation, and durability (ACID) properties of relational data transactions. The data in a non-relational database is independent. -1. When an application loads data from a specified **Storage** file to a **Storage** instance, the system stores the instance in the memory through a static container. Each file of an application or process has only one **Storage** instance in the memory, till the application removes the instance from the memory or deletes the **Storage** file. -2. When obtaining a **Storage** instance, the application can read data from or write data to the instance. The data in the **Storage** instance can be flushed to its **Storage** file by calling the **flush** or **flushSync** method. +## Working Principles -**Figure 1** How lightweight data store works +1. An application can load data from a specified **Storage** file to a **Storage** instance. The system stores the instance in the memory through a static container. Each file of an application or process has only one **Storage** instance in the memory, till the application removes the instance from the memory or deletes the **Storage** file. +2. When obtaining a **Storage** instance, the application can read data from or write data to the instance. The data in the **Storage** instance can be flushed to its **Storage** file by calling the **flush** or **flushSync** method. +**Figure 1** Working mechanism ![](figures/en-us_image_0000001199139454.png) -## Constraints - -- **Storage** instances are loaded to the memory. To minimize non-memory overhead, the number of data records stored in a **Storage** instance cannot exceed 10,000. Delete the instances that are no longer used in a timely manner. -- The key in the key-value pairs is of the string type. It cannot be empty or exceed 80 characters. -- If the value in the key-value pairs is of the string type, it can be empty or contain a maximum of 8192 characters. +## Constraints +- **Storage** instances are loaded to the memory. To minimize non-memory overhead, the number of data records stored in a **Storage** instance cannot exceed 10,000. Delete the instances that are no longer used in a timely manner. +- The key in the key-value pairs is of the string type. It cannot be empty or exceed 80 bytes. +- The value of the string type can be empty, but cannot exceed 8192 bytes if not empty. diff --git a/en/application-dev/device/usb-guidelines.md b/en/application-dev/device/usb-guidelines.md index 5e3e6ba1c139a6bf5717865a040884d8ce6e40a4..e026109ca3d34b44f69d2ae4752425febbd2116c 100644 --- a/en/application-dev/device/usb-guidelines.md +++ b/en/application-dev/device/usb-guidelines.md @@ -16,7 +16,7 @@ The following table lists the USB APIs currently available. For details, see the | ------------------------------------------------------------ | ------------------------------------------------------------ | | hasRight(deviceName: string): boolean | Checks whether the user, for example, the application or system, has the device access permissions. The value **true** is returned if the user has the device access permissions; the value **false** is returned otherwise. | | requestRight(deviceName: string): Promise\ | Requests the temporary permission for a given application to access the USB device. | -| connectDevice(device: USBDevice): Readonly\ | Connects to the USB device based on the device information returned by **getDevices()**. | +| connectDevice(device: USBDevice): Readonly\ | Connects to the USB device based on the device information returned by `getDevices()`. | | getDevices(): Array> | Obtains the USB device list. | | setConfiguration(pipe: USBDevicePipe, config: USBConfig): number | Sets the USB device configuration. | | setInterface(pipe: USBDevicePipe, iface: USBInterface): number | Sets a USB interface. | @@ -113,7 +113,7 @@ You can set a USB device as a host to connect to a device for data transfer. The Claim the corresponding interface from deviceList. interface1 must be one present in the device configuration. */ - usb.claimInterface(pipe , interface1, true); + usb.claimInterface(pipe, interface1, true); ``` 4. Perform data transfer. diff --git a/en/application-dev/reference/apis/js-apis-bluetooth.md b/en/application-dev/reference/apis/js-apis-bluetooth.md index ce8467ecfbf45a124c0a17dc55a18b2fc6d79c76..b65d3e3f9d45c1819ce94926322069c220857669 100644 --- a/en/application-dev/reference/apis/js-apis-bluetooth.md +++ b/en/application-dev/reference/apis/js-apis-bluetooth.md @@ -3,7 +3,7 @@ > **NOTE**
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. -The Bluetooth module provides classic Bluetooth capabilities and Bluetooth Low Energy (BLE) scan and advertising. +The **Bluetooth** module provides classic Bluetooth capabilities and Bluetooth Low Energy (BLE) scan and advertising. ## Modules to Import @@ -12,18 +12,6 @@ The Bluetooth module provides classic Bluetooth capabilities and Bluetooth Low E import bluetooth from '@ohos.bluetooth'; ``` - -## Required Permissions - -ohos.permission.USE_BLUETOOTH - -ohos.permission.MANAGE_BLUETOOTH - -ohos.permission.DISCOVER_BLUETOOTH - -ohos.permission.LOCATION - - ## bluetooth.enableBluetooth8+ enableBluetooth(): boolean @@ -320,7 +308,7 @@ let remoteDeviceClass = bluetooth.getRemoteDeviceClass("XX:XX:XX:XX:XX:XX"); getPairedDevices(): Array<string> -Obtains the Bluetooth pairing list. +Obtains the paired devices. **Required permissions**: ohos.permission.USE_BLUETOOTH @@ -330,7 +318,7 @@ Obtains the Bluetooth pairing list. | Type | Description | | ------------------- | ------------- | -| Array<string> | List of the addresses of the paired Bluetooth devices.| +| Array<string> | Addresses of the paired Bluetooth devices.| **Example** @@ -354,7 +342,7 @@ Sets the Bluetooth scan mode so that the device can be discovered by a remote de | Name | Type | Mandatory | Description | | -------- | --------------------- | ---- | ---------------------------- | | mode | [ScanMode](#scanmode) | Yes | Bluetooth scan mode to set. | -| duration | number | Yes | Duration (in seconds) in which the device can be discovered. The value **0** indicates unlimited time.| +| duration | number | Yes | Duration (in ms) in which the device can be discovered. The value **0** indicates unlimited time.| **Return value** @@ -609,7 +597,7 @@ bluetooth.off('pinRequired', onReceiveEvent); on(type: "bondStateChange", callback: Callback<BondStateParam>): void -Subscribes to the Bluetooth pairing state change events. +Subscribes to the Bluetooth bond state change events. **Required permissions**: ohos.permission.USE_BLUETOOTH @@ -619,8 +607,8 @@ Subscribes to the Bluetooth pairing state change events. | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------------ | -| type | string | Yes | Event type. The value **bondStateChange** indicates a Bluetooth pairing state change event.| -| callback | Callback<[BondStateParam](#bondstate)> | Yes | Callback invoked to return the pairing state. You need to implement this callback. | +| type | string | Yes | Event type. The value **bondStateChange** indicates a Bluetooth bond state change event.| +| callback | Callback<[BondStateParam](#bondstateparam8)> | Yes | Callback invoked to return the bond state. You need to implement this callback. | **Return value** @@ -629,7 +617,7 @@ No value is returned. **Example** ```js -function onReceiveEvent(data) { // data, as the input parameter of the callback, indicates the pairing state. +function onReceiveEvent(data) { // data, as the input parameter of the callback, indicates the bond state. console.info('pair state = '+ JSON.stringify(data)); } bluetooth.on('bondStateChange', onReceiveEvent); @@ -640,7 +628,7 @@ bluetooth.on('bondStateChange', onReceiveEvent); off(type: "bondStateChange", callback?: Callback<BondStateParam>): void -Unsubscribes from the Bluetooth pairing state change events. +Unsubscribes from the Bluetooth bond state change events. **Required permissions**: ohos.permission.USE_BLUETOOTH @@ -650,8 +638,8 @@ Unsubscribes from the Bluetooth pairing state change events. | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | -| type | string | Yes | Event type. The value **bondStateChange** indicates a Bluetooth pairing state change event. | -| callback | Callback<[BondStateParam](#bondstate)> | No | Callback used to report the change of the Bluetooth pairing state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| +| type | string | Yes | Event type. The value **bondStateChange** indicates a Bluetooth bond state change event. | +| callback | Callback<[BondStateParam](#bondstateparam8)> | No | Callback used to report the change of the Bluetooth bond state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| **Return value** @@ -1295,7 +1283,7 @@ Obtains the connection state of the profile. | | | | ------------------------------------------------- | ----------------------- | | Type | Description | -| [ProfileConnectionState](#profileconnectionState) | Profile connection state obtained. | +| [ProfileConnectionState](#profileconnectionstate) | Profile connection state obtained. | ## A2dpSourceProfile @@ -1894,7 +1882,7 @@ Subscribes to the characteristic read request events. | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------------- | | type | string | Yes | Event type. The value **characteristicRead** indicates a characteristic read request event.| -| callback | Callback<[CharacteristicReadReq](#characteristicreadreq)> | Yes | Callback invoked to return a characteristic read request from the GATT client. | +| callback | Callback<[CharacteristicReadReq](#characteristicreadreq)> | Yes | Callback invoked to return a characteristic read request event from the GATT client. | **Return value** @@ -1971,7 +1959,7 @@ Subscribes to the characteristic write request events. | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | -------------------------------------- | | type | string | Yes | Event type. The value **characteristicWrite** indicates a characteristic write request event.| -| callback | Callback<[CharacteristicWriteReq](#descriptorwritereq)> | Yes | Callback invoked to return a characteristic write request from the GATT client. | +| callback | Callback<[CharacteristicWriteReq](#characteristicwritereq)> | Yes | Callback invoked to return a characteristic write request from the GATT client. | **Return value** @@ -2192,6 +2180,7 @@ let gattServer = bluetooth.BLE.createGattServer(); gattServer.off("descriptorWrite"); ``` + ### on('connectStateChange') on(type: "connectStateChange", callback: Callback<BLEConnectChangedState>): void @@ -2410,7 +2399,7 @@ device.getServices().then(result => { readCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<BLECharacteristic>): void -Reads the characteristic value of the specific service of the peer BLE device. This API uses an asynchronous callback to return the result. +Reads the characteristic value of the specific service of the remote BLE device. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.USE_BLUETOOTH @@ -2511,7 +2500,7 @@ device.readCharacteristicValue(characteristic); readDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<BLEDescriptor>): void -Reads the descriptor contained in the specific characteristic of the peer BLE device. This API uses an asynchronous callback to return the result. +Reads the descriptor contained in the specific characteristic of the remote BLE device. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.USE_BLUETOOTH @@ -2683,7 +2672,7 @@ if (retWriteDesc) { setBLEMtuSize(mtu: number): boolean -Sets the maximum transmission unit (MTU) that can be transmitted between the GATT client and its remote BLE device. This method can be used only after a connection is set up by calling [connect](#connect). +Sets the maximum transmission unit (MTU) that can be transmitted between the GATT client and its remote BLE device. This API can be used only after a connection is set up by calling [connect](#connect). **Required permissions**: ohos.permission.USE_BLUETOOTH @@ -3355,6 +3344,18 @@ Defines the pairing request parameters. | pinCode | string | Yes | No | Key for the device pairing. | +## BondStateParam8+ + +Defines the bond state parameters. + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name | Type | Readable | Writable | Description | +| -------- | ------ | ---- | ---- | ----------- | +| deviceId | string | Yes | No | ID of the device.| +| state | BondState | Yes | No | State of the device.| + + ## StateChangeParam8+ Defines the profile state change parameters. @@ -3512,7 +3513,7 @@ Enumerates the A2DP playing states. ## ProfileId8+ -Enumerates the Bluetooth profile IDs. +Enumerates the Bluetooth profiles. **System capability**: SystemCapability.Communication.Bluetooth.Core diff --git a/en/application-dev/reference/apis/js-apis-brightness.md b/en/application-dev/reference/apis/js-apis-brightness.md index 6bbea8b08a752972bcc9354b63841831ae837a88..e0b192951999cae7daba27a9f58d93e6c64af860 100644 --- a/en/application-dev/reference/apis/js-apis-brightness.md +++ b/en/application-dev/reference/apis/js-apis-brightness.md @@ -1,10 +1,10 @@ # Brightness -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
-> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. - The Brightness module provides an API for setting the screen brightness. +> **NOTE** +> +> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import diff --git a/en/application-dev/reference/apis/js-apis-bytrace.md b/en/application-dev/reference/apis/js-apis-bytrace.md index 544a4ba0d27e6c39794e063fc63282ba5455bf5e..69bc43b637e75ee32acaf67fbf12a5658cc81055 100644 --- a/en/application-dev/reference/apis/js-apis-bytrace.md +++ b/en/application-dev/reference/apis/js-apis-bytrace.md @@ -7,7 +7,7 @@ ## Modules to Import - ```js +```js import bytrace from '@ohos.bytrace'; ``` @@ -23,7 +23,7 @@ Marks the start of a timeslice trace task. > > If multiple trace tasks with the same name need to be performed at the same time or a trace task needs to be performed multiple times concurrently, different task IDs must be specified in **startTrace**. If the trace tasks with the same name are not performed at the same time, the same taskId can be used. For details, see the bytrace.finishTrace example. -**System capability**: SystemCapability.Developtools.Bytrace +**System capability**: SystemCapability.HiviewDFX.HiTrace **Parameters** @@ -36,7 +36,7 @@ Marks the start of a timeslice trace task. **Example** - ```js +```js bytrace.startTrace("myTestFunc", 1); bytrace.startTrace("myTestFunc", 1, 5); // The expected duration of the trace is 5 ms. ``` @@ -52,7 +52,7 @@ Marks the end of a timeslice trace task. > > To stop a trace task, the values of name and task ID in **finishTrace** must be the same as those in **startTrace**. -**System capability**: SystemCapability.Developtools.Bytrace +**System capability**: SystemCapability.HiviewDFX.HiTrace **Parameters** @@ -64,7 +64,7 @@ Marks the end of a timeslice trace task. **Example** - ```js +```js bytrace.finishTrace("myTestFunc", 1); ``` @@ -97,7 +97,7 @@ traceByValue(name: string, count: number): void Defines the variable that indicates the number of timeslice trace tasks. -**System capability**: SystemCapability.HiviewDFX.HiTrace +**System capability**: HiviewDFX.HiTrace **Parameters** | Name| Type| Mandatory| Description| @@ -107,7 +107,7 @@ Defines the variable that indicates the number of timeslice trace tasks. **Example** - ```js +```js let traceCount = 3; bytrace.traceByValue("myTestCount", traceCount); traceCount = 4; diff --git a/en/application-dev/reference/apis/js-apis-display.md b/en/application-dev/reference/apis/js-apis-display.md index ffbc73ff530a4d8f9ec39fd6e824760df9448644..aed3f0dfd30e05810bf103c4b04738ae4fe237f9 100644 --- a/en/application-dev/reference/apis/js-apis-display.md +++ b/en/application-dev/reference/apis/js-apis-display.md @@ -1,5 +1,5 @@ # Display -Provides APIs for managing displays, such as obtaining information about the default display, obtaining information about all displays, and listening for the addition and removal of displays. +The **Display** module provides APIs for managing displays, such as obtaining information about the default display, obtaining information about all displays, and listening for the addition and removal of displays. > **NOTE** > @@ -14,11 +14,11 @@ import display from '@ohos.display'; ## DisplayState -Provides the state of a display. +Enumerates the display states. **System capability**: SystemCapability.WindowManager.WindowManager.Core -| Name| Default Value| Description| +| Name| Value| Description| | -------- | -------- | -------- | | STATE_UNKNOWN | 0 | Unknown.| | STATE_OFF | 1 | The display is shut down.| @@ -35,163 +35,169 @@ Describes the attributes of a display. **System capability**: SystemCapability.WindowManager.WindowManager.Core -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| id | number | Yes| No| ID of the display.| -| name | string | Yes| No| Name of the display.| -| alive | boolean | Yes| No| Whether the display is alive.| -| state | [DisplayState](#displaystate) | Yes| No| State of the display.| -| refreshRate | number | Yes| No| Refresh rate of the display.| -| rotation | number | Yes| No| Screen rotation angle of the display.| -| width | number | Yes| No| Width of the display, in pixels.| -| height | number | Yes| No| Height of the display, in pixels.| -| densityDPI | number | Yes| No| Screen density of the display, in DPI.| -| densityPixels | number | Yes| No| Screen density of the display, in pixels.| -| scaledDensity | number | Yes| No| Scaling factor for fonts displayed on the display.| -| xDPI | number | Yes| No| Exact physical dots per inch of the screen in the horizontal direction.| -| yDPI | number | Yes| No| Exact physical dots per inch of the screen in the vertical direction.| +| Name | Type | Readable | Writable | Description | +| ------------- | ----------------------------- | -------- | -------- | ------------------------------------------------------------ | +| id | number | Yes | No | ID of the display. | +| name | string | Yes | No | Name of the display. | +| alive | boolean | Yes | No | Whether the display is alive. | +| state | [DisplayState](#displaystate) | Yes | No | State of the display. | +| refreshRate | number | Yes | No | Refresh rate of the display. | +| rotation | number | Yes | No | Screen rotation angle of the display. | +| width | number | Yes | No | Width of the display, in pixels. | +| height | number | Yes | No | Height of the display, in pixels. | +| densityDPI | number | Yes | No | Screen density of the display, in DPI. | +| densityPixels | number | Yes | No | Screen density of the display, in pixels. | +| scaledDensity | number | Yes | No | Scaling factor for fonts displayed on the display. | +| xDPI | number | Yes | No | Exact physical dots per inch of the screen in the horizontal direction. | +| yDPI | number | Yes | No | Exact physical dots per inch of the screen in the vertical direction. | ## display.getDefaultDisplay getDefaultDisplay(callback: AsyncCallback<Display>): void -Obtains the default display object. +Obtains the default display object. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.WindowManager.WindowManager.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<[Display](#display)> | Yes| Callback used to return the default display object.| + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<[Display](#display)> | Yes| Callback used to return the default display object.| **Example** - ```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 getDefaultDisplay(): Promise<Display> -Obtains the default display object. +Obtains the default display object. This API uses a promise to return the result. **System capability**: SystemCapability.WindowManager.WindowManager.Core **Return value** - | Type | Description | - | ---------------------------------- | ---------------------------------------------- | - | Promise<[Display](#display)> | Promise used to return the default display object.| +| Type | Description | +| ---------------------------------- | ---------------------------------------------- | +| Promise<[Display](#display)> | Promise used to return the default display object.| **Example** - ```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 getAllDisplay(callback: AsyncCallback<Array<Display>>): void -Obtains all the display objects. +Obtains all display objects. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.WindowManager.WindowManager.Core **Parameters** - | Name | Type | Mandatory| Description | - | -------- | ---------------------------------------------------- | ---- | ------------------------------- | - | callback | AsyncCallback<Array<[Display](#display)>> | Yes | Callback used to return all the display objects.| +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------------------- | ---- | ------------------------------- | +| callback | AsyncCallback<Array<[Display](#display)>> | Yes | Callback used to return all the display objects.| **Example** - ```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 getAllDisplay(): Promise<Array<Display>> -Obtains all the display objects. +Obtains all display objects. This API uses a promise to return the result. **System capability**: SystemCapability.WindowManager.WindowManager.Core **Return value** - | Type | Description | - | ----------------------------------------------- | ------------------------------------------------------- | - | Promise<Array<[Display](#display)>> | Promise used to return all the display objects.| +| Type | Description | +| ----------------------------------------------- | ------------------------------------------------------- | +| Promise<Array<[Display](#display)>> | Promise used to return all the display objects.| **Example** - ```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.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); +}).catch((err) => { + console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err)); +}); +``` ## display.on('add'|'remove'|'change') on(type: 'add'|'remove'|'change', callback: Callback<number>): void -Enables listening. +Subscribes to display changes. **System capability**: SystemCapability.WindowManager.WindowManager.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | type | string | Yes| Listening type. The available values are as follows:
- **add**: listening for whether a display is added
- **remove**: listening for whether a display is removed
- **change**: listening for whether a display is changed| - | callback | Callback<number> | Yes| Callback used to return the ID of the display.| + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Event type.
- **add**, indicating the display addition event.
- **remove**, indicating the display removal event.
- **change**, indicating the display change event.| +| callback | Callback<number> | Yes| Callback used to return the ID of the display.| **Example** - ```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') off(type: 'add'|'remove'|'change', callback?: Callback<number>): void -Disables listening. +Unsubscribes from display changes. **System capability**: SystemCapability.WindowManager.WindowManager.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | type | string | Yes| Listening type. The available values are as follows:
- **add**: listening for whether a display is added
- **remove**: listening for whether a display is removed
- **change**: listening for whether a display is changed| - | callback | Callback<number> | No| Callback used to return the ID of the display.| + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Event type.
- **add**, indicating the display addition event.
- **remove**, indicating the display removal event.
- **change**, indicating the display change event.| +| callback | Callback<number> | No| Callback used to return the ID of the display.| **Example** - ```js - display.off("remove"); - ``` +```js +display.off("remove"); +``` diff --git a/en/application-dev/reference/apis/js-apis-featureAbility.md b/en/application-dev/reference/apis/js-apis-featureAbility.md index 821407ada202109ab3b17e560402621ac5ae8356..cf862c2d57454b742fb42208e011efcce06029dc 100644 --- a/en/application-dev/reference/apis/js-apis-featureAbility.md +++ b/en/application-dev/reference/apis/js-apis-featureAbility.md @@ -138,10 +138,10 @@ Starts an ability. This API uses a callback to return the execution result when **Example** ```javascript -import featureAbility from '@ohos.ability.featureability'; +import featureAbility from '@ohos.ability.featureAbility'; import wantConstant from '@ohos.ability.wantConstant' featureAbility.startAbilityForResult( - { + { want: { action: "action.system.home", @@ -154,6 +154,9 @@ featureAbility.startAbilityForResult( uri:"" }, }, + (err, data) => { + console.info("err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)) + } ) ``` @@ -180,7 +183,7 @@ Starts an ability. This API uses a promise to return the execution result when t **Example** ```javascript -import featureAbility from '@ohos.ability.featureability'; +import featureAbility from '@ohos.ability.featureAbility'; import wantConstant from '@ohos.ability.wantConstant' featureAbility.startAbilityForResult( { @@ -284,7 +287,7 @@ Destroys this Page ability, with the result code and data sent to the caller. Th **Example** ```javascript -import featureAbility from '@ohos.ability.featureability'; +import featureAbility from '@ohos.ability.featureAbility'; import wantConstant from '@ohos.ability.wantConstant' featureAbility.terminateSelfWithResult( { @@ -335,7 +338,7 @@ Checks whether the main window of this ability has the focus. This API uses a ca **Example** ```javascript -import featureAbility from '@ohos.ability.featureability'; +import featureAbility from '@ohos.ability.featureAbility'; featureAbility.hasWindowFocus() ``` @@ -358,7 +361,7 @@ Checks whether the main window of this ability has the focus. This API uses a pr **Example** ```javascript -import featureAbility from '@ohos.ability.featureability'; +import featureAbility from '@ohos.ability.featureAbility'; featureAbility.hasWindowFocus().then((data) => { console.info("==========================>hasWindowFocus=======================>"); }); @@ -383,7 +386,7 @@ Obtains the **Want** object sent from this ability. This API uses a callback to **Example** ```javascript -import featureAbility from '@ohos.ability.featureability'; +import featureAbility from '@ohos.ability.featureAbility'; featureAbility.getWant() ``` @@ -406,7 +409,7 @@ Obtains the **Want** object sent from this ability. This API uses a promise to r **Example** ```javascript -import featureAbility from '@ohos.ability.featureability'; +import featureAbility from '@ohos.ability.featureAbility'; featureAbility.getWant().then((data) => { console.info("==========================>getWantCallBack=======================>"); }); @@ -429,7 +432,7 @@ Obtains the application context. **Example** ```javascript -import featureAbility from '@ohos.ability.featureability'; +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext() context.getBundleName() ``` @@ -453,7 +456,7 @@ Destroys this Page ability, with the result code and data sent to the caller. Th **Example** ```javascript -import featureAbility from '@ohos.ability.featureability'; +import featureAbility from '@ohos.ability.featureAbility'; featureAbility.terminateSelf() ``` @@ -476,7 +479,7 @@ Destroys this Page ability, with the result code and data sent to the caller. Th **Example** ```javascript -import featureAbility from '@ohos.ability.featureability'; +import featureAbility from '@ohos.ability.featureAbility'; featureAbility.terminateSelf().then((data) => { console.info("==========================>terminateSelfCallBack=======================>"); }); ``` @@ -926,6 +929,8 @@ Enumerates operation types of the Data ability. | action | Read-only | string | No | Action option. | | parameters | Read-only | {[key: string]: any} | No | List of parameters in the **Want** object. | | entities | Read-only | Array\ | No | List of entities. | +| extensionAbilityType9+ | Read-only | bundle.ExtensionAbilityType | No | Type of the Extension ability. | +| extensionAbilityName9+ | Read-only | string | No | Description of the Extension ability name in the **Want** object. | ## flags diff --git a/en/application-dev/reference/apis/js-apis-hilog.md b/en/application-dev/reference/apis/js-apis-hilog.md index 4d45271a8791a8370ed4950c75ac96c0fb408b8c..fd44ed62b3e67dfac8c3fa44f0f23485e2eeff5d 100644 --- a/en/application-dev/reference/apis/js-apis-hilog.md +++ b/en/application-dev/reference/apis/js-apis-hilog.md @@ -1,6 +1,6 @@ # HiLog -The HiLog subsystem allows your applications or services to output logs based on the specified type, level, and format string. Such logs help you learn the running status of applications and better debug programs. +The HiLog module allows your applications or services to output logs based on the specified type, level, and format string. Such logs help you learn the running status of applications and better debug programs. > **NOTE**
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -23,8 +23,8 @@ Checks whether logs are printable based on the specified service domain, log tag | Name| Type | Mandatory| Description | | ------ | --------------------- | ---- | ------------------------------------------------------------ | -| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**. You can define the value as required.| -| tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| +| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.
You can define the value as required.| +| tag | string | Yes | Log tag in the string format.
You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| | level | [LogLevel](#loglevel) | Yes | Log level. | **Return value** @@ -48,7 +48,7 @@ Enumerates the log levels. | Name | Default Value| Description | | ----- | ------ | ------------------------------------------------------------ | | DEBUG | 3 | Log level used to record more detailed process information than INFO logs to help developers analyze service processes and locate faults.| -| INFO | 4 | Log level used to record key service process nodes and exceptions that occur during service running,
for example, no network signal or login failure.
These logs should be recorded by the dominant module in the service to avoid repeated logging conducted by multiple invoked modules or low-level functions.| +| INFO | 4 | Log level used to record key service process nodes and exceptions that occur during service running, for example, no network signal or login failure.
These logs should be recorded by the dominant module in the service to avoid repeated logging conducted by multiple invoked modules or low-level functions.| | WARN | 5 | Log level used to record severe, unexpected faults that have little impact on users and can be rectified by the programs themselves or through simple operations.| | ERROR | 6 | Log level used to record program or functional errors that affect the normal running or use of the functionality and can be fixed at a high cost, for example, by resetting data.| | FATAL | 7 | Log level used to record program or functionality crashes that cannot be rectified. | @@ -67,8 +67,8 @@ DEBUG logs are not recorded in official versions by default. They are available | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------------------------------ | -| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**. You can define the value as required.| -| tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| +| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.
You can define the value as required.| +| tag | string | Yes | Log tag in the string format.
You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| | format | string | Yes | Format string used to output logs in a specified format. It can contain several parameters, where the parameter type and privacy identifier are mandatory.
Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by ****.| | args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.| @@ -98,8 +98,8 @@ Prints INFO logs. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------------------------------ | -| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**. You can define the value as required.| -| tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| +| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.
You can define the value as required.| +| tag | string | Yes | Log tag in the string format.
You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| | format | string | Yes | Format string used to output logs in a specified format. It can contain several parameters, where the parameter type and privacy identifier are mandatory.
Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by ****.| | args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.| @@ -129,8 +129,8 @@ Prints WARN logs. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------------------------------ | -| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**. You can define the value as required.| -| tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| +| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.
You can define the value as required.| +| tag | string | Yes | Log tag in the string format.
You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| | format | string | Yes | Format string used to output logs in a specified format. It can contain several parameters, where the parameter type and privacy identifier are mandatory.
Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by ****.| | args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.| @@ -160,8 +160,8 @@ Prints ERROR logs. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------------------------------ | -| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**. You can define the value as required.| -| tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| +| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.
You can define the value as required.| +| tag | string | Yes | Log tag in the string format.
You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| | format | string | Yes | Format string used to output logs in a specified format. It can contain several parameters, where the parameter type and privacy identifier are mandatory.
Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by ****.| | args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.| @@ -191,8 +191,8 @@ Prints FATAL logs. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------------------------------ | -| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**. You can define the value as required.| -| tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| +| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.
You can define the value as required.| +| tag | string | Yes | Log tag in the string format.
You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| | format | string | Yes | Format string used to output logs in a specified format. It can contain several parameters, where the parameter type and privacy identifier are mandatory.
Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by ****.| | args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.| diff --git a/en/application-dev/reference/apis/js-apis-hitracemeter.md b/en/application-dev/reference/apis/js-apis-hitracemeter.md index e856ee20a4c8956ff0f05707b596935b68ca9e7a..04a9db2a0e7bc00cb9ff8a017eb6e39c47d97f30 100644 --- a/en/application-dev/reference/apis/js-apis-hitracemeter.md +++ b/en/application-dev/reference/apis/js-apis-hitracemeter.md @@ -1,8 +1,9 @@ # Performance Tracing -This module provides the functions of tracing service processes and monitoring the system performance. It provides the data needed for hiTraceMeter to carry out performance analysis. +The Performance Tracing module provides the functions of tracing service processes and monitoring the system performance. It provides the data needed for hiTraceMeter to carry out performance analysis. -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> **NOTE** +> > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -17,7 +18,7 @@ import hiTraceMeter from '@ohos.hiTraceMeter'; startTrace(name: string, taskId: number): void -Starts a trace task. **expectedTime** is an optional parameter, which specifies the expected duration of the trace. +Starts a trace task. If multiple trace tasks with the same name need to be performed at the same time or a trace task needs to be performed multiple times concurrently, different task IDs must be specified in **startTrace**. diff --git a/en/application-dev/reference/apis/js-apis-logs.md b/en/application-dev/reference/apis/js-apis-logs.md index e2d0aff5a5eec1f468b0511a08f1f593a9af3548..a1e0786bda3cae69131a317ac6d61db35d0652c0 100644 --- a/en/application-dev/reference/apis/js-apis-logs.md +++ b/en/application-dev/reference/apis/js-apis-logs.md @@ -1,30 +1,42 @@ # Log -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** -> The APIs of this module are no longer maintained since API version 7. You are advised to use ['@ohos.hilog](js-apis-hilog.md)' instead. +The Log module provides basic log printing capabilities and supports log printing by log level. -## console.debug - -debug(message: string): void +If you want to use more advanced log printing services, for example, filtering logs by the specified ID, you are advised to use [`@ohos.hilog`](js-apis-hilog.md). -Prints debug logs. - -- Parameters - | Name | Type | Mandatory | Description | - | ------- | ------ | ---- | ----------- | - | message | string | Yes | Text to print.| +> **NOTE** +> +> The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## console.log log(message: string): void -Prints debug logs. +Prints logs. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** -- Parameters - | Name | Type | Mandatory | Description | - | ------- | ------ | ---- | ----------- | - | message | string | Yes | Text to print.| +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| message | string | Yes | Text to print.| + + +## console.debug + +debug(message: string): void + +Prints debug-level logs. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| message | string | Yes | Text to print.| ## console.info @@ -33,10 +45,13 @@ info(message: string): void Prints info-level logs. -- Parameters - | Name | Type | Mandatory | Description | - | ------- | ------ | ---- | ----------- | - | message | string | Yes | Text to print.| +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| message | string | Yes | Text to print.| ## console.warn @@ -45,10 +60,13 @@ warn(message: string): void Prints warn-level logs. -- Parameters - | Name | Type | Mandatory | Description | - | ------- | ------ | ---- | ----------- | - | message | string | Yes | Text to print.| +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| message | string | Yes | Text to print.| ## console.error @@ -57,10 +75,13 @@ error(message: string): void Prints error-level logs. -- Parameters - | Name | Type | Mandatory | Description | - | ------- | ------ | ---- | ----------- | - | message | string | Yes | Text to print.| +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| message | string | Yes | Text to print.| ## Example diff --git a/en/application-dev/reference/apis/js-apis-mediaquery.md b/en/application-dev/reference/apis/js-apis-mediaquery.md index 60892cd01ff976bbbfded7b948c9ff0462919560..2adc09bf03b7dc3f818443eaf0f7ca56abc3439d 100644 --- a/en/application-dev/reference/apis/js-apis-mediaquery.md +++ b/en/application-dev/reference/apis/js-apis-mediaquery.md @@ -26,6 +26,7 @@ Sets the media query criteria and returns the corresponding listening handle. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** + | Name | Type | Mandatory | Description | | --------- | ------ | ---- | ---------------------------------------- | | condition | string | Yes | Matching condition of a media event. For details, see [Syntax of Media Query Conditions](../../ui/ui-ts-layout-mediaquery.md#syntax-of-media-query-conditions).| @@ -37,7 +38,7 @@ Sets the media query criteria and returns the corresponding listening handle. **Example** ```js -listener = mediaquery.matchMediaSync('(orientation: landscape)'); // Listen for landscape events. +let listener = mediaquery.matchMediaSync('(orientation: landscape)'); // Listen for landscape events. ``` @@ -66,7 +67,7 @@ Registers a callback with the corresponding query condition by using the handle. **Parameters** | Name | Type | Mandatory | Description | | -------- | -------------------------------- | ---- | ---------------- | -| type | string | Yes | Must enter the string **'change'**.| +| type | string | Yes | Must enter the string **change**.| | callback | Callback<MediaQueryResult> | Yes | Callback registered with media query. | **Example** @@ -88,7 +89,7 @@ Deregisters a callback with the corresponding query condition by using the handl | callback | Callback<MediaQueryResult> | No | Callback to be deregistered. If the default value is used, all callbacks of the handle are deregistered.| **Example** - ```js + ```ts import mediaquery from '@ohos.mediaquery' let listener = mediaquery.matchMediaSync('(orientation: landscape)'); // Listen for landscape events. @@ -117,10 +118,9 @@ Deregisters a callback with the corresponding query condition by using the handl ### Example -```js +```ts import mediaquery from '@ohos.mediaquery' -let portraitFunc = null @Entry @Component @@ -140,7 +140,7 @@ struct MediaQueryExample { } aboutToAppear() { - portraitFunc = this.onPortrait.bind(this) //bind current js instance + let portraitFunc = this.onPortrait.bind(this) // Bind the current JS instance. this.listener.on('change', portraitFunc) } diff --git a/en/application-dev/reference/apis/js-apis-notification.md b/en/application-dev/reference/apis/js-apis-notification.md index d3756234ba871baa90c70f6e48b6a015f0f50155..1305ce8f886430d5797e4e3654d7791d710068fe 100644 --- a/en/application-dev/reference/apis/js-apis-notification.md +++ b/en/application-dev/reference/apis/js-apis-notification.md @@ -3057,7 +3057,7 @@ Notification.subscribe(subscriber, subscribeCallback); | desc | Yes | Yes | string | No | Notification slot description. | | badgeFlag | Yes | Yes | boolean | No | Whether to display the badge. | | bypassDnd | Yes | Yes | boolean | No | Whether to bypass the DND mode in the system. | -| lockscreenVisibility | Yes | Yes | boolean | No | Mode for displaying the notification on the lock screen. | +| lockscreenVisibility | Yes | Yes | number | No | Mode for displaying the notification on the lock screen. | | vibrationEnabled | Yes | Yes | boolean | No | Whether vibration is supported for the notification. | | sound | Yes | Yes | string | No | Notification alert tone. | | lightEnabled | Yes | Yes | boolean | No | Whether the indicator blinks for the notification. | diff --git a/en/application-dev/reference/apis/js-apis-sensor.md b/en/application-dev/reference/apis/js-apis-sensor.md index b8d487b4af7a528f8474d60e60a3ae828ea10d6c..d9278e34142be1721540537d4d879c95806f49c4 100644 --- a/en/application-dev/reference/apis/js-apis-sensor.md +++ b/en/application-dev/reference/apis/js-apis-sensor.md @@ -1,6 +1,5 @@ # Sensor - > **NOTE** > > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -1351,8 +1350,6 @@ off(type: SensorType.SENSOR_TYPE_ID_HUMIDITY, callback?: Callback<HumidityRes Unsubscribes from sensor data changes. -**Required permissions**: ohos.permission.READ_HEALTH_DATA (a system permission) - **System capability**: SystemCapability.Sensors.Sensor **Parameters** @@ -1405,8 +1402,6 @@ sensor.off(sensor.SensorType.SENSOR_TYPE_ID_LINEAR_ACCELERATION, callback); Unsubscribes from sensor data changes. -**Required permissions**: ohos.permission.ACCELEROMETER (a system permission) - **System capability**: SystemCapability.Sensors.Sensor **Parameters** @@ -1488,6 +1483,8 @@ off(type: SensorType.SENSOR_TYPE_ID_PEDOMETER, callback?: Callback<PedometerR Unsubscribes from sensor data changes. +**Required permissions**: ohos.permission.ACTIVITY_MOTION + **System capability**: SystemCapability.Sensors.Sensor **Parameters** @@ -1718,7 +1715,7 @@ sensor.getGeomagneticField({latitude:80, longitude:0, altitude:0}, 1580486400000 console.error('Operation failed. Error code: ' + err.code + '; message: ' + err.message); return; } - console.info('sensor_getGeomagneticField_promise x: ' + data.x + ',y: ' + data.y + ',z: ' + + console.info('sensor_getGeomagneticField_callback x: ' + data.x + ',y: ' + data.y + ',z: ' + data.z + ',geomagneticDip: ' + data.geomagneticDip + ',deflectionAngle: ' + data.deflectionAngle + ',levelIntensity: ' + data.levelIntensity + ',totalIntensity: ' + data.totalIntensity); }); @@ -1900,7 +1897,6 @@ Obtains the angle change between two rotation matrices. This API uses a callback err.message); return; } - console.info("SensorJsAPI--->Successed to get getAngleModifiy interface get data: " + data.x); for (var i=0; i < data.length; i++) { console.info("data[" + i + "]: " + data[i]); } @@ -1968,7 +1964,6 @@ Converts a rotation vector into a rotation matrix. This API uses a callback to r err.message); return; } - console.info("SensorJsAPI--->Successed to get createRotationMatrix interface get data: " + data.x); for (var i=0; i < data.length; i++) { console.info("data[" + i + "]: " + data[i]); } @@ -2035,7 +2030,6 @@ Converts a rotation vector into a quaternion. This API uses a callback to return err.message); return; } - console.info("SensorJsAPI--->Successed to get createQuaternion interface get data: " + data.x); for (var i=0; i < data.length; i++) { console.info("data[" + i + "]: " + data[i]); } @@ -2102,7 +2096,6 @@ Obtains the device direction based on the rotation matrix. This API uses a callb err.message); return; } - console.info("SensorJsAPI--->Successed to get getDirection interface get data: " + data); for (var i = 1; i < data.length; i++) { console.info("sensor_getDirection_callback" + data[i]); } @@ -2170,7 +2163,6 @@ Creates a rotation matrix based on the gravity vector and geomagnetic vector. Th err.message); return; } - console.info("SensorJsAPI--->Successed to get createRotationMatrix interface get data: " + data.x); for (var i=0; i < data.rotation.length; i++) { console.info("data[" + i + "]: " + data[i]) } @@ -2419,9 +2411,9 @@ Describes the Hall effect sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable | Writable | Description | -| ------ | ------ | ---- | ---- | --------------------------------- | -| status | number | Yes | Yes | Hall effect sensor status. This parameter specifies whether a magnetic field exists around a device. The value **0** means that a magnetic field exists around the device, and **1** means the opposite.| +| Name | Type| Readable| Writable| Description | +| ------ | -------- | ---- | ---- | ------------------------------------------------------------ | +| status | number | Yes | Yes | Hall effect sensor status. This parameter specifies whether a magnetic field exists around a device. The value **0** means that a magnetic field does not exist, and a value greater than **0** means the opposite.| ## MagneticFieldResponse diff --git a/en/application-dev/reference/apis/js-apis-system-battery.md b/en/application-dev/reference/apis/js-apis-system-battery.md index 7b577c8ee81c733cdb1aa1f2ccfcced87829f304..5ec8dacc2ed7a88010e2156b6f82be3a4f9557e2 100644 --- a/en/application-dev/reference/apis/js-apis-system-battery.md +++ b/en/application-dev/reference/apis/js-apis-system-battery.md @@ -1,7 +1,7 @@ # Battery Level -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** -> - The APIs of this module are no longer maintained since API version 7. It is recommended that you use [`@ohos.batteryInfo`](js-apis-battery-info.md) instead. +> **NOTE** +> - The APIs of this module are no longer maintained since API version 6. You are advised to use [`@ohos.batteryInfo`](js-apis-battery-info.md). > > - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -22,20 +22,13 @@ Obtains the current charging state and battery level. **System capability**: SystemCapability.PowerManager.BatteryManager.Core -**Parameter** +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| success | Function | No | Called when the check result is obtained | -| fail | Function | No | Called when the check result fails to be obtained | -| complete | Function | No | Called when the execution is complete | - -The following value will be returned when the check result is obtained. - -| Name | Type | Description | -| -------- | -------- | -------- | -| charging | boolean | Whether the battery is being charged | -| level | number | Current battery level, which ranges from 0.00 to 1.00. | +| success | (data: [BatteryResponse](#batteryresponse)) => void | No| Called when API call is successful.| +| fail | (data: string, code: number) => void | No| Called when API call has failed.| +| complete | () => void | No| Called when API call is complete.| **Example** @@ -52,4 +45,11 @@ export default { }); }, } -``` \ No newline at end of file +``` + +## BatteryResponse + +| Name| Type| Description| +| -------- | -------- | -------- | +| charging | boolean | Whether the battery is being charged.| +| level | number | Current battery level, which ranges from **0.00** to **1.00**.| diff --git a/en/application-dev/reference/apis/js-apis-system-brightness.md b/en/application-dev/reference/apis/js-apis-system-brightness.md index 3b1731b865d28bab4708e8613e6969529ed21cb9..9efb0b0a3b3a4aa3103204b1b41b273bae8398f3 100644 --- a/en/application-dev/reference/apis/js-apis-system-brightness.md +++ b/en/application-dev/reference/apis/js-apis-system-brightness.md @@ -1,7 +1,7 @@ # Screen Brightness -> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note：** -> - The APIs of this module are no longer maintained since API version 7. It is recommended that you use [`@ohos.brightness`](js-apis-brightness.md) instead. +> **NOTE** +> - The APIs of this module are no longer maintained since API version 7. You are advised to use [`@ohos.brightness`](js-apis-brightness.md). > > - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -24,34 +24,35 @@ Obtains the current screen brightness. **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| success | Function | No | Called when the execution is successful. | -| fail | Function | No | Called when the operation fails. | -| complete | Function | No | Called when the execution is complete | +| success | (data: [BrightnessResponse](#brightnessresponse)) => void | No| Called when API call is successful.| +| fail | (data: string, code: number) => void | No| Called when API call has failed.| +| complete | () => void | No| Called when API call is complete.| -The following values will be returned when the operation is successful. +**Return value of success()** -| Name | Type | Description | +| Name| Type| Description| | -------- | -------- | -------- | -| value | number | Screen brightness, which ranges from 1 to 255. | +| value | number | Screen brightness. The value is an integer ranging from **1** to **255**.| + **Example** -```js -export default { - getValue() { - brightness.getValue({ - success: function(data){ - console.log('success get brightness value:' + data.value); - }, - fail: function(data, code) { - console.log('get brightness fail, code: ' + code + ', data: ' + data); - }, - }); - }, -} -``` + ```js + export default { + getValue() { + brightness.getValue({ + success: function(data){ + console.log('success get brightness value:' + data.value); + }, + fail: function(data, code) { + console.log('get brightness fail, code: ' + code + ', data: ' + data); + }, + }); + }, + } + ``` ## brightness.setValue @@ -64,30 +65,30 @@ Sets the screen brightness. **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| value | number | Yes | Screen brightness. The value is an integer ranging from 1 to 255.
- If the value is less than or equal to **0**, value **1** will be used.
- If the value is greater than **255**, value **255** will be used.
- If the value contains decimals, the integral part of the value will be used. For example, if value **8.1** is set, value **8** will be used. | -| success | Function | No | Called when the execution is successful. | -| fail | Function | No | Called when the operation fails. | -| complete | Function | No | Called when the execution is complete. | +| value | number | Yes| Screen brightness. The value is an integer ranging from **1** to **255**.
- If the value is less than or equal to **0**, value **1** will be used.
- If the value is greater than **255**, value **255** will be used.
- If the value contains decimals, the integral part of the value will be used. For example, if value **8.1** is set, value **8** will be used.| +| success | () => void | No| Called when API call is successful.| +| fail | (data: string, code: number) => void | No| Called when API call has failed.| +| complete | () => void | No| Called when API call is complete.| **Example** -```js -export default { - setValue() { - brightness.setValue({ - value: 100, - success: function(){ - console.log('handling set brightness success.'); - }, - fail: function(data, code){ - console.log('handling set brightness value fail, code:' + code + ', data: ' + data); - }, - }); - }, -} -``` + ```js + export default { + setValue() { + brightness.setValue({ + value: 100, + success: function(){ + console.log('handling set brightness success.'); + }, + fail: function(data, code){ + console.log('handling set brightness value fail, code:' + code + ', data: ' + data); + }, + }); + }, + } + ``` ## brightness.getMode @@ -100,34 +101,34 @@ Obtains the screen brightness adjustment mode. **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| success | Function | No | Called when the execution is successful. | -| fail | Function | No | Called when the operation fails. | -| complete | Function | No | Called when the execution is complete | +| success | (data: [BrightnessModeResponse](#brightnessmoderesponse)) => void | No| Called when API call is successful.| +| fail | (data: string, code: number) => void | No| Called when API call has failed.| +| complete | () => void | No| Called when API call is complete.| -The following values will be returned when the operation is successful. +**Return value of success()** -| Name | Type | Description | +| Name| Type| Description| | -------- | -------- | -------- | -| mode | number | The value can be **0** or **1**.
- **0**: The screen brightness is manually adjusted.
- **1**: The screen brightness is automatically adjusted. | +| mode | number | The value can be **0** or **1**.
- **0**: manual adjustment
- **1**: automatic adjustment| **Example** -```js -export default { - getMode() { - brightness.getMode({ - success: function(data){ - console.log('success get mode:' + data.mode); - }, - fail: function(data, code){ - console.log('handling get mode fail, code:' + code + ', data: ' + data); - }, - }); - }, -} -``` + ```js + export default { + getMode() { + brightness.getMode({ + success: function(data){ + console.log('success get mode:' + data.mode); + }, + fail: function(data, code){ + console.log('handling get mode fail, code:' + code + ', data: ' + data); + }, + }); + }, + } + ``` ## brightness.setMode @@ -139,31 +140,30 @@ Sets the screen brightness adjustment mode. **System capability**: SystemCapability.PowerManager.DisplayPowerManager **Parameters** - -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| mode | number | Yes | The value can be **0** or **1**.
- **0**: The screen brightness is manually adjusted.
- **1**: The screen brightness is automatically adjusted. | -| success | Function | No | Called when the execution is successful. | -| fail | Function | No | Called when the operation fails. | -| complete | Function | No | Called when the execution is complete. | +| mode | number | Yes| The value can be **0** or **1**.
- **0**: manual adjustment
- **1**: automatic adjustment| +| success | () => void | No| Called when API call is successful.| +| fail | (data: string, code: number) => void | No| Called when API call has failed.| +| complete | () => void | No| Called when API call is complete.| **Example** -```js -export default { - setMode() { - brightness.setMode({ - mode: 1, - success: function(){ - console.log('handling set mode success.'); - }, - fail: function(data, code){ - console.log('handling set mode fail, code:' + code + ', data: ' + data); - }, - }); - }, -} -``` + ```js + export default { + setMode() { + brightness.setMode({ + mode: 1, + success: function(){ + console.log('handling set mode success.'); + }, + fail: function(data, code){ + console.log('handling set mode fail, code:' + code + ', data: ' + data); + }, + }); + }, + } + ``` ## brightness.setKeepScreenOn @@ -175,28 +175,40 @@ Sets whether to always keep the screen on. Call this API in **onShow()**. **System capability**: SystemCapability.PowerManager.DisplayPowerManager **Parameters** - -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| keepScreenOn | boolean | Yes | Whether to always keep the screen on | -| success | Function | No | Called when the execution is successful. | -| fail | Function | No | Called when the operation fails. | -| complete | Function | No | Called when the execution is complete. | +| keepScreenOn | boolean | Yes| Whether to keep the screen on.| +| success | () => void | No| Called when API call is successful.| +| fail | (data: string, code: number) => void | No| Called when API call has failed.| +| complete | () => void | No| Called when API call is complete.| **Example** -```js -export default { - setKeepScreenOn() { - brightness.setKeepScreenOn({ - keepScreenOn: true, - success: function () { - console.log('handling set keep screen on success.') - }, - fail: function (data, code) { - console.log('handling set keep screen on fail, code:' + code + ', data: ' + data); - }, - }); - }, -} -``` \ No newline at end of file + ```js + export default { + setKeepScreenOn() { + brightness.setKeepScreenOn({ + keepScreenOn: true, + success: function () { + console.log('handling set keep screen on success.') + }, + fail: function (data, code) { + console.log('handling set keep screen on fail, code:' + code + ', data: ' + data); + }, + }); + }, + } + ``` +## + +## BrightnessResponse + +| Name| Type | Description| +| -------- | -------- | -------- | +| value | number | Screen brightness. The value is an integer ranging from **1** to **255**.| + +## BrightnessModeResponse + +| Name| Type | Description| +| -------- | -------- | -------- | +| mode | number | The value can be **0** or **1**.
- **0**: manual adjustment
- **0**: manual adjustment| diff --git a/en/application-dev/reference/apis/js-apis-timer.md b/en/application-dev/reference/apis/js-apis-timer.md index f9e174b5147370f465e140d03aeba6b3802380a0..cf8ca596bd72517835c6bd277c0bf29ebf2b7213 100644 --- a/en/application-dev/reference/apis/js-apis-timer.md +++ b/en/application-dev/reference/apis/js-apis-timer.md @@ -1,5 +1,10 @@ # Timer +The **Timer** module provides basic timer capabilities. You can use the APIs of this module to execute functions at the specified time. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## setTimeout @@ -7,6 +12,8 @@ setTimeout(handler[,delay[,…args]]): number Sets a timer for the system to call a function after the timer goes off. +**System capability**: SystemCapability.ArkUI.ArkUI.Full + **Parameters** | Name| Type| Mandatory| Description| @@ -23,15 +30,15 @@ Sets a timer for the system to call a function after the timer goes off. **Example** -```js -export default { - setTimeOut() { - var timeoutID = setTimeout(function() { - console.log('delay 1s'); - }, 1000); + ```js + export default { + setTimeOut() { + var timeoutID = setTimeout(function() { + console.log('delay 1s'); + }, 1000); + } } -} -``` + ``` ## clearTimeout @@ -40,6 +47,8 @@ clearTimeout(timeoutID: number): void Cancels the timer created via **setTimeout()**. +**System capability**: SystemCapability.ArkUI.ArkUI.Full + **Parameters** | Name| Type| Mandatory| Description| @@ -48,16 +57,16 @@ Cancels the timer created via **setTimeout()**. **Example** -```js -export default { - clearTimeOut() { - var timeoutID = setTimeout(function() { - console.log('do after 1s delay.'); - }, 1000); - clearTimeout(timeoutID); + ```js + export default { + clearTimeOut() { + var timeoutID = setTimeout(function() { + console.log('do after 1s delay.'); + }, 1000); + clearTimeout(timeoutID); + } } -} -``` + ``` ## setInterval @@ -66,6 +75,8 @@ setInterval(handler[, delay[, ...args]]): number Sets a repeating timer for the system to repeatedly call a function at a fixed interval. +**System capability**: SystemCapability.ArkUI.ArkUI.Full + **Parameters** | Name| Type| Mandatory| Description| @@ -82,15 +93,15 @@ Sets a repeating timer for the system to repeatedly call a function at a fixed i **Example** -```js -export default { - setInterval() { - var intervalID = setInterval(function() { - console.log('do very 1s.'); - }, 1000); + ```js + export default { + setInterval() { + var intervalID = setInterval(function() { + console.log('do very 1s.'); + }, 1000); + } } -} -``` + ``` ## clearInterval @@ -99,6 +110,8 @@ clearInterval(intervalID: number): void Cancels the repeating timer set via **setInterval()**. +**System capability**: SystemCapability.ArkUI.ArkUI.Full + **Parameters** | Name| Type| Mandatory| Description| @@ -107,13 +120,13 @@ Cancels the repeating timer set via **setInterval()**. **Example** -```js -export default { - clearInterval() { - var intervalID = setInterval(function() { - console.log('do very 1s.'); - }, 1000); - clearInterval(intervalID); + ```js + export default { + clearInterval() { + var intervalID = setInterval(function() { + console.log('do very 1s.'); + }, 1000); + clearInterval(intervalID); + } } -} -``` \ No newline at end of file + ``` diff --git a/en/application-dev/reference/apis/js-apis-wifi.md b/en/application-dev/reference/apis/js-apis-wifi.md index c4d8d105f13c4214912120eb9fc1659276ba07be..dd45a019584f96e4d7434303c6cbd38228420596 100644 --- a/en/application-dev/reference/apis/js-apis-wifi.md +++ b/en/application-dev/reference/apis/js-apis-wifi.md @@ -1,6 +1,6 @@ # WLAN -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> **NOTE**
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -16,13 +16,13 @@ isWifiActive(): boolean Checks whether the WLAN is activated. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Return value +- **Return value** | **Type**| **Description**| | -------- | -------- | | boolean | Returns **true** if the WLAN is activated; returns **false** otherwise.| @@ -34,31 +34,31 @@ scan(): boolean Starts a scan for WLAN. -- Required permissions: +- **Required permissions**: ohos.permission.SET_WIFI_INFO and ohos.permission.LOCATION -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Return value +- **Return value** | **Type**| **Description**| | -------- | -------- | - | boolean | Returns **true** if the scan is successful; returns **false** otherwise.| + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| ## wifi.getScanInfos getScanInfos(): Promise<Array<WifiScanInfo>> -Obtains the scan result. This method uses a promise to return the result. +Obtains the scan result. This API uses a promise to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO, ohos.permission.GET_WIFI_PEERS_MAC, or ohos.permission.LOCATION -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Return value +- **Return value** | **Type**| **Description**| | -------- | -------- | | Promise< Array<[WifiScanInfo](#wifiscaninfo)> > | Promise used to return the scan result, which is a list of hotspots detected.| @@ -68,20 +68,20 @@ Obtains the scan result. This method uses a promise to return the result. getScanInfos(callback: AsyncCallback<Array<WifiScanInfo>>): void -Obtains the scan result. This method uses an asynchronous callback to return the result. +Obtains the scan result. This API uses an asynchronous callback to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO, ohos.permission.GET_WIFI_PEERS_MAC, or ohos.permission.LOCATION -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | callback | AsyncCallback< Array<[WifiScanInfo](#wifiscaninfo)>> | Yes| Callback invoked to return the result, which is a list of hotspots detected.| -- Example +- **Example** ```js import wifi from '@ohos.wifi'; @@ -130,14 +130,14 @@ Represents WLAN hotspot information. | **Name**| **Type**| **Readable/Writable**| **Description**| | -------- | -------- | -------- | -------- | -| ssid | string | Read only| Hotspot service set identifier (SSID), in UTF-8 format.| +| ssid | string | Read only| Service set identifier (SSID) of the hotspot, in UTF-8 format.| | bssid | string | Read only| Basic service set identifier (BSSID) of the hotspot.| | capabilities | string | Read only| Hotspot capabilities.| | securityType | [WifiSecurityType](#WifiSecurityType) | Read only| WLAN security type.| -| rssi | number | Read only| Signal strength of the hotspot, in dBm.| +| rssi | number | Read only| Received signal strength indicator (RSSI) of the hotspot, in dBm.| | band | number | Read only| Frequency band of the WLAN access point (AP).| | frequency | number | Read only| Frequency of the WLAN AP.| -| channelWidth | number | Read only| Bandwidth of the WLAN AP.| +| channelWidth | number | Read only| Channel width of the WLAN AP.| | timestamp | number | Read only| Timestamp.| @@ -158,23 +158,24 @@ Enumerates the WLAN security types. addUntrustedConfig(config: WifiDeviceConfig): Promise<boolean> -Adds untrusted WLAN configuration. This method uses a promise to return the result. +Adds untrusted WLAN configuration. This API uses a promise to return the result. +- **NOTE**
This API is not supported by OpenHarmony 3.1 Release. -- Required permissions: +- **Required permissions**: ohos.permission.SET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | config | [WifiDeviceConfig](#WifiDeviceConfig) | Yes| WLAN configuration to add.| -- Return value +- **Return value** | **Type**| **Description**| | -------- | -------- | - | Promise<boolean> | Promise used to return the operation result. The value **true** indicates that the operation is successful; **false** indicates the opposite.| + | Promise<boolean> | Promise used to return the operation result. If the operation is successful, **true** is returned; otherwise, **false** is returned.| ## WifiDeviceConfig @@ -182,111 +183,113 @@ Represents the WLAN configuration. | **Name**| **Type**| **Readable/Writable**| **Description**| | -------- | -------- | -------- | -------- | -| ssid | string | Read only| Hotspot service set identifier (SSID), in UTF-8 format.| +| ssid | string | Read only| SSID of the hotspot, in UTF-8 format.| | bssid | string | Read only| BSSID of the hotspot.| -| preSharedKey | string | Read only| Private key of the hotspot.| -| isHiddenSsid | boolean | Read only| Whether to hide the network.| -| securityType | [WifiSecurityType](#WifiSecurityType) | Read only| Security type| +| preSharedKey | string | Read only| PSK of the hotspot.| +| isHiddenSsid | boolean | Read only| Whether the network is hidden.| +| securityType | [WifiSecurityType](#WifiSecurityType) | Read only| Security type.| ## wifi.addUntrustedConfig7+ addUntrustedConfig(config: WifiDeviceConfig, callback: AsyncCallback<boolean>): void -Adds untrusted WLAN configuration. This method uses an asynchronous callback to return the result. +Adds untrusted WLAN configuration. This API uses an asynchronous callback to return the result. -- Required permissions: +- **NOTE**
This API is not supported by OpenHarmony 3.1 Release. + +- **Required permissions**: ohos.permission.SET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | config | [WifiDeviceConfig](#WifiDeviceConfig) | Yes| WLAN configuration to add.| - | callback | AsyncCallback<boolean> | Yes| Promise used to return the operation result. The value **true** indicates that the operation is successful; **false** indicates the opposite.| + | callback | AsyncCallback<boolean> | Yes| Callback invoked to return the result. If the operation is successful, **true** is returned; otherwise, **false** is returned.| ## wifi.removeUntrustedConfig7+ removeUntrustedConfig(config: WifiDeviceConfig): Promise<boolean> -Removes untrusted WLAN configuration. This method uses a promise to return the result. +Removes untrusted WLAN configuration. This API uses a promise to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.SET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | config | [WifiDeviceConfig](#WifiDeviceConfig) | Yes| WLAN configuration to remove.| -- Return value +- **Return value** | **Type**| **Description**| | -------- | -------- | - | Promise<boolean> | Promise used to return the operation result. The value **true** indicates that the operation is successful; **false** indicates the opposite.| + | Promise<boolean> | Promise used to return the result. If the operation is successful, **true** is returned; otherwise, **false** is returned.| ## wifi.removeUntrustedConfig7+ removeUntrustedConfig(config: WifiDeviceConfig, callback: AsyncCallback<boolean>): void -Removes untrusted WLAN configuration. This method uses an asynchronous callback to return the result. +Removes untrusted WLAN configuration. This API uses an asynchronous callback to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.SET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | config | [WifiDeviceConfig](#WifiDeviceConfig) | Yes| WLAN configuration to remove.| - | callback | AsyncCallback<boolean> | Yes| Promise used to return the operation result. The value **true** indicates that the operation is successful; **false** indicates the opposite.| + | callback | AsyncCallback<boolean> | Yes| Callback invoked used to return the result. If the operation is successful, **true** is returned; otherwise, **false** is returned.| ## wifi.getSignalLevel getSignalLevel(rssi: number, band: number): number -Obtains the WLAN signal strength. +Obtains the WLAN signal level. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA - **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | - | rssi | number | Yes| Signal strength of the hotspot, in dBm.| + | rssi | number | Yes| RSSI of the hotspot, in dBm.| | band | number | Yes| Frequency band of the WLAN AP.| -- Return value +- **Return value** | **Type**| **Description**| | -------- | -------- | - | number | Signal strength obtained. The value range is [0, 4].| + | number | Signal level obtained. The value range is [0, 4].| ## wifi.getLinkedInfo getLinkedInfo(): Promise<WifiLinkedInfo> -Obtains WLAN connection information. This method uses a promise to return the result. +Obtains WLAN connection information. This API uses a promise to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Return value +- **Return value** | Type| Description| | -------- | -------- | | Promise<[WifiLinkedInfo](#WifiLinkedInfo)> | Promise used to return the WLAN connection information obtained.| @@ -296,20 +299,20 @@ Obtains WLAN connection information. This method uses a promise to return the re getLinkedInfo(callback: AsyncCallback<WifiLinkedInfo>): void -Obtains WLAN connection information. This method uses a callback to return the result. +Obtains WLAN connection information. This API uses a callback to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | callback | AsyncCallback<[WifiLinkedInfo](#WifiLinkedInfo)> | Yes| Callback invoked to return the WLAN connection information obtained.| -- Example +- **Example** ```js import wifi from '@ohos.wifi'; @@ -335,9 +338,9 @@ Represents the WLAN connection information. | Name| Type| Readable/Writable| Description| | -------- | -------- | -------- | -------- | -| ssid | string | Read only| Hotspot SSID, in UTF-8 format.| +| ssid | string | Read only| SSID of the hotspot, in UTF-8 format.| | bssid | string | Read only| BSSID of the hotspot.| -| rssi | number | Read only| Signal strength of the hotspot, in dBm.| +| rssi | number | Read only| RSSI of the hotspot, in dBm.| | band | number | Read only| Frequency band of the WLAN AP.| | linkSpeed | number | Read only| Speed of the WLAN AP.| | frequency | number | Read only| Frequency of the WLAN AP.| @@ -361,7 +364,7 @@ Enumerates the WLAN connection states. | CONNECTED | 4 | A WLAN connection is established.| | DISCONNECTING | 5 | The WLAN connection is being disconnected.| | DISCONNECTED | 6 | The WLAN connection is disconnected.| -| UNKNOWN | 7 | Failed to set up a WLAN connection.| +| UNKNOWN | 7 | Failed to set up the WLAN connection.| ## wifi.isConnected7+ @@ -370,13 +373,13 @@ isConnected(): boolean Checks whether the WLAN is connected. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Return value +- **Return value** | **Type**| **Description**| | -------- | -------- | | boolean | Returns **true** if the WLAN is connected; returns **false** otherwise.| @@ -388,10 +391,10 @@ isFeatureSupported(featureId: number): boolean Checks whether the device supports the specified WLAN feature. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.Core - **Parameters** @@ -399,7 +402,7 @@ Checks whether the device supports the specified WLAN feature. | -------- | -------- | -------- | -------- | | featureId | number | Yes| Feature ID.| -- Return value +- **Return value** | **Type**| **Description**| | -------- | -------- | | boolean | Returns **true** if the feature is supported; returns **false** otherwise.| @@ -408,14 +411,14 @@ Checks whether the device supports the specified WLAN feature. | Value| Description| | -------- | -------- | | 0x0001 | WLAN infrastructure mode| - | 0x0002 | 5 GHz bandwidth| + | 0x0002 | 5 GHz feature| | 0x0004 | Generic Advertisement Service (GAS)/Access Network Query Protocol (ANQP) feature| | 0x0008 | Wi-Fi Direct| | 0x0010 | SoftAP| | 0x0040 | Wi-Fi AWare| | 0x8000 | WLAN AP/STA concurrency| | 0x8000000 | WPA3 Personal (WPA-3 SAE)| - | 0x10000000 | WPA3-Enterprise Suite-B | + | 0x10000000 | WPA3-Enterprise Suite B | | 0x20000000 | Enhanced open feature| @@ -425,13 +428,13 @@ getIpInfo(): IpInfo Obtains IP information. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Return value +- **Return value** | **Type**| **Description**| | -------- | -------- | | [IpInfo](#IpInfo) | IP information obtained.| @@ -443,13 +446,13 @@ Represents IP information. | **Name**| **Type**| **Readable/Writable**| **Description**| | -------- | -------- | -------- | -------- | -| ipAddress | number | Read only| IP address| -| gateway | number | Read only| Gateway| -| netmask | number | Read only| Subnet mask| -| primaryDns | number | Read only| IP address of the preferred DNS server| -| secondDns | number | Read only| IP address of the alternate DNS server| -| serverIp | number | Read only| IP address of the DHCP server| -| leaseDuration | number | Read only| Lease duration of the IP address| +| ipAddress | number | Read only| IP address.| +| gateway | number | Read only| Gateway.| +| netmask | number | Read only| Subnet mask.| +| primaryDns | number | Read only| IP address of the preferred DNS server.| +| secondDns | number | Read only| IP address of the alternate DNS server.| +| serverIp | number | Read only| IP address of the DHCP server.| +| leaseDuration | number | Read only| Lease duration of the IP address.| ## wifi.getCountryCode7+ @@ -458,13 +461,13 @@ getCountryCode(): string Obtains the country code. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.Core -- Return value +- **Return value** | **Type**| **Description**| | -------- | -------- | | string | Country code obtained.| @@ -474,15 +477,15 @@ Obtains the country code. getP2pLinkedInfo(): Promise<WifiP2pLinkedInfo> -Obtains peer-to-peer (P2P) connection information. This method uses a promise to return the result. +Obtains peer-to-peer (P2P) connection information. This API uses a promise to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Return value +- **Return value** | Type| Description| | -------- | -------- | | Promise<[WifiP2pLinkedInfo](#WifiP2pLinkedInfo)> | Promise used to return the P2P connection information obtained.| @@ -492,18 +495,18 @@ Obtains peer-to-peer (P2P) connection information. This method uses a promise to getP2pLinkedInfo(callback: AsyncCallback<WifiP2pLinkedInfo>): void -Obtains P2P connection information. This method uses a callback to return the result. +Obtains P2P connection information. This API uses an asynchronous callback to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<[WifiP2pLinkedInfo](#WifiP2pLinkedInfo)> | Yes| Callback used to return the P2P connection information obtained.| + | callback | AsyncCallback<[WifiP2pLinkedInfo](#WifiP2pLinkedInfo)> | Yes| Callback invoked to return the P2P connection information obtained.| ## WifiP2pLinkedInfo8+ @@ -531,15 +534,15 @@ Enumerates the P2P connection states. getCurrentGroup(): Promise<WifiP2pGroupInfo> -Obtains the current P2P group information. This method uses a promise to return the result. +Obtains the current P2P group information. This API uses a promise to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Return value +- **Return value** | Type| Description| | -------- | -------- | | Promise<[WifiP2pGroupInfo](#WifiP2pGroupInfo)> | Promise used to return the P2P group information obtained.| @@ -549,18 +552,18 @@ Obtains the current P2P group information. This method uses a promise to return getCurrentGroup(callback: AsyncCallback<WifiP2pGroupInfo>): void -Obtains the P2P group information. This method uses an asynchronous callback to return the result. +Obtains the P2P group information. This API uses an asynchronous callback to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<[WifiP2pGroupInfo](#WifiP2pGroupInfo)> | Yes| Callback used to return the P2P group information obtained.| + | callback | AsyncCallback<[WifiP2pGroupInfo](#WifiP2pGroupInfo)> | Yes| Callback invoked to return the P2P group information obtained.| ## WifiP2pGroupInfo8+ @@ -571,7 +574,7 @@ Represents the P2P group information. | -------- | -------- | -------- | -------- | | isP2pGo | boolean | Read only| Whether it is a group.| | ownerInfo | [WifiP2pDevice](#WifiP2pDevice) | Read only| Device information of the group.| -| passphrase | string | Read only| Private key of the group.| +| passphrase | string | Read only| Passphrase of the group.| | interface | string | Read only| Interface name.| | groupName | string | Read only| Group name.| | networkId | number | Read only| Network ID.| @@ -593,7 +596,7 @@ Represents the P2P device information. ## P2pDeviceStatus8+ -Enumerates the device states. +Enumerates the P2P device states. | Name| Default Value| Description| | -------- | -------- | -------- | @@ -608,15 +611,15 @@ Enumerates the device states. getP2pPeerDevices(): Promise<WifiP2pDevice[]> -Obtains the list of peer devices in a P2P connection. This method uses a promise to return the result. +Obtains the list of peer devices in the P2P connection. This API uses a promise to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Return value +- **Return value** | Type| Description| | -------- | -------- | | Promise<[WifiP2pDevice[]](#WifiP2pDevice)> | Promise used to return the peer device list obtained.| @@ -626,18 +629,18 @@ Obtains the list of peer devices in a P2P connection. This method uses a promise getP2pPeerDevices(callback: AsyncCallback<WifiP2pDevice[]>): void -Obtains the list of peer devices in a P2P connection. This method uses an asynchronous callback to return the result. +Obtains the list of peer devices in the P2P connection. This API uses an asynchronous callback to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<[WifiP2pDevice[]](#WifiP2pDevice)> | Yes| Callback used to return the peer device list obtained.| + | callback | AsyncCallback<[WifiP2pDevice[]](#WifiP2pDevice)> | Yes| Callback involed to return the peer device list obtained.| ## wifi.createGroup8+ @@ -646,10 +649,10 @@ createGroup(config: WifiP2PConfig): boolean; Creates a P2P group. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P - **Parameters** @@ -657,27 +660,27 @@ Creates a P2P group. | -------- | -------- | -------- | -------- | | config | [WifiP2PConfig](#WifiP2PConfig) | Yes| Group configuration.| -- Return value +- **Return value** | Type| Description| | -------- | -------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| ## WifiP2PConfig8+ -Represents P2P configuration. +Represents P2P group configuration. | Name| Type| Readable/Writable| Description| | -------- | -------- | -------- | -------- | | deviceAddress | string | Read only| Device address.| -| netId | number | Read only| Network ID. The value **-1** indicates that a temporary group, and **-2** indicates that a persistent group.| -| passphrase | string | Read only| Private key of the group.| +| netId | number | Read only| Network ID. The value **-1** indicates a temporary group, and **-2** indicates a persistent group.| +| passphrase | string | Read only| Passphrase of the group.| | groupName | string | Read only| Name of the group.| -| goBand | [GroupOwnerBand](#GroupOwnerBand) | Read only| Bandwidth of the group.| +| goBand | [GroupOwnerBand](#GroupOwnerBand) | Read only| Frequency band of the group.| ## GroupOwnerBand8+ -Enumerates the P2P group bandwidths. +Enumerates the P2P group frequency bands. | Name| Default Value| Description| | -------- | -------- | -------- | @@ -689,15 +692,15 @@ Enumerates the P2P group bandwidths. removeGroup(): boolean; -Removes a P2P group. +Removes this P2P group. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Return value +- **Return value** | Type| Description| | -------- | -------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| @@ -709,24 +712,24 @@ p2pConnect(config: WifiP2PConfig): boolean; Sets up a P2P connection. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P - **Parameters** | **Name**| **Type**| Mandatory| **Description**| | -------- | -------- | -------- | -------- | - | config | [WifiP2PConfig](#WifiP2PConfig) | Yes| Connection configuration.| + | config | [WifiP2PConfig](#WifiP2PConfig) | Yes| P2P group configuration.| -- Return value +- **Return value** | Type| Description| | -------- | -------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -- Example +- **Example** ```js import wifi from '@ohos.wifi'; @@ -799,13 +802,13 @@ p2pCancelConnect(): boolean; Cancels this P2P connection. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Return value +- **Return value** | Type| Description| | -------- | -------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| @@ -817,13 +820,13 @@ startDiscoverDevices(): boolean; Starts to discover devices. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Return value +- **Return value** | Type| Description| | -------- | -------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| @@ -835,13 +838,13 @@ stopDiscoverDevices(): boolean; Stops discovering devices. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Return value +- **Return value** | Type| Description| | -------- | -------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| @@ -853,13 +856,13 @@ on(type: "wifiStateChange", callback: Callback<number>): void Registers the WLAN state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **wifiStateChange**.| @@ -880,19 +883,19 @@ off(type: "wifiStateChange", callback?: Callback<number>): void Unregisters the WLAN state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **wifiStateChange**.| | callback | Callback<number> | No| Callback used to return the WLAN state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| -- Example +- **Example** ```js import wifi from '@ohos.wifi'; @@ -901,10 +904,10 @@ Unregisters the WLAN state change events. console.info("Receive power state change event: " + result); } - // Register event + // Register an event. wifi.on(WIFI_POWER_STATE, recvPowerNotifyFunc); - // Unregister event + // Unregister an event. wifi.off(WIFI_POWER_STATE, recvPowerNotifyFunc); ``` @@ -915,13 +918,13 @@ on(type: "wifiConnectionChange", callback: Callback<number>): void Registers the WLAN connection state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **wifiConnectionChange**.| @@ -930,8 +933,8 @@ Registers the WLAN connection state change events. - Enumerates the WLAN connection states. | **Value**| **Description**| | -------- | -------- | - | 0 | Disconnected| - | 1 | Connected| + | 0 | Disconnected.| + | 1 | Connected.| ## wifi.off('wifiConnectionChange')7+ @@ -940,17 +943,17 @@ off(type: "wifiConnectionChange", callback?: Callback<number>): void Unregisters the WLAN connection state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **wifiConnectionChange**.| - | callback | Callback<number> | No| Callback used to report the WLAN connection state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | callback | Callback<number> | No| Callback used to return the WLAN connection state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| ## wifi.on('wifiScanStateChange')7+ @@ -959,13 +962,13 @@ on(type: "wifiScanStateChange", callback: Callback<number>): void Registers the WLAN scan state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **wifiScanStateChange**.| @@ -974,8 +977,8 @@ Registers the WLAN scan state change events. - Enumerates the WLAN scan states. | **Value**| **Description**| | -------- | -------- | - | 0 | Scan failed| - | 1 | Scan successful| + | 0 | Scan failed.| + | 1 | Scan successful.| ## wifi.off('wifiScanStateChange')7+ @@ -984,13 +987,13 @@ off(type: "wifiScanStateChange", callback?: Callback<number>): void Unregisters the WLAN scan state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | @@ -1002,15 +1005,15 @@ Unregisters the WLAN scan state change events. on(type: "wifiRssiChange", callback: Callback<number>): void -Registers the RSSI state change events. +Registers the RSSI change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **wifiRssiChange**.| @@ -1021,19 +1024,19 @@ Registers the RSSI state change events. off(type: "wifiRssiChange", callback?: Callback<number>): void -Unregisters the RSSI state change events. +Unregisters the RSSI change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.STA -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **wifiRssiChange**.| - | callback | Callback<number> | No| Callback used to return the RSSI, in dBm. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | callback | Callback<number> | No| Callback used to return the RSSI. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| ## wifi.on('hotspotStateChange')7+ @@ -1042,13 +1045,13 @@ on(type: "hotspotStateChange", callback: Callback<number>): void Registers the hotspot state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.AP.Core -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **hotspotStateChange**.| @@ -1069,13 +1072,13 @@ off(type: "hotspotStateChange", callback?: Callback<number>): void Unregisters the hotspot state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.AP.Core -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **hotspotStateChange**.| @@ -1086,15 +1089,15 @@ Unregisters the hotspot state change events. on(type: "p2pStateChange", callback: Callback<number>): void -Registers the P2P status change events. +Registers the P2P state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **p2pStateChange**.| @@ -1115,13 +1118,13 @@ off(type: "p2pStateChange", callback?: Callback<number>): void Unregisters the P2P state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **p2pStateChange**.| @@ -1134,13 +1137,13 @@ on(type: "p2pConnectionChange", callback: Callback<WifiP2pLinkedInfo>): vo Registers the P2P connection state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **p2pConnectionChange**.| @@ -1153,13 +1156,13 @@ off(type: "p2pConnectionChange", callback?: Callback<WifiP2pLinkedInfo>): Unregisters the P2P connection state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **p2pConnectionChange**.| @@ -1172,13 +1175,13 @@ on(type: "p2pDeviceChange", callback: Callback<WifiP2pDevice>): void Registers the P2P device state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **p2pDeviceChange**.| @@ -1191,17 +1194,17 @@ off(type: "p2pDeviceChange", callback?: Callback<WifiP2pDevice>): void Unregisters the P2P device state change events. -- Required permissions: +- **Required permissions**: ohos.permission.LOCATION -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **p2pDeviceChange**.| - | callback | Callback<[WifiP2pDevice](#WifiP2pDevice)> | No| Callback used to return the P2P device state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | callback | Callback<[WifiP2pDevice](#WifiP2pDevice)> | No| Callback used to return the P2P peer device state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| ## wifi.on('p2pPeerDeviceChange')8+ @@ -1210,17 +1213,17 @@ on(type: "p2pPeerDeviceChange", callback: Callback<WifiP2pDevice[]>): void Registers the P2P peer device state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **p2pPeerDeviceChange**.| - | callback | Callback<[WifiP2pDevice[]](#WifiP2pDevice)> | Yes| Callback invoked to return the P2P peer device state.| + | callback | Callback<[WifiP2pDevice[]](#WifiP2pDevice)> | Yes| Callback invoked to return the peer device state.| ## wifi.off('p2pPeerDeviceChange')8+ @@ -1229,13 +1232,13 @@ off(type: "p2pPeerDeviceChange", callback?: Callback<WifiP2pDevice[]>): vo Unregisters the P2P peer device state change events. -- Required permissions: +- **Required permissions**: ohos.permission.LOCATION -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **p2pPeerDeviceChange**.| @@ -1248,13 +1251,13 @@ on(type: "p2pPersistentGroupChange", callback: Callback<void>): void Registers the P2P persistent group state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **p2pPersistentGroupChange**.| @@ -1267,13 +1270,13 @@ off(type: "p2pPersistentGroupChange", callback?: Callback<void>): void Unregisters the P2P persistent group state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **p2pPersistentGroupChange**.| @@ -1284,21 +1287,21 @@ Unregisters the P2P persistent group state change events. on(type: "p2pDiscoveryChange", callback: Callback<number>): void -Registers the P2P discovered device state change events. +Registers the P2P device discovery state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **p2pDiscoveryChange**.| - | callback | Callback<number> | Yes| Callback invoked to return the state of the P2P discovered device.| + | callback | Callback<number> | Yes| Callback invoked to return the P2P device discovery state.| -- Enumerates the states of P2P discovered devices. +- Enumerates the P2P device discovery states. | **Value**| **Description**| | -------- | -------- | | 0 | Initial state| @@ -1309,16 +1312,16 @@ Registers the P2P discovered device state change events. off(type: "p2pDiscoveryChange", callback?: Callback<number>): void -Unregisters the P2P discovered device state change events. +Unregisters the P2P device discovery state change events. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.P2P -- Parameters +- **Parameters** | **Name**| **Type**| **Mandatory**| **Description**| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type. The value is **p2pDiscoveryChange**.| - | callback | Callback<number> | No| Callback used to return the state of the P2P discovered device. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | callback | Callback<number> | No| Callback used to return the P2P device discovery state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| diff --git a/en/application-dev/reference/apis/js-apis-wifiext.md b/en/application-dev/reference/apis/js-apis-wifiext.md index 2e2e9394b2a4361fa8adad332c459d4ff33a4e4d..028b396ebb4244ce80eb4a4754bf8d2445474ce3 100644 --- a/en/application-dev/reference/apis/js-apis-wifiext.md +++ b/en/application-dev/reference/apis/js-apis-wifiext.md @@ -1,8 +1,9 @@ # WLAN -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> **NOTE**
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. The APIs described in this document are used only for non-universal products, such as routers. +The APIs of this module are not supported by OpenHarmony 3.1 Release. ## Modules to Import @@ -17,13 +18,13 @@ enableHotspot(): boolean; Enables the WLAN hotspot. -- Required permissions: +- **Required permissions**: ohos.permission.MANAGE_WIFI_HOTSPOT_EXT -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Return value +- **Return value**: | **Type**| **Description**| | -------- | -------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| @@ -35,13 +36,13 @@ disableHotspot(): boolean; Disables the WLAN hotspot. -- Required permissions: +- **Required permissions**: ohos.permission.MANAGE_WIFI_HOTSPOT_EXT -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Return value +- **Return value**: | **Type**| **Description**| | -------- | -------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| @@ -51,15 +52,15 @@ Disables the WLAN hotspot. getSupportedPowerModel(): Promise<Array<PowerModel>> -Obtains the supported power models. The method uses a promise to return the result. +Obtains the supported power models. The API uses a promise to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Return value +- **Return value**: | Type| Description| | -------- | -------- | | Promise<Array<[PowerModel](#PowerModel)>> | Promise used to return the power models obtained.| @@ -67,7 +68,7 @@ Obtains the supported power models. The method uses a promise to return the resu ## PowerModel -Enumerates of the power models. +Enumerates the power models. | Name| Default Value| Description| | -------- | -------- | -------- | @@ -80,33 +81,33 @@ Enumerates of the power models. getSupportedPowerModel(callback: AsyncCallback<Array<PowerModel>>): void -Obtains the supported power models. The method uses an asynchronous callback to return the result. +Obtains the supported power models. The API uses an asynchronous callback to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Parameters +- **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<[PowerModel](#PowerModel)> | Yes| Callback used to return the power models obtained.| + | callback | AsyncCallback<[PowerModel](#PowerModel)> | Yes| Callback invoked to return the power models obtained.| ## wifiext.getPowerModel getPowerModel(): Promise<PowerModel> -Obtains the power model. The method uses a promise to return the result. +Obtains the power model. The API uses a promise to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Return value +- **Return value**: | Type| Description| | -------- | -------- | | Promise<[PowerModel](#PowerModel)> | Promise used to return the power model obtained.| @@ -116,15 +117,15 @@ Obtains the power model. The method uses a promise to return the result. getPowerModel(callback: AsyncCallback<PowerModel>): void -Obtains the power model. The method uses an asynchronous callback to return the result. +Obtains the power model. The API uses an asynchronous callback to return the result. -- Required permissions: +- **Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Parameters +- **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | callback | AsyncCallback<[PowerModel](#PowerModel)> | Yes| Callback invoked to return the power mode obtained.| @@ -136,18 +137,18 @@ setPowerModel(model: PowerModel) : boolean; Sets the power model. -- Required permissions: +- **Required permissions**: ohos.permission.MANAGE_WIFI_HOTSPOT_EXT -- System capability: +- **System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Parameters +- **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | model | AsyncCallback<[PowerModel](#PowerModel)> | Yes| Power model to set.| -- Return value +- **Return value**: | **Type**| **Description**| | -------- | -------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| diff --git a/en/application-dev/reference/apis/js-apis-window.md b/en/application-dev/reference/apis/js-apis-window.md index f73e6f6315b4a18a2dee70d9d5a9a8f0c0e14c90..cf1052ae97ef878030e348cea83f8388092fbde2 100644 --- a/en/application-dev/reference/apis/js-apis-window.md +++ b/en/application-dev/reference/apis/js-apis-window.md @@ -10,7 +10,6 @@ This module provides the following common window-related functions: > > The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. - ## Modules to Import ```js @@ -35,10 +34,10 @@ Enumerates the types of the area where the window cannot be displayed. **System capability**: SystemCapability.WindowManager.WindowManager.Core -| Name | Value | Description | -| ----------- | ---- | ------------------ | -| TYPE_SYSTEM | 0 | Default area of the system.| -| TYPE_CUTOUT | 1 | Notch. | +| Name | Value | Description | +|----------------------------------|-----| ----------------- | +| TYPE_SYSTEM | 0 | Default area of the system.| +| TYPE_CUTOUT | 1 | Notch. | ## WindowMode7+ @@ -64,11 +63,11 @@ Describes the properties of the status bar and navigation bar. | Name | Type| Readable| Writable| Description | | -------------------------------------- | -------- | ---- | ---- | ------------------------------------------------------------ | -| statusBarColor | string | Yes | Yes | Background color of the status bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| +| statusBarColor | string | No | Yes | Background color of the status bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| | isStatusBarLightIcon7+ | boolean | No | Yes | Whether any icon on the status bar is highlighted. | | statusBarContentColor8+ | string | No | Yes | Color of the text on the status bar. | -| navigationBarColor | string | Yes | Yes | Background color of the navigation bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| -| isNavigationBarLightIcon7+ | boolean | No | No | Whether any icon on the navigation bar is highlighted. | +| navigationBarColor | string | No | Yes | Background color of the navigation bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| +| isNavigationBarLightIcon7+ | boolean | No | Yes | Whether any icon on the navigation bar is highlighted. | | navigationBarContentColor8+ | string | No | Yes | Color of the text on the navigation bar. | ## SystemBarRegionTint8+ @@ -81,11 +80,11 @@ Describes the callback for a single system bar. | Name | Type | Readable| Writable| Description | | --------------- | ------------------------- | ---- | ---- | ------------------------------------------------------------ | -| type | [WindowType](#windowtype) | Yes | Yes | Type of the system bar whose properties are changed. Only the status bar and navigation bar are supported.| -| isEnable | boolean | Yes | Yes | Whether the system bar is displayed. | -| region | [Rect](#rect) | Yes | Yes | Current position and size of the system bar. | -| backgroundColor | string | Yes | Yes | Background color of the system bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| -| contentColor | string | Yes | Yes | Color of the text on the system bar. | +| type | [WindowType](#windowtype) | Yes | No | Type of the system bar whose properties are changed. Only the status bar and navigation bar are supported.| +| isEnable | boolean | Yes | No | Whether the system bar is displayed. | +| region | [Rect](#rect) | Yes | No | Current position and size of the system bar. | +| backgroundColor | string | Yes | No | Background color of the system bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| +| contentColor | string | Yes | No | Color of the text on the system bar. | ## SystemBarTintState8+ @@ -98,7 +97,7 @@ Describes the callback for the current system bar. | Name | Type | Readable| Writable| Description | | ---------- | --------------------------------------------------- | ---- | ---- | ---------------------------- | | displayId | number | Yes | No | ID of the current physical screen. | -| regionTint | Array<[SystemBarRegionTint](#systembarregiontint8)> | Yes | Yes | All system bar information that has been changed.| +| regionTint | Array<[SystemBarRegionTint](#systembarregiontint8)> | Yes | No | All system bar information that has been changed.| ## Rect7+ @@ -126,6 +125,7 @@ Describes the area where the window cannot be displayed. | rightRect | [Rect](#rect) | Yes | Yes | Rectangle on the right of the screen.| | bottomRect | [Rect](#rect) | Yes | Yes | Rectangle at the bottom of the screen.| + ## Size7+ Describes the window size. @@ -143,20 +143,20 @@ Describes the window properties. **System capability**: SystemCapability.WindowManager.WindowManager.Core -| Name | Type | Readable| Writable| Description | -| ------------------------------- | ------------------------- | ---- | ---- | -------------------------------------------- | -| windowRect7+ | [Rect](#rect) | Yes | Yes | Window size. | -| type7+ | [WindowType](#windowtype) | Yes | Yes | Window type. | -| isFullScreen | boolean | Yes | Yes | Whether the window is displayed in full screen mode. The default value is `false`. | -| isLayoutFullScreen7+ | boolean | Yes | Yes | Whether the window layout is in full-screen mode (whether the window is immersive). The default value is `false`. | -| focusable7+ | boolean | Yes | No | Whether the window can gain focus. The default value is `true`. | -| touchable7+ | boolean | Yes | No | Whether the window is touchable. The default value is `true`. | -| brightness | number | Yes | Yes | Screen brightness. The value ranges from 0 to 1. The value `1` indicates the maximum brightness. | -| dimBehindValue7+ | number | Yes | Yes | Dimness of the window that is not on top. The value ranges from 0 to 1. The value `1` indicates the maximum dimness.| -| isKeepScreenOn | boolean | Yes | Yes | Whether the screen is always on. The default value is `false`. | -| isPrivacyMode7+ | boolean | Yes | Yes | Whether the window is in privacy mode. The default value is `false`. | -| isRoundCorner7+ | boolean | Yes | Yes | Whether the window has rounded corners. The default value is `false`. | -| isTransparent7+ | boolean | Yes | Yes | Whether the window is transparent. The default value is `false`. | +| Name | Type | Readable| Writable| Description | +| ------------------------------------- | ------------------------- | ---- | ---- | ------------------------------------------------------------ | +| windowRect7+ | [Rect](#rect) | Yes | Yes | Window size. | +| type7+ | [WindowType](#windowtype) | Yes | Yes | Window type. | +| isFullScreen | boolean | Yes | Yes | Whether the window is displayed in full screen mode. The default value is `false`. | +| isLayoutFullScreen7+ | boolean | Yes | Yes | Whether the window layout is in full-screen mode (whether the window is immersive). The default value is `false`. | +| focusable7+ | boolean | Yes | No | Whether the window can gain focus. The default value is `true`. | +| touchable7+ | boolean | Yes | No | Whether the window is touchable. The default value is `true`. | +| brightness | number | Yes | Yes | Screen brightness. The value ranges from 0 to 1. The value `1` indicates the maximum brightness. | +| dimBehindValue7+ | number | Yes | Yes | Dimness of the window that is not on top. The value ranges from 0 to 1. The value `1` indicates the maximum dimness. | +| isKeepScreenOn | boolean | Yes | Yes | Whether the screen is always on. The default value is `false`. | +| isPrivacyMode7+ | boolean | Yes | Yes | Whether the window is in privacy mode. The default value is `false`. | +| isRoundCorner7+ | boolean | Yes | Yes | Whether the window has rounded corners. The default value is `false`. | +| isTransparent7+ | boolean | Yes | Yes | Whether the window is transparent. The default value is `false`. | ## ColorSpace8+ @@ -245,7 +245,7 @@ Creates a subwindow. This API uses an asynchronous callback to return the result | Name | Type | Mandatory| Description | | -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | -| ctx | [Context](js-apis-Context.md) | Yes | Current application context.| +| ctx | [Context](js-apis-Context.md) | Yes | Current application context.| | id | string | Yes | Window ID. | | type | [WindowType](#windowtype) | Yes | Window type. | | callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow created. | @@ -430,7 +430,7 @@ Obtains the top window of the current application. This API uses an asynchronous | Name | Type | Mandatory| Description | | -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | -| ctx | [Context](js-apis-Context.md) | Yes | Current application context. | +| ctx | [Context](js-apis-Context.md) | Yes | Current application context.| | callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the top window obtained. | **Example** @@ -937,8 +937,8 @@ Obtains the area where this window cannot be displayed, for example, the system **Parameters** -| Name | Type | Mandatory| Description | -| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| Name | Type | Mandatory| Description | +| -------- |-----------------------------------------------| ---- | ------------------------------------------------------------ | | type | [AvoidAreaType](#avoidareatype) | Yes | Type of the area. `TYPE_SYSTEM` indicates the default area of the system. `TYPE_CUTOUT` indicates the notch.| | callback | AsyncCallback<[AvoidArea](#avoidarea)> | Yes | Callback used to return the area. | @@ -965,20 +965,21 @@ Obtains the area where this window cannot be displayed, for example, the system **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------------------------------- | ---- | ------------------------------------------------------------ | +| Name| Type | Mandatory| Description | +| ------ |----------------------------------| ---- | ------------------------------------------------------------ | | type | [AvoidAreaType](#avoidareatype) | Yes | Type of the area. `TYPE_SYSTEM` indicates the default area of the system. `TYPE_CUTOUT` indicates the notch.| **Return value** -| Type | Description | -| -------------------------------------- | ----------------------------------- | +| Type | Description | +|-----------------------------------------| ----------------------------------- | | Promise<[AvoidArea](#avoidarea)> | Promise used to return the area.| **Example** ```js -let promise = windowClass.getAvoidArea(); +var type = window.AvoidAreaType.TYPE_SYSTEM; +let promise = windowClass.getAvoidArea(type); promise.then((data)=> { console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data)); }).catch((err)=>{ @@ -1315,7 +1316,7 @@ Checks whether this window is displayed. This API uses an asynchronous callback | Name | Type | Mandatory| Description | | -------- | ---------------------------- | ---- | ------------------------------------------------------------ | -| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value `true` means that this window is displayed, and `false` means the opposite.| +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value `true` means that the window is displayed, and `false` means the opposite.| **Example** @@ -1341,7 +1342,7 @@ Checks whether this window is displayed. This API uses a promise to return the r | Type | Description | | ---------------------- | ------------------------------------------------------------ | -| Promise<boolean> | Promise used to return the result. The value `true` means that this window is displayed, and `false` means the opposite.| +| Promise<boolean> | Promise used to return the result. The value `true` means that the window is displayed, and `false` means the opposite.| **Example** @@ -1408,9 +1409,9 @@ Enables listening for changes to the area where the window cannot be displayed. **Parameters** -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type. The value is fixed at `systemAvoidAreaChange`, indicating the event of changes to the area where the window cannot be displayed.| +| Name | Type | Mandatory| Description | +| -------- |------------------------------------------| ---- | ------------------------------------------------------- | +| type | string | Yes | Event type. The value is fixed at `systemAvoidAreaChange`, indicating the event of changes to the area where the window cannot be displayed.| | callback | Callback<[AvoidArea](#avoidarea)> | Yes | Callback used to return the area. | **Example** @@ -1431,10 +1432,10 @@ Disables listening for changes to the area where the window cannot be displayed. **Parameters** -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type. The value is fixed at `systemAvoidAreaChange`, indicating the event of changes to the area where the window cannot be displayed.| -| callback | Callback<[AvoidArea](#avoidarea)> | No | Callback used to return the area. | +| Name | Type | Mandatory| Description | +| -------- |------------------------------------------| ---- | ------------------------------------------------------- | +| type | string | Yes | Event type. The value is fixed at `systemAvoidAreaChange`, indicating the event of changes to the area where the window cannot be displayed.| +| callback | Callback<[AvoidArea](#avoidarea)> | No | Callback used to return the area. | **Example** @@ -1658,7 +1659,7 @@ Sets the background color for this window. This API uses an asynchronous callbac | Name | Type | Mandatory| Description | | -------- | ------------------------- | ---- | ------------------------------------------------------------ | -| color | string | Yes | Background color to set. The value is a hexadecimal color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| +| color | string | Yes | Background color to set. The value is a hexadecimal color code and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Example** @@ -1686,7 +1687,7 @@ Sets the background color for this window. This API uses a promise to return the | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------------------------------ | -| color | string | Yes | Background color to set. The value is a hexadecimal color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| +| color | string | Yes | Background color to set. The value is a hexadecimal color code and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| **Return value** @@ -1772,8 +1773,9 @@ setDimBehind(dimBehindValue: number, callback: AsyncCallback<void>): void Sets the dimness of the window that is not on top. This API uses an asynchronous callback to return the result. -> **NOTE**: This API cannot be used. - +> **NOTE** +> +> This API cannot be used. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -1802,8 +1804,9 @@ setDimBehind(dimBehindValue: number): Promise<void> Sets the dimness of the window that is not on top. This API uses a promise to return the result. -> **NOTE**: This API cannot be used. - +> **NOTE** +> +> This API cannot be used. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -1956,8 +1959,9 @@ setOutsideTouchable(touchable: boolean, callback: AsyncCallback<void>): vo Sets whether the area outside the subwindow is touchable. This API uses an asynchronous callback to return the result. -> **NOTE**: This API cannot be used. - +> **NOTE** +> +> This API cannot be used. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -1986,8 +1990,9 @@ setOutsideTouchable(touchable: boolean): Promise<void> Sets whether the area outside the subwindow is touchable. This API uses a promise to return the result. -> **NOTE**: This API cannot be used. - +> **NOTE** +> +> This API cannot be used. **System capability**: SystemCapability.WindowManager.WindowManager.Core diff --git a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001250678457.gif b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001250678457.gif index 6b44b6a2adc2528e13e95bc10d2a67874226a63b..96afd9a948c90e22cd52ab4c55218bf97591b3ec 100644 Binary files a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001250678457.gif and b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001250678457.gif differ diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-image.md b/en/application-dev/reference/arkui-ts/ts-basic-components-image.md index 3286784c4ce66c860be6ba6b2e824048d769b4a1..cf29ae5aa813734fdcbf648860938784f40646c6 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-image.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-image.md @@ -35,33 +35,27 @@ Obtains an image from the specified source for subsequent rendering and display. **Parameters** -| Name| Type | Mandatory| Default Value| Description | -| ------ | ------------------------------------------------------------ | ---- | ------ | ------------------------------------------------------------ | -| src | string \| [PixelMap](../apis/js-apis-image.md#pixelmap7) \| [Resource](../../ui/ts-types.md) | Yes | - | Image source. Both local and online images are supported.
When using resources referenced using a relative path, for example, `Image("common/test.jpg")`, the **\** component cannot be called across bundles or modules. Therefore, you are advised to use `$r` to reference image resources that need to be used globally.
\- The following image formats are supported: PNG, JPG, BMP, SVG, GIF.
\- Base64 strings are supported. The value format is `data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data]`, where `[base64 data]` is a Base64 string.
\- The value can also be a path starting with `dataability://`, which is used to access the image path provided by a Data ability. | +| Name | Type | Mandatory | Default Value | Description | +| ---- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | +| src | string \| [PixelMap](../apis/js-apis-image.md#pixelmap7) \| [Resource](/ts-types.md#resource-type) | Yes | - | Image source. Both local and online images are supported.
When using resources referenced using a relative path, for example, `Image("common/test.jpg")`, the **\** component cannot be called across bundles or modules. Therefore, you are advised to use `$r` to reference image resources that need to be used globally.
- The following image formats are supported: PNG, JPG, BMP, SVG, GIF.
\- Base64 strings are supported. \ The value format is `data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data]`, where `[base64 data]` is a Base64 string.
\- The value can also be a path starting with `dataability://`, which is used to access the image path provided by a Data ability.| ## Attributes In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. -| Name | Type | Default Value | Description | -| --------------------- | ---------------------------------------- | ------------------------ | ---------------------------------------- | -| alt | string \| [Resource](../../ui/ts-types.md) | - | Placeholder image displayed during loading. Both local and Internet URIs are supported. | -| objectFit | ImageFit | Cover | Image scale type. | -| objectRepeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | NoRepeat | Whether the image is repeated.
**NOTE**
This attribute is not applicable to SVG images. | -| interpolation | ImageInterpolation | None | Interpolation effect of the image. This attribute is valid only when the image is zoomed in.
**NOTE**
This attribute is not applicable to SVG images or **PixelMap** objects. | -| renderMode | ImageRenderMode | Original | Rendering mode of the image.
**NOTE**
This attribute is not applicable to SVG images. | +| Name | Type | Default Value | Description | +| --------------------- | ------------------------------------------------------- | ------------------------ | ------------------------------------------------------------ | +| alt | string \| [Resource](ts-types.md#resource-type) | - | Placeholder image displayed during loading. Both local and Internet URIs are supported. | +| objectFit | [ImageFit](ts-appendix-enums.md#imagefit) | Cover | Image scale type. | +| objectRepeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | NoRepeat | Whether the image is repeated.
**NOTE**
This attribute is not applicable to SVG images. | +| interpolation | ImageInterpolation | None | Interpolation effect of the image. This attribute is intended to alleviate aliasing that occurs when a low-definition image is zoomed in.
**NOTE**
> This attribute is not applicable to SVG images.
> This attribute is not applicable to **PixelMap** objects. | +| renderMode | ImageRenderMode | Original | Rendering mode of the image.
**NOTE**
This attribute is not applicable to SVG images. | | sourceSize | {
width: number,
height: number
} | - | Decoding size of the image. The original image is decoded into an image of the specified size, in px.
**NOTE**
This attribute is not applicable to **PixelMap** objects. | -| syncLoad8+ | boolean | false | Whether to load images synchronously. By default, images are loaded asynchronously. During synchronous loading, the UI thread is blocked and the placeholder diagram is not displayed. | - -## ImageFit - -| Name | Description | -| --------- | -------------------------------- | -| Cover | The image is scaled with its aspect ratio retained for both sides to be greater than or equal to the display boundaries. | -| Contain | The image is scaled with its aspect ratio retained for the content to be completely displayed within the display boundaries. | -| Fill | The image is scaled to fill the display area, and its aspect ratio is not retained. | -| None | The image is displayed in its original size. Generally, this enum is used together with the **objectRepeat** attribute.| -| ScaleDown | The image is displayed with its aspect ratio retained, in a size smaller than or equal to the original size. | +| matchTextDirection | boolean | false | Whether to display the image in the system language direction. When this parameter is set to true, the image is horizontally flipped in the right-to-left (RTL) language context.| +| fitOriginalSize | boolean | true | Whether to fit the component to the original size of the image source when the component size is not set.| +| fillColor | [ResourceColor](ts-types.md#resourcecolor8) | - | Fill color. This parameter is valid only for SVG images. Once set, the fill color will replace that of the SVG image.| +| autoResize | boolean | true | Whether to resize the image source used for drawing based on the size of the display area during image decoding. This resizing can help reduce the memory usage.| +| syncLoad8+ | boolean | false | Whether to load images synchronously. By default, images are loaded asynchronously. During synchronous loading, the UI thread is blocked and the placeholder diagram is not displayed. | ## ImageInterpolation @@ -82,11 +76,11 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the ## Events -| Name | Description | -| ---------------------------------------- | ---------------------------------------- | -| onComplete(callback: (event?: { width: number, height: number, componentWidth: number,
componentHeight: number, loadingStatus: number }) => void) | Triggered when an image is successfully loaded. The size of the loaded image is returned.
- **width**: width of the image, in pixels.
- **height**: height of the image, in pixels.
- **componentWidth**: width of the container component, in pixels.
- **componentHeight**: height of the container component, in pixels.
- **loadingStatus**: image loading status.
| -| onError(callback: (event?: { componentWidth: number, componentHeight: number }) => void) | Triggered when an exception occurs during image loading.
- **componentWidth**: width of the container component, in pixels.
- **componentHeight**: height of the container component, in pixels.
| -| onFinish(event: () => void) | Triggered when the animation playback in the loaded SVG image is complete. If the animation is an infinite loop, this callback is not triggered.| +| Name | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| onComplete(callback: (event?: { width: number, height: number, componentWidth: number,
componentHeight: number, loadingStatus: number }) => void) | Triggered when an image is successfully loaded. The size of the loaded image is returned.
- **width**: width of the image, in pixels.
- **height**: height of the image, in pixels.
- **componentWidth**: width of the container component, in pixels.
- **componentHeight**: height of the container component, in pixels.
- **loadingStatus**: image loading status. | +| onError(callback: (event?: { componentWidth: number, componentHeight: number }) => void) | Triggered when an exception occurs during image loading.
- **componentWidth**: width of the container component, in pixels.
- **componentHeight**: height of the container component, in pixels. | +| onFinish(event: () => void) | Triggered when the animation playback in the loaded SVG image is complete. If the animation is an infinite loop, this callback is not triggered. | ## Example @@ -179,12 +173,12 @@ struct ImageExample2 { .border({ width: 1 }).borderStyle(BorderStyle.Dashed) .overlay('Template', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) } - + Text('alt').fontSize(12).fontColor(0xcccccc).width('96%').height(30) Image('') .alt($r('app.media.Image_none')) .width(100).height(100).border({ width: 1 }).borderStyle(BorderStyle.Dashed) - + Text('sourceSize').fontSize(12).fontColor(0xcccccc).width('96%') Row({ space: 50 }) { Image($r('app.media.img_example')) @@ -204,7 +198,7 @@ struct ImageExample2 { .border({ width: 1 }).borderStyle(BorderStyle.Dashed) .overlay('w:200 h:200', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) } - + Text('objectRepeat').fontSize(12).fontColor(0xcccccc).width('96%').height(30) Row({ space: 5 }) { Image($r('app.media.ic_health_heart')) diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-richtext.md b/en/application-dev/reference/arkui-ts/ts-basic-components-richtext.md index d5d79e4e4fbc004715cac5dd92fce24f5a7f9b6d..f2f11f2a9e9aa56cdcdc8cecca1895144c1dd27c 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-richtext.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-richtext.md @@ -1,55 +1,58 @@ # RichText -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** -> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. - The **\** component parses and displays HTML text. +> **NOTE** +> +> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. + ## Required Permissions None ## Child Components -None +Not supported ## APIs -RichText\(content:string\) +RichText(content:string) -- Parameters +**Parameters** - | Name| Type| Mandatory| Default Value| Description| - | -------- | -------- | -------- | -------- | -------- | - | content | string | Yes| - | String in HTML format.| +| Name| Type | Mandatory | Default Value | Description | +| -------- | -------- | -------- | -------- | -------- | +| content | string | Yes| - | Text string in HTML format. | ## Events -| Name| Description| +| Name | Description| | -------- | -------- | -| onStart() => void | Triggered when web page loading starts.| -| onComplete() => void | Triggered when web page loading is completed.| +| onStart(callback: () => void) => void | Triggered when web page loading starts. | +| onComplete(callback: () => void) => void | Triggered when web page loading is completed. | ## Supported Tags -| Name| Description| Example| +| Name | Description | Example | | -------- | -------- | -------- | -| \

--\

| Defines six levels of headings in the HTML document. \

defines the most important heading, and \

defines the least important heading.| \

This is an H1 heading\

\

This is an H2 heading\

| -| \

\

| Defines a paragraph.| \

This is a paragraph\

| -| \
| Inserts a newline character.| \

This is a paragraph\
This is a new paragraph\

| -| \
| Defines a thematic break (such as a shift of topic) on an HTML page and creates a horizontal line.| \

This is a paragraph\

\
\

This is a paragraph\

| -| \
\
| Defines a generic container that is generally used to group block-level elements. It allows you to apply CSS styles to multiple elements at the same time.| \
\

This is the heading in a div element\

\
| -| \\ | Displays text in italic style.| \This is in italic style\ | -| \\ | Defines text that should be styled differently or have a non-textual annotation, such as misspelt words or a proper name in Chinese text. It is recommended that you avoid using the \ tag where it could be confused with a hyperlink.| \

\This is an underlined paragraph\\

| -| \ | Used to embed CSS within an HTML document.| \ | -| style | Defines the inline style of an element and is placed inside the tag. Use quotation marks (') to separate the styling text and use semicolons (;) to separate styles, for example, **style='width: 500px;height: 500px;border: 1px solid;margin: 0 auto;'**.| \

This is a heading\

\

This is a paragraph\

| -| \ | Used to embed or reference a client-side script, such as JavaScript.| \ | +| \

--\

| Defines six levels of headings in the HTML document. \

defines the most important heading, and \

defines the least important heading. | \

This is an H1 heading\

\

This is an H2 heading\

| +| \

\

| Defines a paragraph. | \

This is a paragraph\

| +| \
| Inserts a newline character. | \

This is a paragraph\
This is a new paragraph\

| +| \
| Defines a thematic break (such as a shift of topic) on an HTML page and creates a horizontal line. | \

This is a paragraph\

\
\

This is a paragraph\

| +| \
\
| Defines a generic container that is generally used to group block-level elements. It allows you to apply CSS styles to multiple elements at the same time. | \
\

This is the heading in a div element\

\
| +| \\ | Displays text in italic style. | \This is in italic style\ | +| \\ | Defines text that should be styled differently or have a non-textual annotation, such as misspelt words or a proper name in Chinese text. It is recommended that you avoid using the \ tag where it could be confused with a hyperlink. | \

\This is an underlined paragraph\\

| +| \ | Used to embed CSS within an HTML document. | \ | +| style | Defines the inline style of an element and is placed inside the tag. Use quotation marks (') to separate the styling text and use semicolons (;) to separate styles, for example, **style='width: 500px;height: 500px;border: 1px solid;margin: 0 auto;'**. | \

This is a heading\

\

This is a paragraph\

| +| \ | Used to embed or reference a client-side script, such as JavaScript. | \ | ## Example -``` +You can preview how this component looks on a real device. The preview is not yet available in the DevEco Studio Previewer. +```ts +// xxx.ets @Entry @Component struct RichTextExample { diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-search.md b/en/application-dev/reference/arkui-ts/ts-basic-components-search.md index 386f5aa23c7467f88e77d0c34647f2467af903b3..51598a90f72944e959ab2d9b836933c18356cc08 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-search.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-search.md @@ -1,11 +1,11 @@ # Search +The **\** component provides an input area for users to search. + > **NOTE** > > This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. -The **\** component provides an input area for users to search. - ## Required Permissions None @@ -18,34 +18,34 @@ Not supported Search(options?: { value?: string; placeholder?: string; icon?: string; controller?: SearchController }) -- Parameters +**Parameters** - | Name | Type | Mandatory | Default Value | Description | - | -------- | -------- | -------- | -------- | -------- | - | value | string | No| - | Text input in the search text box. | - | placeholder | string | No | - | Text displayed when there is no input. | - | icon | string | No| - | Path to the search icon. By default, the system search icon is used. The supported icon formats are .svg, .jpg, and .png. | - | controller | SearchController | No| - | Controller. | +| Name | Type | Mandatory | Default Value | Description | +| ----------- | ---------------- | ---- | ---- | ---------------------------------------- | +| value | string | No | - | Text input in the search text box. | +| placeholder | string | No | - | Text displayed when there is no input. | +| icon | string | No | - | Path to the search icon. By default, the system search icon is used. The supported icon formats are .svg, .jpg, and .png.| +| controller | SearchController | No | - | Controller. | ## Attributes -| Name | Type | Default Value | Description | -| -------- | -------- | -------- | -------- | -| searchButton | string | –| Text on the search button located next to the search text box. By default, there is no search button. | -| placeholderColor | [ResourceColor](../../ui/ts-types.md) | - | Placeholder text color. | -| placeholderFont | [Font](../../ui/ts-types.md) | - | Placeholder text style. | -| textFont | [Font](../../ui/ts-types.md) | - | Text font for the search text box. | +| Name | Type | Default Value | Description | +| ----------------------- | ---------------------------------------- | ---- | --------------------- | +| searchButton | string | – | Text on the search button located next to the search text box. By default, there is no search button.| +| placeholderColor | [ResourceColor](ts-types.md#resourcecolor8) | - | Placeholder text color. | +| placeholderFont | [Font](ts-types.md#font) | - | Placeholder text style. | +| textFont | [Font](ts-types.md#font) | - | Text font for the search text box. | ## Events -| Name | Description | -| -------- | -------- | -| onSubmit(callback: (value: string) => void) | Triggered when users click the search icon or the search button, or tap the search button on a soft keyboard.
- **value**: current text input. | -| onChange(callback: (value: string) => void) | Triggered when the input in the text box changes.
- **value**: current text input. | -| onCopy(callback: (value: string) => void) | Triggered when data is copied to the pasteboard.
- **value**: text copied. | -| onCut(callback: (value: string) => void) | Triggered when data is cut from the pasteboard.
- **value**: text cut. | -| onPaste(callback: (value: string) => void) | Triggered when data is pasted from the pasteboard.
- **value**: text pasted. | +| Name | Description | +| ---------------------------------------- | ---------------------------------------- | +| onSubmit(callback: (value: string) => void) | Triggered when users click the search icon or the search button, or touch the search button on a soft keyboard.
-**value**: current text input.| +| onChange(callback: (value: string) => void) | Triggered when the input in the text box changes.
-**value**: current text input. | +| onCopy(callback: (value: string) => void) | Triggered when data is copied to the pasteboard.
-**value**: text copied. | +| onCut(callback: (value: string) => void) | Triggered when data is cut from the pasteboard.
-**value**: text cut. | +| onPaste(callback: (value: string) => void) | Triggered when data is pasted from the pasteboard.
-**value**: text pasted. | ## SearchController @@ -61,11 +61,11 @@ caretPosition(value: number): void Sets the position of the caret. -- Parameters +**Parameters** - | Name | Type | Mandatory | Default Value | Description | - | ---- | ------ | ---- | ---- | --------------------- | - | value | number | Yes | - | Length from the start of the text string to the position where the caret is located. | +| Name | Type | Mandatory | Default Value | Description | +| ----- | ------ | ---- | ---- | ----------------- | +| value | number | Yes | - | Length from the start of the character string to the position where the caret is located.| @@ -76,29 +76,30 @@ Sets the position of the caret. @Entry @Component struct SearchExample { - @State changevalue: string = '' - @State submitvalue: string = '' + @State changeValue: string = '' + @State submitValue: string = '' controller: SearchController = new SearchController() build() { Flex({ direction: FlexDirection.Row, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { - Text(this.submitvalue) - Text(this.changevalue) - Search({value: '', placeholder: 'Type to search', controller: this.controller}) + Text(this.submitValue) + Text(this.changeValue) + Search({value: this.changeValue, placeholder: 'Type to search', controller: this.controller}) .searchButton('Search') .width(400) .height(35) .backgroundColor(Color.White) .placeholderColor(Color.Grey) - .placeholderFont({ size: 50, weight: 10, family: 'serif', style: FontStyle.Normal }) + .placeholderFont({ size: 26, weight: 10, family: 'serif', style: FontStyle.Normal }) .onSubmit((value: string) => { - this.submitvalue = value + this.submitValue = value }) .onChange((value: string) => { - this.changevalue = value + this.changeValue = value }) - .margin({ top: 30 }) + .margin({ top: 30, left:10, right:10 }) } } } ``` +![search](figures/search.png) diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-xcomponent.md b/en/application-dev/reference/arkui-ts/ts-basic-components-xcomponent.md index 3a90aab90084be24746bba23aa9b224b15b2b99f..6e66b0cf9bfd93562d37462ccbd9c21ba427e2cd 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-xcomponent.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-xcomponent.md @@ -1,9 +1,10 @@ # XComponent - > **NOTE**
+ > **NOTE** + > > This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. - The **\** can accept and display the EGL/OpenGLES and media data input. +The **\** can accept and display the EGL/OpenGL ES and media data input. ## Required Permissions @@ -15,24 +16,36 @@ ## APIs - XComponent\(value: {id: string, type: string, libraryname?: string, controller?: XComponentController}\) +XComponent\(value: {id: string, type: string, libraryname?: string, controller?: XComponentController}\) - - Name - - | Name | Type | Mandatory | Description | - | ----------- | --------------------------------------- | --------- | ------------------------------------------------------------ | - | id | string | Yes | Unique ID of the component. The value can contain a maximum of 128 characters. | - | type | string | Yes | Type of the component. The options are as follows:
- **surface**: The content of this component is displayed individually, without being combined with that of other components.
- **component**: The content of this component is displayed after having been combined with that of other components. | - | libraryname | string | No | Name of the dynamic library generated after compilation at the application native layer. | - | controller | [XComponentController](#XComponentController) | No | Controller bound to the component, which can be used to invoke methods of the component. | +**Parameters** +| Name | Type | Mandatory | Description | +| --------- | ------ | ---- | ----- | +| id | string | Yes | Unique ID of the component. The value can contain a maximum of 128 characters.| +| type | string | Yes | Type of the component. The options are as follows:
- **surface**: The content of this component is displayed individually, without being combined with that of other components.
- **component**: The content of this component is displayed after having been combined with that of other components.| +| libraryname | string | No | Name of the dynamic library generated after compilation at the application native layer.| +| controller | [XComponentcontroller](#xcomponentcontroller) | No | Controller bound to the component, which can be used to invoke methods of the component.| ## Events -| Name | Description | -| ------------------------------- | ------------------------ | -| onLoad(context?: object) => void | Triggered when the plug-in is loaded. | -| onDestroy() => void | Triggered when the plug-in is destroyed. | +### onLoad + +onLoad(callback: (event?: object) => void ) + +Triggered when the plug-in is loaded. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------------- | ------ | ---- | ----------------------- | +| event | object | No | Context of the **\** object. The APIs contained in the context are defined at the C++ layer by developers.| + +### onDestroy + +onDestroy(event: () => void ) + +Triggered when the plug-in is destroyed. ## XComponentController @@ -50,11 +63,13 @@ getXComponentSurfaceId(): string Obtains the ID of the surface held by the **\**. The ID can be used for @ohos interfaces, such as camera-related interfaces. - - Return value +**System API**: This is a system API. + +**Return value** - | Type | Description | - | ------ | --------------------------- | - | string | ID of the surface held by the **\**. | +| Type | Description | +| ------ | ----------------------- | +| string | ID of the surface held by the **\**.| ### setXComponentSurfaceSize @@ -62,12 +77,14 @@ setXComponentSurfaceSize(value: {surfaceWidth: number, surfaceHeight: number}): Sets the width and height of the surface held by the **\**. -- Parameters +**System API**: This is a system API. - | Name | Type | Mandatory | Default Value | Description | - | ------------- | -------- | ---- | ------ | ----------------------------- | - | surfaceWidth | number | Yes | - | Width of the surface held by the **\**. | - | surfaceHeight | number | Yes | - | Height of the surface held by the **\**. | +**Parameters** + +| Name | Type | Mandatory | Description | +| ------------- | ------ | ---- | ----------------------- | +| surfaceWidth | number | Yes | Width of the surface held by the **\**.| +| surfaceHeight | number | Yes | Height of the surface held by the **\**.| ### getXComponentContext @@ -75,16 +92,18 @@ getXComponentContext(): Object Obtains the context of an **\** object. -- Return value +**Return value** - | Type | Description | - | ------ | ------------------------------------------------------------ | - | Object | Context of an **\** object. The APIs contained in the context are defined by developers. | +| Type | Description | +| ------ | ---------------------------------------- | +| Object | Context of the **\** object. The APIs contained in the context are defined by developers.| ## Example Provide a surface-type **\** to support capabilities such as camera preview. +You can preview how this component looks on a real device. The preview is not yet available in the DevEco Studio Previewer. + ```ts // xxx.ets import camera from '@ohos.multimedia.camera'; diff --git a/en/application-dev/reference/arkui-ts/ts-container-swiper.md b/en/application-dev/reference/arkui-ts/ts-container-swiper.md index 161e30cef3b73797b6e14be707306f38eb80b175..b744026aba94054602fae5d4387aa24da4a6240d 100644 --- a/en/application-dev/reference/arkui-ts/ts-container-swiper.md +++ b/en/application-dev/reference/arkui-ts/ts-container-swiper.md @@ -33,23 +33,23 @@ Swiper(value:{controller?: SwiperController}) [Menu control](ts-universal-attributes-menu.md) is not supported. -| Name | Type | Description | -| --------------------------- | ---------------------------------------- | ---------------------------------------- | -| index | number | Index of the child component currently displayed in the container.
Default value: **0** | -| autoPlay | boolean | Whether to enable automatic playback for child component switching. If this attribute is **true**, the navigation dots indicator does not take effect.
Default value: **false** | -| interval | number | Interval for automatic playback, in ms.
Default value: **3000** | -| indicator | boolean | Whether to enable the navigation dots indicator.
Default value: **true** | -| loop | boolean | Whether to enable loop playback.
The value **true** means to enable loop playback. When LazyForEach is used, it is recommended that the number of the components to load exceed 5.
Default value: **true**| -| duration | number | Duration of the animation for switching child components, in ms.
Default value: **400** | -| vertical | boolean | Whether vertical swiping is used.
Default value: **false** | -| itemSpace | Length | Space between child components.
Default value: **0** | -| displayMode | SwiperDisplayMode | Mode in which elements are displayed along the main axis. This attribute takes effect only when **displayCount** is not set.
Default value: **SwiperDisplayMode.Stretch**| -| cachedCount8+ | number | Number of child components to be cached.
Default value: **1** | -| disableSwipe8+ | boolean | Whether to disable the swipe feature.
Default value: **false** | -| curve8+ | [Curve](ts-animatorproperty.md#Curve) \| string | Animation curve. The ease-in/ease-out curve is used by default. For details about common curves, see [Curve enums](ts-animatorproperty.md#curve-enums). You can also create custom curves ([interpolation curve objects](ts-interpolation-calculation.md)) by using the API provided by the interpolation calculation module.
Default value: **Curve.Ease**| -| indicatorStyle8+ | {
left?: Length,
top?: Length,
right?: Length,
bottom?: Length,
size?: Length,
color?: Color,
selectedColor?: Color
} | Style of the navigation dots indicator.
- **left**: distance between the navigation dots indicator and the left edge of the **\** component.
- **top**: distance between the navigation dots indicator and the top edge of the **\** component.
- **right**: distance between the navigation dots indicator and the right edge of the **\** component.
- **bottom**: distance between the navigation dots indicator and the bottom edge of the **\** component.
- **size**: diameter of the navigation dots indicator.
- **color**: color of the navigation dots indicator.
- **selectedColor**: color of the selected navigation dot.| -| displayCount8+ | number\|string | Number of elements to display.
Default value: **1** | -| effectMode8+ | EdgeEffect | Swipe effect. For details, see **EdgeEffect**.
Default value: **EdgeEffect.Spring**| +| Name | Type | Default Value | Description | +| --------------------------- | ---------------------------------------- | ---------------------------------------- | ---------------------------------------- | +| index | number | 0 | Index of the child component currently displayed in the container. | +| autoPlay | boolean | false | Whether to enable automatic playback for child component switching. If this attribute is **true**, the navigation dots indicator does not take effect. | +| interval | number | 3000 | Interval for automatic playback, in ms. | +| indicator | boolean | true | Whether to enable the navigation dots indicator. | +| loop | boolean | true | Whether to enable loop playback.
The value **true** means to enable loop playback. When LazyForEach is used, it is recommended that the number of the components to load exceed 5. | +| duration | number | 400 | Duration of the animation for switching child components, in ms. | +| vertical | boolean | false | Whether vertical swiping is used. | +| itemSpace | number \| string | 0 | Space between child components. | +| displayMode | SwiperDisplayMode | SwiperDisplayMode.Stretch | Mode in which elements are displayed along the main axis. This attribute takes effect only when **displayCount** is not set. | +| cachedCount8+ | number | 1 | Number of child components to be cached. | +| disableSwipe8+ | boolean | false | Whether to disable the swipe feature. | +| displayCount8+ | number \| string | 1 | Number of elements to display. | +| effectMode8+ | EdgeEffect | EdgeEffect.Spring | Swipe effect. For details, see **EdgeEffect**. | +| curve8+ | [Curve](ts-appendix-enums.md#curve) \| string | Curve.Ease | Animation curve. The ease-in/ease-out curve is used by default. For details about common curves, see [Curve](ts-appendix-enums.md#curve). You can also create custom curves ([interpolation curve objects](ts-interpolation-calculation.md)) by using the API provided by the interpolation calculation module. | +| indicatorStyle8+ | {
left?: [Length](ts-types.md#length),
top?: [Length](ts-types.md#length),
right?: [Length](ts-types.md#length),
bottom?: [Length](ts-types.md#length),
size?: [Length](ts-types.md#length),
mask?: boolean,
color?: [ResourceColor](ts-types.md#resourcecolor8),
selectedColor?: [ResourceColor](ts-types.md#resourcecolor8)
} | - | Style of the navigation dots indicator.
- **left**: distance between the navigation dots indicator and the left edge of the **\** component.
- **top**: distance between the navigation dots indicator and the top edge of the **\** component.
- **right**: distance between the navigation dots indicator and the right edge of the **\** component.
- **bottom**: distance between the navigation dots indicator and the bottom edge of the **\** component.
- **size**: diameter of the navigation dots indicator.
- **color**: color of the navigation dots indicator.
- **selectedColor**: color of the selected navigation dot.| ## SwiperDisplayMode @@ -98,7 +98,7 @@ Stops this animation. ### onChange -onChange( index: number) => void +onChange( index: number) => void Triggered when the index of the currently displayed component changes. diff --git a/en/application-dev/reference/arkui-ts/ts-universal-attributes-component-id.md b/en/application-dev/reference/arkui-ts/ts-universal-attributes-component-id.md index 43907b4096dc2a0eb3c524b33a489bfd8eed1689..e39d1458fbab496546f189571ab6f9f3cb3d624c 100644 --- a/en/application-dev/reference/arkui-ts/ts-universal-attributes-component-id.md +++ b/en/application-dev/reference/arkui-ts/ts-universal-attributes-component-id.md @@ -4,8 +4,7 @@ > **NOTE** > -> - The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. -> - The APIs provided by this module are system APIs. +> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. ## Required Permissions @@ -27,7 +26,7 @@ None getInspectorByKey(id: string): string -Obtains all attributes of the component with the specified ID, excluding the information about child components. +Obtains all attributes of the component with the specified ID, excluding the information about child components. This is a system API. - Parameters | Name | Type | Mandatory | Default Value | Description | @@ -43,7 +42,7 @@ Obtains all attributes of the component with the specified ID, excluding the inf getInspectorTree(): string -Obtains the component tree and component attributes. +Obtains the component tree and component attributes. This is a system API. - Return value @@ -55,7 +54,7 @@ Obtains the component tree and component attributes. sendEventByKey(id: string, action: number, params: string): boolean -Sends an event to the component with the specified ID. +Sends an event to the component with the specified ID. This is a system API. - Parameters | Name | Type | Mandatory | Default Value | Description | @@ -73,7 +72,7 @@ Sends an event to the component with the specified ID. sendTouchEvent(event: TouchObject): boolean -Sends a touch event. +Sends a touch event. This is a system API. - Parameters @@ -91,7 +90,7 @@ Sends a touch event. sendKeyEvent(event: KeyEvent): boolean -Sends a key event. +Sends a key event. This is a system API. - Parameters @@ -109,7 +108,7 @@ Sends a key event. sendMouseEvent(event: MouseEvent): boolean -Sends a mouse event. +Sends a mouse event. This is a system API. - Parameters diff --git a/en/application-dev/reference/arkui-ts/ts-universal-attributes-image-effect.md b/en/application-dev/reference/arkui-ts/ts-universal-attributes-image-effect.md index 5efa02368bf4eb70bca06a7e6a71473853692571..0bebd949e8f8e05dc992f0d78e1d52a8c3745ad9 100644 --- a/en/application-dev/reference/arkui-ts/ts-universal-attributes-image-effect.md +++ b/en/application-dev/reference/arkui-ts/ts-universal-attributes-image-effect.md @@ -1,7 +1,9 @@ -# Image Effect Configuration +# Image Effects +Image effects include background blur, content blur, grayscale, and much more. > **NOTE** +> > This attribute is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. @@ -15,28 +17,30 @@ None | Name | Type | Default Value | Description | | -------- | -------- | -------- | -------- | -| blur | number | - | Adds the content blurring for the current component. The input parameter is the blur radius. The larger the radius is, the more blurred the content is. If the value is **0**, the content is not blurred. | -| backdropBlur | number | - | Adds the background blur effect for the current component. The input parameter is the blur radius. The larger the radius is, the more blurred the background is. If the value is **0**, the background is not blurred. | -| shadow | {
radius: number,
color?: Color,
offsetX?: number,
offsetY?: number
} | - | Adds the shadow effect to the current component. The input parameters are the fuzzy radius (mandatory), shadow color (optional; gray by default), X-axis offset (optional and 0 by default), and Y-axis offset (optional; 0 by default). The offset unit is px. | -| grayscale | number | 0.0 | The value indicates the grayscale conversion ratio. If the input value is **1.0**, the image is converted into a grayscale image. If the input value is **0.0**, the image does not change. If the input value is between **0.0** and **1.0**, the effect changes in linear mode. The unit is percentage. The unit is percentage. | +| blur | number | - | Adds the content blur effect to the current component. The input parameter is the blur radius. The larger the radius is, the more blurred the content is. If the value is **0**, the content is not blurred. | +| backdropBlur | number | - | Adds the background blur effect to the current component. The input parameter is the blur radius. The larger the radius is, the more blurred the background is. If the value is **0**, the background is not blurred. | +| shadow | {
radius: number,
color?: Color \| string \| [Resource](../../ui/ts-types.md#resource-type),
offsetX?: number,
offsetY?: number
} | - | Adds the shadow effect to the current component. The input parameters are the fuzzy radius (mandatory), shadow color (optional; gray by default), X-axis offset (optional and 0 by default), and Y-axis offset (optional; 0 by default). The offset unit is px. | +| grayscale | number | 0.0 | Converts the input image to grayscale. The value indicates the grayscale conversion ratio. If the input value is **1.0**, the image is converted into a grayscale image. If the input value is **0.0**, the image does not change. If the input value is between **0.0** and **1.0**, the effect changes in linear mode. The unit is percentage. The unit is percentage. | | brightness | number | 1.0 | Adds a brightness to the current component. The input parameter is a brightness ratio. The value **1** indicates no effects. The value **0** indicates the complete darkness. If the value is less than **1**, the brightness decreases. If the value is greater than **1**, the brightness increases. A larger value indicates a higher brightness. | | saturate | number | 1.0 | Adds the saturation effect to the current component. The saturation is the ratio of the chromatic component to the achromatic component (gray) in a color. When the input value is **1**, the source image is displayed. When the input value is greater than **1**, a higher percentage of the chromatic component indicates a higher saturation. When the input value is less than **1**, a higher percentage of the achromatic component indicates a lower saturation. The unit is percentage. | | contrast | number | 1.0 | Adds the contrast effect to the current component. The input parameter is a contrast value. If the value is **1**, the source image is displayed. If the value is greater than **1**, a larger value indicates a higher contrast and a clearer image. If the value is less than **1**, a smaller value indicates a lower contrast is. If the value is **0**, the image becomes all gray. The unit is percentage. | | invert | number | 0 | Inverts the input image. The input parameter is an image inversion ratio. The value **1** indicates complete inversion. The value **0** indicates that the image does not change. The unit is percentage. | -| colorBlend 8+ | Color | - | Adds the color blend effect to the current component. The input parameter is the blended color. | +| colorBlend8+ | Color | - | Adds the color blend effect to the current component. The input parameter is the blended color. | | sepia | number | 0 | Converts the image color to sepia. The input parameter is an image inversion ratio. The value **1** indicates the image is completely sepia. The value **0** indicates that the image does not change. The unit is percentage. | -| hueRotate | number \| string | '0deg' |Adds the hue rotation effect to the current component. The input parameter is a rotation angle. If the input value is **0deg**, the image does not change (because the default rotation angle is **0deg**). The input parameter does not have the maximum value. If the value exceeds **360deg**, the image is rotated for one more circle. In other words, the value **370deg** has the same effect as **10deg**.| +| hueRotate | number \| string | '0deg' | Adds the hue rotation effect to the current component. The input parameter is a rotation angle. If the input value is **0deg**, the image does not change (because the default rotation angle is **0deg**). The input parameter does not have the maximum value. If the value exceeds **360deg**, the image is rotated for one more circle. In other words, the value **370deg** has the same effect as **10deg**.| ## Example +You can preview how this component looks on a real device. The preview is not yet available in the DevEco Studio Previewer. -``` +```ts +// xxx.ets @Entry @Component struct ImageEffectsExample { build() { -Column({space: 10}) { + Column({space: 10}) { // Blur the font. Text('font blur').fontSize(15).fontColor(0xCCCCCC).width('90%') Text('text').blur(3).width('90%').height(40) diff --git a/en/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md b/en/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md index 9d801b2503cc4225907879d5eba7596c120db3b6..a9d6cad9cc929354c1218cfe2ea37e375c810901 100644 --- a/en/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md +++ b/en/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md @@ -1,7 +1,8 @@ # Popup Control -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> **NOTE** +> > This attribute is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. @@ -17,44 +18,34 @@ None | -------- | -------- | -------- | -------- | | bindPopup | show: boolean,
popup: PopupOptions \| CustomPopupOptions | - | Settings of the popup bound to a component.
**show**: whether to display the popup on the creation page by default. The default value is **false**.
**popup**: parameters of the current popup. | +## PopupOptions + +| Name | Type | Mandatory | Default Value | Description | +| -------- | -------- | -------- | -------- | -------- | +| message | string | Yes | - | Content of the popup message. | +| placementOnTop | boolean | No | false | Whether to display the popup above the component. The default value is **false**. | +| primaryButton | {
value: string,
action: () => void
} | No | - | First button.
**value**: text of the primary button in the popup.
**action**: callback function for clicking the primary button. | +| secondaryButton | {
value: string,
action: () => void
} | No | - | Second button.
**value**: text of the secondary button in the popup.
**action**: callback function for clicking the secondary button. | +| onStateChange | (isVisible: boolean) => void | No | - | Callback for the popup status change event.
**isVisible**: visibility of the popup. | + +## CustomPopupOptions8+ +| Name | Type | Mandatory | Default Value | Description | +| ------------- | ---------------------------------------------- | ---- | ---------------- | ------------------------------------------------------------ | +| builder | () => any | Yes | - | Builder of the tooltip content. | +| placement | [Placement](ts-appendix-enums.md) | No | Placement.Bottom | Preferred position of the tooltip component. If the set position is insufficient for holding the component, it will be automatically adjusted. | +| maskColor | [Color](ts-appendix-enums.md#color) | No | - | Color of the tooltip mask. | +| popupColor | [Color](ts-appendix-enums.md#color) | No | - | Color of the tooltip. | +| enableArrow | boolean | No | true | Whether to display arrows. Arrows are displayed only for tooltips in the up and down directions. | +| autoCancel | boolean | No | true | Whether to automatically close the tooltip when an operation is performed on the page. | +| onStateChange | (isVisible: boolean) => void | No | - | Callback for the popup status change event. The parameter **isVisible** indicates the visibility of the popup. | -- PopupOptions attributes - | Name | Type | Mandatory | Default Value | Description | - | -------- | -------- | -------- | -------- | -------- | - | message | string | Yes | - | Content of the popup message. | - | placementOnTop | boolean | No | false | Whether to display the popup above the component. The default value is **false**. | - | primaryButton | {
value: string,
action: () => void
} | No | - | First button.
**value**: text of the primary button in the popup.
**action**: callback function for clicking the primary button. | - | secondaryButton | {
value: string,
action: () => void
} | No | - | Second button.
**value**: text of the secondary button in the popup.
**action**: callback function for clicking the secondary button. | - | onStateChange | (isVisible: boolean) => void | No | - | Callback for the popup status change event. The parameter **isVisible** indicates the visibility of the popup. | - -- CustomPopupOptions8+ - | Name | Type | Mandatory | Default Value | Description | - | -------- | -------- | -------- | -------- | -------- | - | builder | () => any | Yes | - | Builder of the tooltip content. | - | placement | Placement | No | Placement.Bottom | Preferred position of the tooltip component. If the set position is insufficient for holding the component, it will be automatically adjusted. | - | maskColor | [Color](../../ui/ts-types.md) | No | - | Color of the tooltip mask. | - | popupColor | [Color](../../ui/ts-types.md) | No | - | Color of the tooltip. | - | enableArrow | boolean | No | true | Whether to display arrows. Arrows are displayed only for tooltips in the up and down directions. | - | autoCancel | boolean | No | true | Whether to automatically close the tooltip when an operation is performed on the page. | - | onStateChange | (isVisible: boolean) => void | No | - | Callback for the popup status change event. The parameter **isVisible** indicates the visibility of the popup. | - -- Placement8+ enums - | Name | Description | - | -------- | -------- | - | Left | The tooltip is on the left of the component. | - | Right | The tooltip is on the right of the component. | - | Top | The tooltip is on the top of the component. | - | Bottom | The tooltip is at the bottom of the component. | - | TopLeft | The tooltip is in the upper left corner of the component. | - | TopRight | The tooltip is in the upper right corner of the component. | - | BottomLeft | The tooltip is in the lower left corner of the component. | - | BottomRight | The tooltip is in the lower right corner of the component. | ## Example -``` +```ts +// xxx.ets @Entry @Component struct PopupExample { @@ -65,7 +56,7 @@ struct PopupExample { @Builder popupBuilder() { Row({ space: 2 }) { Image('/resource/ic_public_thumbsup.svg').width(24).height(24).margin({ left: -5 }) - Text('Custom Popup').fontSize(12) + Text('Custom Popup').fontSize(10) }.width(100).height(50).backgroundColor(Color.White) } diff --git a/en/application-dev/reference/arkui-ts/ts-universal-attributes-z-order.md b/en/application-dev/reference/arkui-ts/ts-universal-attributes-z-order.md index c18d5a4e20ca5f48ab6d5ccf368d9936c174fe0d..8504a31b188eacdd53b90bfe61d1ca1474fc2bd6 100644 --- a/en/application-dev/reference/arkui-ts/ts-universal-attributes-z-order.md +++ b/en/application-dev/reference/arkui-ts/ts-universal-attributes-z-order.md @@ -1,7 +1,9 @@ # Z-order Control +The **zIndex** attribute sets the z-order of a component in the stacking context. -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> **NOTE** +> > This attribute is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. @@ -13,15 +15,16 @@ None ## Attributes - | Name | Type | Default Value | Description | +| Name | Type | Default Value | Description | | -------- | -------- | -------- | -------- | -| zIndex | number | 0 | Hierarchy of sibling components in a container. A larger z-order value indicates a higher display level. | +| zIndex | number | 0 | Hierarchy of sibling components in a container. A larger value indicates a higher display level. | ## Example - -``` + +```ts +// xxx.ets @Entry @Component struct ZIndexExample { @@ -38,7 +41,7 @@ struct ZIndexExample { Text('third child, zIndex(1)') .size({width: '70%', height: '50%'}).backgroundColor(0xc1cbac).align(Alignment.TopStart) .zIndex(1) - } + }.width('100%').height(200) }.width('100%').height(200) } } diff --git a/en/application-dev/ui/js-framework-syntax-css.md b/en/application-dev/ui/js-framework-syntax-css.md index 1ad94016b7e7100fb77353e562f03090f4c9e1c3..46fcc170df8f4688da555b6874a6842c1c6806e8 100644 --- a/en/application-dev/ui/js-framework-syntax-css.md +++ b/en/application-dev/ui/js-framework-syntax-css.md @@ -85,11 +85,11 @@ The following is an example: ```css /* Page style xxx.css */ -/\* Set the style for all
components. \*/ +/* Set the style for all
components. */ div { flex-direction: column; } -/* Set the style for the component whose class is title. */ +/* Set the style for the component whose class is title.*/ .title { font-size: 30px; } @@ -101,13 +101,13 @@ div { .title, .content { padding: 5px; } -/\* Set the style for all texts of components whose class is container.\*/ +/* Set the style for all texts of components whose class is container.*/ .container text { color: \#007dff; } -/\* Set the style for direct descendant texts of components whose class is container.\*/ +/* Set the style for direct descendant texts of components whose class is container.*/ .container > text { - color: \#fa2a2d; + color: #fa2a2d; } ``` @@ -128,7 +128,7 @@ When multiple selectors point to the same element, their priorities are as follo A CSS pseudo-class is a keyword added to a selector that specifies a special state of the selected element(s). For example, :disabled can be used to select the element whose disabled attribute is true. -In addition to a single pseudo-class, a combination of pseudo-classes is supported. For example, **:focus:checked** selects the element whose focus and checked attributes are both set to true. The following table lists the supported single pseudo-class in descending order of priority. +In addition to a single pseudo-class, a combination of pseudo-classes is supported. For example, :focus:checked selects the element whose focus and checked attributes are both set to true. The following table lists the supported single pseudo-class in descending order of priority. | Pseudo-class | Available Components | Description | diff --git a/en/application-dev/ui/ts-application-states-appstorage.md b/en/application-dev/ui/ts-application-states-appstorage.md index ac77b40dd5c85a7494e094b8dc698715786413f8..5877f75ca55ad03cafb78eda50c0b26475f3033e 100644 --- a/en/application-dev/ui/ts-application-states-appstorage.md +++ b/en/application-dev/ui/ts-application-states-appstorage.md @@ -21,7 +21,7 @@ By default, the attributes in the AppStorage are changeable. If needed, AppStora | Set | key: string,
newValue: T | void | Replaces the value of a saved key. | | Link | key: string | @Link | Returns two-way binding to this attribute if there is data with a given key. This means that attribute changes made by a variable or component will be synchronized to the AppStorage, and attribute changes made through the AppStorage will be synchronized to the variable or component. If the attribute with this key does not exist or is read-only, undefined is returned. | | SetAndProp | propName: string,
defaultValue: S | @Prop | Works in a way similar to the Prop API. If the current key is stored in the AppStorage, the value corresponding to the key is returned. If the key has not been created, a Prop instance corresponding to the default value is created and returned. | -| Prop | key: string | @Prop | Returns one-way binding to an attribute with a given key if the attribute exists. This means that attribute changes made through the AppStorage will be synchronized to the variable or component, but attribute changes made by the variable or component will be synchronized to the AppStorage. The variable returned by this method is an immutable one, which is applicable both to the variable and immutable state attributes. If the attribute with the specified key does not exist, undefined is returned.
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**:
> The attribute value used in the prop method must be of a simple type. | +| Prop | key: string | @Prop | Returns one-way binding to an attribute with a given key if the attribute exists. This means that attribute changes made through the AppStorage will be synchronized to the variable or component, but attribute changes made by the variable or component will be synchronized to the AppStorage. The variable returned by this method is an immutable one, which is applicable both to the variable and immutable state attributes. If the attribute with the specified key does not exist, undefined is returned.
**NOTE**
The attribute value used in the prop method must be of a simple type. | | SetOrCreate | key: string,
newValue: T | boolean | If an attribute that has the same name as the specified key exists: replaces the value of the attribute and returns true when the attribute can be modified; retains the original value of the attribute and returns false otherwise.
If an attribute that has the same name as the specified key does not exist: creates an attribute whose key is key and value is newValue. The values null and undefined are not supported. | | Get | key: string | T or undefined | Obtains the value of the specified key. | | Has | propName: string | boolean | Checks whether the attribute corresponding to the specified key value exists. | @@ -51,9 +51,8 @@ One-way data binding can be established between components and the AppStorage th ## Example -``` -let varA = AppStorage.Link('varA') -let envLang = AppStorage.Prop('languageCode') +```ts +// xxx.ets @Entry @Component diff --git a/en/application-dev/ui/ts-component-based-builder.md b/en/application-dev/ui/ts-component-based-builder.md index a07b244ffdc2bd9105102058e6881b14289fdf34..d626bde6074c5e3db373a00f3a78bf6e554cf46f 100644 --- a/en/application-dev/ui/ts-component-based-builder.md +++ b/en/application-dev/ui/ts-component-based-builder.md @@ -4,16 +4,17 @@ The **@Builder** decorated method is used to define the declarative UI description of a component and quickly generate multiple layouts in a custom component. The functionality and syntax of the **@Builder** decorator are the same as those of the [build Function](ts-function-build.md). -``` +```ts +// xxx.ets @Entry @Component struct CompA { - size : number = 100; + size1 : number = 100; @Builder SquareText(label: string) { Text(label) - .width(1 * this.size) - .height(1 * this.size) + .width(1 * this.size1) + .height(1 * this.size1) } @Builder RowOfSquareTexts(label1: string, label2: string) { @@ -21,8 +22,8 @@ struct CompA { this.SquareText(label1) this.SquareText(label2) } - .width(2 * this.size) - .height(1 * this.size) + .width(2 * this.size1) + .height(1 * this.size1) } build() { @@ -32,12 +33,12 @@ struct CompA { this.SquareText("B") // or as long as tsc is used } - .width(2 * this.size) - .height(1 * this.size) + .width(2 * this.size1) + .height(1 * this.size1) this.RowOfSquareTexts("C", "D") } - .width(2 * this.size) - .height(2 * this.size) + .width(2 * this.size1) + .height(2 * this.size1) } } ``` @@ -51,7 +52,8 @@ In certain circumstances, you may need to add a specific function, such as a cli ### Component Initialization Through Parameters When initializing a custom component through parameters, assign a **@Builder** decorated method to the **@BuilderParam** decorated attribute — **content**, and call the value of **content** in the custom component. If no parameter is passed when assigning a value to the **@BuilderParam** decorated attribute (for example, `content: this.specificParam`), define the type of the attribute as a function without a return value (for example, `@BuilderParam content: () => void`). If any parameter is passed when assigning a value to the **@BuilderParam** decorated attribute (for example, `callContent: this.specificParam1("111")`), define the type of the attribute as `any` (for example,`@BuilderParam callContent: any;`). -``` +```ts +// xxx.ets @Component struct CustomContainer { header: string = ""; @@ -100,7 +102,8 @@ struct CustomContainerUser { In a custom component, use the **@BuilderParam** decorated attribute to receive a trailing closure. When the custom component is initialized, the component name is followed by a pair of braces ({}) to form a trailing closure (`CustomComponent(){}`). You can consider a trailing closure as a container and add content to it. For example, you can add a component (`{Column(){Text("content")}`) to a trailing closure. The syntax of the closure is the same as that of [build](../ui/ts-function-build.md). In this scenario, the custom component has one and only one **@BuilderParam** decorated attribute. Example: Add a **\** component and a click event to the closure, and call the **specificParam** method decorated by **@Builder** in the new **\** component. After the **\** component is clicked, the value of the component's `header` attribute will change to `changeHeader`. In addition, when the component is initialized, the content of the trailing closure will be assigned to the `closer` attribute decorated by **@BuilderParam**. -``` +```ts +// xxx.ets @Component struct CustomContainer { header: string = ""; diff --git a/en/application-dev/ui/ts-resource-access.md b/en/application-dev/ui/ts-resource-access.md index 82d53954d3fc86878a48222e449428faf1a341d1..5b4a7627f6b810bf87e457b2b0042f6b806dfc15 100644 --- a/en/application-dev/ui/ts-resource-access.md +++ b/en/application-dev/ui/ts-resource-access.md @@ -5,10 +5,13 @@ To reference an application resource in a project, use the `"$r('app.type.name')"` format. **app** indicates the resource defined in the **resources** directory of the application. **type** indicates the resource type (or the location where the resource is stored). The value can be **color**, **float**, **string**, **plural**, or **media**. **name** indicates the resource name, which you set when defining the resource. -When referencing resources in the **rawfile** sub-directory, use the `"$rawfile('filename')"` format. Currently, **$rawfile** allows only the **\** component to reference image resources. **filename** indicates the relative path of a file in the **rawfile** directory, and the file name must contain the file name extension. Note that the relative path cannot start with a slash (/). +When referencing resources in the **rawfile** sub-directory, use the ```"$rawfile('filename')"``` format. **filename** indicates the relative path of a file in the **rawfile** directory, and the file name must contain the file name extension. Note that the relative path cannot start with a slash (/). > **NOTE** +> > Resource descriptors accept only strings, such as `'app.type.name'`, and cannot be combined. +> +> `$r` returns a **Resource** object. To obtain the corresponding string, use [getString](../reference/apis/js-apis-resource-manager.md#getstring). In the **.ets** file, you can use the resources defined in the **resources** directory. @@ -47,7 +50,7 @@ Image($rawfile('newDir/newTest.png')) // Reference an image in the rawfile direc System resources include colors, rounded corners, fonts, spacing, character strings, and images. By using system resources, you can develop different applications with the same visual style. -To reference a system resource, use the "$r('sys.type.resource_id')" format. Wherein: sys indicates a system resource; type indicates the resource type, which can be color, float, string, or media; resource_id indicates the resource ID, which is determined when the system resource is provided. For details about available system resource IDs. +To reference a system resource, use the ```"$r('sys.type.resource_id')"``` format. Wherein: **sys** indicates a system resource; **type** indicates the resource type, which can be **color**, **float**, **string**, or **media**; **resource_id** indicates the resource ID. ```ts Text('Hello') diff --git a/en/application-dev/ui/ts-syntactic-sugar.md b/en/application-dev/ui/ts-syntactic-sugar.md index 78b908edf1f85a6deaa9fc37b8e7d029d977cab5..de6d2f0cdb280e9160ff3ee4aa6f4895b505fc32 100644 --- a/en/application-dev/ui/ts-syntactic-sugar.md +++ b/en/application-dev/ui/ts-syntactic-sugar.md @@ -1,32 +1,35 @@ # About Syntactic Sugar - ## Decorators -A decorator @Decorator can decorate a class, structure, or class attribute. Multiple decorators can be applied to the same target element and defined on a single line or multiple lines. It is recommended that the decorators be defined on multiple lines. -In the example below, the elements decorated by @Component take on the form of a component, and the variables decorated by @State can be used to represent states. +A decorator **@Decorator** can decorate a class, structure, or class attribute. Multiple decorators can be applied to the same target element and defined on a single line or multiple lines. It is recommended that the decorators be defined on multiple lines. -``` +In the example below, the elements decorated by **@Component** take on the form of a component, and the variables decorated by **@State** can be used to represent states. + + +```ts @Component struct MyComponent { @State count: number = 0 } ``` + Multiple decorators can be defined on a single line, as shown below: -``` +```ts @Entry @Component struct MyComponent { } ``` + However, you are advised to define the decorators on multiple lines, as shown below: -``` +```ts @Entry @Component struct MyComponent { @@ -36,30 +39,29 @@ struct MyComponent { ### Supported Decorators - | Decorator | Decorates... | Description | -| -------- | -------- | -------- | -| @Component | struct | The decorated structure has the component-based capability. The build method must be implemented to update the UI. | -| @Entry | struct | The decorated component is used as the entry of a page. The component is rendered and displayed when the page is loaded. | -| @Preview | struct | Custom components decorated by @Preview can be previewed in the Previewer of DevEco Studio. When the page is loaded, the custom components decorated by @Preview are created and displayed. | -| @Builder | Methods | In the decorated method, you can use the declarative UI description to quickly generate multiple layouts in a custom component. | -| @Extend | Methods | This decorator adds new attribute functions to a preset component, allowing you to quickly define and reuse the custom style of the component. | -| @CustomDialog | struct | This decorator is used to decorate custom pop-up dialog boxes. | -| @State | Primitive data types, classes, and arrays | If the decorated state data is modified, the build method of the component will be called to update the UI. | -| @Prop | Primitive data types | This decorator is used to establish one-way data binding between the parent and child components. When the data associated with the parent component is modified, the UI of the current component is updated. | -| @Link | Primitive data types, classes, and arrays | This decorator is used to establish two-way data binding between the parent and child components. The internal state data of the parent component is used as the data source. Any changes made to one component will be reflected to the other. | -| @Observed | Classes | This decorator is used to indicate that the data changes in the class will be managed by the UI page. | -| @ObjectLink | Objects of @Observed decorated classes | When the decorated state variable is modified, the parent and sibling components that have the state variable will be notified for UI re-rendering. | -| @Consume | Primitive data types, classes, and arrays | When the @Consume decorated variable detects the update of the @Provide decorated variable, the re-rendering of the current custom component is triggered. | -| @Provide | Primitive data types, classes, and arrays | As the data provider, @Provide can update the data of child nodes and trigger page rendering. | -| @Watch | Variables decorated by @State, @Prop, @Link, @ObjectLink, @Provide, @Consume, @StorageProp, or @StorageLink | This decorator is used to listen for the changes of the state variables. The application can register a callback method through @Watch. | +| Decorator | Decorates... | Description | +| ------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| @Component | struct | The decorated structure has the component-based capability. The **build** method must be implemented to update the UI.| +| @Entry | struct | The decorated component is used as the entry of a page. The component is rendered and displayed when the page is loaded. | +| @Preview | struct | Custom components decorated by **@Preview** can be previewed in DevEco Studio. When the target page is loaded, the custom components decorated by **@Preview** are created and displayed.| +| @Builder | Methods | In the decorated method, you can use the declarative UI description to quickly generate multiple layouts in a custom component.| +| @Extend | Methods | This decorator adds attribute functions to a preset component, allowing you to quickly define and reuse the custom style of the component.| +| @CustomDialog | struct | This decorator is used to decorate custom pop-up dialog boxes. | +| @State | Primitive data types, classes, and arrays | If the decorated state data is modified, the **build** method of the component will be called to update the UI. | +| @Prop | Primitive data types | This decorator is used to establish one-way data binding between the parent and child components. When the data associated with the parent component is modified, the UI of the current component is updated.| +| @Link | Primitive data types, classes, and arrays | This decorator is used to establish two-way data binding between the parent and child components. The internal state data of the parent component is used as the data source. Any changes made to one component will be reflected to the other.| +| @Observed | Classes | This decorator is used to indicate that the data changes in the class will be managed by the UI page. | +| @ObjectLink | Objects of **@Observed** decorated classes | When the decorated state variable is modified, the parent and sibling components that have the state variable will be notified for UI re-rendering.| +| @Consume | Primitive data types, classes, and arrays | When the **@Consume** decorated variable detects the update of the **@Provide** decorated variable, the re-rendering of the current custom component is triggered.| +| @Provide | Primitive data types, classes, and arrays | As the data provider, **@Provide** can update the data of child nodes and trigger page rendering.| +| @Watch | Variables decorated by **@State**, **@Prop**, **@Link**, **@ObjectLink**, **@Provide**, **@Consume**, **@StorageProp**, or **@StorageLink** | This decorator is used to listen for the changes of the state variables. The application can register a callback method through **@Watch**. | ## Chain Call You can configure the UI structure and its attributes and events and separate them with a dot(.) to implement chain call. - -``` +```ts Column() { Image('1.jpg') .alt('error.jpg') @@ -71,10 +73,9 @@ Column() { ## struct -Components can be implemented based on structs. Components cannot inherit from each other. The structs implemented components can be created and destroyed more quickly than class implemented components. +Components can be implemented based on **struct**s. Components cannot inherit from each other. The **struct**s implemented components can be created and destroyed more quickly than **class** implemented components. - -``` +```ts @Component struct MyComponent { @State data: string = '' @@ -87,10 +88,9 @@ struct MyComponent { ## Instantiating a struct Without the new Keyword -You can omit the new keyword when instantiating a struct. - +You can omit the **new** keyword when instantiating a **struct**. -``` +```ts // Definition @Component struct MyComponent { @@ -98,7 +98,7 @@ struct MyComponent { } } -// Use +// Usage Column() { MyComponent() } @@ -114,23 +114,22 @@ new Column() { TypeScript has the following restrictions on generators: -- Expressions can be used only in character strings (${expression}), if conditions, ForEach parameters, and component parameters. +- Expressions can be used only in character strings (${expression}), **if** conditions, **ForEach** parameters, and component parameters. -- No expressions should cause any application state variables (@State, @Link, and @Prop) to change. Otherwise, undefined and potentially unstable framework behavior may occur. +- No expressions should cause any application state variables (**@State**, **@Link**, and **@Prop**) to change. Otherwise, undefined and potentially unstable framework behavior may occur. - The generator function cannot contain local variables. -None of the above restrictions apply to anonymous function implementations of event-handling functions (such as onClick) +None of the above restrictions apply to anonymous function implementations of event-handling functions (such as **onClick**) Incorrect: - -``` +```ts build() { let a: number = 1 // invalid: variable declaration not allowed Column() { - Text('Hello ${this.myName.toUpperCase()}') // ok. - ForEach(this.arr.reverse(), ..., ...) // invalid: Array.reverse modifies the @State array varible in place + Text(`Hello ${this.myName.toUpperCase()}`) // ok. + ForEach(this.arr.reverse(), ..., ...) // invalid: Array.reverse modifies the @State array variable in place } buildSpecial() // invalid: no function calls Text(this.calcTextValue()) // this function call is ok. @@ -139,11 +138,13 @@ build() { ## $$ -$$ supports two-way binding for simple variables and @State, @Link, and @Prop decorated variables. +**$$** supports two-way binding for simple variables and **@State**, **@Link**, and **@Prop** decorated variables. -Currently, $$ supports only the rendering between the show parameter of the bindPopup attribute and the @State decorated variable, and the checked attribute of the \ component. +Currently, **$$** supports only the rendering between the **show** parameter of the **[bindPopup](../reference/arkui-ts/ts-universal-attributes-popup.md)** attribute and the **@State** decorated variable, and the **checked** attribute of the **\** component. -``` + +```ts +// xxx.ets @Entry @Component struct bindPopup { @@ -166,3 +167,29 @@ struct bindPopup { } ``` +## Restrictions on Declaring Multiple Data Types of State Variables + +If a **@State**, **@Provide**, **@Link**, or **@Consume** decorated state variable supports multiple data types, they must be all simple data types or references at one time. + +Example: + +```ts +@Entry +@Component +struct Index { + // Incorrect: @State message: string | Resource = 'Hello World' + @State message: string = 'Hello World' + + build() { + Row() { + Column() { + Text(`${ this.message }`) + .fontSize(50) + .fontWeight(FontWeight.Bold) + } + .width('100%') + } + .height('100%') + } +} +``` diff --git a/en/application-dev/ui/ui-js-components-switch.md b/en/application-dev/ui/ui-js-components-switch.md index 4eeffd99b1bac376b5d8e6db2298ec9232003c70..23d0f4285c18022e383d8734784f5d46e56bf445 100644 --- a/en/application-dev/ui/ui-js-components-switch.md +++ b/en/application-dev/ui/ui-js-components-switch.md @@ -9,14 +9,15 @@ The **<switch>** component is used to switch between the on and off states Create a **<switch>** component in the .hml file under **pages/index**. -``` +```html +
``` -``` +```css /* xxx.css */ .container { flex-direction: column; @@ -31,9 +32,9 @@ Create a **<switch>** component in the .hml file under **pages/index**. ## Adding Attributes and Methods - Use the **textoff** and **showtext** attributes to set the status when text is selected and unselected. Set the **checked** attribute to **true** (indicating that the component is on). Add the **change** event that is triggered when the component status changes. After the event is triggered, the **switchChange** function is executed to obtain the current component status (on or off). +Use the **textoff** and **showtext** attributes to set the status when text is selected and unselected. Set the **checked** attribute to **true** (indicating that the component is on). Add the **change** event that is triggered when the component status changes. After the event is triggered, the **switchChange** function is executed to obtain the current component status (on or off). -``` +```html
@@ -41,28 +42,26 @@ Create a **<switch>** component in the .hml file under **pages/index**. ``` -``` +```css /* xxx.css */ .container { width: 100%; - height: 100%; + height: 100%; display: flex; justify-content: center; align-items: center; background-color: #F1F3F5; } -switch{ - // Color of the selected text +switch { texton-color: #002aff; - // Color of the unselected text -textoff-color: silver; + textoff-color: silver; text-padding: 20px; font-size: 50px; } ``` -``` +```js // xxx.js import prompt from '@system.prompt'; export default { @@ -84,7 +83,8 @@ export default { ![en-us_image_0000001276003505](figures/en-us_image_0000001276003505.gif) -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE:** +> **NOTE** +> > The text set by **texton** and **textoff** takes effect only when **showtext** is set to **true**. @@ -94,7 +94,7 @@ Turn on the switch and the default delivery address is used. When the switch is Implementation method: Create a **<switch>** component, set the **checked** attribute to **true**, and change the delivery address through data binding. Set the **display** attribute (the default value is **none**). When the switch is turned off and the **display** attribute is set to **flex**, the address module is displayed and clicking the button can change the color. -``` +```html
@@ -113,11 +113,11 @@ Turn on the switch and the default delivery address is used. When the switch is ``` -``` +```css /* xxx.css */ .container { width: 100%; - height: 100%; + height: 100%; background-color: #F1F3F5; flex-direction: column; padding: 50px; @@ -168,7 +168,7 @@ switch{ ``` -``` +```js // xxx.js import prompt from '@system.prompt'; export default { diff --git a/en/device-dev/driver/driver-platform-i3c-des.md b/en/device-dev/driver/driver-platform-i3c-des.md index 1108e71375a1baa49cf7e649909a392ce612d9de..0ab37dad83fa3e0e89de9419841c61c277ce123e 100644 --- a/en/device-dev/driver/driver-platform-i3c-des.md +++ b/en/device-dev/driver/driver-platform-i3c-des.md @@ -48,6 +48,7 @@ In the Hardware Driver Foundation (HDF), the I3C module uses the unified service Multiple devices, such as I2C target device, I3C target device, and I3C secondary controller, can be connected to an I3C bus. However, the I3C bus must have only one controller. **Figure 1** I3C physical connection + ![](figures/I3C_physical_connection.png "I3C_physical_connection") ### Constraints @@ -159,7 +160,7 @@ if (ret != 2) { } ``` ->![](./public_sys-resources/icon-caution.gif) **Caution**
+>![](../public_sys-resources/icon-caution.gif) **Caution**
>- The device address in the **I3cMsg** structure does not contain the read/write flag bit. The read/write information is passed by the read/write control bit in the member variable **flags**. >- The **I3cTransfer()** function does not limit the number of message structures or the length of data in each message structure. The I3C controller determines these two limits. >- Using **I3cTransfer()** may cause the system to sleep. Do not call it in the interrupt context. diff --git a/en/device-dev/driver/driver-platform-rtc-develop.md b/en/device-dev/driver/driver-platform-rtc-develop.md index 83a9679c40c0821d96a52be191e65813a0873708..4e7fd05b2e7faf90ab643daa9aa5e60733045f35 100644 --- a/en/device-dev/driver/driver-platform-rtc-develop.md +++ b/en/device-dev/driver/driver-platform-rtc-develop.md @@ -63,7 +63,7 @@ The RTC module adaptation involves the following steps: 3. Instantiate the RTC controller object. - Initialize **RtcHost**. - Instantiate **RtcMethod** in the **RtcHost** object. - > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+ > ![icon-note.gif](../public_sys-resources/icon-note.gif) **NOTE**
> For details about the functions in **RtcMethod**, see [Available APIs](#available-apis). 4. Debug the driver. diff --git a/en/device-dev/driver/driver-platform-uart-des.md b/en/device-dev/driver/driver-platform-uart-des.md index 20340bfd49d68136a9ca711cca35ca5c2cdb0834..3ddb92b532569df4718931c9c3ca32b7e7e010c1 100644 --- a/en/device-dev/driver/driver-platform-uart-des.md +++ b/en/device-dev/driver/driver-platform-uart-des.md @@ -1,156 +1,86 @@ -# UART +# UART -## Overview -The Universal Asynchronous Receiver/Transmitter \(UART\) is a universal serial data bus used for asynchronous communication. It enables bi-directional communication between devices in full-duplex mode. +## Overview + +The Universal Asynchronous Receiver/Transmitter (UART) is a universal serial data bus used for asynchronous communication. It enables bi-directional communication between devices in full-duplex mode. + UART is widely used to print information for debugging or to connect to various external modules such as GPS and Bluetooth. -A UART is connected to other modules through two wires \(as shown in [Figure 1](#fig68294715408)\) or four wires \(as shown in [Figure 2](#fig179241542163112)\). -- TX: TX pin of the transmitting UART. It is connected to the RX pin of the peer UART. -- RX: RX pin of the receiving UART. It is connected to the TX pin of the peer UART. -- RTS: Request to Send signal pin. It is connected to the CTS pin of the peer UART and is used to indicate whether the local UART is ready to receive data. -- CTS: Clear to Send signal pin. It is connected to the RTS pin of the peer UART and is used to indicate whether the local UART is allowed to send data to the peer end. - - **Figure 1** 2-wire UART communication - ![](figures/2-wire-uart-communication.png "2-wire-uart-communication") - - **Figure 2** 4-wire UART communication - ![](figures/4-wire-uart-communication.png "4-wire-uart-communication") - - -The transmitting and receiving UARTs must ensure that they have the same settings on particular attributes such as the baud rate and data format \(start bit, data bit, parity bit, and stop bit\) before they start to communicate. During data transmission, a UART sends data to the peer end over the TX pin and receives data from the peer end over the RX pin. When the size of the buffer used by a UART for storing received data reaches the preset threshold, the RTS signal of the UART changes to **1** \(data cannot be received\), and the peer UART stops sending data to it because its CTS signal does not allow it to send data. - - -## Available APIs - -The UART interface defines a set of common functions for operating a UART port, including obtaining and releasing device handles, reading and writing data of a specified length, and obtaining and setting the baud rate, as well as the device attributes. - -**Table 1** APIs for the UART driver - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Capability

-

Function

-

Description

-

Obtaining and releasing device handles

-

-

UartOpen

-

Obtains the UART device handle.

-

UartClose

-

Releases a specified UART device handle.

-

Reading and writing data

-

-

UartRead

-

Reads data of a specified length from a UART device.

-

UartWrite

-

Writes data of a specified length into a UART device.

-

Obtaining and setting the baud rate

-

UartGetBaud

-

Obtains the UART baud rate.

-

UartSetBaud

-

Sets the UART baud rate.

-

Obtaining and setting device attributes

-

-

UartGetAttribute

-

Obtains the UART device attributes.

-

UartSetAttribute

-

Sets the UART device attributes.

-

Setting the transmission mode

-

UartSetTransMode

-

Sets the UART transmission mode.

-
- ->![](../public_sys-resources/icon-note.gif) **NOTE**
->All functions provided in this document can be called only in kernel space. - -## Usage Guidelines - -### How to Use + +A UART is connected to other modules through two wires (as shown in Figure 1) or four wires (as shown in Figure 2). + - TX: TX pin of the transmitting UART. It is connected to the RX pin of the peer UART. + - RX: RX pin of the receiving UART. It is connected to the TX pin of the peer UART. + - RTS: Request to Send signal pin. It is connected to the CTS pin of the peer UART and is used to indicate whether the local UART is ready to receive data. + - CTS: Clear to Send signal pin. It is connected to the RTS pin of the peer UART and is used to indicate whether the local UART is allowed to send data to the peer end. + + **Figure 1** Two-wire UART communication + + ![](figures/2-wire-uart-communication.png "2-wire-uart-communication") + + **Figure 2** Four-wire UART communication + + ![](figures/4-wire-uart-communication.png "4-wire-uart-communication") + +- The transmitting and receiving UARTs must ensure that they have the same settings on particular attributes such as the baud rate and data format (start bit, data bit, parity bit, and stop bit) before they start to communicate. During data transmission, a UART sends data to the peer end over the TX pin and receives data from the peer end over the RX pin. When the size of the buffer used by a UART for storing received data reaches the preset threshold, the RTS signal of the UART changes to **1** (data cannot be received), and the peer UART stops sending data to it because its CTS signal does not allow it to send data. + +- The UART interface defines a set of common functions for operating a UART port, including obtaining and releasing device handles, reading and writing data of a specified length, and obtaining and setting the baud rate, as well as the device attributes. + + +## Available APIs + + **Table 1** UART driver APIs + +| API| Description| +| -------- | -------- | +| UartOpen | Obtains a UART device handle.| +| UartClose | Releases a UART device handle.| +| UartRead | Reads data of the specified length from a UART device.| +| UartWrite | Writes data of the specified length to a UART device.| +| UartGetBaud | Obtains the UART baud rate.| +| UartSetBaud | Sets the UART baud rate.| +| UartGetAttribute | Obtains UART device attributes.| +| UartSetAttribute | Sets UART device attributes.| +| UartSetTransMode | Sets the UART transmission mode.| + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> All APIs described in this document can be called only in kernel mode. + + +## Usage Guidelines + + +### How to Use The figure below illustrates how to use the APIs. -**Figure 3** Using UART driver APIs -![](figures/using-uart-process.png "process-of-using-a-uart-device") - -### Obtaining a UART Device Handle - -Before performing UART communication, call **UartOpen** to obtain a UART device handle. This function returns the pointer to the UART device handle with a specified port number. - -DevHandle UartOpen\(uint32\_t port\); - -**Table 2** Description of UartOpen - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

port

-

UART port number.

-

Return Value

-

Description

-

NULL

-

Failed to obtain the UART device handle.

-

Device handle

-

UART device handle.

-
- -The following example shows how to obtain a UART device handle based on the assumption that the UART port number is **3**: - -``` -DevHandle handle = NULL; /* The UART device handle */ -uint32_t port = 3; /* UART port number */ + **Figure 3** Using UART driver APIs + + ![](figures/using-UART-process.png) + + +### Opening a UART Device Handle + +Before performing UART communication, call **UartOpen** to obtain a UART device handle. This function returns the pointer to the UART device handle with the specified port number. + + +``` +DevHandle UartOpen(uint32_t port); +``` + + **Table 2** Description of UartOpen + +| Parameter| Description| +| -------- | -------- | +| port | UART port number.| +| **Return Value**| **Description**| +| NULL | The operation failed.| +| Device handle| The operation is successful. The obtained UART device handle is returned.| + + Example: Obtain the device handle of UART port 3. + +``` +DevHandle handle = NULL; /* UART device handle */ +uint32_t port = 3; /* UART port number */ handle = UartOpen(port); if (handle == NULL) { HDF_LOGE("UartOpen: failed!\n"); @@ -158,51 +88,29 @@ if (handle == NULL) { } ``` -### Setting the UART Baud Rate - -After obtaining the UART device handle, set the UART baud rate by calling the following function: - -int32\_t UartSetBaud\(DevHandle handle, uint32\_t baudRate\); - -**Table 3** Description of UartSetBaud - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

baudRate

-

Baud rate of the UART to set.

-

Return Value

-

Description

-

0

-

Succeeded in setting the UART baud rate.

-

Negative value

-

Failed to set the UART baud rate.

-
- -The following example shows how to set the UART baud rate to **9600**: +### Setting the UART Baud Rate + +Call **UartSetBaud()** to set the UART baud rate. + + +``` +int32_t UartSetBaud(DevHandle handle, uint32_t baudRate); +``` + + **Table 3** Description of UartSetBaud + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| baudRate | Baud rate to set.| +| **Return Value**| **Description**| +| 0 | The operation is successful.| +| Negative value| The operation failed.| + +Example: Set the UART baud rate to **9600**. + + ``` int32_t ret; /* Set the UART baud rate to 9600. */ @@ -212,51 +120,29 @@ if (ret != 0) { } ``` -### Obtaining the UART Baud Rate - -After setting the UART baud rate, obtain the current baud rate by calling the following function: - -int32\_t UartGetBaud\(DevHandle handle, uint32\_t \*baudRate\); - -**Table 4** Description of UartGetBaud - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

baudRate

-

Pointer to the UART baud rate.

-

Return Value

-

Description

-

0

-

Succeeded in obtaining the UART baud rate.

-

Negative value

-

Failed to obtain the UART baud rate.

-
- -The following example shows how to obtain the UART baud rate: +### Obtaining the UART Baud Rate + +Call **UartGetBaud()** to obtain the UART baud rate. + + +``` +int32_t UartGetBaud(DevHandle handle, uint32_t *baudRate); +``` + + **Table 4** Description of UartGetBaud + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| baudRate | Pointer to the UART baud rate obtained.| +| **Return Value**| **Description**| +| 0 | The operation is successful.| +| Negative value| The operation failed.| + +Example: Obtain the UART baud rate. + + ``` int32_t ret; uint32_t baudRate; @@ -267,168 +153,102 @@ if (ret != 0) { } ``` -### Setting the UART Device Attributes - -Before performing UART communication, set the UART device attributes by calling the following function: - -int32\_t UartSetAttribute\(DevHandle handle, struct UartAttribute \*attribute\); - -**Table 5** Description of UartSetAttribute - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

attribute

-

Pointer to the UART device attributes to set.

-

Return Value

-

Description

-

0

-

Succeeded in setting the UART device attributes.

-

Negative value

-

Failed to set the UART device attributes.

-
- -The following example shows how to set the UART device attributes: +### Setting UART Device Attributes + +Call **UartSetAttribute()** to set UART device attributes. + + +``` +int32_t UartSetAttribute(DevHandle handle, struct UartAttribute *attribute); +``` + + **Table 5** Description of UartSetAttribute + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| attribute | Pointer to the UART device attributes to set.| +| **Return Value**| **Description**| +| 0 | The operation is successful.| +| Negative value| The operation failed.| + +Example: Set UART device attributes. + + ``` int32_t ret; struct UartAttribute attribute; -attribute.dataBits = UART_ATTR_DATABIT_7; /* Set the number of data bits to 7. */ -attribute.parity = UART_ATTR_PARITY_NONE; /* Set the parity bit to no parity. */ +attribute.dataBits = UART_ATTR_DATABIT_7; /* Enable 7 bits to be transferred each time. */ +attribute.parity = UART_ATTR_PARITY_NONE; /* Disable parity check. */ attribute.stopBits = UART_ATTR_STOPBIT_1; /* Set the stop bit to 1. */ attribute.rts = UART_ATTR_RTS_DIS; /* Disable the RTS signal. */ attribute.cts = UART_ATTR_CTS_DIS; /* Disable the CTS signal. */ attribute.fifoRxEn = UART_ATTR_RX_FIFO_EN; /* Enable RX FIFO. */ attribute.fifoTxEn = UART_ATTR_TX_FIFO_EN; /* Enable TX FIFO. */ -/* Set the UART device attributes. */ +/* Set UART device attributes. */ ret = UartSetAttribute(handle, &attribute); if (ret != 0) { HDF_LOGE("UartSetAttribute: failed, ret %d\n", ret); } ``` -### Obtaining UART Device Attributes - -After setting the UART device attributes, obtain the current device attributes by calling the following function: - -int32\_t UartGetAttribute\(DevHandle handle, struct UartAttribute \*attribute\); - -**Table 6** Description of UartGetAttribute - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

attribute

-

Pointer to the UART device attributes.

-

Return Value

-

Description

-

0

-

Succeeded in obtaining the UART device attributes.

-

Negative value

-

Failed to obtain the UART device attributes.

-
- -The following example shows how to obtain the UART device attributes: +### Obtaining UART Device Attributes + +Call **UartGetAttribute()** to obtain the current UART device attributes. + + +``` +int32_t UartGetAttribute(DevHandle handle, struct UartAttribute *attribute); +``` + + **Table 6** Description of UartGetAttribute + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| attribute | Pointer to the UART device attributes obtained.| +| **Return Value**| **Description**| +| 0 | The operation is successful.| +| Negative value| The operation failed.| + +Example: Obtain UART device attributes. + + ``` int32_t ret; struct UartAttribute attribute; -/* Obtain the UART attributes. */ +/* Obtain UART device attributes. */ ret = UartGetAttribute(handle, &attribute); if (ret != 0) { HDF_LOGE("UartGetAttribute: failed, ret %d\n", ret); } ``` -### Setting the UART Transmission Mode - -Before performing UART communication, set the UART transmission mode by calling the following function: - -int32\_t UartSetTransMode\(DevHandle handle, enum UartTransMode mode\); - -**Table 7** Description of UartSetTransMode - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

mode

-

UART transmission mode to set.

-

Return Value

-

Description

-

0

-

Succeeded in setting the UART transmission mode.

-

Negative value

-

Failed to set the UART transmission mode.

-
- -The following example shows how to set the transmission mode to **UART\_MODE\_RD\_BLOCK**: +### Setting the UART Transmission Mode + +Call **UartSetTransMode()** to set the UART transmission mode. + + +``` +int32_t UartSetTransMode(DevHandle handle, enum UartTransMode mode); +``` + + **Table 7** Description of UartSetTransMode + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| mode | UART transmission mode to set.| +| **Return Value**| **Description**| +| 0 | The operation is successful.| +| Negative value| The operation failed.| + +Example: Set the UART transmission mode to **UART_MODE_RD_BLOCK**. + + ``` int32_t ret; /* Set the UART transmission mode. */ @@ -438,116 +258,64 @@ if (ret != 0) { } ``` -### Writing Data of a Specified Length into a UART Device - -To write data into a UART device, call the following function: - -int32\_t UartWrite\(DevHandle handle, uint8\_t \*data, uint32\_t size\); - -**Table 8** Description of UartWrite - - - - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

data

-

Pointer to the data to write.

-

size

-

Length of the data to write.

-

Return Value

-

Description

-

0

-

Succeeded in writing data into the UART device.

-

Negative value

-

Failed to write data into the UART device.

-
- -The following example shows how to write data of a specified length into the UART device: +### Writing Data to a UART Device + +Call **UartWrite()** to write data of the specified length to a UART device. + + +``` +int32_t UartWrite(DevHandle handle, uint8_t *data, uint32_t size); +``` + + **Table 8** Description of UartWrite + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| data | Pointer to the data to write.| +| size | Length of the data to write.| +| **Return Value**| **Description**| +| 0 | The operation is successful.| +| Negative value| The operation failed.| + +Example: Write data to a UART device. + + ``` int32_t ret; uint8_t wbuff[5] = {1, 2, 3, 4, 5}; -/* Write 5-byte data into the UART device. */ +/* Write 5-byte data to the UART device. */ ret = UartWrite(handle, wbuff, 5); if (ret != 0) { HDF_LOGE("UartWrite: failed, ret %d\n", ret); } ``` -### Reading Data of a Specified Length from a UART Device - -To write data into a UART device, call the following function: - -int32\_t UartRead\(DevHandle handle, uint8\_t \*data, uint32\_t size\); - -**Table 9** Description of UartRead - - - - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-

data

-

Pointer to the buffer for receiving the data.

-

size

-

Length of the data to read.

-

Return Value

-

Description

-

Non-negative value

-

Length of the data read from the UART device.

-

Negative value

-

Failed to read data from the UART device.

-
- -The following example shows how to read data of a specified length from the UART device: +### Reading Data from a UART Device + +Call **UartRead()** to read data of the specified length from a UART device. + + +``` +int32_t UartRead(DevHandle handle, uint8_t *data, uint32_t size); +``` + + **Table 9** Description of UartRead + +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle.| +| data | Pointer to the buffer for receiving the data.| +| size | Length of the data to read.| +| **Return Value**| **Description**| +| Non-negative value| The operation is successful. The length of the data read is returned.| +| Negative value| The operation failed.| + +Example: Read data of the specified length from a UART device. + + ``` int32_t ret; uint8_t rbuff[5] = {0}; @@ -558,44 +326,39 @@ if (ret < 0) { } ``` ->![](../public_sys-resources/icon-caution.gif) **CAUTION:** ->Data is successfully read from the UART device if a non-negative value is returned. If the return value is **0**, no valid data can be read from the UART device. If the return value is greater than **0**, the return value is the length of the data actually read from the UART device. The length is less than or equal to the value of **size** and does not exceed the maximum length of data to read at a time specified by the UART controller in use. +> ![icon-caution.gif](../public_sys-resources/icon-caution.gif) **CAUTION**
+> Data is successfully read from the UART device if a non-negative value is returned. If **0** is returned, no valid data can be read from the UART device. A value greater than **0** indicates the length of the data read from the UART device. The data length must be less than or equal to the value of **size** and cannot exceed the maximum length of the data to read at a time specified by the UART controller in use. -### Destroying the UART Device Handle -After the UART communication, destroy the UART device handle by calling the following function: +### Closing a UART Device Handle -void UartClose\(DevHandle handle\); +Call **UartClose()** to close a UART device handle. -This function will release the resources previously obtained. + +``` +void UartClose(DevHandle handle); +``` -**Table 10** Description of UartClose +This function releases the resources requested by **UartOpen**. - - - - - - - - - -

Parameter

-

Description

-

handle

-

UART device handle.

-
+ **Table 10** Description of UartClose -The following example shows how to destroy the UART device handle: +| Parameter| Description| +| -------- | -------- | +| handle | UART device handle to close.| +Example: Close a UART device handle. + + ``` -UartClose(handle); /* Destroy the UART device handle. */ +UartClose(handle); /* Close the UART device handle. */ ``` -## Usage Example -The following is a usage example of a UART device, including how to obtain the UART device handle, set the baud rate, device attributes, and transmission mode, read data from or write data into the UART device, and then destroy the UART device handle. +## Example + The following example shows how to open a UART device handle, set the baud rate, device attributes, and transmission mode, read data from or write data into the UART device, and then close the UART device handle. + ``` #include "hdf_log.h" #include "uart_if.h" @@ -608,16 +371,16 @@ void UartTestSample(void) uint8_t wbuff[5] = { 1, 2, 3, 4, 5 }; uint8_t rbuff[5] = { 0 }; struct UartAttribute attribute; - attribute.dataBits = UART_ATTR_DATABIT_7; /* Set the number of data bits to 7. */ - attribute.parity = UART_ATTR_PARITY_NONE; /* Set the parity bit to no parity. */ + attribute.dataBits = UART_ATTR_DATABIT_7; /* Enable 7 bits to be transferred each time. */ + attribute.parity = UART_ATTR_PARITY_NONE; /* Disable parity check. */ attribute.stopBits = UART_ATTR_STOPBIT_1; /* Set the stop bit to 1. */ attribute.rts = UART_ATTR_RTS_DIS; /* Disable the RTS signal. */ attribute.cts = UART_ATTR_CTS_DIS; /* Disable the CTS signal. */ attribute.fifoRxEn = UART_ATTR_RX_FIFO_EN; /* Enable RX FIFO. */ attribute.fifoTxEn = UART_ATTR_TX_FIFO_EN; /* Enable TX FIFO. */ - /* Set the UART port number actually used. */ + /* Enter the UART port number. */ port = 1; - /* Obtain the UART device handle. */ + /* Open the UART device handle based on the port number. */ handle = UartOpen(port); if (handle == NULL) { HDF_LOGE("UartOpen: failed!\n"); @@ -629,7 +392,7 @@ void UartTestSample(void) HDF_LOGE("UartSetBaud: failed, ret %d\n", ret); goto _ERR; } - /* Set the UART device attributes. */ + /* Set UART device attributes. */ ret = UartSetAttribute(handle, &attribute); if (ret != 0) { HDF_LOGE("UartSetAttribute: failed, ret %d\n", ret); @@ -641,7 +404,7 @@ void UartTestSample(void) HDF_LOGE("UartSetTransMode: failed, ret %d\n", ret); goto _ERR; } - /* Write 5-byte data into the UART device. */ + /* Write 5-byte data to the UART device. */ ret = UartWrite(handle, wbuff, 5); if (ret != 0) { HDF_LOGE("UartWrite: failed, ret %d\n", ret); @@ -654,7 +417,7 @@ void UartTestSample(void) goto _ERR; } _ERR: - /* Destroy the UART device handle. */ + /* Close the UART device handle. */ UartClose(handle); } -``` \ No newline at end of file +``` diff --git a/en/device-dev/driver/driver-platform-uart-develop.md b/en/device-dev/driver/driver-platform-uart-develop.md index 565e815cb5d55c0e8da044db2697a335b1582aee..cf3393d01505ceccb7c34b643a9ce218f148ce6c 100644 --- a/en/device-dev/driver/driver-platform-uart-develop.md +++ b/en/device-dev/driver/driver-platform-uart-develop.md @@ -14,7 +14,7 @@ In the Hardware Driver Foundation (HDF), the Universal Asynchronous Receiver/Tra **UartHostMethod**: - + ``` struct UartHostMethod { int32_t (*Init)(struct UartHost *host); @@ -32,18 +32,18 @@ struct UartHostMethod { **Table 1** Description of the callback functions in UartHostMethod -| Function| Input Parameter| Output Parameter| Return Value| Description| +| Function| Input Parameter| Output Parameter| Return Value| Description| | -------- | -------- | -------- | -------- | -------- | -| Init | **host**: structure pointer to the UART controller at the core layer.| –| HDF_STATUS| Initializes a UART device.| -| Deinit | **host**: structure pointer to the UART controller at the core layer.| –| HDF_STATUS| Deinitializes a UART device.| -| Read | **host**: structure pointer to the UART controller at the core layer.
**size**: data size, which is of the uint32_t type.| **data**: pointer to the output data. The value is of the uint8_t type.| HDF_STATUS| Reads data.| -| Write | **host**: structure pointer to the UART controller at the core layer.
**data**: pointer to the input data. The value is of the uint8_t type.
**size**: data size, which is of the uint32_t type.| –| HDF_STATUS| Writes data.| -| SetBaud | **host**: structure pointer to the UART controller at the core layer.
**baudRate**: pointer to the input baud rate. The value is of the uint32_t type. | –| HDF_STATUS| Sets the baud rate.| -| GetBaud | **host**: structure pointer to the UART controller at the core layer.| **baudRate**: pointer to the output baud rate. The value is of the uint32_t type.| HDF_STATUS| Obtains the current baud rate.| -| GetAttribute | **host**: structure pointer to the UART controller at the core layer.| **attribute**: structure pointer to the UART attributes. For details, see **UartAttribute** in **uart_if.h**.| HDF_STATUS| Obtains UART attributes.| -| SetAttribute | **host**: structure pointer to the UART controller at the core layer.
**attribute**: structure pointer to the UART attributes to set.| –| HDF_STATUS| Sets UART attributes.| -| SetTransMode | **host**: structure pointer to the UART controller at the core layer.
**mode**: transfer mode to set. For details, see **UartTransMode** in **uart_if.h**.| –| HDF_STATUS| Sets the UART transfer mode.| -| PollEvent | **host**: structure pointer to the UART controller at the core layer.
**filep**: void pointer to a file.
**table**: void pointer to poll_table.| –| HDF_STATUS| Polls for pending events.| +| Init | **host**: structure pointer to the UART controller at the core layer.| –| HDF_STATUS| Initializes a UART device.| +| Deinit | **host**: structure pointer to the UART controller at the core layer.| –| HDF_STATUS| Deinitializes a UART device.| +| Read | **host**: structure pointer to the UART controller at the core layer.
**size**: data size, which is of the uint32_t type.| **data**: pointer to the data read. The value is of the uint8_t type. | HDF_STATUS| Reads data.| +| Write | **host**: structure pointer to the UART controller at the core layer.
**data**: pointer to the data to write. The value is of the uint8_t type.
**size**: data size, which is of the uint32_t type. | –| HDF_STATUS| Writes data.| +| SetBaud | **host**: structure pointer to the UART controller at the core layer.
**baudRate**: pointer to the baud rate to set. The value is of the uint32_t type. | –| HDF_STATUS| Sets the baud rate.| +| GetBaud | **host**: structure pointer to the UART controller at the core layer.| **baudRate**: pointer to the baud rate obtained. The value is of the uint32_t type. | HDF_STATUS| Obtains the current baud rate.| +| GetAttribute | **host**: structure pointer to the UART controller at the core layer.| **attribute**: structure pointer to the attribute obtained. For details, see **UartAttribute** in **uart_if.h**. | HDF_STATUS| Obtains UART attributes.| +| SetAttribute | **host**: structure pointer to the UART controller at the core layer.
**attribute**: structure pointer to the attribute to set. | –| HDF_STATUS| Sets UART attributes.| +| SetTransMode | **host**: structure pointer to the UART controller at the core layer.
**mode**: transfer mode to set. For details, see **UartTransMode** in **uart_if.h**.| –| HDF_STATUS| Sets the UART transfer mode.| +| PollEvent | **host**: structure pointer to the UART controller at the core layer.
**filep**: void pointer to a file.
**table**: void pointer to poll_table.| –| HDF_STATUS| Polls for pending events.| ## How to Develop @@ -64,7 +64,8 @@ The UART module adaptation involves the following steps: > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> For details about the functions in **UartHostMethod**, see [Available APIs](#available-apis). -4. Debug the driver.
+4. Debug the driver. + (Optional) For new drivers, verify the basic functions, such as the UART status control and response to interrupts. @@ -72,11 +73,16 @@ The UART module adaptation involves the following steps: The following uses **uart_hi35xx.c** as an example to present the information required for implementing device functions. -1. Instantiate the driver entry.
The driver entry must be a global variable of the **HdfDriverEntry** type (defined in **hdf_device_desc.h**), and the value of **moduleName** must be the same as that in **device_info.hcs**. In the HDF, the start address of each **HdfDriverEntry** object of all loaded drivers is collected to form a segment address space similar to an array for the upper layer to invoke. +1. Instantiate the driver entry. + + The driver entry must be a global variable of the **HdfDriverEntry** type (defined in **hdf_device_desc.h**), and the value of **moduleName** must be the same as that in **device_info.hcs**. + + In the HDF, the start address of each **HdfDriverEntry** object of all loaded drivers is collected to form a segment address space similar to an array for the upper layer to invoke. + Generally, the HDF calls the **Bind** function and then the **Init** function to load a driver. If **Init** fails to be called, the HDF calls **Release** to release driver resources and exit. - UART driver entry example: - + UART driver entry example: + ``` struct HdfDriverEntry g_hdfUartDevice = { .moduleVersion = 1, @@ -89,11 +95,15 @@ The following uses **uart_hi35xx.c** as an example to present the information re HDF_INIT(g_hdfUartDevice); ``` -2. Add the **deviceNode** information to the **device_info.hcs** file and configure the device attributes in the **uart_config.hcs** file.
The **deviceNode** information is related to registration of the driver entry. The device attribute values are closely related to the default values or value ranges of the **UartHost** members at the core layer. - In this example, there is only one UART controller. If there are multiple UART controllers, you need to add the **deviceNode** information to the **device_info** file and add the corresponding device attributes to the **uart_config** file for each controller. - - **device_info.hcs** configuration example +2. Add the **deviceNode** information to the **device_info.hcs** file and configure the device attributes in the **uart_config.hcs** file. + + The **deviceNode** information is related to registration of the driver entry. The device attribute values are closely related to the default values or value ranges of the **UartHost** members at the core layer. + + In this example, there is only one UART controller. If there are multiple UART controllers, you need to add the **deviceNode** information to the **device_info** file and add the corresponding device attributes to the **uart_config** file for each controller. + + - **device_info.hcs** configuration example: - + ``` root { device_info { @@ -103,11 +113,11 @@ The following uses **uart_hi35xx.c** as an example to present the information re priority = 50; device_uart :: device { device0 :: deviceNode { - policy = 1; // The driver publishes services only for kernel-mode processes. - priority = 40; // Driver startup priority. - permission = 0644; // Permission for the driver to create a device node. - moduleName = "HDF_PLATFORM_UART"; // Driver name, which must be the same as moduleName in the HdfDriverEntry structure. - serviceName = "HDF_PLATFORM_UART_0";// Unique name of the service published by the driver. The name is in the HDF_PLATFORM_UART_X format. X indicates the UART controller number. + policy = 1; // The driver publishes services only for kernel-mode processes. + priority = 40; // Driver startup priority. + permission = 0644; // Permission for the driver to create a device node. + moduleName = "HDF_PLATFORM_UART"; // Driver name, which must be the same as moduleName in the HdfDriverEntry structure. + serviceName = "HDF_PLATFORM_UART_0"; // Unique name of the service published by the driver. The name is in the HDF_PLATFORM_UART_X format. X indicates the UART controller number. deviceMatchAttr = "hisilicon_hi35xx_uart_0"; // Keyword for matching the private data of the driver. The value must be the same as that of match_attr in the private data configuration table of the driver. } device1 :: deviceNode { @@ -127,20 +137,20 @@ The following uses **uart_hi35xx.c** as an example to present the information re - **uart_config.hcs** configuration example - + ``` root { platform { - template uart_controller { // Template configuration. In the template, you can configure the common parameters shared by device nodes. + template uart_controller { // Template configuration. In the template, you can configure the common parameters shared by device nodes. match_attr = ""; - num = 0; // (Mandatory) Device number - baudrate = 115200; // (Mandatory) Baud rate. Set the value based on service requirements. - fifoRxEn = 1; // (Mandatory) Enable FIFOs to be received. - fifoTxEn = 1; // (Mandatory) Enable FIFOs to be transferred. - flags = 4; // (Mandatory) Flag signal. - regPbase = 0x120a0000; // (Mandatory) Used for address mapping. - interrupt = 38; // (Mandatory) Interrupt number. - iomemCount = 0x48; // (Mandatory) Used for address mapping. + num = 0; // (Mandatory) Device number. + baudrate = 115200; // (Mandatory) Baud rate. Set the value based on service requirements. + fifoRxEn = 1; // (Mandatory) Enable FIFOs to be received. + fifoTxEn = 1; // (Mandatory) Enable FIFOs to be transferred. + flags = 4; // (Mandatory) Flag signal. + regPbase = 0x120a0000; // (Mandatory) Used for address mapping. + interrupt = 38; // (Mandatory) Interrupt number. + iomemCount = 0x48; // (Mandatory) Used for address mapping. } controller_0x120a0000 :: uart_controller { match_attr = "hisilicon_hi35xx_uart_0";// (Mandatory) The value must be the same as that of deviceMatchAttr of the corresponding device in device_info.hcs. @@ -159,43 +169,44 @@ The following uses **uart_hi35xx.c** as an example to present the information re ``` 3. Initialize the **UartHost** object at the core layer, including defining a custom structure (to pass parameters and data) and implementing the **HdfDriverEntry** member functions (**Bind**, **Init**, and **Release**) to instantiate **UartHostMethod** in **UartHost** (so that the underlying driver functions can be called). + - Defining a custom structure To the driver, the custom structure holds parameters and data. The **DeviceResourceIface** method provided by the HDF reads the values in the **uart_config.hcs** file to initialize the members in the custom structure and passes important parameters, such as the device number, to the **UartHost** object at the core layer. - + ``` - struct UartPl011Port { // Interface structure + struct UartPl011Port { // Interface structure int32_t enable; - unsigned long physBase; // Physical address + unsigned long physBase; // Physical address uint32_t irqNum; // Interrupt number - uint32_t defaultBaudrate;// Default baud rate - uint32_t flags; // Flags related to the following three macros. + uint32_t defaultBaudrate; // Default baud rate + uint32_t flags; // Flags related to the following three macros #define PL011_FLG_IRQ_REQUESTED (1 << 0) #define PL011_FLG_DMA_RX_REQUESTED (1 << 1) #define PL011_FLG_DMA_TX_REQUESTED (1 << 2) - struct UartDmaTransfer *rxUdt; // DMA transfer - struct UartDriverData *udd; // The data structure is defined as follows: + struct UartDmaTransfer *rxUdt; // DMA transfer + struct UartDriverData *udd; // The data structure is defined as follows: }; - struct UartDriverData { // Structure related to data transfer + struct UartDriverData { // Structure related to data transfer uint32_t num; - uint32_t baudrate; // Baud rate (configurable) - struct UartAttribute attr; // Attributes, such as the data bit and stop bit, related to data transfer - struct UartTransfer *rxTransfer; // Buffer (FIFO structure) - wait_queue_head_t wait; // Queuing signal related to conditional variables - int32_t count; // Data count - int32_t state; // UART controller state + uint32_t baudrate; // Baud rate (configurable) + struct UartAttribute attr; // Attributes, such as the data bit and stop bit, related to data transfer. + struct UartTransfer *rxTransfer; // Buffer (FIFO structure) + wait_queue_head_t wait; // Queuing signal related to conditional variables + int32_t count; // Data count + int32_t state; // UART controller state #define UART_STATE_NOT_OPENED 0 #define UART_STATE_OPENING 1 #define UART_STATE_USEABLE 2 #define UART_STATE_SUSPENDED 3 - uint32_t flags; // Status flags + uint32_t flags; // Status flags #define UART_FLG_DMA_RX (1 << 0) #define UART_FLG_DMA_TX (1 << 1) #define UART_FLG_RD_BLOCK (1 << 2) - RecvNotify recv; // Pointer to the function that receives serial port data - struct UartOps *ops; // Custom function pointer structure. For details, see device/hisilicon/drivers/uart/uart_pl011.c. - void *private; // It stores the pointer to the start address of UartPl011Port for easy invocation. + RecvNotify recv; // Pointer to the function that receives serial port data. + struct UartOps *ops; // Custom function pointer structure. For details, see device/hisilicon/drivers/uart/uart_pl011.c. + void *private; // It stores the pointer to the start address of UartPl011Port for easy invocation. }; // UartHost is the controller structure at the core layer. The Init function assigns values to the members of UartHost. @@ -205,12 +216,13 @@ The following uses **uart_hi35xx.c** as an example to present the information re uint32_t num; OsalAtomic atom; void *priv; // It stores the pointer to the start address of the vendor's custom structure for easy invocation. - struct UartHostMethod *method; // Hook at the core layer. You need to implement and instantiate its member functions. + struct UartHostMethod *method; // Hook at the core layer. You need to implement and instantiate its member functions. }; ``` + - Instantiating **UartHostMethod** in **UartHost** (other members are initialized by **Bind**) - + ``` // Example in uart_hi35xx.c: instantiate the hook. struct UartHostMethod g_uartHostMethod = { @@ -229,30 +241,30 @@ The following uses **uart_hi35xx.c** as an example to present the information re - **Bind** function - Input parameter: + **Input parameter**: **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information. - Return value: + **Return value**: - HDF_STATUS
The table below describes some status. For more information, see **HDF_STATUS** in the **/drivers/framework/include/utils/hdf_base.h** file. + **HDF_STATUS**
The table below describes some status. For more information, see **HDF_STATUS** in the **/drivers/framework/include/utils/hdf_base.h** file. - **Table 2** HDF_STATUS + **Table 2** Description of HDF_STATUS - | Status| Description| + | Status| Description| | -------- | -------- | - | HDF_ERR_INVALID_OBJECT | Invalid controller object.| - | HDF_ERR_MALLOC_FAIL | Failed to allocate memory.| - | HDF_ERR_INVALID_PARAM | Invalid parameter.| - | HDF_ERR_IO | I/O error.| - | HDF_SUCCESS | Initialization successful.| - | HDF_FAILURE | Initialization failed.| + | HDF_ERR_INVALID_OBJECT | Invalid controller object.| + | HDF_ERR_MALLOC_FAIL | Failed to allocate memory.| + | HDF_ERR_INVALID_PARAM | Invalid parameter.| + | HDF_ERR_IO | I/O error.| + | HDF_SUCCESS | Initialization successful.| + | HDF_FAILURE | Initialization failed.| - Function description: + **Function description**: Initializes the custom structure object and **UartHost**. - + ``` //uart_hi35xx.c static int32_t HdfUartDeviceBind(struct HdfDeviceObject *device) @@ -267,10 +279,10 @@ The following uses **uart_hi35xx.c** as an example to present the information re ... host = (struct UartHost *)OsalMemCalloc(sizeof(*host));// Allocate memory. ... - host->device = device; // (Mandatory) Prerequisites for conversion between HdfDeviceObject and UartHost - device->service = &(host->service; // (Mandatory) Prerequisites for conversion between HdfDeviceObject and UartHost - host->device->service->Dispatch = UartIoDispatch;// Assign values to Dispatch of service. - OsalAtomicSet(&host->atom, 0); // Initialize or set the atomic services. + host->device = device; // (Mandatory) Prerequisites for conversion between HdfDeviceObject and UartHost. + device->service = &(host->service; // (Mandatory) Prerequisites for conversion between HdfDeviceObject and UartHost. + host->device->service->Dispatch = UartIoDispatch; // Assign values to Dispatch of service. + OsalAtomicSet(&host->atom, 0); // Initialize or set the atomic services. host->priv = NULL; host->method = NULL; return host; @@ -279,19 +291,19 @@ The following uses **uart_hi35xx.c** as an example to present the information re - **Init** function - Input parameter: + **Input parameter**: **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information. - Return value: + **Return value**: - HDF_STATUS + **HDF_STATUS** - Function description: + **Function description**: Initializes the custom structure object and **UartHost**, calls the **artAddDev** function at the core layer, and connects to the VFS. - + ``` int32_t HdfUartDeviceInit(struct HdfDeviceObject *device) { @@ -303,7 +315,7 @@ The following uses **uart_hi35xx.c** as an example to present the information re ... ret = Hi35xxAttach(host, device); // Initialize the UartHost object. ... - host->method = &g_uartHostMethod; // Hook the UartHostMethod instance. + host->method = &g_uartHostMethod; // Attach the UartHostMethod instance. return ret; } // Initialize UartHost. @@ -351,30 +363,34 @@ The following uses **uart_hi35xx.c** as an example to present the information re ``` - **Release** function - Input parameter: + **Input parameter**: **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs information. - Return value: + **Return value**: No value is returned. - Function description: + **Function description**: - Releases the memory and deletes the controller. This function assigns values to the **Release** API in the driver entry structure. When the HDF fails to call the **Init** function to initialize the driver, the **Release** function can be called to release driver resources. All forced conversion operations for obtaining the corresponding object can be successful only when **Init()** has the corresponding value assignment operations. + Releases the memory and deletes the controller. This function assigns values to the **Release** API in the driver entry structure. When the HDF fails to call the **Init** function to initialize the driver, the **Release** function can be called to release driver resources. - + > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** + > + > All forced conversion operations for obtaining the corresponding object can be successful only when **Init()** has the corresponding value assignment operations. + + ``` void HdfUartDeviceRelease(struct HdfDeviceObject *device) { struct UartHost *host = NULL; ... - host = UartHostFromDevice(device);// Forcibly convert HdfDeviceObject to UartHost by using service. For details about the value assignment, see the Bind function. + host = UartHostFromDevice(device); // Forcibly convert HdfDeviceObject to UartHost by using service. For details about the value assignment, see the Bind function. ... if (host->priv != NULL) { - Hi35xxDetach(host); // Customized memory release function. + Hi35xxDetach(host); // Customized memory release function. } - UartHostDestroy(host); // Call the function of the core layer to release the host. + UartHostDestroy(host); // Call the function of the core layer to release the host. } static void Hi35xxDetach(struct UartHost *host) @@ -382,10 +398,10 @@ The following uses **uart_hi35xx.c** as an example to present the information re struct UartDriverData *udd = NULL; struct UartPl011Port *port = NULL; ... - udd = host->priv; // Convert UartHost to UartDriverData. + udd = host->priv; // The conversion from UartHost to UartDriverData is involved. ... - UartRemoveDev(host);// Remove the VFS. - port = udd->private;// Convert UartDriverData to UartPl011Port. + UartRemoveDev (host); // Remove the VFS. + port = udd->private; // The conversion from UartDriverData to UartPl011Port is involved. if (port != NULL) { if (port->physBase != 0) { OsalIoUnmap((void *)port->physBase);// Unmap addresses. @@ -393,7 +409,7 @@ The following uses **uart_hi35xx.c** as an example to present the information re OsalMemFree(port); udd->private = NULL; } - OsalMemFree(udd);//Release UartDriverData. + OsalMemFree (udd); // Release UartDriverData. host->priv = NULL; } ``` diff --git a/zh-cn/application-dev/ability/ability-brief.md b/zh-cn/application-dev/ability/ability-brief.md index 3abd49268bdda3e53128e292c76df4be665c6cf4..56f3ebe85d26dc726db54258f8457635c01d4d52 100644 --- a/zh-cn/application-dev/ability/ability-brief.md +++ b/zh-cn/application-dev/ability/ability-brief.md @@ -1,6 +1,6 @@ # Ability框架概述 -​ Ability是应用所具备能力的抽象，也是应用程序的重要组成部分。Ability是系统调度应用的最小单元，是能够完成一个独立功能的组件。一个应用可以包含一个或多个Ability。 +​ Ability是应用所具备能力的抽象，也是应用程序的重要组成部分。Ability是系统调度应用的最小单元，是能够完成一个独立功能的组件。一个应用可以包含一个或多个Ability。 ​ Ability框架模型具有两种形态： @@ -14,7 +14,7 @@ | 开发方式 | 提供类Web的API，UI开发与Stage模型一致。 | 提供面向对象的开发方式，UI开发与FA模型一致。 | | 引擎实例 | 每个进程内的每个Ability实例独享一个JS VM引擎实例。 | 每个进程内的多个Ability实例共享一个JS VM引擎实例。 | | 进程内对象共享 | 不支持。 | 支持。 | -| 包描述文件 | 使用config.json描述HAP包和组件信息，组件必须使用固定的文件名。 | 使用module.json描述HAP包和组件信息，可以指定入口文件名。 | +| 包描述文件 | 使用config.json描述HAP包和组件信息，组件必须使用固定的文件名。 | 使用module.json5描述HAP包和组件信息，可以指定入口文件名。 | | 组件 | 提供PageAbility(页面展示)，ServiceAbility(服务)，DataAbility(数据分享)以及FormAbility(卡片)。 | 提供Ability(页面展示)、Extension(基于场景的服务扩展)。 | ​ 除了上述设计上的差异外，对于开发者而言，两种模型的主要区别在于： diff --git a/zh-cn/application-dev/ability/stage-ability.md b/zh-cn/application-dev/ability/stage-ability.md index ef785cc275e4b30d6a29e4470c7b963c6c7d3632..e9ad6780e3bfe63292a0fd5a48eba695c5b79590 100644 --- a/zh-cn/application-dev/ability/stage-ability.md +++ b/zh-cn/application-dev/ability/stage-ability.md @@ -1,6 +1,6 @@ # Ability开发指导 ## 场景介绍 -Stage模型是区别于FA模型的一种应用开发模型，对此模型的介绍详见[Stage模型综述](stage-brief.md)。开发Stage模型应用时，需要在module.json和app.json配置文件中对应用的包结构进行声明，对应用包结构配置文件的说明详见[应用包结构配置文件的说明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/quick-start/stage-structure.md)。基于Stage模型的Ability应用开发，主要涉及如下功能逻辑： +Stage模型是区别于FA模型的一种应用开发模型，对此模型的介绍详见[Stage模型综述](stage-brief.md)。开发Stage模型应用时，需要在module.json5和app.json5配置文件中对应用的包结构进行声明，对应用包结构配置文件的说明详见[应用包结构配置文件的说明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/quick-start/stage-structure.md)。基于Stage模型的Ability应用开发，主要涉及如下功能逻辑： - 创建支持使用屏幕浏览及人机交互的Ability应用，包括实现Ability的生命周期、获取Ability配置信息、向用户申请授权及环境变化通知等场景。 - 启动Ability应用，包括相同设备启动Ability、跨设备启动Ability以及指定页面启动Ability等场景。 - 通用组件Call功能，详见[Call调用开发指导](stage-call.md)。 @@ -8,7 +8,7 @@ Stage模型是区别于FA模型的一种应用开发模型，对此模型的介 - 应用迁移，详见[应用迁移开发指导](stage-ability-continuation.md)。 ### 启动模式 -ability支持单实例、多实例和指定实例3种启动模式，在module.json中通过launchType配置。启动模式对应Ability被启动时的行为，对启动模式的详细说明如下： +ability支持单实例、多实例和指定实例3种启动模式，在module.json5中通过launchType配置。启动模式对应Ability被启动时的行为，对启动模式的详细说明如下： | 启动模式 | 描述 |说明 | | ----------- | ------- |---------------- | @@ -16,7 +16,7 @@ ability支持单实例、多实例和指定实例3种启动模式，在module.js | singleton | 单实例 | 系统中只存在唯一一个实例，startAbility时，如果已存在，则复用系统中的唯一一个实例 | | specified | 指定实例 | 运行时由ability内部业务决定是否创建多实例 | -缺省情况下是singleton模式，module.json示例如下： +缺省情况下是singleton模式，module.json5示例如下： ```json { "module": { @@ -146,9 +146,9 @@ export default class MainAbility extends Ability { } ``` ### 应用向用户申请授权 -应用需要获取用户的隐私信息或使用系统能力时，比如获取位置信息、使用相机拍摄照片或录制视频等，需要向用户申请授权。在开发过程中，首先需要明确涉及的敏感权限并在module.json中声明需要的权限，同时通过接口`requestPermissionsFromUser`以动态弹窗的方式向用户申请授权。以访问日历为例，具体示例代码如下： +应用需要获取用户的隐私信息或使用系统能力时，比如获取位置信息、使用相机拍摄照片或录制视频等，需要向用户申请授权。在开发过程中，首先需要明确涉及的敏感权限并在module.json5中声明需要的权限，同时通过接口`requestPermissionsFromUser`以动态弹窗的方式向用户申请授权。以访问日历为例，具体示例代码如下： -在module.json声明需要的权限： +在module.json5声明需要的权限： ```json "requestPermissions": [ { diff --git a/zh-cn/application-dev/ability/stage-serviceextension.md b/zh-cn/application-dev/ability/stage-serviceextension.md index 89e04f91267987fd896b39cc2c3823d73f3893ba..d4d28a6cb32d740982cf8731f51d34708a74b3b8 100644 --- a/zh-cn/application-dev/ability/stage-serviceextension.md +++ b/zh-cn/application-dev/ability/stage-serviceextension.md @@ -61,9 +61,9 @@ ExtensionAbility，是Stage模型中新增的扩展组件的基类，一般用 2.注册ServiceExtensionAbility -需要在应用配置文件module.json中进行注册，注册类型type需要设置为service。 +需要在应用配置文件module.json5中进行注册，注册类型type需要设置为service。 -**module.json配置样例** +**module.json5配置样例** ```json "extensionAbilities":[{ @@ -72,6 +72,6 @@ ExtensionAbility，是Stage模型中新增的扩展组件的基类，一般用 "description": "service", "type": "service", "visible": true, - "srcEntrance": "./ets/ServiceExtAbility/ServiceExtAbility.ts" + "srcEntrance": "./ets/ServiceExtAbility/ServiceExtAbility.ts" }] ``` diff --git a/zh-cn/application-dev/database/database-mdds-guidelines.md b/zh-cn/application-dev/database/database-mdds-guidelines.md index e0d7dec04939ad98fc08acbaade047545a77a597..46ef54dafa6d3044c7a966afc6eb2f4c283a4f1d 100644 --- a/zh-cn/application-dev/database/database-mdds-guidelines.md +++ b/zh-cn/application-dev/database/database-mdds-guidelines.md @@ -14,13 +14,13 @@ | 接口名称 | 描述 | | ------------------------------------------------------------ | ----------------------------------------------- | -| createKVManager(config:KVManagerConfig,callback:AsyncCallback<KVManager>):void
createKVManager(config:KVManagerConfig):Promise<KVManager> | 创建一个`KVManager`对象实例，用于管理数据库对象。 | -| getKVStore<TextendsKVStore>(storeId:string,options:Options,callback:AsyncCallback<T>):void
getKVStore<TextendsKVStore>(storeId:string,options:Options):Promise<T> | 指定`Options`和`storeId`，创建并获取`KVStore`数据库。 | -| put(key:string,value:Uint8Array\|string\|number\|boolean,callback:AsyncCallback<void>):void
put(key:string,value:Uint8Array\|string\|number\|boolean):Promise<void> | 插入和更新数据。 | -| delete(key:string,callback:AsyncCallback<void>):void
delete(key:string):Promise<void> | 删除数据。 | -| get(key:string,callback:AsyncCallback<Uint8Array\|string\|boolean\|number>):void
get(key:string):Promise<Uint8Array\|string\|boolean\|number> | 查询数据。 | -| on(event:'dataChange',type:SubscribeType,observer:Callback<ChangeNotification>):void
on(event:'syncComplete',syncCallback:Callback<Array<[string,number]>>):void | 订阅数据库中数据的变化。 | -| sync(deviceIdList:string[],mode:SyncMode,allowedDelayMs?:number):void | 在手动模式下，触发数据库同步。 | +| createKVManager(config: KVManagerConfig, callback: AsyncCallback<KVManager>): void
createKVManager(config: KVManagerConfig): Promise<KVManager> | 创建一个`KVManager`对象实例，用于管理数据库对象。 | +| getKVStore<TextendsKVStore>(storeId: string, options: Options, callback: AsyncCallback<T>): void
getKVStore<TextendsKVStore>(storeId: string, options: Options): Promise<T> | 指定`Options`和`storeId`，创建并获取`KVStore`数据库。 | +| put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback<void>): void
put(key: string, value: Uint8Array\|string\|number\|boolean): Promise<void> | 插入和更新数据。 | +| delete(key: string, callback: AsyncCallback<void>): void
delete(key: string): Promise<void> | 删除数据。 | +| get(key: string, callback: AsyncCallback<Uint8Array\|string\|boolean\|number>): void
get(key: string): Promise<Uint8Array\|string\|boolean\|number> | 查询数据。 | +| on(event: 'dataChange', type: SubscribeType, observer: Callback<ChangeNotification>): void
on(event: 'syncComplete', syncCallback: Callback<Array<[string,number]>>): void | 订阅数据库中数据的变化。 | +| sync(deviceIdList: string[], mode: SyncMode, allowedDelayMs?: number): void | 在手动模式下，触发数据库同步。 | @@ -34,8 +34,40 @@ ```js import distributedData from '@ohos.data.distributedData'; ``` +2. 请求权限（同步操作时进行该步骤）。 -2. 根据配置构造分布式数据库管理类实例。 + 需要在`config.json`文件里进行配置请求权限，示例代码如下： + + ```json + { + "module": { + "reqPermissions": [ + { + "name": "ohos.permission.DISTRIBUTED_DATASYNC" + } + ] + } + } + ``` + 这个权限还需要在应用首次启动的时候弹窗获取用户授权，可以通过如下代码实现： + + ```js + import featureAbility from '@ohos.ability.featureAbility'; + + function grantPermission() { + console.info('grantPermission'); + let context = featureAbility.getContext(); + context.requestPermissionsFromUser(['ohos.permission.DISTRIBUTED_DATASYNC'], 666, function (result) { + console.info(`result.requestCode=${result.requestCode}`) + + }) + console.info('end grantPermission'); + } + + grantPermission(); + ``` + +3. 根据配置构造分布式数据库管理类实例。 1. 根据应用上下文创建`kvManagerConfig`对象。 2. 创建分布式数据库管理器实例。 @@ -64,7 +96,7 @@ } ``` -3. 获取/创建分布式数据库。 +4. 获取/创建分布式数据库。 1. 声明需要创建的分布式数据库ID描述。 2. 创建分布式数据库，建议关闭自动同步功能（`autoSync:false`），需要同步时主动调用`sync`接口。 @@ -98,7 +130,7 @@ > > 组网设备间同步数据的场景，建议在应用启动时打开分布式数据库，获取数据库的句柄。在该句柄（如示例中的`kvStore`）的生命周期内无需重复创建数据库，可直接使用句柄对数据库进行数据的插入等操作。 -4. 订阅分布式数据变化。 +5. 订阅分布式数据变化。 以下为订阅单版本分布式数据库数据变化通知的代码示例: ```js @@ -107,7 +139,7 @@ }); ``` -5. 将数据写入分布式数据库。 +6. 将数据写入分布式数据库。 1. 构造需要写入分布式数据库的`Key`（键）和`Value`（值）。 2. 将键值数据写入分布式数据库。 @@ -130,7 +162,7 @@ } ``` -6. 查询分布式数据库数据。 +7. 查询分布式数据库数据。 1. 构造需要从单版本分布式数据库中查询的`Key`（键）。 2. 从单版本分布式数据库中获取数据。 @@ -155,7 +187,7 @@ } ``` -7. 同步数据到其他设备。 +8. 同步数据到其他设备。 选择同一组网环境下的设备以及同步模式，进行数据同步。 diff --git a/zh-cn/application-dev/database/database-relational-guidelines.md b/zh-cn/application-dev/database/database-relational-guidelines.md index f60d4a06d6cbd0d68e1be99fccd268f32a6200e2..3a10ebb1d43ba88f9b4ff788232163c0b1e8c9c7 100644 --- a/zh-cn/application-dev/database/database-relational-guidelines.md +++ b/zh-cn/application-dev/database/database-relational-guidelines.md @@ -16,8 +16,8 @@ | 接口名 | 描述 | | -------- | -------- | -|getRdbStore(config:StoreConfig,version:number):Promise<RdbStore> | 获得一个相关的RdbStore，操作关系型数据库，用户可以根据自己的需求配置RdbStore的参数，然后通过RdbStore调用相关接口可以执行相关的数据操作，使用Promise异步回调。
-config：与此RDB存储相关的数据库配置。
-version：数据库版本。 | -| deleteRdbStore(name:string):Promise<void> | 使用指定的数据库文件配置删除数据库，使用Promise异步回调。
-name：数据库名称。 | +|getRdbStore(config: StoreConfig, version: number): Promise<RdbStore> | 获得一个相关的RdbStore，操作关系型数据库，用户可以根据自己的需求配置RdbStore的参数，然后通过RdbStore调用相关接口可以执行相关的数据操作，使用Promise异步回调。
-config：与此RDB存储相关的数据库配置。
-version：数据库版本。 | +| deleteRdbStore(name: string): Promise<void> | 使用指定的数据库文件配置删除数据库，使用Promise异步回调。
-name：数据库名称。 | ### 数据库的增删改查 @@ -31,7 +31,7 @@ | 类名 | 接口名 | 描述 | | -------- | -------- | -------- | - | RdbStore | insert(name:string,values:ValuesBucket):Promise<number> | 向目标表中插入一行数据，使用Promise异步回调。
如果操作成功，返回行ID；否则返回-1。
-name：指定的目标表名。
-values：表示要插入到表中的数据行。 | + | RdbStore | insert(name: string, values: ValuesBucket): Promise<number> | 向目标表中插入一行数据，使用Promise异步回调。
如果操作成功，返回行ID；否则返回-1。
-name：指定的目标表名。
-values：表示要插入到表中的数据行。 | - **更新** @@ -41,7 +41,7 @@ | 类名 | 接口名 | 描述 | | -------- | -------- | -------- | - | RdbStore | update(values:ValuesBucket,rdbPredicates:RdbPredicates):Promise\ | 根据RdbPredicates的指定实例对象更新数据库中的数据，使用Promise异步回调。
返回受影响的行数。
-values：以ValuesBucket存储的要更新的数据。
-rdbPredicates：表示RdbPredicates的实例对象指定的更新条件。 | + | RdbStore | update(values: ValuesBucket, rdbPredicates: RdbPredicates): Promise\ | 根据RdbPredicates的指定实例对象更新数据库中的数据，使用Promise异步回调。
返回受影响的行数。
-values：以ValuesBucket存储的要更新的数据。
-rdbPredicates：表示RdbPredicates的实例对象指定的更新条件。 | - **删除** @@ -51,7 +51,7 @@ | 类名 | 接口名 | 描述 | | -------- | -------- | -------- | - | RdbStore | delete(rdbPredicates:RdbPredicates):Promise\ | 根据rdbPredicates的指定实例对象从数据库中删除数据，使用Promise异步回调。
返回受影响的行数。
-rdbPredicates：RdbPredicates的实例对象指定的删除条件。 | + | RdbStore | delete(rdbPredicates: RdbPredicates): Promise\ | 根据rdbPredicates的指定实例对象从数据库中删除数据，使用Promise异步回调。
返回受影响的行数。
-rdbPredicates：RdbPredicates的实例对象指定的删除条件。 | - **查询** @@ -64,8 +64,8 @@ | 类名 | 接口名 | 描述 | | -------- | -------- | -------- | - | RdbStore | query(rdbPredicates:RdbPredicates,columns:Array):Promise<ResultSet> | 根据指定条件查询数据库中的数据，使用Promise异步回调。
-rdbPredicates：表示RdbPredicates的实例对象指定的查询条件。
-columns：表示要查询的列。如果值为空，则查询应用于所有列。 | - | RdbStore | querySql(sql:string,bindArgs?:Array<ValueType>):Promise<ResultSet> | 根据指定SQL语句查询数据库中的数据，使用Promise异步回调。
-sql：指定要查询的SQL语句。
-bindArgs：SQL语句中参数的值。 | + | RdbStore | query(rdbPredicates: RdbPredicates, columns: Array): Promise<ResultSet> | 根据指定条件查询数据库中的数据，使用Promise异步回调。
-rdbPredicates：表示RdbPredicates的实例对象指定的查询条件。
-columns：表示要查询的列。如果值为空，则查询应用于所有列。 | + | RdbStore | querySql(sql: string, bindArgs?: Array<ValueType>): Promise<ResultSet> | 根据指定SQL语句查询数据库中的数据，使用Promise异步回调。
-sql：指定要查询的SQL语句。
-bindArgs：SQL语句中参数的值。 | ### 数据库谓词的使用 @@ -77,11 +77,11 @@ | 类名 | 接口名 | 描述 | | -------- | -------- | -------- | -| RdbPredicates | equalTo(field:string,value:ValueType):RdbPredicates | 配置谓词以匹配数据字段为ValueType且值等于指定值的字段。
-field：数据库表中的列名。
-value：指示要与谓词匹配的值。
-RdbPredicates：返回与指定字段匹配的谓词。 | -| RdbPredicates | notEqualTo(field:string,value:ValueType):RdbPredicates | 配置谓词以匹配数据字段为ValueType且值不等于指定值的字段。
-field：数据库表中的列名。
-value：指示要与谓词匹配的值。
-RdbPredicates：返回与指定字段匹配的谓词。 | -| RdbPredicates | or():RdbPredicates | 将或条件添加到谓词中。
-RdbPredicates：返回带有或条件的谓词。 | -| RdbPredicates | and():RdbPredicates | 向谓词添加和条件。
-RdbPredicates：返回带有和条件的谓词。 | -| RdbPredicates | contains(field:string,value:string):RdbPredicats | 配置谓词以匹配数据字段为String且value包含指定值的字段。
-field：数据库表中的列名。
-value：指示要与谓词匹配的值。
-RdbPredicates：返回带有包含条件的谓词。 | +| RdbPredicates | equalTo(field: string, value: ValueType): RdbPredicates | 配置谓词以匹配数据字段为ValueType且值等于指定值的字段。
-field：数据库表中的列名。
-value：指示要与谓词匹配的值。
-RdbPredicates：返回与指定字段匹配的谓词。 | +| RdbPredicates | notEqualTo(field: string, value: ValueType): RdbPredicates | 配置谓词以匹配数据字段为ValueType且值不等于指定值的字段。
-field：数据库表中的列名。
-value：指示要与谓词匹配的值。
-RdbPredicates：返回与指定字段匹配的谓词。 | +| RdbPredicates | or(): RdbPredicates | 将或条件添加到谓词中。
-RdbPredicates：返回带有或条件的谓词。 | +| RdbPredicates | and(): RdbPredicates | 向谓词添加和条件。
-RdbPredicates：返回带有和条件的谓词。 | +| RdbPredicates | contains(field: string, value: string): RdbPredicats | 配置谓词以匹配数据字段为String且value包含指定值的字段。
-field：数据库表中的列名。
-value：指示要与谓词匹配的值。
-RdbPredicates：返回带有包含条件的谓词。 | ### 查询结果集的使用 @@ -97,12 +97,12 @@ | 类名 | 接口名 | 描述 | | -------- | -------- | -------- | -| ResultSet | goToFirstRow():boolean | 将结果集移动到第一行。 | -| ResultSet | getString(columnIndex:number):string | 获取当前行指定列的值，以String类型返回。 | -| ResultSet | getBlob(columnIndex:number):Uint8Array | 获取当前行指定列的值，以字节数组形式返回。 | -| ResultSet | getDouble(columnIndex:number):number | 获取当前行指定列的值，以double型返回。 | -| ResultSet | getLong(columnIndex:number):number | 获取当前行指定列的值，以Long形式返回。 | -| ResultSet | close():void | 关闭结果集。 | +| ResultSet | goToFirstRow(): boolean | 将结果集移动到第一行。 | +| ResultSet | getString(columnIndex:number): string | 获取当前行指定列的值，以String类型返回。 | +| ResultSet | getBlob(columnIndex:number): Uint8Array | 获取当前行指定列的值，以字节数组形式返回。 | +| ResultSet | getDouble(columnIndex:number): number | 获取当前行指定列的值，以double型返回。 | +| ResultSet | getLong(columnIndex:number): number | 获取当前行指定列的值，以Long形式返回。 | +| ResultSet | close(): void | 关闭结果集。 | diff --git a/zh-cn/application-dev/device/usb-guidelines.md b/zh-cn/application-dev/device/usb-guidelines.md index 8c836de6508cd2a01eeb76f4a74b93bba695db9c..02a0b2500f8446aebd7482eef124037bd1973be8 100644 --- a/zh-cn/application-dev/device/usb-guidelines.md +++ b/zh-cn/application-dev/device/usb-guidelines.md @@ -17,19 +17,19 @@ USB类开放能力如下，具体请查阅[API参考文档](../reference/apis/js | 接口名 | 描述 | | -------- | -------- | -| hasRight(deviceName:string):boolean | 如果“使用者”（如各种App或系统）有权访问设备则返回true；无权访问设备则返回false。 | -| requestRight(deviceName:string):Promise<boolean> | 请求给定软件包的临时权限以访问设备。 | -| connectDevice(device:USBDevice):Readonly<USBDevicePipe> | 根据`getDevices()`返回的设备信息打开USB设备。 | -| getDevices():Array<Readonly<USBDevice>> | 返回USB设备列表。 | -| setConfiguration(pipe:USBDevicePipe,config:USBConfig):number | 设置设备的配置。 | -| setInterface(pipe:USBDevicePipe,iface:USBInterface):number | 设置设备的接口。 | -| claimInterface(pipe:USBDevicePipe,iface:USBInterface,force?:boolean):number | 获取接口。 | -|bulkTransfer(pipe:USBDevicePipe,endpoint:USBEndpoint,buffer:Uint8Array,timeout?:number):Promise<number> | 批量传输。 | -| closePipe(pipe:USBDevicePipe):number | 关闭设备消息控制通道。 | -| releaseInterface(pipe:USBDevicePipe,iface:USBInterface):number | 释放接口。 | -| getFileDescriptor(pipe:USBDevicePipe):number | 获取文件描述符。 | -| getRawDescriptor(pipe:USBDevicePipe):Uint8Array | 获取原始的USB描述符。 | -| controlTransfer(pipe:USBDevicePipe,contrlparam:USBControlParams,timeout?:number):Promise<number> | 控制传输。 | +| hasRight(deviceName: string): boolean | 如果“使用者”（如各种App或系统）有权访问设备则返回true；无权访问设备则返回false。 | +| requestRight(deviceName: string): Promise<boolean> | 请求给定软件包的临时权限以访问设备。 | +| connectDevice(device: USBDevice): Readonly<USBDevicePipe> | 根据`getDevices()`返回的设备信息打开USB设备。 | +| getDevices(): Array<Readonly<USBDevice>> | 返回USB设备列表。 | +| setConfiguration(pipe: USBDevicePipe, config: USBConfig): number | 设置设备的配置。 | +| setInterface(pipe: USBDevicePipe, iface: USBInterface): number | 设置设备的接口。 | +| claimInterface(pipe: USBDevicePipe, iface: USBInterface, force?: boolean): number | 获取接口。 | +|bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout?: number): Promise<number> | 批量传输。 | +| closePipe(pipe: USBDevicePipe): number | 关闭设备消息控制通道。 | +| releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number | 释放接口。 | +| getFileDescriptor(pipe: USBDevicePipe): number | 获取文件描述符。 | +| getRawDescriptor(pipe: USBDevicePipe): Uint8Array | 获取原始的USB描述符。 | +| controlTransfer(pipe: USBDevicePipe, contrlparam: USBControlParams, timeout?: number): Promise<number> | 控制传输。 | ## 开发步骤 diff --git a/zh-cn/application-dev/device/usb-overview.md b/zh-cn/application-dev/device/usb-overview.md index 4b5b525645fd43beed25f740843ff900d27ea2d5..10732adccacaf2aaf9dc1664f7ae22a8b7d1ea65 100644 --- a/zh-cn/application-dev/device/usb-overview.md +++ b/zh-cn/application-dev/device/usb-overview.md @@ -9,7 +9,7 @@ USB服务是应用访问底层的一种设备抽象概念。开发者根据提 USB服务系统包含USB API、USB Service、USB HAL。 -**图2** USB服务运作机制 +**图1** USB服务运作机制 ![zh-cn_image_0000001237821727](figures/zh-cn_image_0000001237821727.png) diff --git a/zh-cn/application-dev/media/audio-recorder.md b/zh-cn/application-dev/media/audio-recorder.md index 85b07eaef0a61cf7e161c3c37a70928b2d1aa031..739116e193db4ad8f0519ffe6e4784301712d6b7 100644 --- a/zh-cn/application-dev/media/audio-recorder.md +++ b/zh-cn/application-dev/media/audio-recorder.md @@ -191,6 +191,5 @@ export class AudioRecorderDemo { 针对音频录制开发，有以下相关实例可供参考： - [`Recorder:`录音机（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/media/Recorder) -- [`JsRecorder`：录音机（JS）（API8)](https://gitee.com/openharmony/applications_app_samples/tree/master/media/JSRecorder) - [`eTsAudioPlayer`: 音频播放器（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/blob/master/media/Recorder/entry/src/main/ets/MainAbility/pages/Play.ets) - [音频播放器（eTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/Media/Audio_OH_ETS) diff --git a/zh-cn/application-dev/notification/background-agent-scheduled-reminder-guide.md b/zh-cn/application-dev/notification/background-agent-scheduled-reminder-guide.md index 12380b3370f08c172450ab403a5575920d471ba5..e79fc69f643862d720a36ee4c583c7254b8dbc7a 100644 --- a/zh-cn/application-dev/notification/background-agent-scheduled-reminder-guide.md +++ b/zh-cn/application-dev/notification/background-agent-scheduled-reminder-guide.md @@ -1,4 +1,4 @@ -# 开发指导 +# 后台提醒开发指导 ## 场景介绍 @@ -7,138 +7,33 @@ ## 接口说明 -reminderAgent：封装了发布、取消提醒类通知的方法 +reminderAgent：封装了发布、取消提醒类通知的方法。 + +具体后台提醒相关功能接口请见[后台代理提醒](../reference/apis/js-apis-reminderAgent.md)。 **表1** reminderAgent主要接口 | 接口名 | 描述 | | -------- | -------- | -| function publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void;
function publishReminder(reminderReq: ReminderRequest): Promise<number>; | 发布一个定时提醒类通知。
单个应用有效的提醒个数最多支持30个（不包括已经超时，即后续不会再提醒的提醒实例）
整个系统有效的提醒个数最多支持2000个（不包括已经超时，即后续不会再提醒的提醒实例） | -| function cancelReminder(reminderId: number, callback: AsyncCallback<void>): void;
function cancelReminder(reminderId: number): Promise<void>; | 取消一个指定的提醒类通知。(reminderId从publishReminder的返回值获取) | -| function getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void;
function getValidReminders(): Promise<Array<ReminderRequest>>; | 获取当前应用设置的所有有效的提醒。 | -| function cancelAllReminders(callback: AsyncCallback<void>): void;
function cancelAllReminders(): Promise<void>; | 取消当前应用设置的所有提醒 | -| function addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void;
function addNotificationSlot(slot: NotificationSlot): Promise<void>; | 注册一个提醒类需要使用的NotificationSlot | -| function removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void;
function removeNotificationSlot(slotType: notification.SlotType): Promise<void>; | 删除指定类型的NotificationSlot | - -enum ActionButtonType: 在提醒弹出的通知界面上的按钮的类型。 - -**表2** ActionButtonType 枚举类型 - -| 枚举名 | 描述 | -| -------- | -------- | -| ACTION_BUTTON_TYPE_CLOSE | 关闭按钮。关闭提醒的通知，取消延迟提醒。如果正在响铃，点击后会关闭当前提醒的铃声。 | -| ACTION_BUTTON_TYPE_SNOOZE | 延迟按钮。点击当前的提醒会延迟相应时间。 | - -enum ReminderType: 提醒类型 - -**表3** ReminderType 提醒类型枚举 - -| 枚举名 | 描述 | -| -------- | -------- | -| REMINDER_TYPE_TIMER | 指明是倒计时类型 | -| REMINDER_TYPE_CALENDAR | 指明是日历类型 | -| REMINDER_TYPE_ALARM | 指明是闹钟类型 | - -interface ActionButton：在提醒弹出的通知界面上的按钮实例 - -**表4** ActionButton - -| 参数名 | 类型 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -| title | string | 是 | 按钮上显示的名称 | -| type | ActionButtonType | 是 | 按钮的类型 | - -interface WantAgent: 设置点击通知后需要跳转的目标ability信息 - -**表5** WantAgent - -| 参数名 | 类型 | 是否必选 | 描述 | -| -------- | -------- | -------- | -------- | -| pkgName | string | 是 | 目标包的名称 | -| abilityName | string | 是 | 目标ability的名称 | - -interface MaxScreenWantAgent: 设置提醒到达时跳转的目标包。如果设备正在使用中，则弹出一个通知框 - -**表6** MaxScreenWantAgent - -| 参数名 | 类型 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -| pkgName | string | 是 | 目标包的名称 | -| abilityName | string | 是 | 目标ability的名称 | - -interface ReminderRequest: 需要发布的提醒实例的信息 - -**表7** ReminderRequest - -| 参数名 | 类型 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -| reminderType | ReminderType | 是 | 提醒的类型 | -| actionButton | [ActionButton?,ActionButton?] | 否 | 弹出的提醒通知栏中显示的按钮 | -| wantAgent | WantAgent | 否 | 点击通知后需要跳转的目标ability信息 | -| maxScreenWantAgent | MaxScreenWantAgent | 否 | 提醒到达时跳转的目标包。如果设备正在使用中，则弹出一个通知框 | -| ringDuration | number | 否 | 响铃时长 | -| snoozeTimes | number | 否 | 延迟提醒次数 | -| timeInterval | number | 否 | 延迟提醒间隔 | -| title | string | 否 | 提醒的标题 | -| content | string | 否 | 提醒的内容 | -| expiredContent | string | 否 | 提醒“过期”时显示的扩展内容 | -| snoozeContent | string | 否 | 提醒“再响”时显示的扩展内容 | -| notificationId | number | 否 | 提醒使用的notificationRequest的id，参见NotificationRequest.setNotificationId(int id) | -| slotType | SlotType | 否 | 提醒使用的slot类型 | - -interface ReminderRequestCalendar extends ReminderRequest: 日历类提醒实例。 - -如果没有指定重复的月或天，那么第一次指定的目标时间必须大于当前时间，否则应用将异常退出。 - -**表8** ReminderRequestCalendar - -| 参数名 | 类型 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -| dateTime | LocalDateTime | 是 | 设置目标时间(精确到分钟级别) | -| repeatMonths | Array<number> | 否 | 设置重复提醒的月份，范围从 1 到 12 | -| repeatDays | Array<number> | 否 | 设置重复提醒的日期，范围从 1 到 31 | - -interface ReminderRequestAlarm extends ReminderRequest: 闹钟类提醒实例。 - -**表9** ReminderRequestAlarm - -| 参数名 | 类型 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -| hour | number | 是 | 设置目标时间（小时），范围从 0 到 23 | -| minute | number | 是 | 设置目标时间（分钟），范围从 0 到 59 | -| daysOfWeek | Array<number> | 否 | 设置每个星期哪一天重复提醒，范围从 1 到 7 | - -interface ReminderRequestTimer extends ReminderRequest：倒计时提醒实例 - -**表10** ReminderRequestTimer - -| 参数名 | 类型 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -| triggerTimeInSeconds | number | 是 | 设置倒计时秒数 | - -interface LocalDateTime：时间信息实例 - -**表11** LocalDateTime - -| 参数名 | 类型 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -| year | number | 是 | 年 | -| month | number | 是 | 月 | -| day | number | 是 | 日 | -| hour | number | 是 | 时 | -| minute | number | 是 | 分 | -| second | number | 否 | 秒 | - +| publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void
publishReminder(reminderReq: ReminderRequest): Promise<number> | 发布一个定时提醒类通知。
单个应用有效的提醒个数最多支持30个（不包括已经超时，即后续不会再提醒的提醒实例）
整个系统有效的提醒个数最多支持2000个（不包括已经超时，即后续不会再提醒的提醒实例） | +| cancelReminder(reminderId: number, callback: AsyncCallback<void>): void
cancelReminder(reminderId: number): Promise<void> | 取消一个指定的提醒类通知。(reminderId从publishReminder的返回值获取) | +| getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void
getValidReminders(): Promise<Array<ReminderRequest>> | 获取当前应用设置的所有有效的提醒。 | +| cancelAllReminders(callback: AsyncCallback<void>): void
cancelAllReminders(): Promise<void> | 取消当前应用设置的所有提醒 | +| addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void
addNotificationSlot(slot: NotificationSlot): Promise<void> | 注册一个提醒类需要使用的NotificationSlot | +| removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void
removeNotificationSlot(slotType: notification.SlotType): Promise<void> | 删除指定类型的NotificationSlot | ## 开发步骤 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** -> 应用需要配置权限：ohos.permission.PUBLISH_AGENT_REMINDER +> +> 1. 应用需要配置权限：ohos.permission.PUBLISH_AGENT_REMINDER。 +> +> 2. 应用需要申请通知弹窗：[Notification.requestEnableNotification](../reference/apis/js-apis-notification.md#notificationrequestenablenotification8)。 -发布一个10秒倒计时提醒 +1. 定义一个提醒代理。 -1. 定义一个倒计时实例 - ``` + 倒计时实例定义： + ```js import reminderAgent from '@ohos.reminderAgent'; import notification from '@ohos.notification'; export default { @@ -171,8 +66,97 @@ interface LocalDateTime：时间信息实例 } ``` -2. 发布提醒 - ``` + 日历实例定义： + + ```js + // JS工程写法： + // calendar: { + // eTS工程写法： + let calendar : reminderAgent.ReminderRequestCalendar = { + reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR, + dateTime: { + year: 2050, + month: 7, + day: 30, + hour: 11, + minute: 14, + second: 30 + }, + repeatMonths: [1], + repeatDays: [1], + actionButton: [ + { + title: "close", + type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE + }, + { + title: "snooze", + type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE + }, + ], + wantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + maxScreenWantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + ringDuration: 5, + snoozeTimes: 2, + timeInterval: 5, + title: "this is title", + content: "this is content", + expiredContent: "this reminder has expired", + snoozeContent: "remind later", + notificationId: 100, + slotType: notification.SlotType.SOCIAL_COMMUNICATION + } + ``` + + 闹钟实例定义： + + ```js + // JS工程写法： + // alarm: { + // eTS工程写法： + let alarm : reminderAgent.ReminderRequestAlarm = { + reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM, + hour: 11, + minute: 14, + daysOfWeek: [0], + actionButton: [ + { + title: "close", + type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE + }, + { + title: "snooze", + type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE + }, + ], + wantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + maxScreenWantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + ringDuration: 5, + snoozeTimes: 2, + timeInterval: 5, + title: "this is title", + content: "this is content", + expiredContent: "this reminder has expired", + snoozeContent: "remind later", + notificationId: 100, + slotType: notification.SlotType.SOCIAL_COMMUNICATION + } + ``` + +2. 发布倒计时提醒。 + ```js startTimer() { reminderAgent.publishReminder(this.timer, (err, reminderId) =>{ this.printInfo(JSON.stringify(err)); @@ -181,103 +165,13 @@ interface LocalDateTime：时间信息实例 } ``` - html页面： - ``` + HML页面： + ```html
``` -日历实例定义： - -``` -// JS工程写法： -// calendar: { -// eTS工程写法： -let calendar : reminderAgent.ReminderRequestCalendar = { - reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR, - dateTime: { - year: 2050, - month: 7, - day: 30, - hour: 11, - minute: 14, - second: 30 - }, - repeatMonths: [1], - repeatDays: [1], - actionButton: [ - { - title: "close", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - }, - { - title: "snooze", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE - }, - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - ringDuration: 5, - snoozeTimes: 2, - timeInterval: 5, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - snoozeContent: "remind later", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION -} -``` - -闹钟实例定义： - -``` -// JS工程写法： -// alarm: { -// eTS工程写法： -let alarm : reminderAgent.ReminderRequestAlarm = { - reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM, - hour: 11, - minute: 14, - daysOfWeek: [0], - actionButton: [ - { - title: "close", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - }, - { - title: "snooze", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE - }, - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - ringDuration: 5, - snoozeTimes: 2, - timeInterval: 5, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - snoozeContent: "remind later", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION -} -``` - - ## 相关实例 基于后台代理提醒开发，有以下相关实例可供参考： diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md index 2961ee3c783d04e968ccc4398fe8b50ac27e8e22..c9729deab958b26754d49b727a4818a97343f468 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md +++ b/zh-cn/application-dev/reference/apis/js-apis-data-rdb.md @@ -29,7 +29,7 @@ getRdbStore(context: Context, config: StoreConfig, version: number, callback: As | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| context | Context | 是 | 应用程序或功能的上下文。
API version 9之前的Context定义见[Context](js-apis-Context.md)。
API version 9及之后的Context定义见[Context](js-apis-ability-context.md)。| +| context | [Context](js-apis-Context.md) | 是 | 应用上下文。| | config | [StoreConfig](#storeconfig) | 是 | 与此RDB存储相关的数据库配置。 | | version | number | 是 | 数据库版本。 | | callback | AsyncCallback<[RdbStore](#rdbstore)> | 是 | 指定callback回调函数，返回一个RdbStore。 | @@ -37,8 +37,13 @@ getRdbStore(context: Context, config: StoreConfig, version: number, callback: As **示例：** ```js +// 获取context +import featureAbility from '@ohos.ability.featureAbility' +var context = featureAbility.getContext() + +// 获取context后调用getRdbStore const STORE_CONFIG = { name: "RdbTest.db"} -data_rdb.getRdbStore(this.context, STORE_CONFIG, 1, function (err, rdbStore) { +data_rdb.getRdbStore(context, STORE_CONFIG, 1, function (err, rdbStore) { if (err) { console.info("Get RdbStore failed, err: " + err) return @@ -59,7 +64,7 @@ getRdbStore(context: Context, config: StoreConfig, version: number): Promise< | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| context | Context | 是 | 应用程序或功能的上下文。
API version 9之前的Context定义见[Context](js-apis-Context.md)。
API version 9及之后的Context定义见[Context](js-apis-ability-context.md)。 | +| context | [Context](js-apis-Context.md) | 是 | 应用上下文。 | | config | [StoreConfig](#storeconfig) | 是 | 与此RDB存储相关的数据库配置。 | | version | number | 是 | 数据库版本。 | @@ -72,8 +77,13 @@ getRdbStore(context: Context, config: StoreConfig, version: number): Promise< **示例：** ```js +// 获取context +import featureAbility from '@ohos.ability.featureAbility' +var context = featureAbility.getContext() + +// 获取context后调用getRdbStore const STORE_CONFIG = { name: "RdbTest.db" } -let promise = data_rdb.getRdbStore(this.context, STORE_CONFIG, 1); +let promise = data_rdb.getRdbStore(context, STORE_CONFIG, 1); promise.then(async (rdbStore) => { console.log("Get RdbStore successfully.") }).catch((err) => { @@ -92,13 +102,18 @@ deleteRdbStore(context: Context, name: string, callback: AsyncCallback<void&g **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| context | Context | 是 | 应用程序或功能的上下文。
API version 9之前的Context定义见[Context](js-apis-Context.md)。
API version 9及之后的Context定义见[Context](js-apis-ability-context.md)。| +| context | [Context](js-apis-Context.md) | 是 | 应用上下文。| | name | string | 是 | 数据库名称。 | | callback | AsyncCallback<void> | 是 | 指定callback回调函数。 | **示例：** ```js -data_rdb.deleteRdbStore(this.context, "RdbTest.db", function (err, rdbStore) { +// 获取context +import featureAbility from '@ohos.ability.featureAbility' +var context = featureAbility.getContext() + +// 获取context后调用deleteRdbStore +data_rdb.deleteRdbStore(context, "RdbTest.db", function (err) { if (err) { console.info("Delete RdbStore failed, err: " + err) return @@ -118,7 +133,7 @@ deleteRdbStore(context: Context, name: string): Promise<void> **参数** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| context | Context | 是 | 应用程序或功能的上下文。
API version 9之前的Context定义见[Context](js-apis-Context.md)。
API version 9及之后的Context定义见[Context](js-apis-ability-context.md)。| +| context | [Context](js-apis-Context.md) | 是 | 应用上下文。| | name | string | 是 | 数据库名称。 | **返回值**： @@ -128,7 +143,12 @@ deleteRdbStore(context: Context, name: string): Promise<void> **示例：** ```js -let promise = data_rdb.deleteRdbStore(this.context, "RdbTest.db") +// 获取context +import featureAbility from '@ohos.ability.featureAbility' +var context = featureAbility.getContext() + +// 获取context后调用deleteRdbStore +let promise = data_rdb.deleteRdbStore(context, "RdbTest.db") promise.then(()=>{ console.log("Delete RdbStore successfully.") }).catch((err) => { diff --git a/zh-cn/application-dev/reference/apis/js-apis-mediaquery.md b/zh-cn/application-dev/reference/apis/js-apis-mediaquery.md index 1eabfdf4b161a24fa2031fd187ebca5b729e15a5..a2d2dbe01565bb7c553bcf640de3115182381645 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-mediaquery.md +++ b/zh-cn/application-dev/reference/apis/js-apis-mediaquery.md @@ -87,7 +87,7 @@ off(type: 'change', callback?: Callback<MediaQueryResult>): void | callback | Callback<MediaQueryResult> | 否 | 需要去注册的回调，如果参数缺省则去注册该句柄下所有的回调。 | **示例：** - ```js + ```ts import mediaquery from '@ohos.mediaquery' let listener = mediaquery.matchMediaSync('(orientation: landscape)'); //监听横屏事件 @@ -116,11 +116,9 @@ off(type: 'change', callback?: Callback<MediaQueryResult>): void ### 示例 -```js +```ts import mediaquery from '@ohos.mediaquery' -let portraitFunc = null - @Entry @Component struct MediaQueryExample { @@ -139,7 +137,7 @@ struct MediaQueryExample { } aboutToAppear() { - portraitFunc = this.onPortrait.bind(this) //bind current js instance + let portraitFunc = this.onPortrait.bind(this) //bind current js instance this.listener.on('change', portraitFunc) } diff --git a/zh-cn/application-dev/reference/apis/js-apis-pasteboard.md b/zh-cn/application-dev/reference/apis/js-apis-pasteboard.md index d70a37d429d98dbe4bc1478939fe8b8165cdead5..272a9ee2aaf94b0f65e7b708266f8731167e5b96 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-pasteboard.md +++ b/zh-cn/application-dev/reference/apis/js-apis-pasteboard.md @@ -1,29 +1,28 @@ # 剪贴板 +本模块主要提供管理系统剪贴板的能力，为系统复制、粘贴功能提供支持。系统剪贴板支持对文本、HTML、URI、Want等内容的操作。 -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** +> > 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 - ## 导入模块 - -``` +```js import pasteboard from '@ohos.pasteboard'; ``` - ## 属性 -**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Pasteboard。 +**系统能力：** SystemCapability.MiscServices.Pasteboard -| 名称 | 参数类型 | 可读 | 可写 | 说明 | -| -------- | -------- | -------- | -------- | -------- | -| MAX_RECORD_NUM7+ | number | 是 | 否 | 单个PasteData中所能包含的Record的数量上限。 | -| MIMETYPE_TEXT_HTML7+ | string | 是 | 否 | HTML text文本的MIME类型定义。 | -| MIMETYPE_TEXT_WANT7+ | string | 是 | 否 | Want的MIME类型定义。 | -| MIMETYPE_TEXT_PLAIN7+ | string | 是 | 否 | Plain text文本的MIME类型定义。 | -| MIMETYPE_TEXT_URI7+ | string | 是 | 否 | URI文本的MIME类型定义。 | +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------------------------------- | -------- | ---- | ---- | ------------------------------------- | +| MAX_RECORD_NUM7+ | number | 是 | 否 | 单个PasteData中所能包含的最大条目数。 | +| MIMETYPE_TEXT_HTML7+ | string | 是 | 否 | HTML内容的MIME类型定义。 | +| MIMETYPE_TEXT_WANT7+ | string | 是 | 否 | Want内容的MIME类型定义。 | +| MIMETYPE_TEXT_PLAIN7+ | string | 是 | 否 | 纯文本内容的MIME类型定义。 | +| MIMETYPE_TEXT_URI7+ | string | 是 | 否 | URI内容的MIME类型定义。 | ## pasteboard.createPlainTextData @@ -32,78 +31,84 @@ createPlainTextData(text:string): PasteData 构建一个纯文本剪贴板内容对象。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| text | string | 是 | 纯文本数据。 | +**参数：** -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| [PasteData](#pastedata) | 包含此内容的剪贴板内容对象。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------ | +| text | string | 是 | 纯文本内容。 | -**示例** +**返回值：** - ```js - var pasteData = pasteboard.createPlainTextData("content"); - ``` +| 类型 | 说明 | +| ----------------------- | ---------------- | +| [PasteData](#pastedata) | 剪贴板内容对象。 | + +**示例：** + +```js +var pasteData = pasteboard.createPlainTextData("content"); +``` ## pasteboard.createHtmlData7+ createHtmlData(htmlText:string): PasteData -构建一个html文本剪贴板内容对象。 +构建一个HTML剪贴板内容对象。 + +**系统能力：** SystemCapability.MiscServices.Pasteboard -**系统能力**: SystemCapability.MiscServices.Pasteboard +**参数：** -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| htmlText | string | 是 | 待保存的HTML文本内容。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ---------- | +| htmlText | string | 是 | HTML内容。 | -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| [PasteData](#pastedata) | 包含此内容的剪贴板内容对象。 | +**返回值：** -**示例** +| 类型 | 说明 | +| ----------------------- | ---------------- | +| [PasteData](#pastedata) | 剪贴板内容对象。 | - ```js - var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; - var pasteData = pasteboard.createHtmlData(html); - ``` +**示例：** + +```js +var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; +var pasteData = pasteboard.createHtmlData(html); +``` ## pasteboard.createWantData7+ createWantData(want:Want): PasteData -构建一个want剪贴板内容对象。 +构建一个Want剪贴板内容对象。 + +**系统能力：** SystemCapability.MiscServices.Pasteboard + +**参数：** -**系统能力**: SystemCapability.MiscServices.Pasteboard +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------------------------- | ---- | ---------- | +| want | [Want](js-apis-featureAbility.md#want) | 是 | Want内容。 | -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| want | [Want](js-apis-featureAbility.md#want) | 是 | 待保存的Want内容。 | +**返回值：** -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| [PasteData](#pastedata) | 包含此内容的剪贴板内容对象。 | +| 类型 | 说明 | +| ----------------------- | ---------------- | +| [PasteData](#pastedata) | 剪贴板内容对象。 | -**示例** +**示例：** - ```js - var object = { - bundleName: "com.example.aafwk.test", - abilityName: "com.example.aafwk.test.TwoAbility" - }; - var pasteData = pasteboard.createWantData(object); - ``` +```js +var object = { + bundleName: "com.example.aafwk.test", + abilityName: "com.example.aafwk.test.TwoAbility" +}; +var pasteData = pasteboard.createWantData(object); +``` ## pasteboard.createUriData7+ @@ -112,48 +117,51 @@ createUriData(uri:string): PasteData 构建一个URI剪贴板内容对象。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard + +**参数：** -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| uri | string | 是 | 待保存的URI内容。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | --------- | +| uri | string | 是 | URI内容。 | -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| [PasteData](#pastedata) | 包含此内容的剪贴板内容对象。 | +**返回值：** -**示例** +| 类型 | 说明 | +| ----------------------- | ---------------- | +| [PasteData](#pastedata) | 剪贴板内容对象。 | - ```js - var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt"); - ``` +**示例：** +```js +var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt"); +``` ## pasteboard.createPlainTextRecord7+ createPlainTextRecord(text:string): PasteDataRecord -创建一条文本类型的内容条目。 +创建一条纯文本内容条目。 + +**系统能力：** SystemCapability.MiscServices.Pasteboard -**系统能力**: SystemCapability.MiscServices.Pasteboard +**参数：** -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| text | string | 是 | 纯文本内容。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------ | +| text | string | 是 | 纯文本内容。 | -**返回值** -| 类型 | 说明 | -| -------- | -------- | +**返回值：** + +| 类型 | 说明 | +| ------------------------------------ | -------------------------- | | [PasteDataRecord](#pastedatarecord7) | 一条新建的纯文本内容条目。 | -**示例** +**示例：** - ```js - var record = pasteboard.createPlainTextRecord("hello"); - ``` +```js +var record = pasteboard.createPlainTextRecord("hello"); +``` ## pasteboard.createHtmlTextRecord7+ @@ -162,24 +170,26 @@ createHtmlTextRecord(htmlText:string): PasteDataRecord 创建一条HTML内容的条目。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ---------- | +| htmlText | string | 是 | HTML内容。 | -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| htmlText | string | 是 | HTML内容。 | +**返回值：** -**返回值** -| 类型 | 说明 | -| -------- | -------- | +| 类型 | 说明 | +| ------------------------------------ | ------------------------ | | [PasteDataRecord](#pastedatarecord7) | 一条新建的HTML内容条目。 | -**示例** +**示例：** - ```js - var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; - var record = pasteboard.createHtmlTextRecord(html); - ``` +```js +var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; +var record = pasteboard.createHtmlTextRecord(html); +``` ## pasteboard.createWantRecord7+ @@ -188,28 +198,29 @@ createWantRecord(want:Want): PasteDataRecord 创建一条Want内容条目。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard + +**参数：** -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| want | [Want](js-apis-featureAbility.md#want) | 是 | Want类型数据。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------------------------- | ---- | ---------- | +| want | [Want](js-apis-featureAbility.md#want) | 是 | Want内容。 | -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| [PasteDataRecord](#pastedatarecord7) | 一条新建的Want内容条目 | +**返回值：** -**示例** +| 类型 | 说明 | +| ------------------------------------ | ------------------------ | +| [PasteDataRecord](#pastedatarecord7) | 一条新建的Want内容条目。 | - ```js - var object = { - bundleName: "com.example.aafwk.test", - abilityName: "com.example.aafwk.test.TwoAbility" - }; - var record = pasteboard.createWantRecord(object); - ``` +**示例：** +```js +var object = { + bundleName: "com.example.aafwk.test", + abilityName: "com.example.aafwk.test.TwoAbility" +}; +var record = pasteboard.createWantRecord(object); +``` ## pasteboard.createUriRecord7+ @@ -217,38 +228,60 @@ createUriRecord(uri:string): PasteDataRecord 创建一条URI内容的条目。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard + +**参数：** -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| uri | string | 是 | URI内容。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | --------- | +| uri | string | 是 | URI内容。 | -**返回值** -| 类型 | 说明 | -| -------- | -------- | +**返回值：** + +| 类型 | 说明 | +| ------------------------------------ | ----------------------- | | [PasteDataRecord](#pastedatarecord7) | 一条新建的URI内容条目。 | -**示例** +**示例：** + +```js +var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt"); +``` + +## pasteboard.getSystemPasteboard + +getSystemPasteboard(): SystemPasteboard + +获取系统剪贴板对象。 - ```js - var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt"); - ``` +**系统能力：** SystemCapability.MiscServices.Pasteboard + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------- | ---------------- | +| [SystemPasteboard](#systempasteboard) | 系统剪切板对象。 | + +**示例：** + +```js +var systemPasteboard = pasteboard.getSystemPasteboard(); +``` ## PasteDataProperty7+ 定义了剪贴板中所有内容条目的属性，包含时间戳、数据类型以及一些附加数据等。 -**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Pasteboard。 +**系统能力：** SystemCapability.MiscServices.Pasteboard -| 名称 | 参数类型 | 可读 | 可写 | 说明 | -| -------- | -------- | -------- | -------- | -------- | -| additions | {[key: string]: object} | 是 | 是 | 设置的其他附加属性数据。 | -| mimeTypes | Array<string> | 是 | 否 | 剪贴板内容条目的数据类型, 非重复的类型列表。 | -| tag | string | 是 | 是 | 用户自定义标签。 | -| timestamp | number | 是 | 否 | 剪贴板数据的写入时间戳（毫秒）。 | -| localOnly | boolean | 是 | 是 | 配置剪贴板内容的“仅在本地”标志位。
- 默认情况为true。
- 配置为true时，表示内容仅在本地，不会在设备之间传递。
- 配置为false时，表示内容将在设备间传递。 | +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| --------- | --------------------- | ---- | ---- | ------------------------------------------------------------ | +| additions | {[key:string]:object} | 是 | 是 | 设置的其他附加属性数据。 | +| mimeTypes | Array<string> | 是 | 否 | 剪贴板内容条目的数据类型，非重复的类型列表。 | +| tag | string | 是 | 是 | 用户自定义标签。 | +| timestamp | number | 是 | 否 | 剪贴板数据的写入时间戳（单位：ms）。 | +| localOnly | boolean | 是 | 是 | 配置剪贴板内容是否为“仅在本地”。默认值为true。
- 配置为true时，表示内容仅在本地，不会在设备之间传递。
- 配置为false时，表示内容将在设备间传递。 | ## PasteDataRecord7+ @@ -258,74 +291,78 @@ createUriRecord(uri:string): PasteDataRecord ### 属性 -**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Pasteboard。 +**系统能力：** SystemCapability.MiscServices.Pasteboard -| 名称 | 参数类型 | 可读 | 可写 | 说明 | -| -------- | -------- | -------- | -------- | -------- | -| htmlText7+ | string | 是 | 否 | HTML文本内容。 | -| want7+ | [Want](js-apis-featureAbility.md#want) | 是 | 否 | Want文本内容。 | -| mimeType7+ | string | 是 | 否 | 数据类型。 | -| plainText7+ | string | 是 | 否 | 文本内容。 | -| uri7+ | string | 是 | 否 | URI内容。 | +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| ---------------------- | ----------------------------------- | ---- | ---- | ------------ | +| htmlText7+ | string | 是 | 否 | HTML内容。 | +| want7+ | [Want](js-apis-featureAbility.md#want) | 是 | 否 | Want内容。 | +| mimeType7+ | string | 是 | 否 | 数据类型。 | +| plainText7+ | string | 是 | 否 | 纯文本内容。 | +| uri7+ | string | 是 | 否 | URI内容。 | ### convertToText7+ convertToText(): Promise<string> -实例方法，将一个PasteData中的内容强制转换为文本内容，并使用Promise异步方式返回结果。 +将一个PasteData中的内容强制转换为文本内容，使用Promise异步回调。 + +**系统能力：** SystemCapability.MiscServices.Pasteboard -**系统能力**: SystemCapability.MiscServices.Pasteboard +**返回值：** -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| Promise<void> | 异步回调函数，调用成功则返回强制转换的文本内容，调用失败则返回error信息。 | +| 类型 | 说明 | +| --------------------- | ------------------------------------- | +| Promise<string> | Promise对象，返回强制转换的文本内容。 | -**示例** +**示例：** - ```js - var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt"); - record.convertToText().then((data) => { - console.info('convertToText success data : ' + JSON.stringify(data)); - }).catch((error) => { - console.error('convertToText failed because ' + JSON.stringify(error)); - }); - ``` +```js +var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt"); +record.convertToText().then((data) => { + console.info('Succeeded in converting to text. Data: ' + JSON.stringify(data)); +}).catch((err) => { + console.error('Failed to convert to text. Cause: ' + JSON.stringify(err)); +}); +``` ### convertToText7+ convertToText(callback: AsyncCallback<string>): void -实例方法，将一个PasteData中的内容强制转换为文本内容，并使用callback方式返回结果。 +将一个PasteData中的内容强制转换为文本内容，使用callback异步回调。 + +**系统能力：** SystemCapability.MiscServices.Pasteboard -**系统能力**: SystemCapability.MiscServices.Pasteboard +**参数：** -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<string> | 是 | 回调函数，调用成功则返回强制转换的文本内容，调用失败则返回error信息。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------------------------------------------ | +| callback | AsyncCallback<string> | 是 | 回调函数，当转换成功，err为undefined，data为强制转换的文本内容；否则返回错误信息。 | -**示例** +**示例：** - ```js - var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt"); - record.convertToText((err, data) => { - if (err) { - console.error('convertToText failed because ' + JSON.stringify(err)); - return; - } - console.info('convertToText success data : ' + JSON.stringify(data)); - }); - ``` +```js +var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt"); +record.convertToText((err, data) => { + if (err) { + console.error('Failed to convert to text. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in converting to text. Data: ' + JSON.stringify(data)); +}); +``` ## PasteData +剪贴板内容对象。 + 在调用PasteData的接口前，需要先获取一个PasteData对象。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard ### getPrimaryText @@ -336,42 +373,44 @@ getPrimaryText(): string 获取首个条目的纯文本内容。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard + +**返回值：** -**返回值** -| 类型 | 说明 | -| -------- | -------- | +| 类型 | 说明 | +| ------ | ------------ | | string | 纯文本内容。 | -**示例** +**示例：** - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - var plainText = pasteData.getPrimaryText(); - ``` +```js +var pasteData = pasteboard.createPlainTextData("hello"); +var plainText = pasteData.getPrimaryText(); +``` ### getPrimaryHtml7+ getPrimaryHtml(): string -获取首个条目的HTML文本内容。 +获取首个条目的HTML内容。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| string | HTML文本数据。 | +**返回值：** -**示例** +| 类型 | 说明 | +| ------ | ---------- | +| string | HTML内容。 | - ```js - var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; - var pasteData = pasteboard.createHtmlData(html); - var htmlText = pasteData.getPrimaryHtml(); - ``` +**示例：** + +```js +var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; +var pasteData = pasteboard.createHtmlData(html); +var htmlText = pasteData.getPrimaryHtml(); +``` ### getPrimaryWant7+ @@ -380,44 +419,46 @@ getPrimaryWant(): Want 获取首个条目的Want对象内容。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard + +**返回值：** -**返回值** -| 类型 | 说明 | -| -------- | -------- | +| 类型 | 说明 | +| ----------------------------------- | -------------- | | [Want](js-apis-featureAbility.md#want) | Want对象内容。 | -**示例** +**示例：** - ```js - var object = { - bundleName: "com.example.aafwk.test", - abilityName: "com.example.aafwk.test.TwoAbility" - }; - var pasteData = pasteboard.createWantData(object); - var want = pasteData.getPrimaryWant(); - ``` +```js +var object = { + bundleName: "com.example.aafwk.test", + abilityName: "com.example.aafwk.test.TwoAbility" +}; +var pasteData = pasteboard.createWantData(object); +var want = pasteData.getPrimaryWant(); +``` ### getPrimaryUri7+ getPrimaryUri(): string -获取首个条目的URI文本内容。 +获取首个条目的URI内容。 + +**系统能力：** SystemCapability.MiscServices.Pasteboard -**系统能力**: SystemCapability.MiscServices.Pasteboard +**返回值：** -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| string | URI文本内容。 | +| 类型 | 说明 | +| ------ | --------- | +| string | URI内容。 | -**示例** +**示例：** - ```js - var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt"); - var uri = pasteData.getPrimaryUri(); - ``` +```js +var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt"); +var uri = pasteData.getPrimaryUri(); +``` ### addTextRecord7+ @@ -428,43 +469,45 @@ addTextRecord(text: string): void 剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard + +**参数：** -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| text | string | 是 | 纯文本内容。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------ | +| text | string | 是 | 纯文本内容。 | -**示例** +**示例：** - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - pasteData.addTextRecord("good"); - ``` +```js +var pasteData = pasteboard.createPlainTextData("hello"); +pasteData.addTextRecord("good"); +``` ### addHtmlRecord7+ addHtmlRecord(htmlText: string): void -向当前剪贴板内容中添加一条HTML文本条目，并将MIMETYPE_TEXT_HTML添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空，否则添加失败。 +向当前剪贴板内容中添加一条HTML内容条目，并将MIMETYPE_TEXT_HTML添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空，否则添加失败。 剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| htmlText | string | 是 | HTML格式的文本内容。 | +**参数：** -**示例** +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ---------- | +| htmlText | string | 是 | HTML内容。 | - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; - pasteData.addHtmlRecord(html); - ``` +**示例：** + +```js +var pasteData = pasteboard.createPlainTextData("hello"); +var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; +pasteData.addHtmlRecord(html); +``` ### addWantRecord7+ @@ -475,23 +518,24 @@ addWantRecord(want: Want): void 剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard + +**参数：** -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| want | [Want](js-apis-featureAbility.md#want) | 是 | Want对象内容。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------------------------- | ---- | -------------- | +| want | [Want](js-apis-featureAbility.md#want) | 是 | Want对象内容。 | -**示例** +**示例：** - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - var object = { - bundleName: "com.example.aafwk.test", - abilityName: "com.example.aafwk.test.TwoAbility" - }; - pasteData.addWantRecord(object); - ``` +```js +var pasteData = pasteboard.createPlainTextData("hello"); +var object = { + bundleName: "com.example.aafwk.test", + abilityName: "com.example.aafwk.test.TwoAbility" +}; +pasteData.addWantRecord(object); +``` ### addUriRecord7+ @@ -502,19 +546,20 @@ addUriRecord(uri: string): void 剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| uri | string | 是 | URI文本内容。 | +**参数：** -**示例** +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | --------- | +| uri | string | 是 | URI内容。 | - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - pasteData.addUriRecord("dataability:///com.example.myapplication1?user.txt"); - ``` +**示例：** + +```js +var pasteData = pasteboard.createPlainTextData("hello"); +pasteData.addUriRecord("dataability:///com.example.myapplication1/user.txt"); +``` ### addRecord7+ @@ -525,24 +570,24 @@ addRecord(record: PasteDataRecord): void 剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| record | [PasteDataRecord](#pastedatarecord7) | 是 | 待添加的条目。 | +**参数：** -**示例** +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------------------ | ---- | -------------- | +| record | [PasteDataRecord](#pastedatarecord7) | 是 | 待添加的条目。 | - ```js - var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt"); - var textRecord = pasteboard.createPlainTextRecord("hello"); - var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; - var htmlRecord = pasteboard.createHtmlTextRecord(html); - pasteData.addRecord(textRecord); - pasteData.addRecord(htmlRecord); - ``` +**示例：** +```js +var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt"); +var textRecord = pasteboard.createPlainTextRecord("hello"); +var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; +var htmlRecord = pasteboard.createHtmlTextRecord(html); +pasteData.addRecord(textRecord); +pasteData.addRecord(htmlRecord); +``` ### getMimeTypes7+ @@ -550,236 +595,227 @@ getMimeTypes(): Array<string> 获取剪贴板中[PasteDataProperty](#pastedataproperty7)的mimeTypes列表，当剪贴板内容为空时，返回列表为空。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| Array<string> | 非重复的类型列表。 | +**返回值：** -**示例** +| 类型 | 说明 | +| ------------------- | -------------------------------------------- | +| Array<string> | 剪贴板内容条目的数据类型，非重复的类型列表。 | - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - var types = pasteData.getMimeTypes(); - ``` +**示例：** +```js +var pasteData = pasteboard.createPlainTextData("hello"); +var types = pasteData.getMimeTypes(); +``` ### getPrimaryMimeType7+ getPrimaryMimeType(): string -获取首个条目的数据类型。 +获取剪贴板内容中首个条目的数据类型。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| string | 首个条目的数据类型。 | +**返回值：** -**示例** +| 类型 | 说明 | +| ------ | -------------------- | +| string | 首个条目的数据类型。 | - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - var type = pasteData.getPrimaryMimeType(); - ``` +**示例：** +```js +var pasteData = pasteboard.createPlainTextData("hello"); +var type = pasteData.getPrimaryMimeType(); +``` ### getProperty7+ getProperty(): PasteDataProperty -获取属性描述对象。 +获取剪贴板内容的属性描述对象。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| [PasteDataProperty](#pastedataproperty7) | 属性描述对象。 | +**返回值：** -**示例** +| 类型 | 说明 | +| ---------------------------------------- | -------------- | +| [PasteDataProperty](#pastedataproperty7) | 属性描述对象。 | - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - var property = pasteData.getProperty(); - ``` +**示例：** +```js +var pasteData = pasteboard.createPlainTextData("hello"); +var property = pasteData.getProperty(); +``` ### getRecordAt7+ getRecordAt(index: number): PasteDataRecord -获取指定下标的条目。 +获取剪贴板内容中指定下标的条目。 + +**系统能力：** SystemCapability.MiscServices.Pasteboard + +**参数：** -**系统能力**: SystemCapability.MiscServices.Pasteboard +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------- | +| index | number | 是 | 指定条目的下标。 | -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| index | number | 是 | 指定条目的下标。 | +**返回值：** -**返回值** -| 类型 | 说明 | -| -------- | -------- | +| 类型 | 说明 | +| ------------------------------------ | ---------------- | | [PasteDataRecord](#pastedatarecord7) | 指定下标的条目。 | -**示例** +**示例：** - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - var record = pasteData.getRecordAt(0); - ``` +```js +var pasteData = pasteboard.createPlainTextData("hello"); +var record = pasteData.getRecordAt(0); +``` ### getRecordCount7+ getRecordCount(): number -获取剪贴板中条目的个数。 +获取剪贴板内容中条目的个数。 + +**系统能力：** SystemCapability.MiscServices.Pasteboard -**系统能力**: SystemCapability.MiscServices.Pasteboard +**返回值：** -**返回值** -| 类型 | 说明 | -| -------- | -------- | +| 类型 | 说明 | +| ------ | ------------ | | number | 条目的个数。 | -**示例** +**示例：** - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - var count = pasteData.getRecordCount(); - ``` +```js +var pasteData = pasteboard.createPlainTextData("hello"); +var count = pasteData.getRecordCount(); +``` ### getTag7+ getTag(): string -获取用户自定义的标签内容，如果没有设置用户自定义的标签内容将返回空。 +获取剪贴板内容中用户自定义的标签内容，如果没有设置用户自定义的标签内容将返回空。 + +**系统能力：** SystemCapability.MiscServices.Pasteboard -**系统能力**: SystemCapability.MiscServices.Pasteboard +**返回值：** -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| string | 获取用户自定义的标签内容，如果没有设置用户自定义的标签内容将返回空。 | +| 类型 | 说明 | +| ------ | ------------------------------------------------------------ | +| string | 返回用户自定义的标签内容，如果没有设置用户自定义的标签内容，将返回空。 | -**示例** +**示例：** - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - var tag = pasteData.getTag(); - ``` +```js +var pasteData = pasteboard.createPlainTextData("hello"); +var tag = pasteData.getTag(); +``` ### hasMimeType7+ hasMimeType(mimeType: string): boolean -检查内容中是否有指定的数据类型。 +检查剪贴板内容中是否有指定的数据类型。 + +**系统能力：** SystemCapability.MiscServices.Pasteboard -**系统能力**: SystemCapability.MiscServices.Pasteboard +**参数：** -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| mimeType | string | 是 | 待查询的数据类型。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------------ | +| mimeType | string | 是 | 待查询的数据类型。 | -**返回值** -| 类型 | 说明 | -| -------- | -------- | +**返回值：** + +| 类型 | 说明 | +| ------- | ----------------------------------------- | | boolean | 有指定的数据类型返回true，否则返回false。 | -**示例** +**示例：** - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - var hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN); - ``` +```js +var pasteData = pasteboard.createPlainTextData("hello"); +var hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN); +``` ### removeRecordAt7+ removeRecordAt(index: number): boolean -移除指定下标的条目。 +移除剪贴板内容中指定下标的条目。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| index | number | 是 | 指定的下标。 | +**参数：** -**返回值** -| 类型 | 说明 | -| -------- | -------- | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------ | +| index | number | 是 | 指定的下标。 | + +**返回值：** + +| 类型 | 说明 | +| ------- | --------------------------------- | | boolean | 成功移除返回true，失败返回false。 | -**示例** +**示例：** - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - var isRemove = pasteData.removeRecordAt(0); - ``` +```js +var pasteData = pasteboard.createPlainTextData("hello"); +var isRemove = pasteData.removeRecordAt(0); +``` ### replaceRecordAt7+ replaceRecordAt(index: number, record: PasteDataRecord): boolean -替换指定下标的条目。 - -**系统能力**: SystemCapability.MiscServices.Pasteboard +替换剪贴板内容中指定下标的条目。 -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| index | number | 是 | 指定的下标。 | -| record | [PasteDataRecord](#pastedatarecord7) | 是 | 替换后的条目。 | +**系统能力：** SystemCapability.MiscServices.Pasteboard -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| boolean | 成功替换返回true，失败返回false。 | - -**示例** +**参数：** - ```js - var pasteData = pasteboard.createPlainTextData("hello"); - var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt"); - var isReplace = pasteData.replaceRecordAt(0, record); - ``` +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------------------ | ---- | -------------- | +| index | number | 是 | 指定的下标。 | +| record | [PasteDataRecord](#pastedatarecord7) | 是 | 替换后的条目。 | +**返回值：** -## pasteboard.getSystemPasteboard - -getSystemPasteboard(): SystemPasteboard - -获取系统剪切板。 - -**系统能力**: SystemCapability.MiscServices.Pasteboard - -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| [SystemPasteboard](#systempasteboard) | 系统剪切板对象。 | - -**示例** +| 类型 | 说明 | +| ------- | --------------------------------- | +| boolean | 成功替换返回true，失败返回false。 | - ```js - var systemPasteboard = pasteboard.getSystemPasteboard(); - ``` +**示例：** +```js +var pasteData = pasteboard.createPlainTextData("hello"); +var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt"); +var isReplace = pasteData.replaceRecordAt(0, record); +``` ## SystemPasteboard - 在调用SystemPasteboard的接口前，需要先通过[getSystemPasteboard](#pasteboardgetsystempasteboard)获取系统剪切板。 +系统剪贴板对象。 -``` +在调用SystemPasteboard的接口前，需要先通过[getSystemPasteboard](#pasteboardgetsystempasteboard)获取系统剪贴板。 + +```js var systemPasteboard = pasteboard.getSystemPasteboard(); ``` @@ -788,112 +824,117 @@ var systemPasteboard = pasteboard.getSystemPasteboard(); setPasteData(data:PasteData, callback:AsyncCallback<void>): void -将数据写入系统剪切板，并使用callback方式返回结果。 +将数据写入系统剪贴板，使用callback异步回调。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| data | [PasteData](#pastedata) | 是 | PasteData对象。 | -| callback | AsyncCallback<void> | 是 | 回调函数，表示是否成功将数据写入系统剪切板。 | +**参数：** -**示例** +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------------------------ | +| data | [PasteData](#pastedata) | 是 | PasteData对象。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当写入成功，err为undefined，否则为错误对象。 | - ```js - var pasteData = pasteboard.createPlainTextData("content"); - var systemPasteboard = pasteboard.getSystemPasteboard(); - systemPasteboard.setPasteData(pasteData, (error, data) => { - if (error) { - console.error('Failed to setPasteData. Cause: ' + error.message); - return; - } - console.info('setPasteData successfully.'); - }); - ``` +**示例：** + +```js +var pasteData = pasteboard.createPlainTextData("content"); +var systemPasteboard = pasteboard.getSystemPasteboard(); +systemPasteboard.setPasteData(pasteData, (err, data) => { + if (err) { + console.error('Failed to set PasteData. Cause: ' + err.message); + return; + } + console.info('Succeeded in setting PasteData.'); +}); +``` ### setPasteData setPasteData(data:PasteData): Promise<void> -将数据写入系统剪切板，并使用Promise异步方式返回结果。 +将数据写入系统剪贴板，使用Promise异步回调。 + +**系统能力：** SystemCapability.MiscServices.Pasteboard -**系统能力**: SystemCapability.MiscServices.Pasteboard +**参数：** -**参数** -| 参数名 | 类型 | 说明 | -| -------- | -------- | -------- | -| data | [PasteData](#pastedata) | PasteData对象。 | +| 参数名 | 类型 | 说明 | +| ------ | ----------------------- | --------------- | +| data | [PasteData](#pastedata) | PasteData对象。 | -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| Promise<void> | 异步回调函数，表示是否成功将数据写入系统剪切板。 | +**返回值：** -**示例** +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | - ```js - var pasteData = pasteboard.createPlainTextData("content"); - var systemPasteboard = pasteboard.getSystemPasteboard(); - systemPasteboard.setPasteData(pasteData).then((data) => { - console.info('setPasteData success.'); - }).catch((error) => { - console.error('Failed to setPasteData. Cause: ' + error.message); - }); - ``` +**示例：** + +```js +var pasteData = pasteboard.createPlainTextData("content"); +var systemPasteboard = pasteboard.getSystemPasteboard(); +systemPasteboard.setPasteData(pasteData).then((data) => { + console.info('Succeeded in setting PasteData.'); +}).catch((err) => { + console.error('Failed to set PasteData. Cause: ' + err.message); +}); +``` ### getPasteData getPasteData( callback:AsyncCallback<PasteData>): void -读取系统剪切板内容，并使用callback方式返回结果。 +读取系统剪贴板内容，使用callback异步回调。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<[PasteData](#pastedata)> | 是 | 回调函数，返回系统剪切板数据。 | +**参数：** -**示例** +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | +| callback | AsyncCallback<[PasteData](#pastedata)> | 是 | 回调函数。当读取成功，err为undefined，data为返回的系统剪贴板数据；否则返回错误对象。 | - ```js - var systemPasteboard = pasteboard.getSystemPasteboard(); - systemPasteboard.getPasteData((error, pasteData) => { - if (error) { - console.error('Failed to getPasteData. Cause: ' + error.message); - return; - } - var text = pasteData.getPrimaryText(); - }); - ``` +**示例：** + +```js +var systemPasteboard = pasteboard.getSystemPasteboard(); +systemPasteboard.getPasteData((err, pasteData) => { + if (err) { + console.error('Failed to get PasteData. Cause: ' + err.message); + return; + } + var text = pasteData.getPrimaryText(); +}); +``` ### getPasteData getPasteData(): Promise<PasteData> -读取系统剪切板内容，并使用Promise异步方式返回结果。 +读取系统剪贴板内容，使用Promise异步回调。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| Promise<[PasteData](#pastedata)> | 异步回调函数，调返回系统剪切板数据。 | +**返回值：** -**示例** +| 类型 | 说明 | +| -------------------------------------- | --------------------------------- | +| Promise<[PasteData](#pastedata)> | Promise对象，返回系统剪贴板数据。 | - ```js - var systemPasteboard = pasteboard.getSystemPasteboard(); - systemPasteboard.getPasteData().then((pasteData) => { - var text = pasteData.getPrimaryText(); - }).catch((error) => { - console.error('Failed to getPasteData. Cause: ' + error.message); - }) - ``` +**示例：** + +```js +var systemPasteboard = pasteboard.getSystemPasteboard(); +systemPasteboard.getPasteData().then((pasteData) => { + var text = pasteData.getPrimaryText(); +}).catch((err) => { + console.error('Failed to get PasteData. Cause: ' + err.message); +}) +``` ### on('update')7+ @@ -902,23 +943,24 @@ on(type: 'update', callback: () =>void ): void 订阅系统剪贴板内容变化事件，当系统剪贴板中内容变化时触发用户程序的回调。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| type | string | 是 | 取值为'update'，表示系统剪贴板内容变化事件。 | -| callback | function | 是 | 剪贴板中内容变化时触发的用户程序的回调。 | +**参数：** -**示例** +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | -------------------------------------------- | +| type | string | 是 | 取值为'update'，表示系统剪贴板内容变化事件。 | +| callback | function | 是 | 剪贴板中内容变化时触发的用户程序的回调。 | - ```js - var systemPasteboard = pasteboard.getSystemPasteboard(); - var listener = () => { - console.info('The system pasteboard has changed'); - }; - systemPasteboard.on('update', listener); - ``` +**示例：** + +```js +var systemPasteboard = pasteboard.getSystemPasteboard(); +var listener = () => { + console.info('The system pasteboard has changed.'); +}; +systemPasteboard.on('update', listener); +``` ### off('update')7+ @@ -927,120 +969,124 @@ off(type: 'update', callback?: () =>void ): void 取消订阅系统剪贴板内容变化事件。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard + +**参数：** -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| type | string | 是 | 取值为'update'，表示系统剪贴板内容变化事件。 | -| callback | function | 否 | 剪贴板中内容变化时触发的用户程序的回调。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | -------------------------------------------- | +| type | string | 是 | 取值为'update'，表示系统剪贴板内容变化事件。 | +| callback | function | 否 | 剪贴板中内容变化时触发的用户程序的回调。 | -**示例** +**示例：** - ```js - let listener = () => { - console.info('The system pasteboard has changed'); - }; - systemPasteboard.off('update', listener); - ``` +```js +let listener = () => { + console.info('The system pasteboard has changed.'); +}; +systemPasteboard.off('update', listener); +``` ### hasPasteData7+ hasPasteData(callback: AsyncCallback<boolean>): void -判断系统剪切板中是否有内容，并使用callback异步方式返回结果。 +判断系统剪贴板中是否有内容，使用callback异步回调。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | 是 | 返回为true表示系统剪切板中有内容，返回false表示系统剪切板中没有内容。 | +**参数：** -**示例** +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | ------------------------------------------------------------ | +| callback | AsyncCallback<boolean> | 是 | 返回true表示系统剪贴板中有内容，返回false表示系统剪贴板中没有内容。 | - ```js - systemPasteboard.hasPasteData((err, data) => { - if (err) { - console.error('failed to hasPasteData because ' + JSON.stringify(err)); - return; - } - console.info('success hasPasteData : ' + JSON.stringify(data)); - }); - ``` +**示例：** + +```js +systemPasteboard.hasPasteData((err, data) => { + if (err) { + console.error('Failed to check the PasteData. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in checking the PasteData. Data: ' + JSON.stringify(data)); +}); +``` ### hasPasteData7+ hasPasteData(): Promise<boolean> -判断系统剪切板中是否有内容，并使用Promise异步方式返回结果。 +判断系统剪贴板中是否有内容，使用Promise异步回调。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**返回值** -| 类型 | 说明 | -| -------- | -------- | -| Promise<boolean> | 返回为true表示系统剪切板中有内容，返回false表示系统剪切板中没有内容。 | +**返回值：** -**示例** +| 类型 | 说明 | +| ---------------------- | ------------------------------------------------------------ | +| Promise<boolean> | 返回true表示系统剪贴板中有内容，返回false表示系统剪贴板中没有内容。 | - ```js - systemPasteboard.hasPasteData().then((data) => { - console.info('success hasPasteData : ' + JSON.stringify(data)); - }).catch((error) => { - console.error('failed to hasPasteData because ' + JSON.stringify(error)); - }); - ``` +**示例：** + +```js +systemPasteboard.hasPasteData().then((data) => { + console.info('Succeeded in checking the PasteData. Data: ' + JSON.stringify(data)); +}).catch((err) => { + console.error('Failed to check the PasteData. Cause: ' + JSON.stringify(err)); +}); +``` ### clear7+ clear(callback: AsyncCallback<void>): void -清空系统剪切板内容，并使用callback异步方式返回结果。 +清空系统剪贴板内容，使用callback异步回调。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**参数** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<void> | 是 | 回调函数，表示是否成功清空系统剪切板内容。 | +**参数：** -**示例** +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | -------------------------------------------------------- | +| callback | AsyncCallback<void> | 是 | 回调函数。当成功清空时，err为undefined；否则为错误对象。 | - ```js - systemPasteboard.clear((err, data) => { - if (err) { - console.error('failed to clear because ' + JSON.stringify(err)); - return; - } - console.info('success clear'); - }); - ``` +**示例：** + +```js +systemPasteboard.clear((err, data) => { + if (err) { + console.error('Failed to clear the PasteData. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in clearing the PasteData.'); +}); +``` ### clear7+ clear(): Promise<void> -清空系统剪切板内容，并使用Promise异步方式返回结果。 +清空系统剪贴板内容，使用Promise异步回调。 -**系统能力**: SystemCapability.MiscServices.Pasteboard +**系统能力：** SystemCapability.MiscServices.Pasteboard -**返回值** +**返回值：** -| 类型 | 说明 | -| -------- | -------- | -| Promise<void> | 异步回调函数，表示是否成功清空系统剪切板内容。 | +| 类型 | 说明 | +| ------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。 | -**示例** +**示例：** - ```js - systemPasteboard.clear().then((data) => { - console.info('success clear'); - }).catch((error) => { - console.error('failed to clear because ' + JSON.stringify(error)); - }); - ``` +```js +systemPasteboard.clear().then((data) => { + console.info('Succeeded in clearing the PasteData.'); +}).catch((err) => { + console.error('Failed to clear the PasteData. Cause: ' + JSON.stringify(err)); +}); +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-prompt.md b/zh-cn/application-dev/reference/apis/js-apis-prompt.md index 475fd483adb8d59ee6b39ee809491787e1628f34..1d5a74215d16113afb684fda480645764ca0874c 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-prompt.md +++ b/zh-cn/application-dev/reference/apis/js-apis-prompt.md @@ -45,7 +45,7 @@ showToast(options: ShowToastOptions): void | 名称 | 类型 | 必填 | 说明 | | -------- | -------------- | ---- | ---------------------------------------- | | message | string | 是 | 显示的文本信息。 | -| duration | number | 否 | 默认值1500ms，建议区间：1500ms-10000ms，若小于1500ms则取默认值。 | +| duration | number | 否 | 默认值1500ms，取值区间：1500ms-10000ms。若小于1500ms则取默认值，若大于10000ms则取上限值10000ms。 | | bottom | <length> | 否 | 设置弹窗边框距离屏幕底部的位置。 | ## prompt.showDialog diff --git a/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md b/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md index 2c5dae2c90cf473c31493edccae2acb873cda1b4..1dbff0f41711dd5a702ec3ba7c7494c6a0ae2a1a 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md +++ b/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md @@ -19,7 +19,7 @@ import reminderAgent from'@ohos.reminderAgent'; publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void -发布一个后台代理提醒，使用callback方式实现异步调用。 +发布一个后台代理提醒，使用callback方式实现异步调用，该方法需要申请通知弹窗[Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8)后才能调用。 **需要权限**： ohos.permission.PUBLISH_AGENT_REMINDER @@ -53,7 +53,7 @@ publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number& publishReminder(reminderReq: ReminderRequest): Promise<number> -发布一个后台代理提醒，使用Promise方式实现异步调用。 +发布一个后台代理提醒，使用Promise方式实现异步调用，该方法需要申请通知弹窗[Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8)后才能调用。 **系统能力**： SystemCapability.Notification.ReminderAgent @@ -453,7 +453,7 @@ export default { ## MaxScreenWantAgent -提醒到达时自动拉起的目标ability信息。 +全屏显示提醒到达时自动拉起的目标ability信息，该接口预留。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194352434.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194352434.png index b2728fd1b4e050edddf499398b44a7e3aa634109..f1b942fee8437b1197ef3e9f40c98187a76f8c44 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194352434.png and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194352434.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194352468.gif b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194352468.gif index e22d25b7aa139409766723e4ed0fd6172b85b6cf..58feeb2988e8d9a643234691ae4d5cf5ccef6d4f 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194352468.gif and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001194352468.gif differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238712439.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238712439.png index b2728fd1b4e050edddf499398b44a7e3aa634109..f1b942fee8437b1197ef3e9f40c98187a76f8c44 100644 Binary files a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238712439.png and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001238712439.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777771.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777771.png new file mode 100644 index 0000000000000000000000000000000000000000..06cbacf1470de12c79c2020aa8c6be95506e58b5 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777771.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777772.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777772.png new file mode 100644 index 0000000000000000000000000000000000000000..9c68b723dd3966886d384028663d4a7d6633c027 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777772.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777773.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777773.png new file mode 100644 index 0000000000000000000000000000000000000000..7dbcbb2d5710b17866b9d5b034437b91a700a3f9 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777773.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777774.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777774.png new file mode 100644 index 0000000000000000000000000000000000000000..60f430b646b45a3e3b16a9bb024e4a14e48bf4d3 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777774.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777775.png b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777775.png new file mode 100644 index 0000000000000000000000000000000000000000..60f430b646b45a3e3b16a9bb024e4a14e48bf4d3 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_000000127777775.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-checkboxgroup.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-checkboxgroup.md index 649e80e27b5cc1b229767dc628437644f52c35fe..9b7b588d64e4f56a1b3ed976a02f8791272ea8df 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-checkboxgroup.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-checkboxgroup.md @@ -6,25 +6,21 @@ > > 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -## 权限列表 - -无 - ## 子组件 无 ## 接口 -CheckboxGroup( option?: {group?: string} ) +CheckboxGroup( options?: {group?: string} ) 创建多选框群组，可以控制群组内的Checkbox全选或者不全选，相同group的Checkbox和CheckboxGroup为同一群组。 **参数：** -| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | -| ----- | ------ | ---- | ---- | ----- | -| group | string | 否 | - | 群组名称。 | +| 参数名 | 参数类型 | 必填 | 参数描述 | +| ------ | -------- | ---- | ---------- | +| group | string | 否 | 群组名称。 | ## 属性 @@ -50,7 +46,7 @@ CheckboxGroup的选中状态或群组内的Checkbox的选中状态发生变化 | 名称 | 参数类型 | 描述 | | ------ | ------------------- | -------------- | | name | Array<string> | checkBox名称。 | -| status | selectStatus | 选中状态。 | +| status | SelectStatus | 选中状态。 | ## SelectStatus枚举说明 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-textclock.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-textclock.md index eb6d626447062499f886c054f30cb79ae5b1c89b..740d95324f07a4273850097a8cb7798fc173876e 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-textclock.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-textclock.md @@ -27,9 +27,9 @@ TextClock(options?: {timeZoneOffset?: number, controller?: TextClockController}) ## 属性 -| 名称 | 参数类型 | 默认值 | 描述 | -| ------ | ------ | -------- | ---------------------------------------- | -| format | string | 'hhmmss' | 设置显示时间格式，如“yyyy/mm/dd”、“yyyy-mm-dd”等。支持的时间格式化字符串：
  • yyyy（年份）
  • mm（英文月份简写）
  • mmm（英文月份简写）
  • mmmm（英文月份全称）
  • dd（英文星期简写）
  • ddd（英文星期简写）
  • dddd（英文星期全称）
  • HH（24小时制）
  • hh（12小时制）
  • MM/mm（分钟）
  • SS/ss（秒）
| +| 名称 | 参数类型 | 默认值 | 描述 | +| ------ | -------- | ------ | ------------------------------------------------------------ | +| format | string | 'hms' | 设置显示时间格式。
日期间隔符固定为"/"，时间间隔符为":"。
如yyyyMMdd，yyyy-MM-dd显示为yyyy/MM/dd，
hhmmss显示为hh:mm:ss。
时间格式只用写一位即可，如"hhmmss"等同于"hms"。
支持的时间格式化字符串：
- YYYY/yyyy：完整年份。
- YY/yy：年份后两位。
- M：月份(若想使用01月则使用MM)。
- d：日期(若想使用01日则使用dd)。
- D：年中日(一年中的第几天)。
- H：24小时制。
- h：12小时制。
- m：分钟。
- s：秒。
- SSS：毫秒。 | ## 事件 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-textpicker.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-textpicker.md index 028b6a61b14c9729341d8018202f379cb6f16da5..33d9d449208361ec6c1ee2ba3e7e34245390015c 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-textpicker.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-textpicker.md @@ -37,7 +37,7 @@ TextPicker(options?: {range: string[] | [Resource](ts-types.md#resource), select | 名称 | 描述 | | ------------------------------------------------------------ | ------------------------------------------------------------ | -| onChange(callback: (value: string, index: number) => void) | 滑动选中TextPicker文本内容后，触发该回调。
- value: 当前选中项的文本。
- index: 当前选中项的下标。 | +| onChange(callback: (value: string, index: number) => void) | 滑动选中TextPicker文本内容后，触发该回调。
- value: 当前选中项的文本。
- index: 当前选中项的索引值。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-xcomponent.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-xcomponent.md index 7ec01cd1c95acabd638e8f78acef211df9a65aee..2c2803ddd9ef2b27c80651ea30214036a745545b 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-xcomponent.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-xcomponent.md @@ -49,7 +49,7 @@ onDestroy(event: () => void ) ## XComponentController -xcomponent 组件的控制器，可以将此对象绑定至XComponent组件，然后通过控制器带调用组件方法。 +xcomponent 组件的控制器，可以将此对象绑定至XComponent组件，然后通过控制器来调用组件方法。 ### 创建对象 @@ -59,7 +59,7 @@ xcomponentController: XComponentController = new XComponentController() ### getXComponentSurfaceId -getXComponentSurfaceId(): string +getXComponentSurfaceId() 获取XComponent对应Surface的ID，供@ohos接口使用，比如camera相关接口。 @@ -71,9 +71,10 @@ getXComponentSurfaceId(): string | ------ | ----------------------- | | string | XComponent持有Surface的ID。 | + ### setXComponentSurfaceSize -setXComponentSurfaceSize(value: {surfaceWidth: number, surfaceHeight: number}): void +setXComponentSurfaceSize(value: {surfaceWidth: number, surfaceHeight: number}) 设置XComponent持有Surface的宽度和高度。 @@ -86,9 +87,10 @@ setXComponentSurfaceSize(value: {surfaceWidth: number, surfaceHeight: number}): | surfaceWidth | number | 是 | XComponent持有Surface的宽度。 | | surfaceHeight | number | 是 | XComponent持有Surface的高度。 | + ### getXComponentContext -getXComponentContext(): Object +getXComponentContext() 获取XComponent实例对象的context。 @@ -98,6 +100,7 @@ getXComponentContext(): Object | ------ | ---------------------------------------- | | Object | 获取XComponent实例对象的context，context包含的具体接口方法由开发者自定义。 | + ## 示例 提供surface类型XComponent，支持相机预览等能力。 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-longpressgesture.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-longpressgesture.md index 968822562d65285622fec9dd220f1890b5eea363..72f4fa886e2e872d1486b6978b057603494b7778 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-longpressgesture.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-longpressgesture.md @@ -1,7 +1,6 @@ # LongPressGesture > **说明：** -> > 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 @@ -21,15 +20,10 @@ LongPressGesture(value?: { fingers?: number, repeat?: boolean, duration?: number | 名称 | 功能描述 | | ------------------------------------------------------------ | --------------------------------------------------- | -| onAction(event: (event?: [GestureEvent](ts-gesture-settings.md)) => void) | LongPress手势识别成功回调。 | -| onActionEnd(event: (event?: [GestureEvent](ts-gesture-settings.md)) => void) | LongPress手势识别成功，手指抬起后触发回调。 | +| onAction(event: (event?: [GestureEvent](ts-gesture-settings.md)) => void) | LongPress手势识别成功回调。 | +| onActionEnd(event: (event?: [GestureEvent](ts-gesture-settings.md)) => void) | LongPress手势识别成功，手指抬起后触发回调。 | | onActionCancel(event: () => void) | LongPress手势识别成功，接收到触摸取消事件触发回调。 | -## GestureEvent对象中与LongPress手势相关的属性 - -| 属性名称 | 属性类型 | 描述 | -| ------ | ------- | ------------ | -| repeat | boolean | 事件是否为重复触发事件。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-pangesture.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-pangesture.md index 2790bb7d157c54a67d3468c0832ad92fce682e88..cc9e5454901204c10a0d132a1e62a62a3f13f3ab 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-pangesture.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-pangesture.md @@ -3,7 +3,6 @@ 用于触发拖动手势事件，滑动的最小距离为5vp时拖动手势识别成功。 > **说明：** -> > 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 @@ -15,22 +14,23 @@ PanGesture(value?: { fingers?: number, direction?: PanDirection, distance?: numb | 参数名称 | 参数类型 | 必填 | 参数描述 | | --------- | ------------ | ---- | ------------------------------------------------------------ | -| fingers | number | 否 | 触发滑动的最少手指数，最小为1指， 最大取值为10指。
默认值：1 | +| fingers | number | 否 | 触发拖动的最少手指数，最小为1指， 最大取值为10指。
默认值：1 | | direction | PanDirection | 否 | 触发拖动的手势方向，此枚举值支持逻辑与(&)和逻辑或（\|）运算。
默认值：PanDirection.All | | distance | number | 否 | 最小拖动识别距离，单位为vp。
默认值：5.0
**说明：**
> tab滑动与该拖动手势事件同时存在时，可将distance值设为1，使拖动更灵敏，避免造成事件错乱。 | ## PanDirection枚举说明 -| 名称 | 描述 | -| ---------- | ---------- | -| All | 所有方向可滑动。 | -| Horizontal | 水平方向可滑动。 | -| Vertical | 竖直方向可滑动。 | -| Left | 向左滑动。 | -| Right | 向右滑动。 | -| Up | 向上滑动。 | -| Down | 向下滑动。 | -| None | 任何方向都不可滑动。 | + | 名称 | 描述 | + | -------- | -------- | + | All | 所有方向。 | + | Horizontal | 水平方向。 | + | Vertical | 竖直方向。 | + | Left | 向左拖动。 | + | Right | 向右拖动。 | + | Up | 向上拖动。 | + | Down | 向下拖动。 | + | None | 任何方向都不可触发拖动手势事件。 | + ## PanGestureOptions @@ -40,31 +40,26 @@ PanGestureOptions(options?: { fingers?: number, direction?: PanDirection, distan **参数：** -同PanGesture参数说明。 + 同PanGesture参数说明。 **接口：** -| 名称 | 功能描述 | -| -------------------------------------- | -------------- | -| setDirection(value: PanDirection) | 设置direction属性。 | -| setDistance(value: number) | 设置distance属性。 | -| setFingers(value: number) | 设置fingers属性。 | + | 名称 | 功能描述 | + | -------- | -------- | + | setDirection(value: PanDirection) | 设置direction属性。 | + | setDistance(value: number) | 设置distance属性。 | + | setFingers(value: number) | 设置fingers属性。 | -## 事件 -| 名称 | 功能描述 | -| ------------------------------------------------------------ | --------------------------------------------- | -| onActionStart(event: (event?: [GestureEvent](ts-gesture-settings.md)) => void) | Pan手势识别成功回调。 | -| onActionUpdate(event: (event?: [GestureEvent](ts-gesture-settings.md)) => void) | Pan手势移动过程中回调。 | -| onActionEnd(event: (event?: [GestureEvent](ts-gesture-settings.md)) => void) | Pan手势识别成功，手指抬起后触发回调。 | -| onActionCancel(event: () => void) | Pan手势识别成功，接收到触摸取消事件触发回调。 | +## 事件 -## GestureEvent对象中与Pan手势相关的属性 +| 名称 | 功能描述 | +| -------- | -------- | +| onActionStart(event: (event?: [GestureEvent](ts-gesture-settings.md)) => void) | Pan手势识别成功回调。 | +| onActionUpdate(event: (event?: [GestureEvent](ts-gesture-settings.md)) => void) | Pan手势移动过程中回调。 | +| onActionEnd(event: (event?: [GestureEvent](ts-gesture-settings.md)) => void) | Pan手势识别成功，手指抬起后触发回调。 | +| onActionCancel(event: () => void) | Pan手势识别成功，接收到触摸取消事件触发回调。 | -| 属性名称 | 属性类型 | 描述 | -| ------- | ------ | -------------- | -| offsetX | number | 手势事件偏移量，单位为vp。 | -| offsetY | number | 手势事件偏移量，单位为vp。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-pinchgesture.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-pinchgesture.md index 6a91265143b898025950c6a711c1694cb604ba58..d9127d6d716188129a0beb4e1f88ed35dda82148 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-pinchgesture.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-pinchgesture.md @@ -1,7 +1,6 @@ # PinchGesture > **说明：** -> > 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 @@ -25,13 +24,6 @@ PinchGesture(value?: { fingers?: number, distance?: number }) | onActionEnd(event:(event?: [GestureEvent](ts-gesture-settings.md)) => void) | Pinch手势识别成功，手指抬起后触发回调。 | | onActionCancel(event: () => void) | Pinch手势识别成功，接收到触摸取消事件触发回调。 | -## GestureEvent对象中与Pinch手势相关的属性 - -| 属性名称 | 属性类型 | 描述 | -| ------------ | ------ | -------------------------- | -| scale | number | 缩放比例，用于PinchGesture手势触发场景。 | -| pinchCenterX | number | 捏合手势中心点X轴坐标，单位为px。 | -| pinchCenterY | number | 捏合手势中心点Y轴坐标，单位为px。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-rotationgesture.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-rotationgesture.md index e2a12b1b1236e806ec71102fc64bc0a9a33b7cfb..2438f474128d9f66883484bb39bc6745367355d1 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-rotationgesture.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-rotationgesture.md @@ -1,7 +1,6 @@ # RotationGesture > **说明：** -> > 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 @@ -25,11 +24,6 @@ RotationGesture(value?: { fingers?: number, angle?: number }) | onActionEnd(event: (event?: [GestureEvent](ts-gesture-settings.md)) => void) | Rotation手势识别成功，手指抬起后触发回调。 | | onActionCancel(event: () => void) | Rotation手势识别成功，接收到触摸取消事件触发回调。 | -## GestureEvent对象中与Rotation手势相关的属性 - -| 属性名称 | 属性类型 | 描述 | -| ----- | ------ | ----- | -| angle | number | 旋转角度。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-swipegesture.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-swipegesture.md index 8e7e8cd3f868ef2e864b93033fc2c6311377bf74..9c7c53050b9077afa4df1898d2ae92abe281c430 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-swipegesture.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-swipegesture.md @@ -1,7 +1,6 @@ # SwipeGesture > **说明：** -> > 从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 @@ -11,25 +10,28 @@ SwipeGesture(value?: { fingers?: number; direction?: SwipeDirection; speed?: num **参数：** -| 参数名称 | 参数类型 | 必填 | 默认值 | 参数描述 | -| --------- | -------------- | ---- | ------------------ | ----------------------------- | -| fingers | number | 否 | 1 | 触发滑动的最少手指数，默认为1，最小为1指，最大为10指。 | -| direction | SwipeDirection | 否 | SwipeDirection.All | 滑动方向。 | -| speed | number | 否 | 100 | 识别滑动的最小速度（100VP/秒）。 | + | 参数名称 | 参数类型 | 必填 | 默认值 | 参数描述 | + | -------- | -------- | -------- | -------- | -------- | + | fingers | number | 否 | 1 | 触发滑动的最少手指数，默认为1，最小为1指，最大为10指。 | + | direction | SwipeDirection | 否 | SwipeDirection.All | 触发滑动手势的滑动方向。 | + | speed | number | 否 | 100 | 识别滑动的最小速度（默认为100vp/秒）。 | ## SwipeDirection枚举说明 -| 名称 | 描述 | -| ---------- | ----- | -| All | 所有方向。 | -| Horizontal | 水平方向。 | -| Vertical | 竖直方向。 | + | 名称 | 描述 | + | -------- | -------- | + | All | 所有方向。 | + | Horizontal | 水平方向。 | + | Vertical | 竖直方向。 | + | None | 任何方向均不可触发。 | + ## 事件 -| 名称 | 功能描述 | -| ------------------------------------------------------------ | ---------------------- | -| onAction(event: (event?: [GestureEvent](ts-gesture-settings.md)) => void) | 滑动手势识别成功回调。 | +| 名称 | 功能描述 | +| -------- | -------- | +| onAction(event:(event?: [GestureEvent](ts-gesture-settings.md)) => void) | 滑动手势识别成功回调。 | + ![zh-cn_image_0000001231374559](figures/zh-cn_image_0000001231374661.png) ## 示例 @@ -52,7 +54,7 @@ struct SwipeGestureExample { .width(260).height(260) .rotate({x: 0, y: 0, z: 1, angle: this.rotateAngle}) .gesture( - SwipeGesture({fingers: 1, direction:SwipeDirection.Vertical}) + SwipeGesture({fingers: 1, direction: SwipeDirection.Vertical}) .onAction((event: GestureEvent) => { this.speed = event.speed this.rotateAngle = event.angle diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-tapgesture.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-tapgesture.md index 87a7adc53548fb270421ac709452d94bfd236a86..b21fd010632a8cb75f46d635d557c0f32e8abdc8 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-tapgesture.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-tapgesture.md @@ -1,7 +1,6 @@ # TapGesture > **说明：** -> > 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md b/zh-cn/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md index 08db299f856f4fdae23a238e0bc16c6c6bfcdee4..152ff182e77fc382f99a785de5ad2aa95194deb9 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md @@ -1,8 +1,7 @@ # CanvasRenderingContext2D对象 -> **说明：** -> -> 从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 使用RenderingContext在Canvas组件上进行绘制，绘制对象可以是矩形、文本、图片等。 @@ -12,51 +11,50 @@ CanvasRenderingContext2D(setting: RenderingContextSetting) -**参数：** +**参数：** -| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | -| ------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | -| setting | [RenderingContextSettings](#renderingcontextsettings) | 是 | - | 见[RenderingContextSettings](#renderingcontextsettings)。 | + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | ------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | + | setting | [RenderingContextSettings](#renderingcontextsettings) | 是 | - | 见[RenderingContextSettings](#renderingcontextsettings)。 | ### RenderingContextSettings -RenderingContextSettings(antialias?: bool) +RenderingContextSettings(antialias?: boolean) 用来配置CanvasRenderingContext2D对象的参数，包括是否开启抗锯齿。 -**参数：** -| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | -| --------- | ---- | ---- | ----- | ---------------- | -| antialias | bool | 否 | false | 表明canvas是否开启抗锯齿。 | +**参数：** + + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | --------- | ------- | ---- | ----- | ---------------- | + | antialias | boolean | 否 | false | 表明canvas是否开启抗锯齿。 | ## 属性 -| 名称 | 类型 | 默认值 | 描述 | -| ---------------------------------------- | ---------------------------------------- | ---------------------------------------- | ---------------------------------------- | -| [fillStyle](#fillstyle) | <color> \| [CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#canvaspattern) | - | 指定绘制的填充色。
- 类型为<color>时，表示设置填充区域的颜色。
- 类型为CanvasGradient时，表示渐变对象，使用[createLinearGradient](#createlineargradient)方法创建。
- 类型为CanvasPattern时，使用[createPattern](#createpattern)方法创建。 | -| [lineWidth](#linewidth) | number | - | 设置绘制线条的宽度。 | -| [strokeStyle](#strokestyle) | <color> \| [CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#canvaspattern) | - | 设置描边的颜色。
- 类型为<color>时，表示设置描边使用的颜色。
- 类型为CanvasGradient时，表示渐变对象，使用[createLinearGradient](#createlineargradient)方法创建。
- 类型为CanvasPattern时，使用[createPattern](#createpattern)方法创建。 | -| [lineCap](#linecap) | string | 'butt' | 指定线端点的样式，可选值为：
- 'butt'：线端点以方形结束。
- 'round'：线端点以圆形结束。
- 'square'：线端点以方形结束，该样式下会增加一个长度和线段厚度相同，宽度是线段厚度一半的矩形。 | -| [lineJoin](#linejoin) | string | 'miter' | 指定线段间相交的交点样式，可选值为：
- 'round'：在线段相连处绘制一个扇形，扇形的圆角半径是线段的宽度。
- 'bevel'：在线段相连处使用三角形为底填充， 每个部分矩形拐角独立。
- 'miter'：在相连部分的外边缘处进行延伸，使其相交于一点，形成一个菱形区域，该属性可以通过设置miterLimit属性展现效果。 | -| [miterLimit](#miterlimit) | number | 10 | 设置斜接面限制值，该值指定了线条相交处内角和外角的距离。 | -| [font](#font) | string | 'normal normal 14px sans-serif' | 设置文本绘制中的字体样式。
语法：ctx.font='font-size font-family'
- font-size(可选)，指定字号和行高，单位只支持px。
- font-family(可选)，指定字体系列。
语法：ctx.font='font-style font-weight font-size font-family'
- font-style(可选)，用于指定字体样式，支持如下几种样式：'normal',talic。
- font-weight(可选)，用于指定字体的粗细，支持如下几种类型：'normal', 'bold', 'bolder', 'lighter', 100, 200, 300, 400, 500, 600, 700, 800, 900。
- font-size(可选)，指定字号和行高，单位只支持px。
- font-family(可选)，指定字体系列，支持如下几种类型：'sans-serif', 'serif', 'monospace'。 | -| [textAlign](#textalign) | string | 'left' | 设置文本绘制中的文本对齐方式，可选值为：
- 'left'：文本左对齐。
- 'right'：文本右对齐。
- 'center'：文本居中对齐。
- 'start'：文本对齐界线开始的地方。
- 'end'：文本对齐界线结束的地方。
>  **说明：**
> ltr布局模式下'start'和'left'一致，rtl布局模式下'start'和'right'一致·。 | -| [textBaseline](#textbaseline) | string | 'alphabetic' | 设置文本绘制中的水平对齐方式，可选值为：
- 'alphabetic'：文本基线是标准的字母基线。
- 'top'：文本基线在文本块的顶部。
- 'hanging'：文本基线是悬挂基线。
- 'middle'：文本基线在文本块的中间。
- 'ideographic'：文字基线是表意字基线；如果字符本身超出了alphabetic基线，那么ideograhpic基线位置在字符本身的底部。
- 'bottom'：文本基线在文本块的底部。 与ideographic基线的区别在于ideographic基线不需要考虑下行字母。 | -| [globalAlpha](#globalalpha) | number | - | 设置透明度，0.0为完全透明，1.0为完全不透明。 | -| [lineDashOffset](#linedashoffset) | number | 0.0 | 设置画布的虚线偏移量，精度为float。 | -| [globalCompositeOperation](#globalcompositeoperation) | string | 'source-over' | 设置合成操作的方式。类型字段可选值有'source-over'，'source-atop'，'source-in'，'source-out'，'destination-over'，'destination-atop'，'destination-in'，'destination-out'，'lighter'，'copy'，'xor'。 | -| [shadowBlur](#shadowblur) | number | 0.0 | 设置绘制阴影时的模糊级别，值越大越模糊，精度为float。 | -| [shadowColor](#shadowcolor) | <color> | - | 设置绘制阴影时的阴影颜色。 | -| [shadowOffsetX](#shadowoffsetx) | number | - | 设置绘制阴影时和原有对象的水平偏移值。 | -| [shadowOffsetY](#shadowoffsety) | number | - | 设置绘制阴影时和原有对象的垂直偏移值。 | -| [imageSmoothingEnabled](#imagesmoothingenabled) | boolean | true | 用于设置绘制图片时是否进行图像平滑度调整，true为启用，false为不启用。 | -| imageSmoothingQuality | string | 'low' | 用于设置图像平滑度，支持如下三种类型：'low', 'medium', 'high'。 | - -> **说明：** -> -> <color>类型格式为 'rgb(255, 255, 255)'，'rgba(255, 255, 255, 1.0)'，'\#FFFFFF'。 +| 名称 | 类型 | 描述 | +| ---------------------------------------- | ---------------------------------------- | ---------------------------------------- | +| [fillStyle](#fillstyle) | string \| [CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#canvaspattern) | 指定绘制的填充色。
- 类型为string时，表示设置填充区域的颜色。
- 类型为CanvasGradient时，表示渐变对象，使用[createLinearGradient](#createlineargradient)方法创建。
- 类型为CanvasPattern时，使用[createPattern](#createpattern)方法创建。 | +| [lineWidth](#linewidth) | number | 设置绘制线条的宽度。 | +| [strokeStyle](#strokestyle) | string \| [CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#canvaspattern) | 设置描边的颜色。
- 类型为string时，表示设置描边使用的颜色。
- 类型为CanvasGradient时，表示渐变对象，使用[createLinearGradient](#createlineargradient)方法创建。
- 类型为CanvasPattern时，使用[createPattern](#createpattern)方法创建。 | +| [lineCap](#linecap) | CanvasLineCap | 指定线端点的样式，可选值为：
- 'butt'：线端点以方形结束。
- 'round'：线端点以圆形结束。
- 'square'：线端点以方形结束，该样式下会增加一个长度和线段厚度相同，宽度是线段厚度一半的矩形。
默认值：'butt'。 | +| [lineJoin](#linejoin) | CanvasLineJoin | 指定线段间相交的交点样式，可选值为：
- 'round'：在线段相连处绘制一个扇形，扇形的圆角半径是线段的宽度。
- 'bevel'：在线段相连处使用三角形为底填充， 每个部分矩形拐角独立。
- 'miter'：在相连部分的外边缘处进行延伸，使其相交于一点，形成一个菱形区域，该属性可以通过设置miterLimit属性展现效果。
默认值：'miter'。 | +| [miterLimit](#miterlimit) | number | 设置斜接面限制值，该值指定了线条相交处内角和外角的距离。
默认值：10。 | +| [font](#font) | string | 设置文本绘制中的字体样式。
语法：ctx.font='font-size font-family'
- font-size(可选)，指定字号和行高，单位只支持px。
- font-family(可选)，指定字体系列。
语法：ctx.font='font-style font-weight font-size font-family'
- font-style(可选)，用于指定字体样式，支持如下几种样式：'normal','italic'。
- font-weight(可选)，用于指定字体的粗细，支持如下几种类型：'normal', 'bold', 'bolder', 'lighter', 100, 200, 300, 400, 500, 600, 700, 800, 900。
- font-size(可选)，指定字号和行高，单位只支持px。
- font-family(可选)，指定字体系列，支持如下几种类型：'sans-serif', 'serif', 'monospace'。
默认值：'normal normal 14px sans-serif'。 | +| [textAlign](#textalign) | CanvasTextAlign | 设置文本绘制中的文本对齐方式，可选值为：
- 'left'：文本左对齐。
- 'right'：文本右对齐。
- 'center'：文本居中对齐。
- 'start'：文本对齐界线开始的地方。
- 'end'：文本对齐界线结束的地方。
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> ltr布局模式下'start'和'left'一致，rtl布局模式下'start'和'right'一致·。
默认值：'left'。 | +| [textBaseline](#textbaseline) | CanvasTextBaseline | 设置文本绘制中的水平对齐方式，可选值为：
- 'alphabetic'：文本基线是标准的字母基线。
- 'top'：文本基线在文本块的顶部。
- 'hanging'：文本基线是悬挂基线。
- 'middle'：文本基线在文本块的中间。
- 'ideographic'：文字基线是表意字基线；如果字符本身超出了alphabetic基线，那么ideograhpic基线位置在字符本身的底部。
- 'bottom'：文本基线在文本块的底部。 与ideographic基线的区别在于ideographic基线不需要考虑下行字母。
默认值：'alphabetic'。 | +| [globalAlpha](#globalalpha) | number | 设置透明度，0.0为完全透明，1.0为完全不透明。 | +| [lineDashOffset](#linedashoffset) | number | 设置画布的虚线偏移量，精度为float。
默认值：0.0。 | +| [globalCompositeOperation](#globalcompositeoperation) | string | 设置合成操作的方式。类型字段可选值有'source-over'，'source-atop'，'source-in'，'source-out'，'destination-over'，'destination-atop'，'destination-in'，'destination-out'，'lighter'，'copy'，'xor'。
默认值：'source-over'。 | +| [shadowBlur](#shadowblur) | number | 设置绘制阴影时的模糊级别，值越大越模糊，精度为float。
默认值：0.0。 | +| [shadowColor](#shadowcolor) | string | 设置绘制阴影时的阴影颜色。 | +| [shadowOffsetX](#shadowoffsetx) | number | 设置绘制阴影时和原有对象的水平偏移值。 | +| [shadowOffsetY](#shadowoffsety) | number | 设置绘制阴影时和原有对象的垂直偏移值。 | +| [imageSmoothingEnabled](#imagesmoothingenabled) | boolean | 用于设置绘制图片时是否进行图像平滑度调整，true为启用，false为不启用。
默认值：true。 | + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +>fillStyle、shadowColor与 strokeStyle 中string类型格式为 'rgb(255, 255, 255)'，'rgba(255, 255, 255, 1.0)'，'\#FFFFFF'。 ### fillStyle @@ -427,6 +425,7 @@ struct LineDashOffset { .onReady(() =>{ this.context.arc(100, 75, 50, 0, 6.28) this.context.setLineDash([10,20]) + this.context.lineDashOffset = 10.0; this.context.stroke(); }) } @@ -597,6 +596,7 @@ struct ShadowOffsetX { struct ShadowOffsetY { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -660,16 +660,19 @@ fillRect(x: number, y: number, w: number, h: number): void 填充一个矩形。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 说明 | -| ------ | ------ | ---- | ---- | ------------- | -| x | number | 是 | 0 | 指定矩形左上角点的x坐标。 | -| y | number | 是 | 0 | 指定矩形左上角点的y坐标。 | -| width | number | 是 | 0 | 指定矩形的宽度。 | -| height | number | 是 | 0 | 指定矩形的高度。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 说明 | + | ------ | ------ | ---- | ---- | ------------- | + | x | number | 是 | 0 | 指定矩形左上角点的x坐标。 | + | y | number | 是 | 0 | 指定矩形左上角点的y坐标。 | + | width | number | 是 | 0 | 指定矩形的宽度。 | + | height | number | 是 | 0 | 指定矩形的高度。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct FillRect { @@ -701,21 +704,25 @@ strokeRect(x: number, y: number, w: number, h: number): void 绘制具有边框的矩形，矩形内部不填充。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 说明 | -| ------ | ------ | ---- | ---- | ------------ | -| x | number | 是 | 0 | 指定矩形的左上角x坐标。 | -| y | number | 是 | 0 | 指定矩形的左上角y坐标。 | -| width | number | 是 | 0 | 指定矩形的宽度。 | -| height | number | 是 | 0 | 指定矩形的高度。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 说明 | + | ------ | ------ | ---- | ---- | ------------ | + | x | number | 是 | 0 | 指定矩形的左上角x坐标。 | + | y | number | 是 | 0 | 指定矩形的左上角y坐标。 | + | w | number | 是 | 0 | 指定矩形的宽度。 | + | h | number | 是 | 0 | 指定矩形的高度。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct StrokeRect { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -741,21 +748,25 @@ clearRect(x: number, y: number, w: number, h: number): void 删除指定区域内的绘制内容。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ------ | ------ | ---- | ---- | ------------- | -| x | number | 是 | 0 | 指定矩形上的左上角x坐标。 | -| y | number | 是 | 0 | 指定矩形上的左上角y坐标。 | -| width | number | 是 | 0 | 指定矩形的宽度。 | -| height | number | 是 | 0 | 指定矩形的高度。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ------ | ------ | ---- | ---- | ------------- | + | x | number | 是 | 0 | 指定矩形上的左上角x坐标。 | + | y | number | 是 | 0 | 指定矩形上的左上角y坐标。 | + | w | number | 是 | 0 | 指定矩形的宽度。 | + | h | number | 是 | 0 | 指定矩形的高度。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct ClearRect { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -779,24 +790,29 @@ clearRect(x: number, y: number, w: number, h: number): void ### fillText -fillText(text: string, x: number, y: number): void +fillText(text: string, x: number, y: number, maxWidth?: number): void 绘制填充类文本。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 说明 | -| ---- | ------ | ---- | ---- | --------------- | -| text | string | 是 | “” | 需要绘制的文本内容。 | -| x | number | 是 | 0 | 需要绘制的文本的左下角x坐标。 | -| y | number | 是 | 0 | 需要绘制的文本的左下角y坐标。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 说明 | + | ---- | ------ | ---- | ---- | --------------- | + | text | string | 是 | “” | 需要绘制的文本内容。 | + | x | number | 是 | 0 | 需要绘制的文本的左下角x坐标。 | + | y | number | 是 | 0 | 需要绘制的文本的左下角y坐标。 | + | maxWidth | number | 否 | - | 指定文本允许的最大宽度。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct FillText { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -819,24 +835,29 @@ fillText(text: string, x: number, y: number): void ### strokeText -strokeText(text: string, x: number, y: number): void +strokeText(text: string, x: number, y: number, maxWidth?:number): void 绘制描边类文本。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---- | ------ | ---- | ---- | --------------- | -| text | string | 是 | “” | 需要绘制的文本内容。 | -| x | number | 是 | 0 | 需要绘制的文本的左下角x坐标。 | -| y | number | 是 | 0 | 需要绘制的文本的左下角y坐标。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---- | ------ | ---- | ---- | --------------- | + | text | string | 是 | “” | 需要绘制的文本内容。 | + | x | number | 是 | 0 | 需要绘制的文本的左下角x坐标。 | + | y | number | 是 | 0 | 需要绘制的文本的左下角y坐标。 | + | maxWidth | number | 否 | - | 需要绘制的文本的最大宽度 。| + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct StrokeText { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -863,28 +884,49 @@ measureText(text: string): TextMetrics 该方法返回一个文本测算的对象，通过该对象可以获取指定文本的宽度值。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 说明 | -| ---- | ------ | ---- | ---- | ---------- | -| text | string | 是 | "" | 需要进行测量的文本。 | +**参数：** + + | 参数 | 类型 | 必填 | 默认值 | 说明 | + | ---- | ------ | ---- | ---- | ---------- | + | text | string | 是 | "" | 需要进行测量的文本。 | + +**返回值：** -- 返回值 | 类型 | 说明 | | ----------- | ------- | | TextMetrics | 文本的尺寸信息 | -- TextMetrics类型描述 - | 属性 | 类型 | 描述 | - | ----- | ------ | ------- | - | width | number | 字符串的宽度。 | +**TextMetrics类型描述:** + + | 属性 | 类型 | 描述 | + | ----- | ------ | ------- | + | width | number | 字符串的宽度。 | + | height | number | 字符串的高度。 | + | actualBoundingBoxAscent | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到渲染文本的矩形边界顶部的距离，当前值为0。 | + | actualBoundingBoxDescent | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到渲染文本的矩形边界底部的距离，当前值为0。 | + | actualBoundingBoxLeft | number | 平行于基线，从CanvasRenderingContext2D.textAlign 属性确定的对齐点到文本矩形边界左侧的距离，当前值为0。 | + | actualBoundingBoxRight | number | 平行于基线，从CanvasRenderingContext2D.textAlign 属性确定的对齐点到文本矩形边界右侧的距离，当前值为0。| + | alphabeticBaseline | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到线框的 alphabetic 基线的距离，当前值为0。| + | emHeightAscent | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到线框中 em 方块顶部的距离，当前值为0。| + | emHeightDescent | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到线框中 em 方块底部的距离，当前值为0。| + | fontBoundingBoxAscent | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到渲染文本的所有字体的矩形最高边界顶部的距离，当前值为0。| + | fontBoundingBoxDescent | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到渲染文本的所有字体的矩形边界最底部的距离，当前值为0。| + | hangingBaseline | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到线框的 hanging 基线的距离，当前值为0。| + | ideographicBaseline | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到线框的 ideographic 基线的距离，当前值为0。| -**示例：** - ``` + + + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct MeasureText { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -912,19 +954,22 @@ stroke(path?: Path2D): void 进行边框绘制操作。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---- | ---------------------------------------- | ---- | ---- | ------------ | -| path | [Path2D](ts-components-canvas-path2d.md) | 否 | null | 需要绘制的Path2D。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---- | ---------------------------------------- | ---- | ---- | ------------ | + | path | [Path2D](ts-components-canvas-path2d.md) | 否 | null | 需要绘制的Path2D。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct Stroke { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -953,14 +998,16 @@ beginPath(): void 创建一个新的绘制路径。 -**示例：** - ``` +**示例：** + + ```ts + // xxx.ets @Entry @Component struct BeginPath { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -991,20 +1038,23 @@ moveTo(x: number, y: number): void 路径从当前点移动到指定点。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 说明 | -| ---- | ------ | ---- | ---- | --------- | -| x | number | 是 | 0 | 指定位置的x坐标。 | -| y | number | 是 | 0 | 指定位置的y坐标。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 说明 | + | ---- | ------ | ---- | ---- | --------- | + | x | number | 是 | 0 | 指定位置的x坐标。 | + | y | number | 是 | 0 | 指定位置的y坐标。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct MoveTo { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1033,20 +1083,23 @@ lineTo(x: number, y: number): void 从当前点到指定点进行路径连接。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---- | ------ | ---- | ---- | --------- | -| x | number | 是 | 0 | 指定位置的x坐标。 | -| y | number | 是 | 0 | 指定位置的y坐标。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---- | ------ | ---- | ---- | --------- | + | x | number | 是 | 0 | 指定位置的x坐标。 | + | y | number | 是 | 0 | 指定位置的y坐标。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct LineTo { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1075,14 +1128,16 @@ closePath(): void 结束当前路径形成一个封闭路径。 -**示例：** - ``` +**示例：** + + ```ts + // xxx.ets @Entry @Component struct ClosePath { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1109,25 +1164,34 @@ closePath(): void ### createPattern -createPattern(image: ImageBitmap, repetition: string): void +createPattern(image: ImageBitmap, repetition: string | null): CanvasPattern | null 通过指定图像和重复方式创建图片填充的模板。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | -| image | [ImageBitmap](ts-components-canvas-imagebitmap.md) | 是 | null | 图源对象，具体参考ImageBitmap对象。 | -| repetition | string | 是 | “” | 设置图像重复的方式，取值为：'repeat'、'repeat-x'、 'repeat-y'、'no-repeat'。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | + | image | [ImageBitmap](ts-components-canvas-imagebitmap.md) | 是 | null | 图源对象，具体参考ImageBitmap对象。 | + | repetition | string | 是 | “” | 设置图像重复的方式，取值为：'repeat'、'repeat-x'、 'repeat-y'、'no-repeat'。 | + +**返回值：**： + + | 类型 | 说明 | + | ---------- | ---------------------------------------- | + | [CanvasPattern](#canvaspattern) | 通过指定图像和重复方式创建图片填充的模板对象。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct CreatePattern { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private img:ImageBitmap = new ImageBitmap("common/images/icon.jpg") - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1155,24 +1219,27 @@ bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, 创建三次贝赛尔曲线的路径。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---- | ------ | ---- | ---- | -------------- | -| cp1x | number | 是 | 0 | 第一个贝塞尔参数的x坐标值。 | -| cp1y | number | 是 | 0 | 第一个贝塞尔参数的y坐标值。 | -| cp2x | number | 是 | 0 | 第二个贝塞尔参数的x坐标值。 | -| cp2y | number | 是 | 0 | 第二个贝塞尔参数的y坐标值。 | -| x | number | 是 | 0 | 路径结束时的x坐标值。 | -| y | number | 是 | 0 | 路径结束时的y坐标值。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---- | ------ | ---- | ---- | -------------- | + | cp1x | number | 是 | 0 | 第一个贝塞尔参数的x坐标值。 | + | cp1y | number | 是 | 0 | 第一个贝塞尔参数的y坐标值。 | + | cp2x | number | 是 | 0 | 第二个贝塞尔参数的x坐标值。 | + | cp2y | number | 是 | 0 | 第二个贝塞尔参数的y坐标值。 | + | x | number | 是 | 0 | 路径结束时的x坐标值。 | + | y | number | 是 | 0 | 路径结束时的y坐标值。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct BezierCurveTo { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1201,21 +1268,25 @@ quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void 创建二次贝赛尔曲线的路径。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---- | ------ | ---- | ---- | ----------- | -| cpx | number | 是 | 0 | 贝塞尔参数的x坐标值。 | -| cpy | number | 是 | 0 | 贝塞尔参数的y坐标值。 | -| x | number | 是 | 0 | 路径结束时的x坐标值。 | -| y | number | 是 | 0 | 路径结束时的y坐标值。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---- | ------ | ---- | ---- | ----------- | + | cpx | number | 是 | 0 | 贝塞尔参数的x坐标值。 | + | cpy | number | 是 | 0 | 贝塞尔参数的y坐标值。 | + | x | number | 是 | 0 | 路径结束时的x坐标值。 | + | y | number | 是 | 0 | 路径结束时的y坐标值。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct QuadraticCurveTo { private settings: RenderingContextSettings = new RenderingContextSettings(true); private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1240,28 +1311,31 @@ quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void ### arc -arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void +arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void 绘制弧线路径。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ------------- | ------- | ---- | ----- | ---------- | -| x | number | 是 | 0 | 弧线圆心的x坐标值。 | -| y | number | 是 | 0 | 弧线圆心的y坐标值。 | -| radius | number | 是 | 0 | 弧线的圆半径。 | -| startAngle | number | 是 | 0 | 弧线的起始弧度。 | -| endAngle | number | 是 | 0 | 弧线的终止弧度。 | -| anticlockwise | boolean | 否 | false | 是否逆时针绘制圆弧。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ------------- | ------- | ---- | ----- | ---------- | + | x | number | 是 | 0 | 弧线圆心的x坐标值。 | + | y | number | 是 | 0 | 弧线圆心的y坐标值。 | + | radius | number | 是 | 0 | 弧线的圆半径。 | + | startAngle | number | 是 | 0 | 弧线的起始弧度。 | + | endAngle | number | 是 | 0 | 弧线的终止弧度。 | + | counterclockwise | boolean | 否 | false | 是否逆时针绘制圆弧。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct Arc { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1289,23 +1363,26 @@ arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void 依据圆弧经过的点和圆弧半径创建圆弧路径。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ------ | ------ | ---- | ---- | --------------- | -| x1 | number | 是 | 0 | 圆弧经过的第一个点的x坐标值。 | -| y1 | number | 是 | 0 | 圆弧经过的第一个点的y坐标值。 | -| x2 | number | 是 | 0 | 圆弧经过的第二个点的x坐标值。 | -| y2 | number | 是 | 0 | 圆弧经过的第二个点的y坐标值。 | -| radius | number | 是 | 0 | 圆弧的圆半径值。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ------ | ------ | ---- | ---- | --------------- | + | x1 | number | 是 | 0 | 圆弧经过的第一个点的x坐标值。 | + | y1 | number | 是 | 0 | 圆弧经过的第一个点的y坐标值。 | + | x2 | number | 是 | 0 | 圆弧经过的第二个点的x坐标值。 | + | y2 | number | 是 | 0 | 圆弧经过的第二个点的y坐标值。 | + | radius | number | 是 | 0 | 圆弧的圆半径值。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct ArcTo { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1329,31 +1406,33 @@ arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void ### ellipse -ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void +ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void 在规定的矩形区域绘制一个椭圆。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 说明 | -| ------------- | ------- | ---- | ----- | ----------------- | -| x | number | 是 | 0 | 椭圆圆心的x轴坐标。 | -| y | number | 是 | 0 | 椭圆圆心的y轴坐标。 | -| radiusX | number | 是 | 0 | 椭圆x轴的半径长度。 | -| radiusY | number | 是 | 0 | 椭圆y轴的半径长度。 | -| rotation | number | 是 | 0 | 椭圆的旋转角度，单位为弧度。 | -| startAngle | number | 是 | 0 | 椭圆绘制的起始点角度，以弧度表示。 | -| endAngle | number | 是 | 0 | 椭圆绘制的结束点角度，以弧度表示。 | -| anticlockwise | boolean | 否 | false | 是否以逆时针方向绘制椭圆。 | +**参数：** -**示例：** + | 参数 | 类型 | 必填 | 默认值 | 说明 | + | ------------- | ------- | ---- | ----- | ----------------- | + | x | number | 是 | 0 | 椭圆圆心的x轴坐标。 | + | y | number | 是 | 0 | 椭圆圆心的y轴坐标。 | + | radiusX | number | 是 | 0 | 椭圆x轴的半径长度。 | + | radiusY | number | 是 | 0 | 椭圆y轴的半径长度。 | + | rotation | number | 是 | 0 | 椭圆的旋转角度，单位为弧度。 | + | startAngle | number | 是 | 0 | 椭圆绘制的起始点角度，以弧度表示。 | + | endAngle | number | 是 | 0 | 椭圆绘制的结束点角度，以弧度表示。 | + | counterclockwise | boolean | 否 | false | 是否以逆时针方向绘制椭圆。 | - ``` +**示例：** + + ```ts + // xxx.ets @Entry @Component struct CanvasExample { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1377,26 +1456,29 @@ ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number ### rect -rect(x: number, y: number, width: number, height: number): void +rect(x: number, y: number, w: number, h: number): void 创建矩形路径。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ------ | ------ | ---- | ---- | ------------- | -| x | number | 是 | 0 | 指定矩形的左上角x坐标值。 | -| y | number | 是 | 0 | 指定矩形的左上角y坐标值。 | -| width | number | 是 | 0 | 指定矩形的宽度。 | -| height | number | 是 | 0 | 指定矩形的高度。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ------ | ------ | ---- | ---- | ------------- | + | x | number | 是 | 0 | 指定矩形的左上角x坐标值。 | + | y | number | 是 | 0 | 指定矩形的左上角y坐标值。 | + | w | number | 是 | 0 | 指定矩形的宽度。 | + | h | number | 是 | 0 | 指定矩形的高度。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct CanvasExample { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1419,12 +1501,21 @@ rect(x: number, y: number, width: number, height: number): void ### fill -fill(): void +fill(fillRule?: CanvasFillRule): void 对封闭路径进行填充。 -**示例：** - ``` +**参数:** + + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ------ | ------ | ---- | ---- | ------------- | + | fillRule | CanvasFillRule | 否 | "nonzero" | 指定要填充对象的规则。
可选参数为："nonzero", "evenodd"。| + + +**示例:** + + ```ts + // xxx.ets @Entry @Component struct Fill { @@ -1451,14 +1542,73 @@ fill(): void ![zh-cn_image_0000001238952381](figures/zh-cn_image_0000001238952381.png) +fill(path: Path2D, fillRule?: CanvasFillRule): void + +对封闭路径进行填充。 + +**参数:** + + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ------ | ------ | ---- | ---- | ------------- | + | path | Path2D | 是 | | Path2D填充路径。 | + | fillRule | CanvasFillRule | 否 | "nonzero" | 指定要填充对象的规则。
可选参数为："nonzero", "evenodd"。| + + +**示例:** + +```ts +// xxx.ets +@Entry +@Component +struct Fill { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + let region = new Path2D(); + region.moveTo(30, 90); + region.lineTo(110, 20); + region.lineTo(240, 130); + region.lineTo(60, 130); + region.lineTo(190, 20); + region.lineTo(270, 90); + region.closePath(); + // Fill path + this.context.fillStyle = 'green'; + this.context.fill(region, "evenodd"); + }) + } + .width('100%') + .height('100%') + } +} + ``` + + ![zh-cn_image_000000127777774](figures/zh-cn_image_000000127777774.png) + + ### clip -clip(): void +clip(fillRule?: CanvasFillRule): void 设置当前路径为剪切路径。 -**示例：** - ``` +**参数:** + + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ------ | ------ | ---- | ---- | ------------- | + | fillRule | CanvasFillRule | 否 | "nonzero" | 指定要剪切对象的规则。
可选参数为："nonzero", "evenodd"。| + +**示例:** + + ```ts + // xxx.ets @Entry @Component struct Clip { @@ -1488,25 +1638,75 @@ clip(): void ![zh-cn_image_0000001194032462](figures/zh-cn_image_0000001194032462.png) +clip(path: Path2D, fillRule?: CanvasFillRule): void + +对封闭路径进行填充。该接口为空接口。 + +**参数:** + + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ------ | ------ | ---- | ---- | ------------- | + | path | Path2D | 是 | - | Path2D剪切路径。 | + | fillRule | CanvasFillRule | 否 | "nonzero" | 指定要剪切对象的规则。
可选参数为："nonzero", "evenodd"。| + + + +### filter + +filter(filter: string): void + +为Canvas图形设置各类滤镜效果。该接口为空接口。 + +**参数:** + + | 参数 | 类型 | 必填 | 默认值 | 说明 | + | ------ | ------ | ---- | ---- | ------------- | + | filter | string | 是 | - | 接受各类滤镜效果的函数。| + + +### getTransform + +getTransform(): Matrix2D + +获取当前被应用到上下文的转换矩阵。该接口为空接口。 + + +### resetTransform + +resetTransform(): void + +使用单位矩阵重新设置当前变形。该接口为空接口。 + + +### direction + +direction(direction: CanvasDirection): void + +绘制文本时，描述当前文本方向的属性。该接口为空接口。 + + ### rotate -rotate(rotate: number): void +rotate(angle: number): void 针对当前坐标轴进行顺时针旋转。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ------ | ------ | ---- | ---- | ---------------------------------------- | -| rotate | number | 是 | 0 | 设置顺时针旋转的弧度值，可以通过Math.PI / 180将角度转换为弧度值。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ------ | ------ | ---- | ---- | ---------------------------------------- | + | angle | number | 是 | 0 | 设置顺时针旋转的弧度值，可以通过Math.PI / 180将角度转换为弧度值。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct Rotate { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1533,20 +1733,23 @@ scale(x: number, y: number): void 设置canvas画布的缩放变换属性，后续的绘制操作将按照缩放比例进行缩放。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---- | ------ | ---- | ---- | ----------- | -| x | number | 是 | 0 | 设置水平方向的缩放值。 | -| y | number | 是 | 0 | 设置垂直方向的缩放值。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---- | ------ | ---- | ---- | ----------- | + | x | number | 是 | 0 | 设置水平方向的缩放值。 | + | y | number | 是 | 0 | 设置垂直方向的缩放值。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct Scale { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1570,35 +1773,38 @@ scale(x: number, y: number): void ### transform -transform(scaleX: number, skewX: number, skewY: number, scaleY: number, translateX: number, translateY: number): void +transform(a: number, b: number, c: number, d: number, e: number, f: number): void transform方法对应一个变换矩阵，想对一个图形进行变化的时候，只要设置此变换矩阵相应的参数，对图形的各个定点的坐标分别乘以这个矩阵，就能得到新的定点的坐标。矩阵变换效果可叠加。 -> **说明：** -> 变换后的坐标计算方式（x和y为变换前坐标，x'和y'为变换后坐标）： +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 变换后的坐标计算方式（x和y为变换前坐标，x'和y'为变换后坐标）： > -> - x' = scaleX \* x + skewY \* y + translateX +> - x' = scaleX \* x + skewY \* y + translateX > -> - y' = skewX \* x + scaleY \* y + translateY +> - y' = skewX \* x + scaleY \* y + translateY -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---------- | ------ | ---- | ---- | -------- | -| scaleX | number | 是 | 0 | 指定水平缩放值。 | -| skewX | number | 是 | 0 | 指定水平倾斜值。 | -| skewY | number | 是 | 0 | 指定垂直倾斜值。 | -| scaleY | number | 是 | 0 | 指定垂直缩放值。 | -| translateX | number | 是 | 0 | 指定水平移动值。 | -| translateY | number | 是 | 0 | 指定垂直移动值。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---------- | ------ | ---- | ---- | -------- | + | a | number | 是 | 0 |scaleX: 指定水平缩放值。 | + | b | number | 是 | 0 |skewX: 指定水平倾斜值。 | + | c | number | 是 | 0 |skewY: 指定垂直倾斜值。 | + | d | number | 是 | 0 |scaleY: 指定垂直缩放值。 | + | e | number | 是 | 0 |translateX: 指定水平移动值。 | + | f | number | 是 | 0 |translateY: 指定垂直移动值。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct Transform { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1627,28 +1833,31 @@ transform方法对应一个变换矩阵，想对一个图形进行变化的时 ### setTransform -setTransform(scaleX: number, skewX: number, skewY: number, scale: number, translateX: number, translateY: number): void +setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void setTransfrom方法使用的参数和transform()方法相同，但setTransform()方法会重置现有的变换矩阵并创建新的变换矩阵。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---------- | ------ | ---- | ---- | -------- | -| scaleX | number | 是 | 0 | 指定水平缩放值。 | -| skewX | number | 是 | 0 | 指定水平倾斜值。 | -| skewY | number | 是 | 0 | 指定垂直倾斜值。 | -| scaleY | number | 是 | 0 | 指定垂直缩放值。 | -| translateX | number | 是 | 0 | 指定水平移动值。 | -| translateY | number | 是 | 0 | 指定垂直移动值。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---------- | ------ | ---- | ---- | -------- | + | a | number | 是 | 0 |scaleX: 指定水平缩放值。 | + | b | number | 是 | 0 |skewX: 指定水平倾斜值。 | + | c | number | 是 | 0 |skewY: 指定垂直倾斜值。 | + | d | number | 是 | 0 |scaleY: 指定垂直缩放值。 | + | e | number | 是 | 0 |translateX: 指定水平移动值。 | + | f | number | 是 | 0 |translateY: 指定垂直移动值。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct SetTransform { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1672,26 +1881,34 @@ setTransfrom方法使用的参数和transform()方法相同，但setTransform() ![zh-cn_image_0000001238712421](figures/zh-cn_image_0000001238712421.png) +setTransform(transform?: Matrix2D): void + +以Matrix2D对象为模板重置现有的变换矩阵并创建新的变换矩阵。该接口为空接口。 + + ### translate translate(x: number, y: number): void 移动当前坐标系的原点。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---- | ------ | ---- | ---- | -------- | -| x | number | 是 | 0 | 设置水平平移量。 | -| y | number | 是 | 0 | 设置竖直平移量。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---- | ------ | ---- | ---- | -------- | + | x | number | 是 | 0 | 设置水平平移量。 | + | y | number | 是 | 0 | 设置竖直平移量。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct Translate { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1717,34 +1934,38 @@ translate(x: number, y: number): void drawImage(image: ImageBitmap | PixelMap, dx: number, dy: number): void -drawImage(image: ImageBitmap | PixelMap, dx: number, dy: number, dWidth: number, dHeight: number): void +drawImage(image: ImageBitmap | PixelMap, dx: number, dy: number, dw: number, dh: number): void -drawImage(image: ImageBitmap | PixelMap, sx: number, sy: number, sWidth: number, sHeight: number, dx: number, dy: number, dWidth: number, dHeight: number):void +drawImage(image: ImageBitmap | PixelMap, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number):void 进行图像绘制。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | -| image | [ImageBitmap](ts-components-canvas-imagebitmap.md)或[PixelMap](../apis/js-apis-image.md#pixelmap7) | 是 | null | 图片资源，请参考ImageBitmap或PixelMap。 | -| sx | number | 否 | 0 | 裁切源图像时距离源图像左上角的x坐标值。 | -| sy | number | 否 | 0 | 裁切源图像时距离源图像左上角的y坐标值。 | -| sWidth | number | 否 | 0 | 裁切源图像时需要裁切的宽度。 | -| sHeight | number | 否 | 0 | 裁切源图像时需要裁切的高度。 | -| dx | number | 是 | 0 | 绘制区域左上角在x轴的位置。 | -| dy | number | 是 | 0 | 绘制区域左上角在y 轴的位置。 | -| dWidth | number | 否 | 0 | 绘制区域的宽度。 当绘制区域的宽度和裁剪图像的宽度不一致时，将图像宽度拉伸或压缩为绘制区域的宽度。 | -| dHeight | number | 否 | 0 | 绘制区域的高度。 当绘制区域的高度和裁剪图像的高度不一致时，将图像高度拉伸或压缩为绘制区域的高度。 | +**参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | + | image | [ImageBitmap](ts-components-canvas-imagebitmap.md)或[PixelMap](../apis/js-apis-image.md#pixelmap7) | 是 | null | 图片资源，请参考ImageBitmap或PixelMap。 | + | sx | number | 否 | 0 | 裁切源图像时距离源图像左上角的x坐标值。 | + | sy | number | 否 | 0 | 裁切源图像时距离源图像左上角的y坐标值。 | + | sw | number | 否 | 0 | 裁切源图像时需要裁切的宽度。 | + | sh | number | 否 | 0 | 裁切源图像时需要裁切的高度。 | + | dx | number | 是 | 0 | 绘制区域左上角在x轴的位置。 | + | dy | number | 是 | 0 | 绘制区域左上角在y 轴的位置。 | + | dw | number | 否 | 0 | 绘制区域的宽度。当绘制区域的宽度和裁剪图像的宽度不一致时，将图像宽度拉伸或压缩为绘制区域的宽度。 | + | dh | number | 否 | 0 | 绘制区域的高度。当绘制区域的高度和裁剪图像的高度不一致时，将图像高度拉伸或压缩为绘制区域的高度。 | -**示例：** - ``` + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct ImageExample { private settings: RenderingContextSettings = new RenderingContextSettings(true); private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); private img:ImageBitmap = new ImageBitmap("common/images/example.jpg"); + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1766,79 +1987,257 @@ drawImage(image: ImageBitmap | PixelMap, sx: number, sy: number, sWidth: number, ### createImageData -createImageData(width: number, height: number): Object +createImageData(sw: number, sh: number): ImageData 创建新的ImageData 对象，请参考[ImageData](ts-components-canvas-imagebitmap.md)。 -**参数：** -| 参数 | 类型 | 必填 | 默认 | 描述 | -| ------ | ------ | ---- | ---- | ------------- | -| width | number | 是 | 0 | ImageData的宽度。 | -| height | number | 是 | 0 | ImageData的高度。 | +**参数：** + + | 参数 | 类型 | 必填 | 默认 | 描述 | + | ------ | ------ | ---- | ---- | ------------- | + | sw | number | 是 | 0 | ImageData的宽度。 | + | sh | number | 是 | 0 | ImageData的高度。 | ### createImageData -createImageData(imageData: Object): Object +createImageData(imageData: ImageData): ImageData 创建新的ImageData 对象，请参考[ImageData](ts-components-canvas-imagebitmap.md)。 -**参数：** -| 参数 | 类型 | 必填 | 默认 | 描述 | -| --------- | ------ | ---- | ---- | ----------------- | -| imagedata | Object | 是 | null | 复制现有的ImageData对象。 | +**参数：** + + | 参数 | 类型 | 必填 | 默认 | 描述 | + | --------- | ------ | ---- | ---- | ----------------- | + | imagedata | [ImageData](ts-components-canvas-imagebitmap.md)| 是 | null | 复制现有的ImageData对象。 | + + **返回值：** + + | 类型 | 说明 | + | ---------- | ---------------------------------------- | + | [ImageData](ts-components-canvas-imagebitmap.md) | 新的ImageData对象。| + ### getPixelMap getPixelMap(sx: number, sy: number, sw: number, sh: number): PixelMap 以当前canvas指定区域内的像素创建[PixelMap](../apis/js-apis-image.md#pixelmap7)对象。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---- | ------ | ---- | ---- | --------------- | -| sx | number | 是 | 0 | 需要输出的区域的左上角x坐标。 | -| sy | number | 是 | 0 | 需要输出的区域的左上角y坐标。 | -| sw | number | 是 | 0 | 需要输出的区域的宽度。 | -| sh | number | 是 | 0 | 需要输出的区域的高度。 | + +**参数：** + + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---- | ------ | ---- | ---- | --------------- | + | sx | number | 是 | 0 | 需要输出的区域的左上角x坐标。 | + | sy | number | 是 | 0 | 需要输出的区域的左上角y坐标。 | + | sw | number | 是 | 0 | 需要输出的区域的宽度。 | + | sh | number | 是 | 0 | 需要输出的区域的高度。 | + +**返回值：** + + | 类型 | 说明 | + | ---------- | ---------------------------------------- | + | [PixelMap](../apis/js-apis-image.md#pixelmap7) | 新的PixelMap对象。 | ### getImageData -getImageData(sx: number, sy: number, sw: number, sh: number): Object +getImageData(sx: number, sy: number, sw: number, sh: number): ImageData 以当前canvas指定区域内的像素创建[ImageData](ts-components-canvas-imagebitmap.md)对象。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---- | ------ | ---- | ---- | --------------- | -| sx | number | 是 | 0 | 需要输出的区域的左上角x坐标。 | -| sy | number | 是 | 0 | 需要输出的区域的左上角y坐标。 | -| sw | number | 是 | 0 | 需要输出的区域的宽度。 | -| sh | number | 是 | 0 | 需要输出的区域的高度。 | + +**参数：** + + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---- | ------ | ---- | ---- | --------------- | + | sx | number | 是 | 0 | 需要输出的区域的左上角x坐标。 | + | sy | number | 是 | 0 | 需要输出的区域的左上角y坐标。 | + | sw | number | 是 | 0 | 需要输出的区域的宽度。 | + | sh | number | 是 | 0 | 需要输出的区域的高度。 | + + **返回值：** + + | 类型 | 说明 | + | ---------- | ---------------------------------------- | + | [ImageData](ts-components-canvas-imagebitmap.md) | 新的ImageData对象。 | ### putImageData -putImageData(imageData: Object, dx: number, dy: number, dirtyX?: number, dirtyY?: number, dirtyWidth?: number, dirtyHeight?: number): void +putImageData(imageData: ImageData, dx: number, dy: number): void + +putImageData(imageData: ImageData, dx: number, dy: number, dirtyX: number, dirtyY: number, dirtyWidth: number, dirtyHeight: number): void 使用[ImageData](ts-components-canvas-imagebitmap.md)数据填充新的矩形区域。 +**参数：** + + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ----------- | ------ | ---- | ------------ | ----------------------------- | + | imagedata | [ImageData](ts-components-canvas-imagebitmap.md) | 是 | null | 包含像素值的ImageData对象。 | + | dx | number | 是 | 0 | 填充区域在x轴方向的偏移量。 | + | dy | number | 是 | 0 | 填充区域在y轴方向的偏移量。 | + | dirtyX | number | 否 | 0 | 源图像数据矩形裁切范围左上角距离源图像左上角的x轴偏移量。 | + | dirtyY | number | 否 | 0 | 源图像数据矩形裁切范围左上角距离源图像左上角的y轴偏移量。 | + | dirtyWidth | number | 否 | imagedata的宽度 | 源图像数据矩形裁切范围的宽度。 | + | dirtyHeight | number | 否 | imagedata的高度 | 源图像数据矩形裁切范围的高度。 | + +**示例：** + + ```ts + // xxx.ets + @Entry + @Component + struct PutImageData { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + var imageData = this.context.createImageData(100, 100) + for (var i = 0; i < imageData.data.length; i += 4) { + imageData.data[i + 0] = 255 + imageData.data[i + 1] = 0 + imageData.data[i + 2] = 255 + imageData.data[i + 3] = 255 + } + this.context.putImageData(imageData, 10, 10) + }) + } + .width('100%') + .height('100%') + } + } + ``` + + ![zh-cn_image_0000001238952387](figures/zh-cn_image_0000001238952387.png) + + +### setLineDash + +setLineDash(segments: number[]): void + +设置画布的虚线样式。 + **参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ----------- | ------ | ---- | ------------ | ----------------------------- | -| imagedata | Object | 是 | null | 包含像素值的ImageData对象。 | -| dx | number | 是 | 0 | 填充区域在x轴方向的偏移量。 | -| dy | number | 是 | 0 | 填充区域在y轴方向的偏移量。 | -| dirtyX | number | 否 | 0 | 源图像数据矩形裁切范围左上角距离源图像左上角的x轴偏移量。 | -| dirtyY | number | 否 | 0 | 源图像数据矩形裁切范围左上角距离源图像左上角的y轴偏移量。 | -| dirtyWidth | number | 否 | imagedata的宽度 | 源图像数据矩形裁切范围的宽度。 | -| dirtyHeight | number | 否 | imagedata的高度 | 源图像数据矩形裁切范围的高度。 | + +| 参数 | 类型 | 描述 | +| -------- | ----- | -------------------- | +| segments | number[] | 描述线段如何交替和线段间距长度的数组。 | + +**示例：** + + ```ts + // xxx.ets + @Entry + @Component + struct SetLineDash { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.context.arc(100, 75, 50, 0, 6.28) + this.context.setLineDash([10,20]) + }) + } + .width('100%') + .height('100%') + } + } + ``` + + ![zh-cn_image_000000127777771](figures/zh-cn_image_000000127777771.png) + + +### getLineDash + +getLineDash(): number[] + +获得当前画布的虚线样式。 + +**返回值：** + +| 类型 | 说明 | +| ----- | ------------------------ | +| number[] | 返回数组，该数组用来描述线段如何交替和间距长度。 | **示例：** + + ```ts + // xxx.ets + @Entry + @Component + struct GetLineDash { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + var grad = this.context.createLinearGradient(50,0, 300,100) + this.context.arc(100, 75, 50, 0, 6.28) + this.context.setLineDash([10,20]) + this.context.stroke(); + let res = this.context.getLineDash() + }) + } + .width('100%') + .height('100%') + } + } ``` + + +### imageSmoothingQuality + +imageSmoothingQuality(quality: imageSmoothingQuality) + +用于设置图像平滑度。该接口为空接口。 + + **参数：** + +| 参数 | 类型 | 描述 | +| ------ | ----------- | ------------------ | +| quality |imageSmoothingQuality | 支持如下三种类型：'low', 'medium', 'high'。 | + + + +### transferFromImageBitmap + +transferFromImageBitmap(bitmap: ImageBitmap): void + +显示给定的ImageBitmap对象。 + +**参数：** + +| 参数 | 类型 | 描述 | +| ------ | ----------- | ------------------ | +| bitmap |[ImageData](ts-components-canvas-imagebitmap.md) | 待显示的ImageBitmap对象。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct PutImageData { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { @@ -1847,14 +2246,16 @@ putImageData(imageData: Object, dx: number, dy: number, dirtyX?: number, dirtyY? .height('100%') .backgroundColor('#ffff00') .onReady(() =>{ - var imageData = this.context.createImageData(100, 100) + var imageData = this.offContext.createImageData(100, 100) for (var i = 0; i < imageData.data.length; i += 4) { imageData.data[i + 0] = 255 imageData.data[i + 1] = 0 imageData.data[i + 2] = 255 imageData.data[i + 3] = 255 } - this.context.putImageData(imageData, 10, 10) + this.offContext.putImageData(imageData, 10, 10) + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) }) } .width('100%') @@ -1862,8 +2263,52 @@ putImageData(imageData: Object, dx: number, dy: number, dirtyX?: number, dirtyY? } } ``` + ![zh-cn_image_000000127777773](figures/zh-cn_image_000000127777773.png) - ![zh-cn_image_0000001238952387](figures/zh-cn_image_0000001238952387.png) +### toDataURL + +toDataURL(type?: string, quality?: number): string + +生成一个包含图片展示的URL。 + +**参数：** + +| 参数名 | 参数类型 | 必填 | 描述 | +| ------- | ------ | ---- | ---------------------------------------- | +| type | string | 否 | 可选参数，用于指定图像格式，默认格式为image/png。 | +| quality | number | 否 | 在指定图片格式为image/jpeg或image/webp的情况下，可以从0到1的区间内选择图片的质量。如果超出取值范围，将会使用默认值0.92。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | --------- | +| string | 图像的URL地址。 | + +**示例：** + + ```ts + // xxx.ets +@Entry +@Component +struct ToDataURL { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + var dataURL = this.context.toDataURL(); + }) + } + .width('100%') + .height('100%') + } +} + ``` ### restore @@ -1872,14 +2317,17 @@ restore(): void 对保存的绘图上下文进行恢复。 -**示例：** - ``` +**示例：** + + ```ts + // xxx.ets @Entry @Component struct CanvasExample { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + private img:ImageBitmap = new ImageBitmap("common/images/icon.jpg") + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1901,16 +2349,18 @@ restore(): void save(): void -对当前的绘图上下文进行保存。 +将当前状态放入栈中，保存canvas的全部状态，通常在需要保存绘制状态时调用。 -**示例：** - ``` +**示例：** + + ```ts + // xxx.ets @Entry @Component struct CanvasExample { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -1934,16 +2384,19 @@ createLinearGradient(x0: number, y0: number, x1: number, y1: number): void 创建一个线性渐变色。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---- | ------ | ---- | ---- | -------- | -| x0 | number | 是 | 0 | 起点的x轴坐标。 | -| y0 | number | 是 | 0 | 起点的y轴坐标。 | -| x1 | number | 是 | 0 | 终点的x轴坐标。 | -| y1 | number | 是 | 0 | 终点的y轴坐标。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---- | ------ | ---- | ---- | -------- | + | x0 | number | 是 | 0 | 起点的x轴坐标。 | + | y0 | number | 是 | 0 | 起点的y轴坐标。 | + | x1 | number | 是 | 0 | 终点的x轴坐标。 | + | y1 | number | 是 | 0 | 终点的y轴坐标。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct CreateLinearGradient { @@ -1980,18 +2433,21 @@ createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, 创建一个径向渐变色。 -**参数：** -| 参数 | 类型 | 必填 | 默认值 | 描述 | -| ---- | ------ | ---- | ---- | ----------------- | -| x0 | number | 是 | 0 | 起始圆的x轴坐标。 | -| y0 | number | 是 | 0 | 起始圆的y轴坐标。 | -| r0 | number | 是 | 0 | 起始圆的半径。必须是非负且有限的。 | -| x1 | number | 是 | 0 | 终点圆的x轴坐标。 | -| y1 | number | 是 | 0 | 终点圆的y轴坐标。 | -| r1 | number | 是 | 0 | 终点圆的半径。必须为非负且有限的。 | +**参数：** -**示例：** - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | ---- | ------ | ---- | ---- | ----------------- | + | x0 | number | 是 | 0 | 起始圆的x轴坐标。 | + | y0 | number | 是 | 0 | 起始圆的y轴坐标。 | + | r0 | number | 是 | 0 | 起始圆的半径。必须是非负且有限的。 | + | x1 | number | 是 | 0 | 终点圆的x轴坐标。 | + | y1 | number | 是 | 0 | 终点圆的y轴坐标。 | + | r1 | number | 是 | 0 | 终点圆的半径。必须为非负且有限的。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct CreateRadialGradient { diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-canvas.md b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-canvas.md index 32a14b8bc4e168b013a9f8380f68e43c1cb56231..e74488c562835c6153ba7e8127e8f27a44cdb25d 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-canvas.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-canvas.md @@ -1,8 +1,6 @@ # Canvas -> **说明：** -> -> 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 +> **说明：** 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 提供画布组件，用于自定义绘制图形。 @@ -16,13 +14,13 @@ ## 接口 -Canvas(context: CanvasRenderingContext2D) +Canvas(context?: CanvasRenderingContext2D) **参数：** -| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | -| ------- | ---------------------------------------- | ---- | ---- | ---------------------------- | -| context | [CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md) | 是 | - | 见CanvasRenderingContext2D对象。 | + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | ------- | ---------------------------------------- | ---- | ---- | ---------------------------- | + | context | [CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md) | 否 | - | 见CanvasRenderingContext2D对象。 | ## 属性 @@ -34,7 +32,7 @@ Canvas(context: CanvasRenderingContext2D) | 名称 | 参数 | 描述 | | ----------------------------- | ---- | -------------------- | -| onReady(callback: () => void) | 无 | 画布组件的事件回调，可以在此时进行绘制。 | +| onReady(event: () => void) | 无 | 画布组件的事件回调，可以在此时进行绘制。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagebitmap.md b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagebitmap.md index 503f356cdfb8a25f2fd707d7f910198f409a4322..e2f3f510bef985abf5c868223bf71f477219ea80 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagebitmap.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagebitmap.md @@ -1,17 +1,25 @@ # ImageBitmap对象 > **说明：** -> -> 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 +> 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -CanvasImageData对象可以存储canvas渲染的像素数据。 +ImageBitmap对象可以存储canvas渲染的像素数据。 ## 属性 -| 属性 | 类型 | 描述 | -| ------ | ------------------------- | ---------------------------- | -| width | number | 矩形区域实际像素宽度。 | -| height | number | 矩形区域实际像素高度。 | -| data | <Uint8ClampedArray> | 一维数组，保存了相应的颜色数据，数据值范围为0到255。 | +| 属性 | 类型 | 描述 | +| -------- | -------- | -------- | +| width | number | ImageBitmap的像素宽度。 | +| height | number | ImageBitmap的像素高度。 | + + +## 方法 + + +### close + +close() + +释放ImageBitmap对象相关联的所有图形资源。该接口为空接口。 \ No newline at end of file diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagedata.md b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagedata.md index 7a0306444c98c9e9f42f4d966d7515813c554bc5..d1df7c7a5ec2294b75c43ee390e0cfb3ccfad0ff 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagedata.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-imagedata.md @@ -1,8 +1,7 @@ # ImageData对象 > **说明：** -> -> 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 +> 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 ImageData对象可以存储canvas渲染的像素数据。 @@ -10,8 +9,9 @@ ImageData对象可以存储canvas渲染的像素数据。 ## 属性 -| 属性 | 类型 | 描述 | -| ------ | ------------------------- | ---------------------------- | -| width | number | 矩形区域实际像素宽度。 | -| height | number | 矩形区域实际像素高度。 | -| data | <Uint8ClampedArray> | 一维数组，保存了相应的颜色数据，数据值范围为0到255。 | +| 属性 | 类型 | 描述 | +| -------- | -------- | -------- | +| width | number | 矩形区域实际像素宽度。 | +| height | number | 矩形区域实际像素高度。 | +| data | Uint8ClampedArray | 一维数组，保存了相应的颜色数据，数据值范围为0到255。 | + diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-lottie.md b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-lottie.md index c1dce5fd99edd0a7f2a89e2564f76814039eddb1..e623316d5201d24517c2ddc507e28c4a20a5a626 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-lottie.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-lottie.md @@ -17,7 +17,10 @@ import lottie from '@ohos/lottieETS' ``` > **说明：** -> 在Terminal窗口使用 `npm install @ohos/lottieETS` 命令下载Lottie，下载之前需要配置权限。 +> +> 在Terminal窗口使用 `npm install @ohos/lottieETS` 命令下载Lottie。 +> +> 安装ohos npm 三方包时，需要先执行`npm config set @ohos:registry=https://repo.harmonyos.com/npm/`设置仓库地址。 ## lottie.loadAnimation diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-path2d.md b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-path2d.md index e457d286728476cdd8a566903c5622843104270f..63004c2e78848e356e474a5ee4b38d13f6162c66 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-path2d.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-components-canvas-path2d.md @@ -1,8 +1,7 @@ # Path2D对象 > **说明：** -> -> 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 +> 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 路径对象，支持通过对象的接口进行路径的描述，并通过Canvas的stroke接口进行绘制。 @@ -10,26 +9,31 @@ ## addPath -addPath(path: Object): void +addPath(path: path2D, transform?:Matrix2D): void 将另一个路径添加到当前的路径对象中。 -- 参数 - | 参数 | 类型 | 必填 | 默认值 | 描述 | - | ---- | ------ | ---- | ---- | -------------- | - | path | Object | 是 | null | 需要添加到当前路径的路径对象 | +**参数：** -- 示例 - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | -------- | -------- | -------- | -------- | -------- | + | path | path2D | 是 | - | 需要添加到当前路径的路径对象。| + | transform | Matrix2D | 否 | null | 新增路径的变换矩阵对象。 | + + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct AddPath { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - + private path2Da: Path2D = new Path2D("M250 150 L150 350 L350 350 Z") private path2Db: Path2D = new Path2D() - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -56,15 +60,17 @@ closePath(): void 将路径的当前点移回到路径的起点，当前点到起点间画一条直线。如果形状已经闭合或只有一个点，则此功能不执行任何操作。 -- 示例 - ``` +**示例：** + + ```ts + // xxx.ets @Entry @Component struct ClosePath { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private path2Db: Path2D = new Path2D() - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -94,21 +100,24 @@ moveTo(x: number, y: number): void 将路径的当前坐标点移动到目标点，移动过程中不绘制线条。 -- 参数 - | 参数 | 类型 | 必填 | 默认值 | 描述 | - | ---- | ------ | ---- | ---- | ------- | - | x | number | 是 | 0 | 目标点X轴坐标 | - | y | number | 是 | 0 | 目标点Y轴坐标 | +**参数：** -- 示例 - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | -------- | -------- | -------- | -------- | -------- | + | x | number | 是 | 0 | 目标点X轴坐标。 | + | y | number | 是 | 0 | 目标点Y轴坐标。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct MoveTo { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private path2Db: Path2D = new Path2D() - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -138,21 +147,24 @@ lineTo(x: number, y: number): void 从当前点绘制一条直线到目标点。 -- 参数 - | 参数 | 类型 | 必填 | 默认值 | 描述 | - | ---- | ------ | ---- | ---- | ------- | - | x | number | 是 | 0 | 目标点X轴坐标 | - | y | number | 是 | 0 | 目标点Y轴坐标 | +**参数：** -- 示例 - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | -------- | -------- | -------- | -------- | -------- | + | x | number | 是 | 0 | 目标点X轴坐标。 | + | y | number | 是 | 0 | 目标点Y轴坐标。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct LineTo { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private path2Db: Path2D = new Path2D() - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -183,25 +195,28 @@ bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, 创建三次贝赛尔曲线的路径。 -- 参数 - | 参数 | 类型 | 必填 | 默认值 | 描述 | - | ---- | ------ | ---- | ---- | -------------- | - | cp1x | number | 是 | 0 | 第一个贝塞尔参数的x坐标值。 | - | cp1y | number | 是 | 0 | 第一个贝塞尔参数的y坐标值。 | - | cp2x | number | 是 | 0 | 第二个贝塞尔参数的x坐标值。 | - | cp2y | number | 是 | 0 | 第二个贝塞尔参数的y坐标值。 | - | x | number | 是 | 0 | 路径结束时的x坐标值。 | - | y | number | 是 | 0 | 路径结束时的y坐标值。 | - -- 示例 - ``` +**参数：** + + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | -------- | -------- | -------- | -------- | -------- | + | cp1x | number | 是 | 0 | 第一个贝塞尔参数的x坐标值。 | + | cp1y | number | 是 | 0 | 第一个贝塞尔参数的y坐标值。 | + | cp2x | number | 是 | 0 | 第二个贝塞尔参数的x坐标值。 | + | cp2y | number | 是 | 0 | 第二个贝塞尔参数的y坐标值。 | + | x | number | 是 | 0 | 路径结束时的x坐标值。 | + | y | number | 是 | 0 | 路径结束时的y坐标值。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct BezierCurveTo { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private path2Db: Path2D = new Path2D() - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -228,23 +243,26 @@ quadraticCurveTo(cpx: number, cpy: number, x: number ,y: number): void 创建二次贝赛尔曲线的路径。 -- 参数 - | 参数 | 类型 | 必填 | 默认值 | 描述 | - | ---- | ------ | ---- | ---- | ----------- | - | cpx | number | 是 | 0 | 贝塞尔参数的x坐标值。 | - | cpy | number | 是 | 0 | 贝塞尔参数的y坐标值。 | - | x | number | 是 | 0 | 路径结束时的x坐标值。 | - | y | number | 是 | 0 | 路径结束时的y坐标值。 | +**参数：** -- 示例 - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | -------- | -------- | -------- | -------- | -------- | + | cpx | number | 是 | 0 | 贝塞尔参数的x坐标值。 | + | cpy | number | 是 | 0 | 贝塞尔参数的y坐标值。 | + | x | number | 是 | 0 | 路径结束时的x坐标值。 | + | y | number | 是 | 0 | 路径结束时的y坐标值。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct QuadraticCurveTo { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private path2Db: Path2D = new Path2D() - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -268,29 +286,32 @@ quadraticCurveTo(cpx: number, cpy: number, x: number ,y: number): void ## arc -arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void +arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void 绘制弧线路径。 -- 参数 - | 参数 | 类型 | 必填 | 默认值 | 描述 | - | ------------- | ------- | ---- | ----- | ---------- | - | x | number | 是 | 0 | 弧线圆心的x坐标值。 | - | y | number | 是 | 0 | 弧线圆心的y坐标值。 | - | radius | number | 是 | 0 | 弧线的圆半径。 | - | startAngle | number | 是 | 0 | 弧线的起始弧度。 | - | endAngle | number | 是 | 0 | 弧线的终止弧度。 | - | anticlockwise | boolean | 否 | false | 是否逆时针绘制圆弧。 | - -- 示例 - ``` +**参数：** + + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | -------- | -------- | -------- | -------- | -------- | + | x | number | 是 | 0 | 弧线圆心的x坐标值。 | + | y | number | 是 | 0 | 弧线圆心的y坐标值。 | + | radius | number | 是 | 0 | 弧线的圆半径。 | + | startAngle | number | 是 | 0 | 弧线的起始弧度。 | + | endAngle | number | 是 | 0 | 弧线的终止弧度。 | + | counterclockwise | boolean | 否 | false | 是否逆时针绘制圆弧。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct Arc { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private path2Db: Path2D = new Path2D() - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -316,24 +337,27 @@ arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void 依据圆弧经过的点和圆弧半径创建圆弧路径。 -- 参数 - | 参数 | 类型 | 必填 | 默认值 | 描述 | - | ------ | ------ | ---- | ---- | --------------- | - | x1 | number | 是 | 0 | 圆弧经过的第一个点的x坐标值。 | - | y1 | number | 是 | 0 | 圆弧经过的第一个点的y坐标值。 | - | x2 | number | 是 | 0 | 圆弧经过的第二个点的x坐标值。 | - | y2 | number | 是 | 0 | 圆弧经过的第二个点的y坐标值。 | - | radius | number | 是 | 0 | 圆弧的圆半径值。 | +**参数：** -- 示例 - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | -------- | -------- | -------- | -------- | -------- | + | x1 | number | 是 | 0 | 圆弧经过的第一个点的x坐标值。 | + | y1 | number | 是 | 0 | 圆弧经过的第一个点的y坐标值。 | + | x2 | number | 是 | 0 | 圆弧经过的第二个点的x坐标值。 | + | y2 | number | 是 | 0 | 圆弧经过的第二个点的y坐标值。 | + | radius | number | 是 | 0 | 圆弧的圆半径值。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct ArcTo { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private path2Db: Path2D = new Path2D() - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -356,31 +380,34 @@ arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void ## ellipse -ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, anticlockwise?: number): void +ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise?: number): void 在规定的矩形区域绘制一个椭圆。 -- 参数 - | 参数 | 类型 | 必填 | 默认值 | 描述 | - | ------------- | ------ | ---- | ---- | ------------------------------------ | - | x | number | 是 | 0 | 椭圆圆心的x轴坐标。 | - | y | number | 是 | 0 | 椭圆圆心的y轴坐标。 | - | radiusX | number | 是 | 0 | 椭圆x轴的半径长度。 | - | radiusY | number | 是 | 0 | 椭圆y轴的半径长度。 | - | rotation | number | 是 | 0 | 椭圆的旋转角度，单位为弧度。 | - | startAngle | number | 是 | 0 | 椭圆绘制的起始点角度，以弧度表示。 | - | endAngle | number | 是 | 0 | 椭圆绘制的结束点角度，以弧度表示。 | - | anticlockwise | number | 否 | 0 | 是否以逆时针方向绘制椭圆，0为顺时针，1为逆时针。(可选参数，默认为0) | - -- 示例 - ``` +**参数：** + + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | -------- | -------- | -------- | -------- | -------- | + | x | number | 是 | 0 | 椭圆圆心的x轴坐标。 | + | y | number | 是 | 0 | 椭圆圆心的y轴坐标。 | + | radiusX | number | 是 | 0 | 椭圆x轴的半径长度。 | + | radiusY | number | 是 | 0 | 椭圆y轴的半径长度。 | + | rotation | number | 是 | 0 | 椭圆的旋转角度，单位为弧度。 | + | startAngle | number | 是 | 0 | 椭圆绘制的起始点角度，以弧度表示。 | + | endAngle | number | 是 | 0 | 椭圆绘制的结束点角度，以弧度表示。 | + | counterclockwise | number | 否 | 0 | 是否以逆时针方向绘制椭圆，0为顺时针，1为逆时针。(可选参数，默认为0) | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct CanvasExample { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private path2Db: Path2D = new Path2D() - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) @@ -403,27 +430,30 @@ ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number ## rect -rect(x: number, y: number, width: number, height: number): void +rect(x: number, y: number, w: number, h: number): void 创建矩形路径。 -- 参数 - | 参数 | 类型 | 必填 | 默认值 | 描述 | - | ------ | ------ | ---- | ---- | ------------- | - | x | number | 是 | 0 | 指定矩形的左上角x坐标值。 | - | y | number | 是 | 0 | 指定矩形的左上角y坐标值。 | - | width | number | 是 | 0 | 指定矩形的宽度。 | - | height | number | 是 | 0 | 指定矩形的高度。 | +**参数：** -- 示例 - ``` + | 参数 | 类型 | 必填 | 默认值 | 描述 | + | -------- | -------- | -------- | -------- | -------- | + | x | number | 是 | 0 | 指定矩形的左上角x坐标值。 | + | y | number | 是 | 0 | 指定矩形的左上角y坐标值。 | + | w | number | 是 | 0 | 指定矩形的宽度。 | + | h | number | 是 | 0 | 指定矩形的高度。 | + +**示例：** + + ```ts + // xxx.ets @Entry @Component struct CanvasExample { private settings: RenderingContextSettings = new RenderingContextSettings(true) private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) private path2Db: Path2D = new Path2D() - + build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Canvas(this.context) diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-container-alphabet-indexer.md b/zh-cn/application-dev/reference/arkui-ts/ts-container-alphabet-indexer.md index 6452dfd07a1fbc8e6cfd8661fddba16d195e2c5e..8a63a73e3165d76f039697605846d7dbf5202316 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-container-alphabet-indexer.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-container-alphabet-indexer.md @@ -41,7 +41,7 @@ AlphabetIndexer(value: {arrayValue: Array<string>, selected: number}) | popupFont | [Font](ts-types.md#font) | 设置提示弹窗字体样式。 | | font | [Font](ts-types.md#font) | 设置字母索引条默认字体样式。 | | itemSize | string \| number | 设置字母索引条字母区域大小，字母区域为正方形，即正方形边长。 | -| alignStyle | IndexerAlign | 设置提示弹窗的弹出位置。 | +| alignStyle | IndexerAlign | 设置字母索引条弹框的对齐样式，支持弹窗显示在索引条右侧和左侧。
默认值：IndexerAlign.Right | | selected | number | 设置选中项索引值。 | | popupPosition | {
x?:[Length](ts-types.md#length)
y?:[Length](ts-types.md#length)
} | 设置弹出窗口相对于索引器条上边框中点的位置。 | diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-container-tabcontent.md b/zh-cn/application-dev/reference/arkui-ts/ts-container-tabcontent.md index 13ceeecf8af610e54a3e0e67403df739059ebfd6..2e49627ae5042a02a8ccbcc23710e38ece7b49e2 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-container-tabcontent.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-container-tabcontent.md @@ -7,11 +7,6 @@ > 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -## 权限列表 - -无 - - ## 子组件 支持单个子组件。 @@ -28,7 +23,7 @@ TabContent() | 名称 | 参数类型 | 默认值 | 描述 | | ------ | ------------------------------------------------------------ | ------ | ------------------------------------------------------------ | -| tabBar | string \| [Resource](ts-types.md#resource) \| {
icon?: string \| [Resource](ts-types.md#resource),
text?: string \| [Resource](ts-types.md#resource)
}
\| [CustomBuilder](ts-types.md#custombuilder8)8+ | - | 设置TabBar上显示内容。
CustomBuilder: 构造器，内部可以传入组件（API8版本以上适用）。
>  **说明：**
> 如果icon采用svg格式图源，则要求svg图源删除其自有宽高属性值。如采用带有自有宽高属性的svg图源，icon大小则是svg本身内置的宽高属性值大小。 | +| tabBar | string \| [Resource](ts-types.md#resource) \| {
icon?: string \| [Resource](ts-types.md#resource),
text?: string \| [Resource](ts-types.md#resource)
}
\| [CustomBuilder](ts-types.md#custombuilder8)8+ | - | 设置TabBar上显示内容。
CustomBuilder: 构造器，内部可以传入组件（API8版本以上适用）。
**说明：**
如果icon采用svg格式图源，则要求svg图源删除其自有宽高属性值。如采用带有自有宽高属性的svg图源，icon大小则是svg本身内置的宽高属性值大小。 | > **说明：** > - TabContent组件不支持设置通用宽度属性，其宽度默认撑满Tabs父组件。 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-container-tabs.md b/zh-cn/application-dev/reference/arkui-ts/ts-container-tabs.md index 3d57780417811d75a9bee3d98e1754ad6d8e763c..a6c008d453e8f8bfacae8b91b5a66f344b2f0d9c 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-container-tabs.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-container-tabs.md @@ -7,11 +7,6 @@ > 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -## 权限列表 - -无 - - ## 子组件 包含子组件[TabContent](ts-container-tabcontent.md)。 @@ -19,7 +14,7 @@ ## 接口说明 -Tabs(value: {barPosition?: BarPosition, index?: number, controller?: [TabsController](#tabscontroller)}) +Tabs(value?: {barPosition?: BarPosition, index?: number, controller?: [TabsController](#tabscontroller)}) **参数：** diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-circle.md b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-circle.md index c9883c3e88261d2626e10e20a8f6f44f066d664c..6a9f1a8f1ee8e78ea521df05e11b5f0b697b4372 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-circle.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-circle.md @@ -19,21 +19,32 @@ ## 接口 -Circle(value?: {width: string | number, height: string | number}) +Circle(options?: {width?: string | number, height?: string | number}) -**参数：** +- 参数 + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | -------- | -------- | -------- | -------- | -------- | + | width | string \| number | 否 | 0 | 宽度。 | + | height | string \| number | 否 | 0 | 高度。 | -| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | -| ------ | -------------------------- | ---- | ------ | -------- | -| width | string \| number | 是 | - | 宽度。 | -| height | string \| number | 是 | - | 高度。 | ## 属性 -| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | -| -------- | -------- | ------ | ---- | ------------------ | -| width | Length | 0 | 否 | 圆所在矩形的宽度。 | -| height | Length | 0 | 否 | 圆所在矩形的高度。 | +除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： + +| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | +| -------- | -------- | -------- | -------- | -------- | +| fill | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置填充区域颜色。 | +| fillOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置填充区域透明度。 | +| stroke | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置线条颜色。 | +| strokeDashArray | Array<Length> | [] | 否 | 设置线条间隙。 | +| strokeDashOffset | number \| string | 0 | 否 | 线条绘制起点的偏移量。 | +| strokeLineCap | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | LineCapStyle.Butt | 否 | 设置线条端点绘制样式。 | +| strokeLineJoin | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | LineJoinStyle.Miter | 否 | 设置线条拐角绘制样式。 | +| strokeMiterLimit | number \| string | 4 | 否 | 设置锐角绘制成斜角的极限值。 | +| strokeOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置线条透明度。 | +| strokeWidth | Length | 1 | 否 | 设置线条宽度。 | +| antiAlias | boolean | true | 否 | 是否开启抗锯齿效果。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-ellipse.md b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-ellipse.md index 8bd5b9e6a42a870e5685abb223235498460b73d4..fc57ec26d00126bf70d81ef531589a5dabcb43f5 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-ellipse.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-ellipse.md @@ -20,21 +20,32 @@ ## 接口 -Ellipse(value?: {width: string | number, height: string | number}) +ellipse(options?: {width?: string | number, height?: string | number}) -**参数：** +- 参数 + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | -------- | -------- | -------- | -------- | -------- | + | width | string \| number | 否 | 0 | 宽度。 | + | height | string \| number | 否 | 0 | 高度。 | -| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | -| ------ | -------------------------- | ---- | ------ | -------- | -| width | string \| number | 是 | - | 宽度。 | -| height | string \| number | 是 | - | 高度。 | ## 属性 -| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | -| -------- | -------- | ------ | ---- | -------------------- | -| width | Length | 0 | 否 | 椭圆所在矩形的宽度。 | -| height | Length | 0 | 否 | 椭圆所在矩形的高度。 | +除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： + +| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | +| -------- | -------- | -------- | -------- | -------- | +| fill | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置填充区域颜色。 | +| fillOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置填充区域透明度。 | +| stroke | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 |设置线条颜色。 | +| strokeDashArray | Array<Length> | [] | 否 | 设置线条间隙。 | +| strokeDashOffset | number \| string | 0 | 否 | 线条绘制起点的偏移量。 | +| strokeLineCap | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | LineCapStyle.Butt | 否 | 设置线条端点绘制样式。 | +| strokeLineJoin | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | LineJoinStyle.Miter | 否 | 设置线条拐角绘制样式。 | +| strokeMiterLimit | number \| string | 4 | 否 | 设置锐角绘制成斜角的极限值。 | +| strokeOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置线条透明度。 | +| strokeWidth | Length | 1 | 否 | 设置线条宽度。 | +| antiAlias | boolean | true | 否 | 是否开启抗锯齿效果。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-line.md b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-line.md index ce8dd447cbdac93ac60bba2f74acee9072c25a80..cc7e767ef5e05905bcbccc945dd6a8b267dc637e 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-line.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-line.md @@ -19,29 +19,34 @@ ## 接口 -Line(value?: {width: string | number, height: string | number}) +Line(options?: {width?: string | number, height?: string | number}) -**参数：** +- 参数 + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | -------- | -------- | -------- | -------- | -------- | + | width | string \| number | 否 | 0 | 宽度。 | + | height | string \| number | 否 | 0 | 高度。 | -| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | -| ------ | -------------------------- | ---- | ------ | -------- | -| width | string \| number | 是 | - | 宽度。 | -| height | string \| number | 是 | - | 高度。 | ## 属性 -| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | -| ---------- | ------------- | ----------- | ---- | ------------------------ | -| width | [Length](ts-types.md#length) | 0 | 否 | 直线所在矩形的宽度。 | -| height | [Length](ts-types.md#length) | 0 | 否 | 直线所在矩形的高度。 | -| startPoint | Array<Point> | [0, 0] | 是 | 直线起点坐标(相对坐标)。 | -| endPoint | Array<Point> | [0, 0] | 是 | 直线终点坐标(相对坐标)。 | - -## Point - -| 名称 | 类型定义 | 描述 | -| ----- | --------------------- | ---------------------------------------------------- | -| Point | [[Length](ts-types.md#length), [Length](ts-types.md#length)] | 用于描述点坐标，第一个值为x轴坐标，第二个值为y坐标。 | +除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： + +| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | +| -------- | -------- | -------- | -------- | -------- | +| startPoint | Array | [0, 0] | 是 | 直线起点坐标点(相对坐标)。 | +| endPoint | Array | [0, 0] | 是 | 直线终点坐标点(相对坐标)。 | +| fill | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置填充区域颜色。 | +| fillOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置填充区域透明度。 | +| stroke | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置线条颜色。 | +| strokeDashArray | Array<Length> | [] | 否 | 设置线条间隙。 | +| strokeDashOffset | number \| string | 0 | 否 | 线条绘制起点的偏移量。 | +| strokeLineCap | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | LineCapStyle.Butt | 否 | 设置线条端点绘制样式。 | +| strokeLineJoin | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | LineJoinStyle.Miter | 否 | 设置线条拐角绘制样式。 | +| strokeMiterLimit | number \| string | 4 | 否 | 设置锐角绘制成斜角的极限值。 | +| strokeOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置线条透明度。 | +| strokeWidth | Length | 1 | 否 | 设置线条宽度。 | +| antiAlias | boolean | true | 否 | 是否开启抗锯齿效果。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-path.md b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-path.md index 1846c4a63257deb3cd99566af1baf231b2b43e2e..9ad93694d6b5feb317d6d014e733e51344eb5737 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-path.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-path.md @@ -14,50 +14,54 @@ ## 接口 -Path(value?: { width?: number | string, height?: number | string, commands?: string }) +Path(value?: { width?: number | string; height?: number | string; commands?: string }) -**参数：** +- 参数 -| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | -| -------- | ---------------- | ---- | ---- | ----------- | -| width | number \| string | 否 | 0 | 路径所在矩形的宽度。 | -| height | number \| string | 否 | 0 | 路径所在矩形的高度。 | -| commands | string | 否 | '' | 路径绘制的命令字符串。 | + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | -------- | -------- | ---- | ------ | -------------------- | + | width | number \| string | 否 | 0 | 路径所在矩形的宽度 | + | height | number \| string | 否 | 0 | 路径所在矩形的高度 | + | commands | string | 否 | '' | 路径绘制的命令字符串 | -## 属性 - -| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | -| -------- | --------------------------------------- | ------ | ---- | ------------------------ | -| width | [Length](../../ui/ts-types.md#长度类型) | 0 | 否 | 路径所在矩形画布的宽度。 | -| height | [Length](../../ui/ts-types.md#长度类型) | 0 | 否 | 路径所在矩形画布的高度。 | -| commands | string | '' | 否 | 路径绘制的命令字符串。 | - - -支持的绘制命令如下： - - -- M = moveto - -- L = lineto - -- H = horizontal lineto - -- V = vertical lineto - -- C = curveto - -- S = smooth curveto - -- Q = quadratic Belzier curve - -- T = smooth quadratic Belzier curveto - -- A = elliptical Arc - -- Z = closepath + +## 属性 -如 commands('M0 20 L50 50 L50 100 Z')定义了一条路径，开始于位置（0，20），到达位置（50，50）后再到（50，100），最后在（0，20）处关闭路径。 +除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： + +| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | +| -------- | ----------------------------------- | ---- | ---- | ---------------------------------------- | +| commands | string | '' | 否 | 路径绘制的命令字符串，单位为px。像素单位转换方法请参考[像素单位转换](../../ui/ts-pixel-units.md)。 | +| fill | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置填充区域颜色。 | +| fillOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置填充区域透明度。 | +| stroke | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置线条颜色。 | +| strokeDashArray | Array<Length> | [] | 否 | 设置线条间隙。 | +| strokeDashOffset | number \| string | 0 | 否 | 线条绘制起点的偏移量。 | +| strokeLineCap | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | LineCapStyle.Butt | 否 | 设置线条端点绘制样式。 | +| strokeLineJoin | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | LineJoinStyle.Miter | 否 | 设置线条拐角绘制样式。 | +| strokeMiterLimit | number \| string | 4 | 否 | 设置锐角绘制成斜角的极限值。 | +| strokeOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置线条透明度。 | +| strokeWidth | Length | 1 | 否 | 设置线条宽度。 | +| antiAlias | boolean | true | 否 | 是否开启抗锯齿效果。 | + + +commands支持的绘制命令如下： + +| 命令 | 名称 | 参数 | 说明 | +| ---- | -------------------------------- | ---------------------------------------- | ---------------------------------------- | +| M | moveto | （x y） | 在给定的 (x, y) 坐标处开始一个新的子路径。例如，`M 0 0` 表示将（0, 0）点作为新子路径的起始点。 | +| L | lineto | （x y） | 从当前点到给定的 (x, y) 坐标画一条线，该坐标成为新的当前点。例如，`L 50 50` 表示绘制当前点到（50, 50）点的直线，并将（50, 50）点作为新子路径的起始点。 | +| H | horizontal lineto | x | 从当前点绘制一条水平线，等效于将y坐标指定为0的L命令。例如，`H 50 ` 表示绘制当前点到（50, 0）点的直线，并将（50, 0）点作为新子路径的起始点。 | +| V | vertical lineto | y | 从当前点绘制一条垂直线，等效于将x坐标指定为0的L命令。例如，`V 50 ` 表示绘制当前点到（0, 50）点的直线，并将（0, 50）点作为新子路径的起始点。 | +| C | curveto | (x1 y1 x2 y2 x y) | 使用 (x1, y1) 作为曲线起点的控制点， (x2, y2) 作为曲线终点的控制点，从当前点到 (x, y) 绘制三次贝塞尔曲线。例如，`C100 100 250 100 250 200 ` 表示绘制当前点到（250, 200）点的三次贝塞尔曲线，并将（250, 200）点作为新子路径的起始点。 | +| S | smooth curveto | (x2 y2 x y) | (x2, y2) 作为曲线终点的控制点，绘制从当前点到 (x, y) 绘制三次贝塞尔曲线。若前一个命令是C或S，则起点控制点是上一个命令的终点控制点相对于起点的映射。 例如，`C100 100 250 100 250 200 S400 300 400 200`第二段贝塞尔曲线的起点控制点为（250, 300）。如果没有前一个命令或者前一个命令不是 C或S，则第一个控制点与当前点重合。 | +| Q | quadratic Belzier curve | (x1 y1 x y) | 使用 (x1, y1) 作为控制点，从当前点到 (x, y) 绘制二次贝塞尔曲线。例如，`Q400 50 600 300 ` 表示绘制当前点到（600, 300）点的二次贝塞尔曲线，并将（600, 300）点作为新子路径的起始点。 | +| T | smooth quadratic Belzier curveto | (x y) | 绘制从当前点到 (x, y) 绘制二次贝塞尔曲线。若前一个命令是Q或T，则控制点是上一个命令的终点控制点相对于起点的映射。 例如，`Q400 50 600 300 T1000 300`第二段贝塞尔曲线的控制点为（800, 350）。 如果没有前一个命令或者前一个命令不是 Q或T，则第一个控制点与当前点重合。 | +| A | elliptical Arc | (rx ry x-axis-rotation large-arc-flag sweep-flag x y) | 从当前点到 (x, y) 绘制一条椭圆弧。椭圆的大小和方向由两个半径 (rx, ry) 和x-axis-rotation定义，指示整个椭圆相对于当前坐标系如何旋转（以度为单位）。 large-arc-flag 和 sweep-flag确定弧的绘制方式。 | +| Z | closepath | none | 通过将当前路径连接回当前子路径的初始点来关闭当前子路径。 | + +例如： commands('M0 20 L50 50 L50 100 Z')定义了一个三角形，起始于位置（0，20），接着绘制点（0，20）到点（50，50）的直线，再绘制点（50，50）到点（50，100）的直线，最后绘制点（50，100）到（0，20）的直线关闭路径，形成封闭三角形。 ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-polygon.md b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-polygon.md index ed3a3a4d402b5e6d2246a02b8c7b23c5954c94b1..31188de70e296d8251ec0ce82b98789b492f0ddf 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-polygon.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-polygon.md @@ -19,22 +19,41 @@ ## 接口 -Polygon(value?:{width?: string | number, height?: string | number}) +Polygon(options?: {width?: string | number, height?: string | number}) -**参数：** +- 参数 + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | -------- | -------- | -------- | -------- | -------- | + | width | string \| number | 否 | 0 | 宽度。 | + | height | string \| number | 否 | 0 | 高度。 | -| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | -| ------ | -------------------------- | ---- | ------ | -------- | -| width | string \| number | 是 | - | 宽度。 | -| height | string \| number | 是 | - | 高度。 | ## 属性 -| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | -| -------- | ---------------- | ------ | ---- | ---------------------- | -| width | Length | 0 | 否 | 多边形所在矩形的宽度。 | -| height | Length | 0 | 否 | 多边形所在矩形的高度。 | -| points | Array<any> | - | 是 | 多边形的顶点坐标列表。 | +除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： + +| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | +| -------- | -------- | -------- | -------- | -------- | +| points | Array<Point> | [] | 否 | 多边形的顶点坐标列表。 | +| fill | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置填充区域颜色。 | +| fillOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置填充区域透明度。 | +| stroke | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置线条颜色。 | +| strokeDashArray | Array<Length> | [] | 否 | 设置线条间隙。 | +| strokeDashOffset | number \| string | 0 | 否 | 线条绘制起点的偏移量。 | +| strokeLineCap | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | LineCapStyle.Butt | 否 | 设置线条端点绘制样式。 | +| strokeLineJoin | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | LineJoinStyle.Miter | 否 | 设置线条拐角绘制样式。 | +| strokeMiterLimit | number \| string | 4 | 否 | 设置锐角绘制成斜角的极限值。 | +| strokeOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置线条透明度。 | +| strokeWidth | Length | 1 | 否 | 设置线条宽度。 | +| antiAlias | boolean | true | 否 | 是否开启抗锯齿效果。 | + +## Point + +点坐标类型。 + +| 名称 | 类型定义 | 描述 | +| --------- | -------------------- | ------------------------------------------------------------ | +| Point | [number, number] | 第一个参数为x轴坐标，第二个参数为y轴坐标（相对坐标）。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-polyline.md b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-polyline.md index cd7e78f61fca6fc2bf15433cfbd2c34e4c9894bd..6d754199f6e8fe2025d4d806519b89c3638ca0e6 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-polyline.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-polyline.md @@ -20,22 +20,41 @@ ## 接口 -Polyline(value?: {width?: string | number, height?: string | number}) +Polyline(options?: {width?: string | number, height?: string | number}) -**参数：** +- 参数 + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | -------- | -------- | -------- | -------- | -------- | + | width | string \| number | 否 | 0 | 宽度。 | + | height | string \| number | 否 | 0 | 高度。 | -| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | -| ------ | -------------------------- | ---- | ------ | -------- | -| width | string \| number | 是 | - | 宽度。 | -| height | string \| number | 是 | - | 高度。 | ## 属性 -| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | -| -------- | ---------------- | ------ | ---- | -------------------- | -| width | Length | 0 | 否 | 折线所在矩形的宽度。 | -| height | Length | 0 | 否 | 折线所在矩形的高度。 | -| points | Array<any> | - | 是 | 折线经过坐标点列表。 | +除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： + +| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | +| -------- | -------- | -------- | -------- | -------- | +| points | Array<Point> | [] | 否 | 折线经过坐标点列表。 | +| fill | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置填充区域颜色。 | +| fillOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置填充区域透明度。 | +| stroke | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置线条颜色。 | +| strokeDashArray | Array<Length> | [] | 否 | 设置线条间隙。 | +| strokeDashOffset | number \| string | 0 | 否 | 线条绘制起点的偏移量。 | +| strokeLineCap | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | LineCapStyle.Butt | 否 | 设置线条端点绘制样式。 | +| strokeLineJoin | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | LineJoinStyle.Miter | 否 | 设置线条拐角绘制样式。 | +| strokeMiterLimit | number \| string | 4 | 否 | 设置锐角绘制成斜角的极限值。 | +| strokeOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置线条透明度。 | +| strokeWidth | Length | 1 | 否 | 设置线条宽度。 | +| antiAlias | boolean | true | 否 | 是否开启抗锯齿效果。 | + +## Point + +点坐标类型。 + +| 名称 | 类型定义 | 描述 | +| --------- | -------------------- | ------------------------------------------------------------ | +| Point | [number, number] | 第一个参数为x轴坐标，第二个参数为y轴坐标（相对坐标）。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-rect.md b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-rect.md index ab63e2c22bac7962b5ff03a45405d15bcd1b157a..a0668570471f2d1c3bd9651bfaa6abef790411b6 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-rect.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-rect.md @@ -20,27 +20,39 @@ ## 接口 -Rect(value:{value?: {width?: number | string ,height?: number | string ,radius?: number | string | Array<Length>} | {width?: number | string ,height?: number | string ,radiusWidth?: number | string ,radiusHeight?: number | string }}) +Rect(options?: {width?: string | number,height?: string | number,radius?: string | number | Array<string | number>} | + {width?: string | number,height?: string | number,radiusWidth?: string | number,radiusHeight?: string | number}) -**options参数说明：** +- 参数 + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | -------- | -------- | -------- | -------- | -------- | + | width | string \| number | 否 | 0 | 宽度。 | + | height | string \| number | 否 | 0 | 高度。 | + | radius | string \| number \| Array<string \| number> | 否 | 0 | 圆角半径，支持分别设置四个角的圆角度数。 | + | radiusWidth | string \| number | 否 | 0 | 圆角宽度。 | + | radiusHeight | string \| number | 否 | 0 | 圆角高度。 | -| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | -| ------------ | ----------------------------------------------------------- | ---- | ------ | ---------------------------------------- | -| width | number \| string | 是 | - | 宽度。 | -| height | number \| string | 是 | - | 高度。 | -| radius | number \| string \| Array<any> | 否 | 0 | 圆角半径，支持分别设置四个角的圆角度数。 | -| radiusWidth | number \| string | 否 | 0 | 圆角宽度。 | -| radiusHeight | number \| string | 否 | 0 | 圆角高度。 | ## 属性 -| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | -| ------------ | ------------------------------------ | ------ | ---- | -------------------------------- | -| width | Length | 0 | 否 | 宽度。 | -| height | Length | 0 | 否 | 高度。 | -| radiusWidth | string \| number | 0 | 否 | 圆角的宽度，仅设置宽时宽高一致。 | -| radiusHeight | string \| number | 0 | 否 | 圆角的高度，仅设置高时宽高一致。 | -| radius | Length \| Array<any> | 0 | 否 | 圆角大小。 | +除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： + +| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | +| -------- | -------- | -------- | -------- | -------- | +| radiusWidth | string \| number | 0 | 否 | 圆角的宽度，仅设置宽时宽高一致。 | +| radiusHeight | string \| number | 0 | 否 | 圆角的高度，仅设置高时宽高一致。 | +| radius | string \| number \| Array<string \| number> | 0 | 否 | 圆角半径大小。 | +| fill | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置填充区域颜色。 | +| fillOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置填充区域透明度。 | +| stroke | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置线条颜色。 | +| strokeDashArray | Array<Length> | [] | 否 | 设置线条间隙。 | +| strokeDashOffset | number \| string | 0 | 否 | 线条绘制起点的偏移量。 | +| strokeLineCap | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | LineCapStyle.Butt | 否 | 设置线条端点绘制样式。 | +| strokeLineJoin | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | LineJoinStyle.Miter | 否 | 设置线条拐角绘制样式。 | +| strokeMiterLimit | number \| string | 4 | 否 | 设置锐角绘制成斜角的极限值。 | +| strokeOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置线条透明度。 | +| strokeWidth | Length | 1 | 否 | 设置线条宽度。 | +| antiAlias | boolean | true | 否 | 是否开启抗锯齿效果。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-shape.md b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-shape.md index b00ca3fa6b198dbafc1a1152e163b9f03310f91a..70472c53c508d202710a7211d9da7aa2b5b5b409 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-shape.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-drawing-components-shape.md @@ -23,31 +23,33 @@ ## 接口 -Shape(value?: {target?: PixelMap}) +Shape(value?: PixelMap) -**参数：** +- 参数 + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | -------- | -------- | -------- | -------- | -------- | + | value | PixelMap | 否 | - | 绘制目标，可将图形绘制在指定的PixelMap对象中，若未设置，则在当前绘制目标中进行绘制。 | -| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | -| ------ | -------- | ---- | ------ | ------------------------------------------------------------ | -| target | PixelMap | 否 | null | 绘制目标，可将图形绘制在指定的PixelMap对象中，若未设置，则在当前绘制目标中进行绘制。 | ## 属性 -| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | -| ---------------- | ------------------------------------------------------------ | ------------------- | ---- | -------------------------- | -| viewPort | {
x?: [Length](ts-types.md#length),
y?:  [Length](ts-types.md#length),
width?:  [Length](ts-types.md#length),
height?:  [Length](ts-types.md#length)
} | - | 是 | 形状的视口。 | -| fill | [ResourceColor](ts-types.md#resourcecolor8) | Black | 否 | 填充颜色。 | -| stroke | [ResourceColor](ts-types.md#resourcecolor8) | - | 否 | 边框颜色。 | -| strokeDashArray | Array<any> | [] | 否 | 设置边框的间隙。 | -| strokeDashOffset | number \| string | 0 | 否 | 边框绘制起点的偏移量。 | -| strokeLineCap | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | LineCapStyle.Butt | 否 | 路径端点绘制样式。 | -| strokeLineJoin | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | LineJoinStyle.Miter | 否 | 边框拐角绘制样式。 | -| strokeMiterLimit | number \| string | 4 | 否 | 锐角绘制成斜角的极限值。 | -| strokeOpacity | number \| string \| [Resource](ts-types.md#resource) | 1 | 否 | 设置边框的不透明度。 | -| strokeWidth | number \| string | 1 | 否 | 设置边框的宽度。 | -| antiAlias | boolean | true | 否 | 是否开启抗锯齿。 | -| mesh | Array<any>,
column:number,
row:number | - | 否 | 绘制网格时调用。 | -| fillOpacity | number \| string \|  [Resource](ts-types.md#resource) | 1 | 否 | 设置形状填充部分的透明度。 | +除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： + +| 参数名称 | 参数类型 | 默认值 | 必填 | 参数描述 | +| -------- | -------- | -------- | -------- | -------- | +| viewPort | {
x?: number \| string,
y?: number \| string,
width?: number \| string,
height?: number \| string
} | { x:0, y:0, width:0, height:0 } | 否 | 形状的视口。 | +| fill | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置填充区域颜色。 | +| fillOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置填充区域透明度。 | +| stroke | [ResourceColor](../../ui/ts-types.md) | Color.Black | 否 | 设置线条颜色。 | +| strokeDashArray | Array<Length> | [] | 否 | 设置线条间隙。 | +| strokeDashOffset | number \| string | 0 | 否 | 线条绘制起点的偏移量。 | +| strokeLineCap | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | LineCapStyle.Butt | 否 | 设置线条端点绘制样式。 | +| strokeLineJoin | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | LineJoinStyle.Miter | 否 | 设置线条拐角绘制样式。 | +| strokeMiterLimit | number \| string | 4 | 否 | 设置锐角绘制成斜角的极限值。 | +| strokeOpacity | number \| string \| [Resource](../../ui/ts-types.md#resource类型) | 1 | 否 | 设置线条透明度。 | +| strokeWidth | number \| string | 1 | 否 | 设置线条宽度。 | +| antiAlias | boolean | true | 否 | 是否开启抗锯齿效果。 | +| mesh8+ | Array<number>,number,number | [],0,0 | 否 | 设置mesh效果。第一个参数为长度（column + 1）* （row + 1）* 2的数组，它记录了扭曲后的位图各个顶点位置，第二个参数为mesh矩阵列数column，第三个参数为mesh矩阵行数row。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-gesture-settings.md b/zh-cn/application-dev/reference/arkui-ts/ts-gesture-settings.md index 50268acf5cdb0f46cfe5cb04d8124660b7880d27..8fe61b8d874cf99ed9f63ed79ddd9ea49cadec63 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-gesture-settings.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-gesture-settings.md @@ -43,7 +43,7 @@ ## 响应手势事件 -组件通过gesture方法绑定手势对象，可以通过手势对象提供的事件相应响应手势操作。如通过TapGesture对象的onAction事件响应点击事件。具体事件定义见各个手势对象章节。 +组件通过gesture方法绑定手势对象，可以通过手势对象提供的事件相应响应手势操作。例如通过TapGesture对象的onAction事件响应点击事件。其余手势的事件定义见各个手势对象章节。 - TapGesture事件说明 | 名称 | 功能描述 | @@ -51,10 +51,36 @@ | onAction((event?:GestureEvent) => void) | Tap手势识别成功回调。 | - GestureEvent对象说明 - | 属性名称 | 属性类型 | 描述 | + | 名称 | 类型 | 描述 | | -------- | -------- | -------- | - | timestamp | number | 事件时间戳。 | - | target8+ | [EventTarget](ts-universal-events-click.md) | 触发手势事件的元素对象。 | + | timestamp8+ | number | 事件时间戳。 | + | target8+ | [EventTarget](ts-universal-events-click.md) | 触发手势事件的元素对象显示区域。 | + | source8+ | SourceType | 事件输入设备。 | + | repeat | boolean | 是否为重复触发事件，用于LongPressGesture手势触发场景。 | + | fingerList8+ | FingerInfo[] | 触发事件的所有手指信息，用于LongPressGesture与TapGesture手势触发场景。 | + | offsetX | number | 手势事件x轴偏移量，单位为vp，用于PanGesture手势触发场景。 | + | offsetY | number | 手势事件y轴偏移量，单位为vp，用于PanGesture手势触发场景。 | + | angle | number | 用于RotationGesture手势触发场景时，表示旋转角度；用于SwipeGesture手势触发场景时，表示滑动手势的角度，即两根手指间的线段与水平方向的夹角变化的度数。
>  **说明：**
> 角度计算方式：滑动手势被识别到后，连接两根手指之间的线被识别为起始线条，随着手指的滑动，手指之间的线条会发生旋转，根据起始线条两端点和当前线条两端点的坐标，使用反正切函数分别计算其相对于水平方向的夹角，最后arctan2(cy2-cy1,cx2-cx1)-arctan2(y2-y1,x2-x1)为旋转的角度。以起始线条为坐标系，顺时针旋转为0到180度，逆时针旋转为-180到0度。 | + | speed8+ | number | 滑动手势速度，即所有手指滑动的平均速度，单位为vp/秒，用于SwipeGesture手势触发场景。 | + | scale | number | 缩放比例，用于PinchGesture手势触发场景。 | + | pinchCenterX | number | 捏合手势中心点x轴坐标，单位为vp，用于PinchGesture手势触发场景。 | + | pinchCenterY | number | 捏合手势中心点y轴坐标，单位为vp，用于PinchGesture手势触发场景。 | + +- SourceType + | 名称 | 描述 | + | -------- | -------- | + | Unknown | 未知设备。 | + | Mouse | 鼠标。 | + | TouchScreen | 触摸屏。 | + +- FingerInfo对象说明 + | 名称 | 类型 | 描述 | + | -------- | -------- | -------- | + | id | number | 手指的索引编号。 | + | globalX | number | 相对于设备屏幕左上角的x轴坐标。 | + | globalY | number | 相对于设备屏幕左上角的y轴坐标。 | + | localX | number | 相对于当前组件元素左上角的x轴坐标。 | + | localY | number | 相对于当前组件元素左上角的y轴坐标。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-matrix-transformation.md b/zh-cn/application-dev/reference/arkui-ts/ts-matrix-transformation.md index 40d89097abf49f7a49ec24b5e49387c645d66c86..0cc8f66a7e55f6d722b4ed0109bb971db2b6f284 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-matrix-transformation.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-matrix-transformation.md @@ -6,7 +6,7 @@ ## 导入模块 -``` +```ts import matrix4 from '@ohos.matrix4' ``` @@ -30,35 +30,35 @@ Matrix的构造函数，可以通过传入的参数创建一个四阶矩阵， | array | Array<number> | 是 | [1, 0, 0, 0,
0, 1, 0, 0,
0, 0, 1, 0,
0, 0, 0, 1] | 参数为长度为16（4\*4）的number数组, 详情见参数描述。 | - 返回值 - | 类型 | 说明 | + | 类型 | 说明 | | -------- | -------- | - | Object | 根据入参创建的四阶矩阵对象。 | + | Object | 根据入参创建的四阶矩阵对象。 | - 参数描述 - | 参数名 | 类型 | 必填 | 说明 | + | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | m00 | number | 是 | x轴缩放值，单位矩阵默认为1。 | - | m01 | number | 是 | 第2个值，xyz轴旋转会影响这个值。 | - | m02 | number | 是 | 第3个值，xyz轴旋转会影响这个值。 | - | m03 | number | 是 | 无实际意义。 | - | m10 | number | 是 | 第5个值，xyz轴旋转会影响这个值。 | - | m11 | number | 是 | y轴缩放值，单位矩阵默认为1。 | - | m12 | number | 是 | 第7个值，xyz轴旋转会影响这个值。 | - | m13 | number | 是 | 无实际意义。 | - | m20 | number | 是 | 第9个值，xyz轴旋转会影响这个值。 | - | m21 | number | 是 | 第10个值，xyz轴旋转会影响这个值。 | - | m22 | number | 是 | z轴缩放值，单位矩阵默认为1。 | - | m23 | number | 是 | 无实际意义。 | - | m30 | number | 是 | x轴平移值，单位px，单位矩阵默认为0。 | - | m31 | number | 是 | y轴平移值，单位px，单位矩阵默认为0。 | - | m32 | number | 是 | z轴平移值，单位px，单位矩阵默认为0。 | - | m33 | number | 是 | 齐次坐标下生效，产生透视投影效果。 | + | m00 | number | 是 | x轴缩放值，单位矩阵默认为1。 | + | m01 | number | 是 | 第2个值，xyz轴旋转会影响这个值。 | + | m02 | number | 是 | 第3个值，xyz轴旋转会影响这个值。 | + | m03 | number | 是 | 无实际意义。 | + | m10 | number | 是 | 第5个值，xyz轴旋转会影响这个值。 | + | m11 | number | 是 | y轴缩放值，单位矩阵默认为1。 | + | m12 | number | 是 | 第7个值，xyz轴旋转会影响这个值。 | + | m13 | number | 是 | 无实际意义。 | + | m20 | number | 是 | 第9个值，xyz轴旋转会影响这个值。 | + | m21 | number | 是 | 第10个值，xyz轴旋转会影响这个值。 | + | m22 | number | 是 | z轴缩放值，单位矩阵默认为1。 | + | m23 | number | 是 | 无实际意义。 | + | m30 | number | 是 | x轴平移值，单位px，单位矩阵默认为0。 | + | m31 | number | 是 | y轴平移值，单位px，单位矩阵默认为0。 | + | m32 | number | 是 | z轴平移值，单位px，单位矩阵默认为0。 | + | m33 | number | 是 | 齐次坐标下生效，产生透视投影效果。 | - 示例 - ``` - import Matrix4 from '@ohos.matrix4' + ```ts + import matrix4 from '@ohos.matrix4' // 创建一个四阶矩阵 - let matrix = Matrix4.init([1.0, 0.0, 0.0, 0.0, + let matrix = matrix4.init([1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0]) @@ -74,19 +74,19 @@ Matrix的初始化函数，可以返回一个单位矩阵对象。 - 返回值 - | 类型 | 说明 | + | 类型 | 说明 | | -------- | -------- | - | Object | 单位矩阵对象。 | + | Object | 单位矩阵对象。 | - 示例 - ``` + ```ts // matrix1 和 matrix2 效果一致 - import Matrix4 from '@ohos.matrix4' - let matrix = Matrix4.init([1.0, 0.0, 0.0, 0.0, + import matrix4 from '@ohos.matrix4' + let matrix = matrix4.init([1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0]) - let matrix2 = Matrix4.identity() + let matrix2 = matrix4.identity() ``` @@ -99,17 +99,17 @@ Matrix的拷贝函数，可以拷贝一份当前的矩阵对象。 - 返回值 - | 类型 | 说明 | + | 类型 | 说明 | | -------- | -------- | - | Object | 当前矩阵的拷贝对象。 | + | Object | 当前矩阵的拷贝对象。 | - 示例 - ``` - import Matrix4 from '@ohos.matrix4' + ```ts + import matrix4 from '@ohos.matrix4' @Entry @Component struct Test { - private matrix1 = Matrix4.identity().translate({x:100}) + private matrix1 = matrix4.identity().translate({x:100}) private matrix2 = this.matrix1.copy().scale({x:2}) build() { Column() { @@ -142,23 +142,23 @@ Matrix的叠加函数，可以将两个矩阵的效果叠加起来生成一个 - 参数 - | 参数名 | 类型 | 必填 | 默认值 | 说明 | + | 参数名 | 类型 | 必填 | 默认值 | 说明 | | -------- | -------- | -------- | -------- | -------- | - | matrix | Matrix4 | 是 | - | 待叠加的矩阵对象。 | + | matrix | Matrix4 | 是 | - | 待叠加的矩阵对象。 | - 返回值 - | 类型 | 说明 | + | 类型 | 说明 | | -------- | -------- | - | Object | 矩阵叠加后的对象。 | + | Object | 矩阵叠加后的对象。 | - 示例 - ``` - import Matrix4 from '@ohos.matrix4' + ```ts + import matrix4 from '@ohos.matrix4' @Entry @Component struct Test { - private matrix1 = Matrix4.identity().translate({x:200}).copy() - private matrix2 = Matrix4.identity().scale({x:2}).copy() + private matrix1 = matrix4.identity().translate({x:200}).copy() + private matrix2 = matrix4.identity().scale({x:2}).copy() build() { Column() { // 先平移x轴100px，再缩放两倍x轴 @@ -183,16 +183,16 @@ Matrix的逆函数，可以返回一个当前矩阵对象的逆矩阵，即效 - 返回值 - | 类型 | 说明 | + | 类型 | 说明 | | -------- | -------- | - | Object | 当前矩阵的逆矩阵对象。 | + | Object | 当前矩阵的逆矩阵对象。 | - 示例 - ``` - import Matrix4 from '@ohos.matrix4' + ```ts + import matrix4 from '@ohos.matrix4' // matrix1(宽放大2倍) 和 matrix2(宽缩小2倍) 效果相反 - let matrix1 = Matrix4.identity().scale({x:2}) - let matrix2 = matrix1.invert() + let matrix1 = matrix4.identity().scale({x:2}) + let matrix2 = matrix1.copy().invert() ``` @@ -205,25 +205,25 @@ Matrix的平移函数，可以为当前矩阵增加x轴/Y轴/Z轴平移效果。 - 参数 - | 参数名 | 类型 | 必填 | 默认值 | 说明 | + | 参数名 | 类型 | 必填 | 默认值 | 说明 | | -------- | -------- | -------- | -------- | -------- | - | x | number | 否 | 0 | x轴的平移距离，单位px。 | - | y | number | 否 | 0 | y轴的平移距离，单位px。 | - | z | number | 否 | 0 | z轴的平移距离，单位px。 | + | x | number | 否 | 0 | x轴的平移距离，单位px。 | + | y | number | 否 | 0 | y轴的平移距离，单位px。 | + | z | number | 否 | 0 | z轴的平移距离，单位px。 | - 返回值 - | 类型 | 说明 | + | 类型 | 说明 | | -------- | -------- | - | Object | 增加好平移效果后的矩阵对象。 | + | Object | 增加好平移效果后的矩阵对象。 | - 示例 - ``` - import Matrix4 from '@ohos.matrix4' + ```ts + import matrix4 from '@ohos.matrix4' @Entry @Component struct Test { - private matrix1 = Matrix4.identity().translate({x:100, y:200, z:30}) + private matrix1 = matrix4.identity().translate({x:100, y:200, z:30}) build() { Column() { Image($r("app.media.bg1")).transform(this.matrix1) @@ -246,27 +246,27 @@ Matrix的缩放函数，可以为当前矩阵增加x轴/Y轴/Z轴缩放效果。 - 参数 - | 参数名 | 类型 | 必填 | 默认值 | 说明 | + | 参数名 | 类型 | 必填 | 默认值 | 说明 | | -------- | -------- | -------- | -------- | -------- | - | x | number | 否 | 1 | x轴的缩放倍数。 | - | y | number | 否 | 1 | y轴的缩放倍数。 | - | z | number | 否 | 1 | z轴的缩放倍数。 | - | centerX | number | 否 | 0 | 变换中心点x轴坐标。 | - | centerY | number | 否 | 0 | 变换中心点y轴坐标。 | + | x | number | 否 | 1 | x轴的缩放倍数。 | + | y | number | 否 | 1 | y轴的缩放倍数。 | + | z | number | 否 | 1 | z轴的缩放倍数。 | + | centerX | number | 否 | 0 | 变换中心点x轴坐标。 | + | centerY | number | 否 | 0 | 变换中心点y轴坐标。 | - 返回值 - | 类型 | 说明 | + | 类型 | 说明 | | -------- | -------- | - | Object | 增加好缩放效果后的矩阵对象。 | + | Object | 增加好缩放效果后的矩阵对象。 | - 示例 - ``` - import Matrix4 from '@ohos.matrix4' + ```ts + import matrix4 from '@ohos.matrix4' @Entry @Component struct Test { - private matrix1 = Matrix4.identity().scale({x:2, y:3, z:4, centerX:50, centerY:50}) + private matrix1 = matrix4.identity().scale({x:2, y:3, z:4, centerX:50, centerY:50}) build() { Column() { Image($r("app.media.bg1")).transform(this.matrix1) @@ -289,28 +289,28 @@ Matrix的旋转函数，可以为当前矩阵增加x轴/Y轴/Z轴旋转效果。 - 参数 - | 参数名 | 类型 | 必填 | 默认值 | 说明 | + | 参数名 | 类型 | 必填 | 默认值 | 说明 | | -------- | -------- | -------- | -------- | -------- | - | x | number | 否 | 1 | 旋转轴向量x坐标。 | - | y | number | 否 | 1 | 旋转轴向量y坐标。 | - | z | number | 否 | 1 | 旋转轴向量z坐标。 | - | angle | number | 否 | 0 | 旋转角度。 | - | centerX | number | 否 | 0 | 变换中心点x轴坐标。 | - | centerY | number | 否 | 0 | 变换中心点y轴坐标。 | + | x | number | 否 | 1 | 旋转轴向量x坐标。 | + | y | number | 否 | 1 | 旋转轴向量y坐标。 | + | z | number | 否 | 1 | 旋转轴向量z坐标。 | + | angle | number | 否 | 0 | 旋转角度。 | + | centerX | number | 否 | 0 | 变换中心点x轴坐标。 | + | centerY | number | 否 | 0 | 变换中心点y轴坐标。 | - 返回值 - | 类型 | 说明 | + | 类型 | 说明 | | -------- | -------- | - | Object | 增加好旋转效果后的矩阵对象。 | + | Object | 增加好旋转效果后的矩阵对象。 | - 示例 - ``` - import Matrix4 from '@ohos.matrix4' + ```ts + import matrix4 from '@ohos.matrix4' @Entry @Component struct Test { - private matrix1 = Matrix4.identity().rotate({x:1, y:1, z:2, angle:30}) + private matrix1 = matrix4.identity().rotate({x:1, y:1, z:2, angle:30}) build() { Column() { Image($r("app.media.bg1")).transform(this.matrix1) @@ -333,25 +333,25 @@ Matrix的坐标点转换函数，可以将当前的变换效果作用到一个 - 参数 - | 参数名 | 类型 | 必填 | 默认值 | 说明 | + | 参数名 | 类型 | 必填 | 默认值 | 说明 | | -------- | -------- | -------- | -------- | -------- | - | point | Point | 是 | - | 需要转换的坐标点。 | + | point | Point | 是 | - | 需要转换的坐标点。 | - 返回值 - | 类型 | 说明 | + | 类型 | 说明 | | -------- | -------- | - | Point | 返回矩阵变换后的Point对象。 | + | Point | 返回矩阵变换后的Point对象。 | - 示例 - ``` - import Matrix4 from '@ohos.matrix4' + ```ts + import matrix4 from '@ohos.matrix4' import prompt from '@system.prompt' @Entry @Component struct Test { - private matrix1 = Matrix4.identity().transformPoint([100, 10]) + private matrix1 = matrix4.identity().transformPoint([100, 10]) build() { Column() { Button("get Point") diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-media-components-video.md b/zh-cn/application-dev/reference/arkui-ts/ts-media-components-video.md index 2ebe1ba22ebfdf25bfd8133f271111f47a8798d8..1a1d6e4b6767a22f03971a22f5d6e7d8ce7d9652 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-media-components-video.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-media-components-video.md @@ -1,10 +1,11 @@ # Video -> **说明：** -> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 - 视频播放组件。 +> **说明：** +> +> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 + ## 权限列表 使用网络视频时，需要在config或者module.json对应的"abilities"中添加网络使用权限ohos.permission.INTERNET。 @@ -27,7 +28,7 @@ ## 接口 - Video(value: {src?: string | Resource, currentProgressRate?: number | string | PlaybackSpeed, previewUri?: string | PixelMap | Resource, controller?: VideoController}) +Video(value: {src?: string | Resource, currentProgressRate?: number | string | PlaybackSpeed, previewUri?: string | PixelMap | Resource, controller?: VideoController}) **参数：** @@ -68,10 +69,10 @@ | onPause(event:() => void) | 暂停时触发该事件。 | | onFinish(event:() => void) | 播放结束时触发该事件。 | | onError(event:() => void) | 播放失败时触发该事件。 | -| onPrepared(callBack:(event?: { duration: number }) => void) | 视频准备完成时触发该事件，通过duration可以获取视频时长，单位为s。
- duration: 视频的时长。 | -| onSeeking(callBack:(event?: { time: number }) => void) | 操作进度条过程时上报时间信息，单位为s。 | -| onSeeked(callBack:(event?: { time: number }) => void) | 操作进度条完成后，上报播放时间信息，单位为s。 | -| onUpdate(callBack:(event?: { time: number }) => void) | 播放进度变化时触发该事件，单位为s，更新时间间隔为250ms。 | +| onPrepared(callback:(event?: { duration: number }) => void) | 视频准备完成时触发该事件，通过duration可以获取视频时长，单位为s。
- duration: 视频的时长。 | +| onSeeking(callback:(event?: { time: number }) => void) | 操作进度条过程时上报时间信息，单位为s。 | +| onSeeked(callback:(event?: { time: number }) => void) | 操作进度条完成后，上报播放时间信息，单位为s。 | +| onUpdate(callback:(event?: { time: number }) => void) | 播放进度变化时触发该事件，单位为s，更新时间间隔为250ms。 | ## VideoController diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-methods-textpicker-dialog.md b/zh-cn/application-dev/reference/arkui-ts/ts-methods-textpicker-dialog.md index 94cb1603b4f6efd9eec769a04b6aa27c80efbf2f..8105b2ed1eb65069c16d37442f3ee997695fa3d1 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-methods-textpicker-dialog.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-methods-textpicker-dialog.md @@ -21,7 +21,7 @@ show(options: TextPickerDialogOptions) | range | string[] | 是 | - | 选择器的数据选择范围。 | | selected | number | 否 | 0 | 选中项在数组中的index值。 | | value | string | 否 | 第一个元素值 | 选中项的值，优先级低于selected。 | - | defaultPickerItemHeight | number | 否 | - | 默认Picker内容项元素高度。 | + | defaultPickerItemHeight | number \| string | 否 | - | 默认Picker内容项元素高度。 | | onAccept | (value: TextPickerResult) => void | 否 | - | 点击弹窗中确定按钮时触发。 | | onCancel | () => void | 否 | - | 点击弹窗中取消按钮时触发。 | | onChange | (value: TextPickerResult) => void | 否 | - | 滑动选择器，当前选择项改变时触发。 | diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md b/zh-cn/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md index f62674077b93bb96247757fbbdd6d202fdbd3e39..29f42de35dc9438639a8b5fe09b9959b92871aed 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md @@ -11,39 +11,40 @@ OffscreenCanvasRenderingContext2D(width: number, height: number, setting: RenderingContextSettings) -- 参数 - | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | - | ------- | ---------------------------------------- | ---- | ---- | ------------------------------ | - | width | number | 是 | - | 离屏画布的宽度 | - | height | number | 是 | - | 离屏画布的高度 | - | setting | [RenderingContextSettings](ts-canvasrenderingcontext2d.md#renderingcontextsettings) | 是 | - | 见RenderingContextSettings接口描述。 | +**参数：** +| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | +| ------- | ---------------------------------------- | ---- | ---- | ------------------------------ | +| width | number | 是 | - | 离屏画布的宽度 | +| height | number | 是 | - | 离屏画布的高度 | +| setting | [RenderingContextSettings](ts-canvasrenderingcontext2d.md#renderingcontextsettings) | 是 | - | 见RenderingContextSettings接口描述。 | -## 属性 -| 名称 | 类型 | 默认值 | 描述 | -| ---------------------------------------- | ---------------------------------------- | ---------------------------------------- | ---------------------------------------- | -| [fillStyle](#fillstyle) | <color> \| [CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#canvaspattern) | - | 指定绘制的填充色。
- 类型为<color>时，表示设置填充区域的颜色。
- 类型为CanvasGradient时，表示渐变对象，使用 [createLinearGradient](#createlineargradient)方法创建。
- 类型为CanvasPattern时，使用[createPattern](#createpattern)方法创建。 | -| [lineWidth](#linewidth) | number | - | 设置绘制线条的宽度。 | -| [strokeStyle](#strokestyle) | <color> \| [CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#canvaspattern) | - | 设置描边的颜色。
- 类型为<color>时，表示设置描边使用的颜色。
- 类型为CanvasGradient时，表示渐变对象，使用[createLinearGradient](#createlineargradient)方法创建。
- 类型为CanvasPattern时，使用[createPattern](#createpattern)方法创建。 | -| [lineCap](#linecap) | string | 'butt' | 指定线端点的样式，可选值为：
- 'butt'：线端点以方形结束。
- 'round'：线端点以圆形结束。
- 'square'：线端点以方形结束，该样式下会增加一个长度和线段厚度相同，宽度是线段厚度一半的矩形。 | -| [lineJoin](#linejoin) | string | 'miter' | 指定线段间相交的交点样式，可选值为：
- 'round'：在线段相连处绘制一个扇形，扇形的圆角半径是线段的宽度。
- 'bevel'：在线段相连处使用三角形为底填充， 每个部分矩形拐角独立。
- 'miter'：在相连部分的外边缘处进行延伸，使其相交于一点，形成一个菱形区域，该属性可以通过设置miterLimit属性展现效果。 | -| [miterLimit](#miterlimit) | number | 10 | 设置斜接面限制值，该值指定了线条相交处内角和外角的距离。 | -| [font](#font) | string | 'normal normal 14px sans-serif' | 设置文本绘制中的字体样式。
语法：ctx.font='font-size font-family'
- font-size(可选)，指定字号和行高，单位只支持px。
- font-family(可选)，指定字体系列。
语法：ctx.font='font-style font-weight font-size font-family'
- font-style(可选)，用于指定字体样式，支持如下几种样式：'normal', 'italic'。
- font-weight(可选)，用于指定字体的粗细，支持如下几种类型：'normal', 'bold', 'bolder', 'lighter', 100, 200, 300, 400, 500, 600, 700, 800, 900。
- font-size(可选)，指定字号和行高，单位只支持px。
- font-family(可选)，指定字体系列，支持如下几种类型：'sans-serif', 'serif', 'monospace'。 | -| [textAlign](#textalign) | string | 'left' | 设置文本绘制中的文本对齐方式，可选值为：
- 'left'：文本左对齐。
- 'right'：文本右对齐。
- 'center'：文本居中对齐。
- 'start'：文本对齐界线开始的地方。
- 'end'：文本对齐界线结束的地方。
>  **说明：**
> ltr布局模式下start和left一致，rtl布局模式下start和right一致·。 | -| [textBaseline](#textbaseline) | string | 'alphabetic' | 设置文本绘制中的水平对齐方式，可选值为：
- 'alphabetic'：文本基线是标准的字母基线。
- 'top'：文本基线在文本块的顶部。
- 'hanging'：文本基线是悬挂基线。
- 'middle'：文本基线在文本块的中间。
- 'ideographic'：文字基线是表意字基线；如果字符本身超出了alphabetic基线，那么ideograhpic基线位置在字符本身的底部。
- 'bottom'：文本基线在文本块的底部。 与ideographic基线的区别在于ideographic 基线不需要考虑下行字母。 | -| [globalAlpha](#globalalpha) | number | - | 设置透明度，0.0为完全透明，1.0为完全不透明。 | -| [lineDashOffset](#linedashoffset) | number | 0.0 | 设置画布的虚线偏移量，精度为float。 | -| [globalCompositeOperation](#globalcompositeoperation) | string | 'source-over' | 设置合成操作的方式。类型字段可选值有'source-over'，'source-atop'，'source-in'，'source-out'，'destination-over'，'destination-atop'，'destination-in'，'destination-out'，'lighter'，'copy'，'xor'。 | -| [shadowBlur](#shadowblur) | number | 0.0 | 设置绘制阴影时的模糊级别，值越大越模糊，精度为float。 | -| [shadowColor](#shadowcolor) | <color> | - | 设置绘制阴影时的阴影颜色。 | -| [shadowOffsetX](#shadowoffsetx) | number | - | 设置绘制阴影时和原有对象的水平偏移值。 | -| [shadowOffsetY](#shadowoffsety) | number | - | 设置绘制阴影时和原有对象的垂直偏移值。 | -| [imageSmoothingEnabled](#imagesmoothingenabled) | boolean | true | 用于设置绘制图片时是否进行图像平滑度调整，true为启用，false为不启用。 | -| imageSmoothingQuality | string | 'low' | 用于设置图像平滑度，支持如下三种类型：'low', 'medium', 'high'。 | +## 属性 -> **说明：** -> <color>类型格式为 'rgb(255, 255, 255)'，'rgba(255, 255, 255, 1.0)'，'\#FFFFFF'。 +| 名称 | 类型 | 描述 | +| ---------------------------------------- | ---------------------------------------- | ---------------------------------------- | +| [fillStyle](#fillstyle) | string \| [CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#canvaspattern) | 指定绘制的填充色。
- 类型为string时，表示设置填充区域的颜色。
- 类型为CanvasGradient时，表示渐变对象，使用[createLinearGradient](#createlineargradient)方法创建。
- 类型为CanvasPattern时，使用[createPattern](#createpattern)方法创建。 | +| [lineWidth](#linewidth) | number | 设置绘制线条的宽度。 | +| [strokeStyle](#strokestyle) | string \| [CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#canvaspattern) | 设置描边的颜色。
- 类型为string时，表示设置描边使用的颜色。
- 类型为CanvasGradient时，表示渐变对象，使用[createLinearGradient](#createlineargradient)方法创建。
- 类型为CanvasPattern时，使用[createPattern](#createpattern)方法创建。 | +| [lineCap](#linecap) | CanvasLineCap | 指定线端点的样式，可选值为：
- 'butt'：线端点以方形结束。
- 'round'：线端点以圆形结束。
- 'square'：线端点以方形结束，该样式下会增加一个长度和线段厚度相同，宽度是线段厚度一半的矩形。
- 默认值：'butt'。 | +| [lineJoin](#linejoin) | CanvasLineJoin | 指定线段间相交的交点样式，可选值为：
- 'round'：在线段相连处绘制一个扇形，扇形的圆角半径是线段的宽度。
- 'bevel'：在线段相连处使用三角形为底填充， 每个部分矩形拐角独立。
- 'miter'：在相连部分的外边缘处进行延伸，使其相交于一点，形成一个菱形区域，该属性可以通过设置miterLimit属性展现效果。
- 默认值：'miter'。 | +| [miterLimit](#miterlimit) | number | 设置斜接面限制值，该值指定了线条相交处内角和外角的距离。
- 默认值：10。 | +| [font](#font) | string | 设置文本绘制中的字体样式。
语法：ctx.font='font-size font-family'
- font-size(可选)，指定字号和行高，单位只支持px。
- font-family(可选)，指定字体系列。
语法：ctx.font='font-style font-weight font-size font-family'
- font-style(可选)，用于指定字体样式，支持如下几种样式：'normal','italic'。
- font-weight(可选)，用于指定字体的粗细，支持如下几种类型：'normal', 'bold', 'bolder', 'lighter', 100, 200, 300, 400, 500, 600, 700, 800, 900。
- font-size(可选)，指定字号和行高，单位只支持px。
- font-family(可选)，指定字体系列，支持如下几种类型：'sans-serif', 'serif', 'monospace'。
- 默认值：'normal normal 14px sans-serif'。 | +| [textAlign](#textalign) | CanvasTextAlign | 设置文本绘制中的文本对齐方式，可选值为：
- 'left'：文本左对齐。
- 'right'：文本右对齐。
- 'center'：文本居中对齐。
- 'start'：文本对齐界线开始的地方。
- 'end'：文本对齐界线结束的地方。
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> ltr布局模式下'start'和'left'一致，rtl布局模式下'start'和'right'一致·。
- 默认值：'left'。 | +| [textBaseline](#textbaseline) | CanvasTextBaseline | 设置文本绘制中的水平对齐方式，可选值为：
- 'alphabetic'：文本基线是标准的字母基线。
- 'top'：文本基线在文本块的顶部。
- 'hanging'：文本基线是悬挂基线。
- 'middle'：文本基线在文本块的中间。
- 'ideographic'：文字基线是表意字基线；如果字符本身超出了alphabetic基线，那么ideograhpic基线位置在字符本身的底部。
- 'bottom'：文本基线在文本块的底部。 与ideographic基线的区别在于ideographic基线不需要考虑下行字母。
- 默认值：'alphabetic'。 | +| [globalAlpha](#globalalpha) | number | 设置透明度，0.0为完全透明，1.0为完全不透明。 | +| [lineDashOffset](#linedashoffset) | number | 设置画布的虚线偏移量，精度为float。
- 默认值：0.0。 | +| [globalCompositeOperation](#globalcompositeoperation) | string | 设置合成操作的方式。类型字段可选值有'source-over'，'source-atop'，'source-in'，'source-out'，'destination-over'，'destination-atop'，'destination-in'，'destination-out'，'lighter'，'copy'，'xor'。
- 默认值：'source-over'。 | +| [shadowBlur](#shadowblur) | number | 设置绘制阴影时的模糊级别，值越大越模糊，精度为float。
- 默认值：0.0。 | +| [shadowColor](#shadowcolor) | string | 设置绘制阴影时的阴影颜色。 | +| [shadowOffsetX](#shadowoffsetx) | number | 设置绘制阴影时和原有对象的水平偏移值。 | +| [shadowOffsetY](#shadowoffsety) | number | 设置绘制阴影时和原有对象的垂直偏移值。 | +| [imageSmoothingEnabled](#imagesmoothingenabled) | boolean | 用于设置绘制图片时是否进行图像平滑度调整，true为启用，false为不启用。
- 默认值：true。 | +| imageSmoothingQuality | string | 用于设置图像平滑度，支持如下三种类型：'low', 'medium', 'high'。
- 默认值：'low'。 | + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +>fillStyle、shadowColor与 strokeStyle 中string类型格式为 'rgb(255, 255, 255)'，'rgba(255, 255, 255, 1.0)'，'\#FFFFFF'。 ### fillStyle @@ -143,7 +144,6 @@ struct StrokeStyleExample { } ``` - ![zh-cn_image_0000001238712437](figures/zh-cn_image_0000001238712437.png) @@ -445,6 +445,7 @@ struct LineDashOffset { .onReady(() =>{ this.offContext.arc(100, 75, 50, 0, 6.28) this.offContext.setLineDash([10,20]) + this.offContext.lineDashOffset = 10.0; this.offContext.stroke(); var image = this.offContext.transferToImageBitmap() this.context.transferFromImageBitmap(image) @@ -454,8 +455,8 @@ struct LineDashOffset { .height('100%') } } -``` +``` ![zh-cn_image_0000001238712439](figures/zh-cn_image_0000001238712439.png) @@ -700,7 +701,8 @@ fillRect(x: number, y: number, w: number, h: number): void 填充一个矩形。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 说明 | | ------ | ------ | ---- | ---- | ------------- | | x | number | 是 | 0 | 指定矩形左上角点的x坐标。 | @@ -708,8 +710,10 @@ fillRect(x: number, y: number, w: number, h: number): void | width | number | 是 | 0 | 指定矩形的宽度。 | | height | number | 是 | 0 | 指定矩形的高度。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct FillRect { @@ -744,7 +748,8 @@ strokeRect(x: number, y: number, w: number, h: number): void 绘制具有边框的矩形，矩形内部不填充。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 说明 | | ------ | ------ | ---- | ---- | ------------ | | x | number | 是 | 0 | 指定矩形的左上角x坐标。 | @@ -752,8 +757,10 @@ strokeRect(x: number, y: number, w: number, h: number): void | width | number | 是 | 0 | 指定矩形的宽度。 | | height | number | 是 | 0 | 指定矩形的高度。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct StrokeRect { @@ -787,7 +794,8 @@ clearRect(x: number, y: number, w: number, h: number): void 删除指定区域内的绘制内容。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ------ | ------ | ---- | ---- | ------------- | | x | number | 是 | 0 | 指定矩形上的左上角x坐标。 | @@ -795,8 +803,10 @@ clearRect(x: number, y: number, w: number, h: number): void | width | number | 是 | 0 | 指定矩形的宽度。 | | height | number | 是 | 0 | 指定矩形的高度。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct ClearRect { @@ -828,19 +838,23 @@ clearRect(x: number, y: number, w: number, h: number): void ### fillText -fillText(text: string, x: number, y: number): void +fillText(text: string, x: number, y: number, maxWidth?: number): void 绘制填充类文本。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 默认值 | 说明 | | ---- | ------ | ---- | ---- | --------------- | | text | string | 是 | “” | 需要绘制的文本内容。 | | x | number | 是 | 0 | 需要绘制的文本的左下角x坐标。 | | y | number | 是 | 0 | 需要绘制的文本的左下角y坐标。 | + | maxWidth | number | 否 | - | 指定文本允许的最大宽度。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct FillText { @@ -875,15 +889,19 @@ strokeText(text: string, x: number, y: number): void 绘制描边类文本。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ---- | ------ | ---- | ---- | --------------- | | text | string | 是 | “” | 需要绘制的文本内容。 | | x | number | 是 | 0 | 需要绘制的文本的左下角x坐标。 | | y | number | 是 | 0 | 需要绘制的文本的左下角y坐标。 | + | maxWidth | number | 否 | - | 需要绘制的文本的最大宽度 。| -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct StrokeText { @@ -918,23 +936,40 @@ measureText(text: string): TextMetrics 该方法返回一个文本测算的对象，通过该对象可以获取指定文本的宽度值。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 说明 | | ---- | ------ | ---- | ---- | ---------- | | text | string | 是 | "" | 需要进行测量的文本。 | -- 返回值 + **返回值：** + | 类型 | 说明 | | ----------- | ------- | | TextMetrics | 文本的尺寸信息 | -- TextMetrics类型描述 - | 属性 | 类型 | 描述 | - | ----- | ------ | ------- | - | width | number | 字符串的宽度。 | - -- 示例 - ``` +**TextMetrics类型描述:** + + | 属性 | 类型 | 描述 | + | ----- | ------ | ------- | + | width | number | 字符串的宽度。 | + | height | number | 字符串的高度。 | + | actualBoundingBoxAscent | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到渲染文本的矩形边界顶部的距离，当前值为0。 | + | actualBoundingBoxDescent | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到渲染文本的矩形边界底部的距离，当前值为0。 | + | actualBoundingBoxLeft | number | 平行于基线，从CanvasRenderingContext2D.textAlign 属性确定的对齐点到文本矩形边界左侧的距离，当前值为0。 | + | actualBoundingBoxRight | number | 平行于基线，从CanvasRenderingContext2D.textAlign 属性确定的对齐点到文本矩形边界右侧的距离，当前值为0。| + | alphabeticBaseline | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到线框的 alphabetic 基线的距离，当前值为0。| + | emHeightAscent | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到线框中 em 方块顶部的距离，当前值为0。| + | emHeightDescent | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到线框中 em 方块底部的距离，当前值为0。| + | fontBoundingBoxAscent | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到渲染文本的所有字体的矩形最高边界顶部的距离，当前值为0。| + | fontBoundingBoxDescent | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到渲染文本的所有字体的矩形边界最底部的距离，当前值为0。| + | hangingBaseline | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到线框的 hanging 基线的距离，当前值为0。| + | ideographicBaseline | number | 从CanvasRenderingContext2D.textBaseline 属性标明的水平线到线框的 ideographic 基线的距离，当前值为0。| + + **示例：** + + ```ts + // xxx.ets @Entry @Component struct MeasureText { @@ -970,13 +1005,16 @@ stroke(path?: Path2D): void 进行边框绘制操作。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ---- | ---------------------------------------- | ---- | ---- | ------------ | | path | [Path2D](ts-components-canvas-path2d.md) | 否 | null | 需要绘制的Path2D。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct Stroke { @@ -1013,8 +1051,10 @@ beginPath(): void 创建一个新的绘制路径。 -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct BeginPath { @@ -1053,14 +1093,17 @@ moveTo(x: number, y: number): void 路径从当前点移动到指定点。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 说明 | | ---- | ------ | ---- | ---- | --------- | | x | number | 是 | 0 | 指定位置的x坐标。 | | y | number | 是 | 0 | 指定位置的y坐标。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct MoveTo { @@ -1097,14 +1140,17 @@ lineTo(x: number, y: number): void 从当前点到指定点进行路径连接。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ---- | ------ | ---- | ---- | --------- | | x | number | 是 | 0 | 指定位置的x坐标。 | | y | number | 是 | 0 | 指定位置的y坐标。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct LineTo { @@ -1141,8 +1187,10 @@ closePath(): void 结束当前路径形成一个封闭路径。 -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct ClosePath { @@ -1177,18 +1225,27 @@ closePath(): void ### createPattern -createPattern(image: ImageBitmap, repetition: string): CanvasPattern +createPattern(image: ImageBitmap, repetition: string | null): CanvasPattern | null 通过指定图像和重复方式创建图片填充的模板。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ---------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | | image | [ImageBitmap](ts-components-canvas-imagebitmap.md) | 是 | null | 图源对象，具体参考ImageBitmap对象。 | | repetition | string | 是 | “” | 设置图像重复的方式，取值为：'repeat'、'repeat-x'、 'repeat-y'、'no-repeat'。 | -- 示例 - ``` +**返回值：** + + | 类型 | 说明 | + | ---------- | ---------------------------------------- | + | [CanvasPattern](#canvaspattern) | 通过指定图像和重复方式创建图片填充的模板对象。 | + + **示例：** + + ```ts + // xxx.ets @Entry @Component struct CreatePattern { @@ -1225,7 +1282,8 @@ bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, 创建三次贝赛尔曲线的路径。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ---- | ------ | ---- | ---- | -------------- | | cp1x | number | 是 | 0 | 第一个贝塞尔参数的x坐标值。 | @@ -1235,8 +1293,10 @@ bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, | x | number | 是 | 0 | 路径结束时的x坐标值。 | | y | number | 是 | 0 | 路径结束时的y坐标值。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct BezierCurveTo { @@ -1273,7 +1333,8 @@ quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void 创建二次贝赛尔曲线的路径。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ---- | ------ | ---- | ---- | ----------- | | cpx | number | 是 | 0 | 贝塞尔参数的x坐标值。 | @@ -1281,8 +1342,10 @@ quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void | x | number | 是 | 0 | 路径结束时的x坐标值。 | | y | number | 是 | 0 | 路径结束时的y坐标值。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct QuadraticCurveTo { @@ -1315,11 +1378,12 @@ quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void ### arc -arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void +arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void 绘制弧线路径。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ------------- | ------- | ---- | ----- | ---------- | | x | number | 是 | 0 | 弧线圆心的x坐标值。 | @@ -1327,10 +1391,12 @@ arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, | radius | number | 是 | 0 | 弧线的圆半径。 | | startAngle | number | 是 | 0 | 弧线的起始弧度。 | | endAngle | number | 是 | 0 | 弧线的终止弧度。 | - | anticlockwise | boolean | 否 | false | 是否逆时针绘制圆弧。 | + | counterclockwise | boolean | 否 | false | 是否逆时针绘制圆弧。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct Arc { @@ -1366,7 +1432,8 @@ arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void 依据圆弧经过的点和圆弧半径创建圆弧路径。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ------ | ------ | ---- | ---- | --------------- | | x1 | number | 是 | 0 | 圆弧经过的第一个点的x坐标值。 | @@ -1375,8 +1442,10 @@ arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void | y2 | number | 是 | 0 | 圆弧经过的第二个点的y坐标值。 | | radius | number | 是 | 0 | 圆弧的圆半径值。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct ArcTo { @@ -1408,11 +1477,12 @@ arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void ### ellipse -ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void +ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void 在规定的矩形区域绘制一个椭圆。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 说明 | | ------------- | ------- | ---- | ----- | ----------------- | | x | number | 是 | 0 | 椭圆圆心的x轴坐标。 | @@ -1422,11 +1492,12 @@ ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number | rotation | number | 是 | 0 | 椭圆的旋转角度，单位为弧度。 | | startAngle | number | 是 | 0 | 椭圆绘制的起始点角度，以弧度表示。 | | endAngle | number | 是 | 0 | 椭圆绘制的结束点角度，以弧度表示。 | - | anticlockwise | boolean | 否 | false | 是否以逆时针方向绘制椭圆。 | + | counterclockwise | boolean | 否 | false | 是否以逆时针方向绘制椭圆。 | -- 示例 + **示例：** - ``` + ```ts + // xxx.ets @Entry @Component struct CanvasExample { @@ -1458,20 +1529,23 @@ ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number ### rect -rect(x: number, y: number, width: number, height: number): void +rect(x: number, y: number, w: number, h: number): void 创建矩形路径。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ------ | ------ | ---- | ---- | ------------- | | x | number | 是 | 0 | 指定矩形的左上角x坐标值。 | | y | number | 是 | 0 | 指定矩形的左上角y坐标值。 | - | width | number | 是 | 0 | 指定矩形的宽度。 | - | height | number | 是 | 0 | 指定矩形的高度。 | + | w | number | 是 | 0 | 指定矩形的宽度。 | + | h | number | 是 | 0 | 指定矩形的高度。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct CanvasExample { @@ -1506,8 +1580,10 @@ fill(): void 对封闭路径进行填充。 -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct Fill { @@ -1542,8 +1618,10 @@ clip(): void 设置当前路径为剪切路径。 -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct Clip { @@ -1577,17 +1655,20 @@ clip(): void ### rotate -rotate(rotate: number): void +rotate(angle: number): void 针对当前坐标轴进行顺时针旋转。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ------ | ------ | ---- | ---- | ---------------------------------------- | - | rotate | number | 是 | 0 | 设置顺时针旋转的弧度值，可以通过Math.PI / 180将角度转换为弧度值。 | + | angle | number | 是 | 0 | 设置顺时针旋转的弧度值，可以通过Math.PI / 180将角度转换为弧度值。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct Rotate { @@ -1622,14 +1703,17 @@ scale(x: number, y: number): void 设置canvas画布的缩放变换属性，后续的绘制操作将按照缩放比例进行缩放。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ---- | ------ | ---- | ---- | ----------- | | x | number | 是 | 0 | 设置水平方向的缩放值。 | | y | number | 是 | 0 | 设置垂直方向的缩放值。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct Scale { @@ -1661,29 +1745,32 @@ scale(x: number, y: number): void ### transform -transform(scaleX: number, skewX: number, skewY: number, scaleY: number, translateX: number, translateY: number): void +transform(a: number, b: number, c: number, d: number, e: number, f: number): void transform方法对应一个变换矩阵，想对一个图形进行变化的时候，只要设置此变换矩阵相应的参数，对图形的各个定点的坐标分别乘以这个矩阵，就能得到新的定点的坐标。矩阵变换效果可叠加。 -> **说明：** +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > 变换后的坐标计算方式（x和y为变换前坐标，x'和y'为变换后坐标）： > > - x' = scaleX \* x + skewY \* y + translateX > > - y' = skewX \* x + scaleY \* y + translateY -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ---------- | ------ | ---- | ---- | -------- | - | scaleX | number | 是 | 0 | 指定水平缩放值。 | - | skewX | number | 是 | 0 | 指定水平倾斜值。 | - | skewY | number | 是 | 0 | 指定垂直倾斜值。 | - | scaleY | number | 是 | 0 | 指定垂直缩放值。 | - | translateX | number | 是 | 0 | 指定水平移动值。 | - | translateY | number | 是 | 0 | 指定垂直移动值。 | - -- 示例 - ``` + | a | number | 是 | 0 |scaleX: 指定水平缩放值。 | + | b | number | 是 | 0 |skewX: 指定水平倾斜值。 | + | c | number | 是 | 0 |skewY: 指定垂直倾斜值。 | + | d | number | 是 | 0 |scaleY: 指定垂直缩放值。 | + | e | number | 是 | 0 |translateX: 指定水平移动值。 | + | f | number | 是 | 0 |translateY: 指定垂直移动值。 | + + **示例：** + + ```ts + // xxx.ets @Entry @Component struct Transform { @@ -1720,22 +1807,25 @@ transform方法对应一个变换矩阵，想对一个图形进行变化的时 ### setTransform -setTransform(scaleX: number, skewX: number, skewY: number, scale: number, translateX: number, translateY: number): void +setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void setTransfrom方法使用的参数和transform()方法相同，但setTransform()方法会重置现有的变换矩阵并创建新的变换矩阵。 -- 参数 +**参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ---------- | ------ | ---- | ---- | -------- | - | scaleX | number | 是 | 0 | 指定水平缩放值。 | - | skewX | number | 是 | 0 | 指定水平倾斜值。 | - | skewY | number | 是 | 0 | 指定垂直倾斜值。 | - | scaleY | number | 是 | 0 | 指定垂直缩放值。 | - | translateX | number | 是 | 0 | 指定水平移动值。 | - | translateY | number | 是 | 0 | 指定垂直移动值。 | - -- 示例 - ``` + | a | number | 是 | 0 |scaleX: 指定水平缩放值。 | + | b | number | 是 | 0 |skewX: 指定水平倾斜值。 | + | c | number | 是 | 0 |skewY: 指定垂直倾斜值。 | + | d | number | 是 | 0 |scaleY: 指定垂直缩放值。 | + | e | number | 是 | 0 |translateX: 指定水平移动值。 | + | f | number | 是 | 0 |translateY: 指定垂直移动值。 | + + **示例：** + + ```ts + // xxx.ets @Entry @Component struct SetTransform { @@ -1773,14 +1863,17 @@ translate(x: number, y: number): void 移动当前坐标系的原点。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ---- | ------ | ---- | ---- | -------- | | x | number | 是 | 0 | 设置水平平移量。 | | y | number | 是 | 0 | 设置竖直平移量。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct Translate { @@ -1814,28 +1907,31 @@ translate(x: number, y: number): void drawImage(image: ImageBitmap | PixelMap, dx: number, dy: number): void -drawImage(image: ImageBitmap | PixelMap, dx: number, dy: number, dWidth: number, dHeight: number): void +drawImage(image: ImageBitmap | PixelMap, dx: number, dy: number, dw: number, dh: number): void -drawImage(image: ImageBitmap | PixelMap, sx: number, sy: number, sWidth: number, sHeight: number, dx: number, dy: number, dWidth: number, dHeight: number):void +drawImage(image: ImageBitmap | PixelMap, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number):void 进行图像绘制。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ------- | ---------------------------------------- | ---- | ---- | -------------------- | | image | [ImageBitmap](ts-components-canvas-imagebitmap.md) 或[PixelMap](../apis/js-apis-image.md#pixelmap7)| 是 | null | 图片资源，请参考ImageBitmap或PixelMap。 | | sx | number | 否 | 0 | 裁切源图像时距离源图像左上角的x坐标值。 | | sy | number | 否 | 0 | 裁切源图像时距离源图像左上角的y坐标值。 | - | sWidth | number | 否 | 0 | 裁切源图像时需要裁切的宽度。 | - | sHeight | number | 否 | 0 | 裁切源图像时需要裁切的高度。 | + | sw | number | 否 | 0 | 裁切源图像时需要裁切的宽度。 | + | sh | number | 否 | 0 | 裁切源图像时需要裁切的高度。 | | dx | number | 是 | 0 | 绘制区域左上角在x轴的位置。 | | dy | number | 是 | 0 | 绘制区域左上角在y 轴的位置。 | - | dWidth | number | 否 | 0 | 绘制区域的宽度。 | - | dHeight | number | 否 | 0 | 绘制区域的高度。 | + | dw | number | 否 | 0 | 绘制区域的宽度。 | + | dh | number | 否 | 0 | 绘制区域的高度。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct Index { @@ -1866,34 +1962,44 @@ drawImage(image: ImageBitmap | PixelMap, sx: number, sy: number, sWidth: number, ### createImageData -createImageData(width: number, height: number): Object +createImageData(sw: number, sh: number): ImageData 根据宽高创建ImageData对象，请参考[ImageData](ts-components-canvas-imagebitmap.md)。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认 | 描述 | | ------ | ------ | ---- | ---- | ------------- | - | width | number | 是 | 0 | ImageData的宽度。 | - | height | number | 是 | 0 | ImageData的高度。 | + | sw | number | 是 | 0 | ImageData的宽度。 | + | sh | number | 是 | 0 | ImageData的高度。 | ### createImageData -createImageData(imageData: ImageData): Object +createImageData(imageData: ImageData): ImageData 根据已创建的ImageData对象创建新的ImageData对象，请参考[ImageData](ts-components-canvas-imagebitmap.md)。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认 | 描述 | | --------- | ---------------------------------------- | ---- | ---- | ---------------- | | imagedata | [ImageData](ts-components-canvas-imagebitmap.md) | 是 | null | 被复制的ImageData对象。 | + **返回值：** + + | 类型 | 说明 | + | ---------- | ---------------------------------------- | + | [ImageData](ts-components-canvas-imagebitmap.md) | 新的ImageData对象 | + ### getPixelMap getPixelMap(sx: number, sy: number, sw: number, sh: number): PixelMap 以当前canvas指定区域内的像素创建[PixelMap](../apis/js-apis-image.md#pixelmap7)对象。 -- 参数 + + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | -------- | -------- | -------- | -------- | -------- | | sx | number | 是 | 0 | 需要输出的区域的左上角x坐标。 | @@ -1901,13 +2007,21 @@ getPixelMap(sx: number, sy: number, sw: number, sh: number): PixelMap | sw | number | 是 | 0 | 需要输出的区域的宽度。 | | sh | number | 是 | 0 | 需要输出的区域的高度。 | +**返回值：** + + | 类型 | 说明 | + | ---------- | ---------------------------------------- | + | [PixelMap](../apis/js-apis-image.md#pixelmap7) | 新的PixelMap对象 | + + ### getImageData -getImageData(sx: number, sy: number, sw: number, sh: number): Object +getImageData(sx: number, sy: number, sw: number, sh: number): ImageData 以当前canvas指定区域内的像素创建[ImageData](ts-components-canvas-imagebitmap.md)对象。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ---- | ------ | ---- | ---- | --------------- | | sx | number | 是 | 0 | 需要输出的区域的左上角x坐标。 | @@ -1915,14 +2029,23 @@ getImageData(sx: number, sy: number, sw: number, sh: number): Object | sw | number | 是 | 0 | 需要输出的区域的宽度。 | | sh | number | 是 | 0 | 需要输出的区域的高度。 | + **返回值：** + + | 类型 | 说明 | + | ---------- | ---------------------------------------- | + | [ImageData](ts-components-canvas-imagebitmap.md) | 新的ImageData对象 | + ### putImageData -putImageData(imageData: Object, dx: number, dy: number, dirtyX?: number, dirtyY?: number, dirtyWidth?: number, dirtyHeight?: number): void +putImageData(imageData: Object, dx: number, dy: number): void + +putImageData(imageData: Object, dx: number, dy: number, dirtyX: number, dirtyY: number, dirtyWidth?: number, dirtyHeight: number): void 使用[ImageData](ts-components-canvas-imagebitmap.md)数据填充新的矩形区域。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ----------- | ------ | ---- | ------------ | ----------------------------- | | imagedata | Object | 是 | null | 包含像素值的ImageData对象。 | @@ -1933,8 +2056,10 @@ putImageData(imageData: Object, dx: number, dy: number, dirtyX?: number, dirtyY? | dirtyWidth | number | 否 | imagedata的宽度 | 源图像数据矩形裁切范围的宽度。 | | dirtyHeight | number | 否 | imagedata的高度 | 源图像数据矩形裁切范围的高度。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct PutImageData { @@ -1968,6 +2093,225 @@ putImageData(imageData: Object, dx: number, dy: number, dirtyX?: number, dirtyY? ![zh-cn_image_0000001194192464](figures/zh-cn_image_0000001194192464.png) +### setLineDash + +setLineDash(segments: number[]): void + +设置画布的虚线样式。 + +**参数：** + +| 参数 | 类型 | 描述 | +| -------- | ----- | -------------------- | +| segments | number[] | 描述线段如何交替和线段间距长度的数组。 | + +**示例：** + + ```ts +@Entry +@Component +struct SetLineDash { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.offContext.arc(100, 75, 50, 0, 6.28) + this.offContext.setLineDash([10,20]) + this.offContext.stroke(); + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') + .height('100%') + } +} + ``` + ![zh-cn_image_000000127777772](figures/zh-cn_image_000000127777772.png) + + +### getLineDash + +getLineDash(): number[] + +获得当前画布的虚线样式。 + +**返回值：** + +| 类型 | 说明 | +| ----- | ------------------------ | +| number[] | 返回数组，该数组用来描述线段如何交替和间距长度。 | + +**示例：** + + ```ts + // xxx.ets + @Entry + @Component + struct GetLineDash { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + var grad = this.context.createLinearGradient(50,0, 300,100) + this.offContext.arc(100, 75, 50, 0, 6.28) + this.offContext.setLineDash([10,20]) + this.offContext.stroke(); + let res = this.offContext.getLineDash() + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') + .height('100%') + } + } + ``` + + +### transferFromImageBitmap + +transferFromImageBitmap(bitmap: ImageBitmap): void + +显示给定的ImageBitmap对象。 + +**参数：** + +| 参数 | 类型 | 描述 | +| ------ | ----------- | ------------------ | +| bitmap | [ImageData](ts-components-canvas-imagebitmap.md) | 待显示的ImageBitmap对象。 | + +**示例：** + + ```ts + // xxx.ets + @Entry + @Component + struct GetLineDash { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.offContext.fillRect(0, 0, 200, 200) + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') + .height('100%') + } + } + ``` + ![zh-cn_image_000000127777773](figures/zh-cn_image_000000127777773.png) + +### toDataURL + +toDataURL(type?: string, quality?: number): string + +生成一个包含图片展示的URL。 + +**参数：** + +| 参数名 | 参数类型 | 必填 | 描述 | +| ------- | ------ | ---- | ---------------------------------------- | +| type | string | 否 | 可选参数，用于指定图像格式，默认格式为image/png。 | +| quality | number | 否 | 在指定图片格式为image/jpeg或image/webp的情况下，可以从0到1的区间内选择图片的质量。如果超出取值范围，将会使用默认值0.92。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | --------- | +| string | 图像的URL地址。 | + +**示例：** + + ```ts + // xxx.ets +@Entry +@Component +struct ToDataURL { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + var dataURL = this.offContext.toDataURL(); + }) + } + .width('100%') + .height('100%') + } +} + ``` + + +### transferToImageBitmap + +transferToImageBitmap(): ImageBitmap + +在离屏画布最近渲染的图像上创建一个ImageBitmap对象。 + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------- | --------------- | +| [ImageData](ts-components-canvas-imagebitmap.md)| 存储离屏画布上渲染的像素数据。 | + + + **示例：** + + ```ts + // xxx.ets + @Entry + @Component + struct CanvasExample { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.offContext.restore() + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') + .height('100%') + } + } + ``` ### restore @@ -1975,8 +2319,10 @@ restore(): void 对保存的绘图上下文进行恢复。 -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct CanvasExample { @@ -2008,8 +2354,10 @@ save(): void 对当前的绘图上下文进行保存。 -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct CanvasExample { @@ -2041,7 +2389,8 @@ createLinearGradient(x0: number, y0: number, x1: number, y1: number): void 创建一个线性渐变色。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ---- | ------ | ---- | ---- | -------- | | x0 | number | 是 | 0 | 起点的x轴坐标。 | @@ -2049,8 +2398,10 @@ createLinearGradient(x0: number, y0: number, x1: number, y1: number): void | x1 | number | 是 | 0 | 终点的x轴坐标。 | | y1 | number | 是 | 0 | 终点的y轴坐标。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct CreateLinearGradient { @@ -2090,7 +2441,8 @@ createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, 创建一个径向渐变色。 -- 参数 + **参数：** + | 参数 | 类型 | 必填 | 默认值 | 描述 | | ---- | ------ | ---- | ---- | ----------------- | | x0 | number | 是 | 0 | 起始圆的x轴坐标。 | @@ -2100,8 +2452,10 @@ createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, | y1 | number | 是 | 0 | 终点圆的y轴坐标。 | | r1 | number | 是 | 0 | 终点圆的半径。必须为非负且有限的。 | -- 示例 - ``` + **示例：** + + ```ts + // xxx.ets @Entry @Component struct CreateRadialGradient { diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-page-transition-animation.md b/zh-cn/application-dev/reference/arkui-ts/ts-page-transition-animation.md index 1c7595fe804ee158e8f87dc050835f8758df2c3b..8e59c95ec873576948fa0b84a538850dd7b4448d 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-page-transition-animation.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-page-transition-animation.md @@ -25,8 +25,8 @@ - RouteType枚举说明 | 名称 | 描述 | | -------- | -------- | - | Pop | 重定向指定页面 | - | Push | 跳转到下一页面。 | + | Pop | 重定向指定页面。PageA跳转到PageB时，PageA为Exit+Push，PageB为Enter+Push。 | + | Push | 跳转到下一页面。PageB返回至PageA时，PageA为Enter+Pop，PageB为Exit+Pop。 | ## 属性 @@ -63,22 +63,19 @@ PageTransitionEnter和PageTransitionExit组件支持的事件： 自定义方式1：配置了当前页面的入场动画为淡入，退场动画为缩小。 -``` +```ts // index.ets @Entry @Component struct PageTransitionExample1 { @State scale1: number = 1 @State opacity1: number = 1 - @State active: boolean = false + build() { Column() { Navigator({ target: 'pages/page1', type: NavigationType.Push }) { Image($r('app.media.bg1')).width("100%").height("100%") } - .onClick(() => { - this.active = true - }) }.scale({ x: this.scale1 }).opacity(this.opacity1) } // 自定义方式1：完全自定义转场过程的效果 @@ -97,14 +94,14 @@ struct PageTransitionExample1 { } ``` -``` +```ts // page1.ets @Entry @Component struct AExample { @State scale2: number = 1 @State opacity2: number = 1 - @State active: boolean = false + build() { Column() { Navigator({ target: 'pages/index' ,type: NavigationType.Push}) { @@ -132,23 +129,19 @@ struct AExample { 自定义方式2：配置了当前页面的入场动画为从左侧滑入，退场为缩小加透明度变化。 -``` +```ts // index.ets @Entry @Component struct PageTransitionExample { @State scale1: number = 1 @State opacity1: number = 1 - @State active: boolean = false build() { Column() { Navigator({ target: 'pages/page1', type: NavigationType.Push }) { Image($r('app.media.bg1')).width("100%").height("100%") } - .onClick(() => { - this.active = true - }) }.scale({ x: this.scale1 }).opacity(this.opacity1) } @@ -163,23 +156,19 @@ struct PageTransitionExample { } ``` -``` +```ts // page1.ets @Entry @Component struct PageTransitionExample1 { @State scale2: number = 1 @State opacity2: number = 1 - @State active: boolean = false build() { Column() { Navigator({ target: 'pages/index', type: NavigationType.Push }) { Image($r('app.media.bg2')).width ("100%").height("100%") } - .onClick(() => { - this.active = true - }) }.scale({ x: this.scale2 }).opacity(this.opacity2) } diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-background.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-background.md index 869a5aa65625c4fd9b61e5dd27f1022c6ba8e6a9..123a5f48d8d9ba221c339b662e0b71861edd0d89 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-background.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-background.md @@ -1,26 +1,21 @@ # 背景设置 -> **说明：** -> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 - - 设置组件的背景色。 - -## 权限列表 - -无 +> **说明：** +> +> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 ## 属性 -| 名称 | 参数类型 | 默认值 | 描述 | -| -------- | -------- | -------- | -------- | -| backgroundColor | Color | - | 设置组件的背景色。 | -| backgroundImage | src: string,
repeat?: [ImageRepeat](ts-appendix-enums.md#imagerepeat) | - | src参数：图片地址，支持网络图片资源和本地图片资源地址(不支持svg类型的图片)。
repeat参数：设置背景图片的重复样式，默认不重复。 | -| backgroundImageSize | {
width?: Length,
height?: Length
} \| [ImageSize](ts-appendix-enums.md#imagesize) | Auto | 设置背景图像的高度和宽度。当输入为{width: Length, height: Length}对象时，如果只设置一个属性，则第二个属性保持图片原始宽高比进行调整。默认保持原图的比例不变。 | -| backgroundImagePosition | {
x?: Length,
y?: Length
} \| [Alignment](ts-appendix-enums.md#alignment) | {
x: 0,
y: 0
} | 设置背景图在组件中显示位置。 | +| 名称 | 参数类型 | 描述 | +| -------- | -------- | -------- | +| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 设置组件的背景色。 | +| backgroundImage | src: [ResourceStr](ts-types.md#resourcestr),
repeat?: [ImageRepeat](ts-appendix-enums.md#imagerepeat) | src：图片地址，支持网络图片资源和本地图片资源地址(不支持svg类型的图片)。
repeat：设置背景图片的重复样式，默认不重复。 | +| backgroundImageSize | {
width?: [Length](ts-types.md#length),
height?: [Length](ts-types.md#length)
} \| [ImageSize](ts-appendix-enums.md#imagesize) | 设置背景图像的高度和宽度。当输入为{width: Length, height: Length}对象时，如果只设置一个属性，则第二个属性保持图片原始宽高比进行调整。默认保持原图的比例不变。
默认值：ImageSize.Auto | +| backgroundImagePosition | {
x?: [Length](ts-types.md#length),
y?: [Length](ts-types.md#length)
} \| [Alignment](ts-appendix-enums.md#alignment) | 设置背景图在组件中显示位置。
{
x: 0,
y: 0
} | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-border.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-border.md index 3a50b531df13f3ec7d1ea5582da3cc6078c2818c..9a1b22fd75740e1ee7cb8a44dc0eadb323d9d46c 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-border.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-border.md @@ -1,27 +1,22 @@ # 边框设置 -> **说明：** -> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 - - 设置组件边框样式。 - -## 权限列表 - -无 +> **说明：** +> +> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 ## 属性 -| 名称 | 参数类型 | 默认值 | 描述 | -| -------- | -------- | -------- | -------- | -| border | {
width?: Length,
color?: Color,
radius?: Length,
style?: [BorderStyle](ts-appendix-enums.md#borderstyle)
} | - | 统一边框样式设置接口。 | -| borderStyle | [BorderStyle](ts-appendix-enums.md#borderstyle) |  BorderStyle.Solid | 设置元素的边框样式。 | -| borderWidth | Length | 0 | 设置元素的边框宽度。 | -| borderColor | Color | - | 设置元素的边框颜色。 | -| borderRadius | Length | 0 | 设置元素的边框圆角半径。 | +| 名称 | 参数类型 | 描述 | +| -------- | -------- | -------- | +| border | {
width?: [Length](ts-types.md#length),
color?: [ResourceColor](ts-types.md#resourcecolor),
radius?: [Length](ts-types.md#length),
style?: [BorderStyle](ts-appendix-enums.md#borderstyle)
} | 统一边框样式设置接口。 | +| borderStyle | [BorderStyle](ts-appendix-enums.md#borderstyle) | 设置元素的边框样式。
默认值：BorderStyle.Solid | +| borderWidth | [Length](ts-types.md#length) | 设置元素的边框宽度。 | +| borderColor | [ResourceColor](ts-types.md#resourcecolor) | 设置元素的边框颜色。 | +| borderRadius | [Length](ts-types.md#length) | 设置元素的边框圆角半径。 | diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-menu.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-menu.md index 447edde654f97fd91f34e5708e9ed9bbbc4b3e9a..3c65b9b1f6591b2b12571864b3ae51444c8d091c 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-menu.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-menu.md @@ -5,24 +5,19 @@ > 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -## 权限列表 - -无 - - ## 属性 -| 名称 | 参数类型 | 默认值 | 描述 | -| ---------------------------- | ------------------------------------------------------------ | ------ | ------------------------------------------------------------ | -| bindMenu | Array8+ | - | 给组件绑定菜单，点击后弹出菜单。弹出菜单项支持文本和自定义两种功能。 | -| bindContextMenu8+ | content: [CustomBuilder](ts-types.md#custombuilder8)
responseType: [ResponseType](ts-appendix-enums.md#responsetype8) | - | 给组件绑定菜单，触发方式为长按或者右键点击，弹出菜单项需要自定义。 | +| 名称 | 参数类型 | 描述 | +| ---------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| bindMenu | Array8+ | content: [CustomBuilder](ts-types.md#custombuilder8)
responseType: [ResponseType](ts-appendix-enums.md#responsetype8) | 给组件绑定菜单，触发方式为长按或者右键点击，弹出菜单项需要自定义。 | ## MenuItem -| 名称 | 类型 | 描述 | -| ------ | ----------------------- | ----------- | -| value | string | 菜单项文本。 | +| 名称 | 类型 | 描述 | +| ------ | ----------------------- | ---------------------- | +| value | string | 菜单项文本。 | | action | () => void | 点击菜单项的事件回调。 | diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-opacity.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-opacity.md index 44e5d0785420e0b501daee22dcb22b20ad1a548f..04cf60d25ddc9558e4c1e944b455532fe762d49c 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-opacity.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-opacity.md @@ -7,17 +7,12 @@ > 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -## 权限列表 - -无 - - ## 属性 -| 名称 | 参数类型 | 默认值 | 描述 | -| ------- | ------ | ---- | ---------------------------------- | -| opacity | number | 1 | 元素的不透明度，取值范围为0到1，1表示为不透明，0表示为完全透明。 | +| 名称 | 参数类型 | 描述 | +| ------- | ---------------------------------------------------- | ------------------------------------------------------------ | +| opacity | number \| [Resource](ts-types.md#resource) | 元素的不透明度，取值范围为0到1，1表示为不透明，0表示为完全透明。
默认值：1 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-polymorphic-style.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-polymorphic-style.md index 44c2a17684ecdd23ab19b72b29f4699d354b8f1a..f3ddeacc02f67ef3bb7ab370f5493acd4c3fac5b 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-polymorphic-style.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-polymorphic-style.md @@ -1,30 +1,27 @@ # 多态样式 -> **说明：** -> 从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 - - 设置组件不同状态下的样式。 - -## 权限列表 - -无 +> **说明：** +> +> 从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 ## 属性 -| 名称 | 参数类型 | 默认值 | 描述 | -| ----------- | ----------- | ---- | ------------ | -| stateStyles | StateStyles | - | 设置组件不同状态的样式。 | +| 名称 | 参数类型 | 描述 | +| ----------- | ----------- | ------------------------ | +| stateStyles | StateStyles | 设置组件不同状态的样式。 | ## StateStyles接口说明 -| 名称 | 类型 | 必填 | 默认值 | 描述 | -| -------- | ----------- | ---- | ---- | ---------- | -| normal | ()=>void | 否 | - | 组件无状态时的样式。 | -| pressed | ()=>void | 否 | - | 组件按下状态的样式。 | -| disabled | ()=>void | 否 | - | 组件禁用状态的样式。 | +| 名称 | 类型 | 必填 | 描述 | +| -------- | ---- | ---- | -------------------- | +| normal | any | 否 | 组件无状态时的样式。 | +| pressed | any | 否 | 组件按下状态的样式。 | +| disabled | any | 否 | 组件禁用状态的样式。 | +| focused | any | 否 | 组件获焦状态的样式。 | +| clicked | any | 否 | 组件点击状态的样式。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md index 4d81ce020ef1e3f91d4ea69fcdc5907966711673..ae882e08ac4b44096bf99dfcb21a15446866ac7a 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md @@ -5,39 +5,34 @@ > 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -## 权限列表 - -无 - - -## 属性 - - -| 名称 | 参数类型 | 默认值 | 描述 | -| --------- | ---------------------------------------- | ---- | ---------------------------------------- | -| bindPopup | show: boolean,
popup: PopupOptions\| CustomPopupOptions | - | 给组件绑定Popup，点击弹出弹窗。
show: 创建页面弹窗提示是否默认显示，默认值为false。
popup: 配置当前弹窗提示的参数。 | - -## PopupOptions类型接口说明 - -| 名称 | 类型 | 必填 | 默认值 | 描述 | -| --------------- | ---------------------------------------- | ---- | ----- | ---------------------------------------- | -| message | string | 是 | - | 弹窗信息内容。 | -| placementOnTop | boolean | 否 | false | 是否在组件上方显示，默认值为false。 | -| primaryButton | {
value: string,
action: () => void
} | 否 | - | 第一个按钮。
value: 弹窗里主按钮的文本。
action: 点击主按钮的回调函数。 | -| secondaryButton | {
value: string,
action: () => void
} | 否 | - | 第二个按钮。
value: 弹窗里辅助按钮的文本。
action: 点击辅助按钮的回调函数。 | -| onStateChange | (isVisible: boolean) => void | 否 | - | 弹窗状态变化事件回调，参数isVisible为弹窗当前的显示状态。 | - -## CustomPopupOptions8+类型接口说明 - -| 名称 | 类型 | 必填 | 默认值 | 描述 | -| ------------- | ---------------------------------------------- | ---- | ---------------- | ------------------------------------------------------------ | -| builder | () => any | 是 | - | 提示气泡内容的构造器。 | -| placement | [Placement](ts-appendix-enums.md#placement8) | 否 | Placement.Bottom | 气泡组件优先显示的位置，当前位置显示不下时，会自动调整位置。 | -| maskColor | [Color](ts-appendix-enums.md#color) | 否 | - | 提示气泡遮障层的颜色。 | -| popupColor | [Color](ts-appendix-enums.md#color) | 否 | - | 提示气泡的颜色。 | -| enableArrow | boolean | 否 | true | 是否显示箭头，只有上、下方向的气泡会显示箭头。 | -| autoCancel | boolean | 否 | true | 页面有操作时，是否自动关闭气泡 | -| onStateChange | (isVisible: boolean) => void | 否 | - | 弹窗状态变化事件回调，参数为弹窗当前的显示状态。 | +## 接口 + + +| 名称 | 参数类型 | 描述 | +| --------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| bindPopup | show: boolean,
popup: PopupOptions\| CustomPopupOptions8+ | 给组件绑定Popup，点击弹出弹窗。
show: 创建页面弹窗提示是否默认显示，默认值为false。
popup: 配置当前弹窗提示的参数。 | + +## PopupOptions类型说明 + +| 名称 | 类型 | 必填 | 描述 | +| --------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| message | string | 是 | 弹窗信息内容。 | +| placementOnTop | boolean | 否 | 是否在组件上方显示，默认值为false。 | +| primaryButton | {
value: string,
action: () => void
} | 否 | 第一个按钮。
value: 弹窗里主按钮的文本。
action: 点击主按钮的回调函数。 | +| secondaryButton | {
value: string,
action: () => void
} | 否 | 第二个按钮。
value: 弹窗里辅助按钮的文本。
action: 点击辅助按钮的回调函数。 | +| onStateChange | (event:{isVisible: boolean }) => void | 否 | 弹窗状态变化事件回调，参数isVisible为弹窗当前的显示状态。 | + +## CustomPopupOptions8+类型说明 + +| 名称 | 类型 | 必填 | 描述 | +| ------------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| builder | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 提示气泡内容的构造器。 | +| placement | [Placement](ts-appendix-enums.md#placement8) | 否 | 气泡组件优先显示的位置，当前位置显示不下时，会自动调整位置。
默认值：Placement.Bottom | +| maskColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 提示气泡遮障层的颜色。 | +| popupColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 提示气泡的颜色。 | +| enableArrow | boolean | 否 | 是否显示箭头，只有上、下方向的气泡会显示箭头。
默认值：true | +| autoCancel | boolean | 否 | 页面有操作时，是否自动关闭气泡
默认值：true | +| onStateChange | (event:{isVisible: boolean }) => void | 否 | 弹窗状态变化事件回调，参数为弹窗当前的显示状态。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-size.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-size.md index 474f34717426e12263e2d5cbaeb61354744465ec..ff5c7cccc7a293ad4ae0c0856e4f63501a9c16ab 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-size.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-size.md @@ -5,23 +5,18 @@ > 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -## 权限列表 - -无 - - ## 属性 -| 名称 | 参数说明 | 默认值 | 描述 | -| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -| width | Length | - | 设置组件自身的宽度，缺省时使用元素自身内容需要的宽度。 | -| height | Length | - | 设置组件自身的高度，缺省时使用元素自身内容需要的高度。 | -| size | {
width?: Length,
height?: Length
} | - | 设置高宽尺寸。 | -| padding | {
top?: Length,
right?: Length,
bottom?: Length,
left?: Length
} \| Length | 0 | 设置内边距属性。
参数为Length类型时，四个方向内边距同时生效。 | -| margin | {
top?: Length,
right?: Length,
bottom?: Length,
left?: Length
}
\| Length | 0 | 设置外边距属性。
参数为Length类型时，四个方向外边距同时生效。 | -| constraintSize | {
minWidth?: Length,
maxWidth?: Length,
minHeight?: Length,
maxHeight?: Length
} | {
minWidth: 0,
maxWidth: Infinity,
minHeight: 0,
maxHeight: Infinity
} | 设置约束尺寸，组件布局时，进行尺寸范围限制。 | -| layoutWeight | number | 0 | 容器尺寸确定时，元素与兄弟节点主轴布局尺寸按照权重进行分配，忽略本身尺寸设置，表示自适应占满剩余空间。
>  **说明：**
> 仅在Row/Column/Flex布局中生效。 | +| 名称 | 参数说明 | 描述 | +| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| width | [Length](ts-types.md#length) | 设置组件自身的宽度，缺省时使用元素自身内容需要的宽度。 | +| height | [Length](ts-types.md#length) | 设置组件自身的高度，缺省时使用元素自身内容需要的高度。 | +| size | {
width?: [Length](ts-types.md#length),
height?: [Length](ts-types.md#length)
} | 设置高宽尺寸。 | +| padding | [Padding](ts-types.md#padding) \| [Length](ts-types.md#length) | 设置内边距属性。
参数为Length类型时，四个方向内边距同时生效。
默认值：0 | +| margin | [Margin](ts-types.md#margin) \| [Length](ts-types.md#length) | 设置外边距属性。
参数为Length类型时，四个方向外边距同时生效。
默认值：0 | +| constraintSize | {
minWidth?: [Length](ts-types.md#length),
maxWidth?: [Length](ts-types.md#length),
minHeight?: [Length](ts-types.md#length),
maxHeight?: [Length](ts-types.md#length)
} | 设置约束尺寸，组件布局时，进行尺寸范围限制。
默认值：
{
minWidth: 0,
maxWidth: Infinity,
minHeight: 0,
maxHeight: Infinity
} | +| layoutWeight | number \| string | 容器尺寸确定时，元素与兄弟节点主轴布局尺寸按照权重进行分配，忽略本身尺寸设置，表示自适应占满剩余空间。
默认值：0
**说明：**
仅在Row/Column/Flex布局中生效。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-touch-target.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-touch-target.md index 2043171acbda94af034e0b4bac847e9a902ea05a..700349d0a0cefe05271e1c2995ecf99dad61b2a0 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-touch-target.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-touch-target.md @@ -1,37 +1,35 @@ # 触摸热区设置 +适用于支持通用点击事件、通用触摸事件、通用手势处理的组件。 + > **说明：** > > 从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -适用于支持通用点击事件、通用触摸事件、通用手势处理的组件。 - - -## 权限列表 - -无 - - ## 属性 -| 名称 | 参数类型 | 默认值 | 描述 | -| -------------- | ---------------------------------------- | ---------------------------------------- | ---------------------------------------- | -| responseRegion | Array<Rectangle> \| Rectangle | {
x：0,
y：0,
width：'100%',
height：'100%'
} | 设置一个或多个触摸热区，包括位置和大小。
>  **说明：**
> -百分比是相对于组件本身来度量的。
> -x和y可以设置正负值百分比。当x设置为'100%'时表示热区往右偏移组件本身宽度大小，当x设置为'-100%'时表示热区往左偏移组件本身宽度大小。当y设置为'100%'时表示热区往下偏移组件本身高度大小，当y设置为'-100%'时表示热区往上偏移组件本身高度大小。
> -width和height只能设置正值百分比。width：'100%'表示热区宽度设置为该组件本身的宽度。比如组件本身宽度是100vp，那么'100%'表示热区宽度也为100vp。height：'100%'表示热区高度设置为该组件本身的高度。 | +| 名称 | 参数类型 | 描述 | +| -------------- | --------------------------------------------- | ------------------------------------------------------------ | +| responseRegion | Array<Rectangle> \| Rectangle | 设置一个或多个触摸热区，包括位置和大小。
默认值：
{
x：0,
y：0,
width：'100%',
height：'100%'
} | ### Rectangle对象说明 -| 名称 | 类型 | 必填 | 默认值 | 描述 | -| ------ | ------ | ---- | ---- | ------------------ | -| x | Length | 否 | 0vp | 触摸点相对于组件本身左边沿的X坐标。 | -| y | Length | 否 | 0vp | 触摸点相对于组件本身左边沿的Y坐标。 | -| width | Length | 否 | 100% | 触摸热区范围的宽度。 | -| height | Length | 否 | 100% | 触摸热区范围的高度。 | +| 名称 | 类型 | 必填 | 默认值 | 描述 | +| ------ | ---------------------------- | ---- | ------ | --------------------------------------------------- | +| x | [Length](ts-types.md#length) | 否 | 0vp | 触摸点相对于组件本身左边沿的X坐标。
默认值：0vp | +| y | [Length](ts-types.md#length) | 否 | 0vp | 触摸点相对于组件本身左边沿的Y坐标。
默认值：0vp | +| width | [Length](ts-types.md#length) | 否 | 100% | 触摸热区范围的宽度。
默认值：100% | +| height | [Length](ts-types.md#length) | 否 | 100% | 触摸热区范围的高度。
默认值：100% | > **说明：** > - > 当x和y都设置为正值时，表示组件的触摸热区的范围整体往组件本身右下角偏移，偏移的大小可通过数值来设置。 + > x和y可以设置正负值百分比。当x设置为'100%'时表示热区往右偏移组件本身宽度大小，当x设置为'-100%'时表示热区往左偏移组件本身宽度大小。当y设置为'100%'时表示热区往下偏移组件本身高度大小，当y设置为'-100%'时表示热区往上偏移组件本身高度大小。 + > + > width和height只能设置正值百分比。width：'100%'表示热区宽度设置为该组件本身的宽度。比如组件本身宽度是100vp，那么'100%'表示热区宽度也为100vp。height：'100%'表示热区高度设置为该组件本身的高度。 + > + > 百分比是相对于组件本身来度量的。 ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-click.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-click.md index 8bfa7a8329c9ef79129b3c60b80df0e2826d7f3a..6f8902fb7626655e717ca8742fc90f2a564eeacb 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-click.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-click.md @@ -5,26 +5,22 @@ > 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -## 权限列表 - -无 - - ## 事件 -| 名称 | 支持冒泡 | 功能描述 | -| ---------------------------------------- | ---- | --------------------------------- | -| onClick(callback: (event?: ClickEvent) => void) | 否 | 点击动作触发该方法调用，event参数见ClickEvent介绍。 | +| 名称 | 支持冒泡 | 功能描述 | +| ------------------------------------------------------------ | -------- | --------------------------------------------------- | +| onClick(event: (event?: ClickEvent) => void) | 否 | 点击动作触发该方法调用，event参数见ClickEvent介绍。 | ## ClickEvent对象说明 -| 属性名称 | 类型 | 描述 | -| ------------------- | -------------------------------- | ------------------- | -| screenX | number | 点击点相对于设备屏幕左边沿的X坐标。 | -| screenY | number | 点击点相对于设备屏幕上边沿的Y坐标。 | -| x | number | 点击点相对于被点击元素左边沿的X坐标。 | -| y | number | 点击点相对于被点击元素上边沿的Y坐标。 | -| target8+ | [EventTarget](#eventtarget8对象说明) | 被点击元素对象。 | -| timestamp | number | 事件时间戳。 | +| 属性名称 | 类型 | 描述 | +| ---------------------- | ------------------------------------ | ------------------------------------- | +| screenX | number | 点击点相对于设备屏幕左边沿的X坐标。 | +| screenY | number | 点击点相对于设备屏幕上边沿的Y坐标。 | +| x | number | 点击点相对于被点击元素左边沿的X坐标。 | +| y | number | 点击点相对于被点击元素上边沿的Y坐标。 | +| target8+ | [EventTarget](#eventtarget8对象说明) | 被点击元素对象。 | +| timestamp8+ | number | 事件时间戳。 | +| source8+ | [SourceType](ts-gesture-settings.md) | 事件输入设备。 | ## EventTarget8+对象说明 | 名称 | 参数类型 | 描述 | diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-key.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-key.md index 09498cc8ea25edbd6770891c8b2881f558ac71cc..e25e4e76fdf9a41d9c947f05b6a35be53b5fe35a 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-key.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-key.md @@ -21,23 +21,16 @@ ## KeyEvent对象说明 -### 属性 - -| 属性名称 | 类型 | 描述 | -| ------------------------------------- | --------------------------- | -------------------------- | -| type | [KeyType](ts-appendix-enums.md#keytype) | 按键的类型。 | -| [keyCode](../apis/js-apis-keycode.md) | number | 按键的键码。 | -| keyText | string | 按键的键值。 | -| keySource | [KeySource](ts-appendix-enums.md#keysource) | 触发当前按键的输入设备类型。 | -| deviceId | number | 触发当前按键的输入设备ID。 | -| metaKey | number | 按键发生时元键的状态，1表示按压态，0表示未按压态。 | -| timestamp | number | 按键发生时的时间戳。 | - -### 接口 - -| 接口名称 | 功能描述 | -| ---------------------------- | --------- | -| stopPropagation(): void | 阻塞事件冒泡传递。 | + | 名称 | 类型 | 描述 | + | ------------------------------------- | --------------------------- | -------------------------- | + | type | [KeyType](ts-appendix-enums.md#keytype) | 按键的类型。 | + | [keyCode](../apis/js-apis-keycode.md) | number | 按键的键码。 | + | keyText | string | 按键的键值。 | + | keySource | [KeySource](ts-appendix-enums.md#keysource) | 触发当前按键的输入设备类型。 | + | deviceId | number | 触发当前按键的输入设备ID。 | + | metaKey | number | 按键发生时元键的状态，1表示按压态，0表示未按压态。 | + | timestamp | number | 按键发生时的时间戳。 | + | stopPropagation | () => void | 阻塞事件冒泡传递。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-touch.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-touch.md index 1797ffa5e4771aff380ab24fa8497d1eb6ca8bdc..9f94105c21c5eee879c1ce401df723112bfe6086 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-touch.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-touch.md @@ -5,38 +5,29 @@ > 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -## 权限列表 - -无 - - ## 事件 -| 名称 | 是否冒泡 | 功能描述 | -| ---------------------------------------- | ---- | ---------------------------------------- | -| onTouch(callback: (event?: TouchEvent) => void) | 是 | 触摸动作触发该方法调用，event参数见[TouchEvent](#touchevent对象说明)介绍。 | +| 名称 | 是否冒泡 | 功能描述 | +| ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| onTouch(event: (event?: TouchEvent) => void) | 是 | 触摸动作触发该方法调用，event参数见[TouchEvent](#touchevent对象说明)介绍。 | ## TouchEvent对象说明 -### 属性 + | 名称 | 类型 | 描述 | + | ------------------- | ---------------------------------------- | ------------ | + | type | [TouchType](ts-appendix-enums.md#touchtype) | 触摸事件的类型。 | + | touches | Array<[TouchObject](#touchobject对象说明)> | 全部手指信息。 | + | changedTouches | Array<[TouchObject](#touchobject对象说明)> | 当前发生变化的手指信息。 | + | stopPropagation | () => void | 阻塞事件冒泡。 | + | timestamp8+ | number | 事件时间戳。 | + | target8+ | [EventTarget](ts-universal-events-click.md) | 触发手势事件的元素对象显示区域。 | + | source8+ | [SourceType](ts-gesture-settings.md) | 事件输入设备。 | -| 属性名称 | 类型 | 描述 | -| ------------------- | ------------------------------------------------------------ | ---------------------------------- | -| type | [TouchType](ts-appendix-enums.md#touchtype) | 触摸事件的类型。 | -| touches | Array<[TouchObject](#touchobject对象说明)> | 全部手指信息。 | -| changedTouches | Array<[TouchObject](#touchobject对象说明)> | 当前发生变化的手指信息。 | -| timestamp | number | 距离开机时间的时间戳，单位为毫秒。 | -| target8+ | [EventTarget](ts-universal-events-click.md#eventtarget8对象说明) | 被触摸元素对象。 | - -### 接口 - -| 接口名称 | 功能描述 | -| ---------------------- | ------- | -| stopPropagation()：void | 阻塞事件冒泡。 | ## TouchObject对象说明 -| 属性名称 | 类型 | 描述 | + +| 名称 | 类型 | 描述 | | ------- | --------------------------- | ------------------- | | type | [TouchType](ts-appendix-enums.md#touchtype) | 触摸事件的类型。 | | id | number | 手指唯一标识符。 | diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-mouse-key.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-mouse-key.md index 1735b4af8a9184d39c1166ad8f0744de31d282ad..2264ace64b057a1b55edc3d52c4e84d8a28d0fa6 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-mouse-key.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-mouse-key.md @@ -5,29 +5,28 @@ > 从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -## 权限列表 - -无 - - ## 事件 -| 名称 | 支持冒泡 | 描述 | -| ---------------------------------------- | ---- | ---------------------------------------- | -| onHover(callback: (isHover: boolean) => void) | 否 | 鼠标进入或退出组件时触发该回调。
isHover：表示鼠标是否悬浮在组件上，鼠标进入时为true, 退出时为false。 | -| onMouse(callback: (event?: MouseEvent) => void) | 是 | 当前组件被鼠标按键点击时或者鼠标在组件上移动时，触发该回调，event参数包含触发事件时的时间戳、鼠标按键、动作、点击触点在整个屏幕上的坐标和点击触点相对于当前组件的坐标。 | +| 名称 | 支持冒泡 | 描述 | +| ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| onHover(event: (isHover: boolean) => void) | 否 | 鼠标进入或退出组件时触发该回调。
isHover：表示鼠标是否悬浮在组件上，鼠标进入时为true, 退出时为false。 | +| onMouse(event: (event?: MouseEvent) => void) | 是 | 当前组件被鼠标按键点击时或者鼠标在组件上移动时，触发该回调，event参数包含触发事件时的时间戳、鼠标按键、动作、点击触点在整个屏幕上的坐标和点击触点相对于当前组件的坐标。 | ## MouseEvent对象说明 -| 属性名称 | 属性类型 | 描述 | + +| 名称 | 属性类型 | 描述 | | --------- | ------------------------------- | -------------------- | -| timestamp | number | 触发事件时的时间戳。 | | screenX | number | 点击触点相对于屏幕左上角的x轴坐标。 | | screenY | number | 点击触点相对于屏幕左上角的y轴坐标。 | | x | number | 点击触点相对于当前组件左上角的x轴坐标。 | | y | number | 点击触点相对于当前组件左上角的y轴坐标。 | | button | [MouseButton](ts-appendix-enums.md#mousebutton) | 鼠标按键。 | | action | [MouseAction](ts-appendix-enums.md#mouseaction) | 事件动作。 | +| stopPropagation | () => void | 阻塞事件冒泡。 | +| timestamp8+ | number | 事件时间戳。 | +| target8+ | [EventTarget](ts-universal-events-click.md) | 触发手势事件的元素对象显示区域。 | +| source8+ | [SourceType](ts-gesture-settings.md) | 事件输入设备。 | ## 示例