Skip to content

D
Docs

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

通知 161
Star 293
Fork 28
D
Docs
“b40addd107d512f05b9f04509bca5fb4abac0dfe”上不存在“git@gitcode.net:MarkPoloChina/VueJS.git”
提交 e20d2376 编写于 作者: E esterzhou
浏览文件
操作

update docs (9575) 

Signed-off-by: Nesterzhou <ester.zhou@huawei.com>
上级 275b5648
隐藏空白更改
内联 并排
Showing with 765 addition and 222 deletion
en/application-dev/reference/apis/js-apis-settings.md
浏览文件 @ e20d2376
# Settings # Settings
> **NOTE**<br> The **settings** module provides APIs for setting data items.
> The initial APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
This module provides APIs for setting data items.
> **NOTE**
>
> The initial APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
## Modules to Import ## Modules to Import
```typescript ```js
import settings from '@ohos.settings'; import settings from '@ohos.settings';
``` ```
## date
Provides data items for setting the time and date formats.
### Attributes
**System capability**: SystemCapability.Applications.settings.Core
| Name | Type | Readable| Writable| Description |
| ------------------- | ------ | ---- | ---- | ------------------------------------------------------------ |
| DATE_FORMAT | string | Yes | Yes | Date format.<br>The value can be **mm/dd/yyyy**, **dd/mm/yyyy**, or **yyyy/mm/dd**, where **mm** indicates the month, **dd** indicates the day, and **yyyy** indicates the year.|
| TIME_FORMAT | string | Yes | Yes | Time format.<br>**12**: 12-hour format.<br>**24**: 24-hour format.|
| AUTO_GAIN_TIME | string | Yes | Yes | Whether the date, time, and time zone are automatically obtained from the Network Identity and Time Zone (NITZ).<br>The value **true** means that the date, time, and time zone are automatically obtained from NITZ; and **false** means the opposite.|
| AUTO_GAIN_TIME_ZONE | string | Yes | Yes | Whether the time zone is automatically obtained from NITZ.<br>The value **true** means that the time zone is automatically obtained from NITZ; and **false** means the opposite.|
## display
Provides data items for setting the display effects.
### Attributes
**System capability**: SystemCapability.Applications.settings.Core
| Name | Type | Readable| Writable| Description |
| ----------------------------- | ------ | ---- | ---- | ------------------------------------------------------------ |
| FONT_SCALE | string | Yes | Yes | Scale factor of the font. The value is a floating point number. |
| SCREEN_BRIGHTNESS_STATUS | string | Yes | Yes | Screen brightness. The value ranges from 0 to 255. |
| AUTO_SCREEN_BRIGHTNESS | string | Yes | Yes | Whether automatic screen brightness adjustment is enabled.<br>**AUTO_SCREEN_BRIGHTNESS_MODE**: Automatic screen brightness adjustment is enabled.<br>**MANUAL_SCREEN_BRIGHTNESS_MODE**: Automatic screen brightness adjustment is disabled.|
| AUTO_SCREEN_BRIGHTNESS_MODE | number | Yes | Yes | Value of **AUTO_SCREEN_BRIGHTNESS** when automatic screen brightness adjustment is enabled. |
| MANUAL_SCREEN_BRIGHTNESS_MODE | number | Yes | Yes | Value of **AUTO_SCREEN_BRIGHTNESS** when automatic screen brightness adjustment is disabled. |
| SCREEN_OFF_TIMEOUT | string | Yes | Yes | Waiting time for the device to enter the sleep state when not in use (unit: ms). |
| DEFAULT_SCREEN_ROTATION | string | Yes | Yes | Rotation angle. This attribute is valid only when screen auto-rotation is disabled.<br>**0**: The screen rotates by 0 degrees.<br>**1**: The screen rotates by 90 degrees.<br>**2**: The screen rotates by 180 degrees.<br>**3**: The screen rotates by 270 degrees.|
| ANIMATOR_DURATION_SCALE | string | Yes | Yes | Scale factor for the animation duration. This affects the start delay and duration of all such animations.<br>If the value is **0**, the animation ends immediately. The default value is **1**.|
| TRANSITION_ANIMATION_SCALE | string | Yes | Yes | Scale factor for transition animations.<br>The value **0** indicates that the transition animations are disabled. |
| WINDOW_ANIMATION_SCALE | string | Yes | Yes | Scale factor for normal window animations.<br>The value **0** indicates that window animations are disabled. |
| DISPLAY_INVERSION_STATUS | string | Yes | Yes | Whether display color inversion is enabled.<br>**1**: Display color inversion is enabled.<br>**0**: Display color inversion is disabled.|
## general
Provides data items for setting the general information about the device.
### Attributes
**System capability**: SystemCapability.Applications.settings.Core
| Name | Type | Readable| Writable| Description |
| -------------------------------- | ------ | ---- | ---- | ------------------------------------------------------------ |
| SETUP_WIZARD_FINISHED | string | Yes | Yes | Whether the startup wizard is running.<br>If the value is **0**, the startup wizard is not running.<br>If the value is not **0**, the startup wizard is running.|
| END_BUTTON_ACTION | string | Yes | Yes | Action after the call end button is pressed if the user is not in a call.<br>**0**: Nothing happens.<br>**1**: The home screen is displayed.<br>**2**: The device enters sleep mode and the screen is locked.<br>**3**: The home screen is displayed. If the focus is already on the home screen, the device will enter sleep mode.|
| ACCELEROMETER_ROTATION_STATUS | string | Yes | Yes | Whether the accelerometer is used to change screen orientation, that is, whether to enable auto-rotation.<br>**1**: The accelerometer is used.<br>**0**: The accelerometer is not used.|
| AIRPLANE_MODE_STATUS | string | Yes | Yes | Whether airplane mode is enabled.<br>**1**: Airplane mode is enabled.<br>**0**: Airplane mode is disabled.|
| DEVICE_PROVISION_STATUS | string | Yes | Yes | Whether the device is preconfigured.<br>On a multi-user device with a single system user, the screen may be locked when the value is **true**. In addition, other features cannot be started on the system user unless they are marked to display on the lock screen.|
| HDC_STATUS | string | Yes | Yes | Whether the hard disk controller (HDC) on the USB device is enabled.<br>**true**: HDC is enabled.<br>**false**: HDC is disabled.|
| BOOT_COUNTING | string | Yes | Yes | Number of boot operations after the device is powered on. |
| CONTACT_METADATA_SYNC_STATUS | string | Yes | Yes | Whether contacts metadata synchronization is enabled.<br>**true**: Contacts metadata synchronization is enabled.<br>**false**: Contacts metadata synchronization is disabled.|
| DEVELOPMENT_SETTINGS_STATUS | string | Yes | Yes | Whether developer options are enabled.<br>**true**: Developer options are enabled.<br>**false**: Developer options are disabled.|
| DEVICE_NAME | string | Yes | Yes | Device name. |
| USB_STORAGE_STATUS | string | Yes | Yes | Whether USB mass storage is enabled.<br>**true**: USB mass storage is enabled.<br>**false**: USB mass storage is disabled.|
| DEBUGGER_WAITING | string | Yes | Yes | Whether the device waits for the debugger when starting an application to debug.<br>**1**: The device waits for the debugger.<br>**0**: The device does not wait for the debugger. In this case, the application runs normally.|
| DEBUG_APP_PACKAGE | string | Yes | Yes | Bundle name of the application to be debugged. |
| ACCESSIBILITY_STATUS | string | Yes | Yes | Whether accessibility is enabled.<br>**1**: Accessibility is enabled.<br>**0**: Accessibility is disabled.|
| ACTIVATED_ACCESSIBILITY_SERVICES | string | Yes | Yes | List of activated accessibility features. |
| GEOLOCATION_ORIGINS_ALLOWED | string | Yes | Yes | Default geographic location that can be used by the browser. Multiple geographic locations are separated by spaces. |
| SKIP_USE_HINTS | string | Yes | Yes | Whether the application should attempt to skip all introductory hints at the first startup. This feature is intended for temporary or experienced users.<br>**1**: The application attempts to skip all introductory hints at the first startup.<br>**0**: The application does not skip all introductory hints at the first startup.|
| TOUCH_EXPLORATION_STATUS | string | Yes | Yes | Whether touch exploration is enabled.<br>**1**: Touch exploration is enabled.<br>**0**: Touch exploration is disabled.|
## input
Provides data items for setting input methods.
### Attributes
**System capability**: SystemCapability.Applications.settings.Core
| Name | Type | Readable| Writable| Description |
| ------------------------------------ | ------ | ---- | ---- | ------------------------------------------------------------ |
| DEFAULT_INPUT_METHOD | string | Yes | Yes | Default input method and its ID. |
| ACTIVATED_INPUT_METHOD_SUB_MODE | string | Yes | Yes | Type and ID of the default input method keyboard. |
| ACTIVATED_INPUT_METHODS | string | Yes | Yes | List of activated input methods.<br>The list is a string that contains the IDs and keyboard types of activated input methods. The IDs are separated by colons (:), and keyboard types are separated by semicolons (;). An example format is **ima0:keyboardType0;keyboardType1;ima1:ima2:keyboardTypes0,** where **ima** indicates the ID of an input method, and **keyboardType** indicates the keyboard type.|
| SELECTOR_VISIBILITY_FOR_INPUT_METHOD | string | Yes | Yes | Whether the input method selector is visible.<br>**1**: The input method selector is visible.<br>**0**: The input method selector is invisible.|
| AUTO_CAPS_TEXT_INPUT | string | Yes | Yes | Whether automatic capitalization is enabled for the text editor.<br>**0**: Automatic capitalization is disabled.<br>**1**: Automatic capitalization is enabled.|
| AUTO_PUNCTUATE_TEXT_INPUT | string | Yes | Yes | Whether automatic punctuation is enabled for the text editor. Automatic punctuation enables the text editor to convert two spaces into a period (.) and a space.<br>**0**: Automatic punctuation is disabled.<br>**1**: Automatic punctuation is enabled.|
| AUTO_REPLACE_TEXT_INPUT | string | Yes | Yes | Whether autocorrect is enabled for the text editor. Autocorrect enables the text editor to correct typos.<br>**0**: Autocorrect is disabled.<br>**1**: Autocorrect is enabled |
| SHOW_PASSWORD_TEXT_INPUT | string | Yes | Yes | Whether password presentation is enabled in the text editor. Password presentation enables the text editor to show password characters when the user types them.<br>**0**: Password presentation is disabled.<br>**1**: Password presentation is enabled.|
## network
Provides data items for setting network information.
### Attributes
**System capability**: SystemCapability.Applications.settings.Core
| Name | Type | Readable| Writable| Description |
| ------------------------ | ------ | ---- | ---- | ------------------------------------------------------------ |
| DATA_ROAMING_STATUS | string | Yes | Yes | Whether data roaming is enabled.<br>**true**: Data roaming is enabled.<br>**false**: Data roaming is disabled.|
| HTTP_PROXY_CFG | string | Yes | Yes | Host name and port number of the global HTTP proxy. The host name and port number are separated by a colon (:).|
| NETWORK_PREFERENCE_USAGE | string | Yes | Yes | User preferences for the network to use. |
## phone
Provides data items for setting the modes of answering incoming and outgoing calls.
### Attributes
**System capability**: SystemCapability.Applications.settings.Core
| Name | Type | Readable| Writable| Description |
| ------------------ | ------ | ---- | ---- | ------------------------------------------------------------ |
| RTT_CALLING_STATUS | string | Yes | Yes | Whether the real-time text (RTT) feature is enabled. If this feature is enabled, incoming and outgoing calls are answered as RTT calls when supported by the device and carrier.<br> **1**: RTT is enabled.<br> **0**: RTT is disabled.|
## sound
Provides data items for setting the sound effects.
### Attributes
**System capability**: SystemCapability.Applications.settings.Core
| Name | Type | Readable| Writable| Description |
| ---------------------------- | ------ | ---- | ---- | ------------------------------------------------------------ |
| VIBRATE_WHILE_RINGING | string | Yes | Yes | Whether the device vibrates when it is ringing for an incoming call. This attribute is applicable to the phone and settings applications and affects only the scenario where the device rings for an incoming call. It does not affect any other application or scenario.|
| DEFAULT_ALARM_ALERT | string | Yes | Yes | Storage area of the system default alarms and alerts. |
| DTMF_TONE_TYPE_WHILE_DIALING | string | Yes | Yes | Type of the dual tone multi-frequency (DTMF) tone played while dialing.<br>**0**: normal short tone.<br>**1**: long tone.|
| DTMF_TONE_WHILE_DIALING | string | Yes | Yes | Whether the DTMF tone is played when dialing.<br>**1**: DTMF tone is played when dialing.<br>**0**: DTMF tone is not played when dialing.|
| AFFECTED_MODE_RINGER_STREAMS | string | Yes | Yes | Which audio streams are affected by changes on the ringing mode and Do Not Disturb (DND) mode. If you want a specific audio stream to be affected by changes of the ringing mode and DDN mode, set the corresponding bit to **1**.|
| AFFECTED_MUTE_STREAMS | string | Yes | Yes | Audio streams affected by the mute mode. If you want a specific audio stream to remain muted in mute mode, set the corresponding bit to **1**.|
| DEFAULT_NOTIFICATION_SOUND | string | Yes | Yes | Storage area of the system default notification tone. |
| DEFAULT_RINGTONE | string | Yes | Yes | Storage area of the system default ringtone. |
| SOUND_EFFECTS_STATUS | string | Yes | Yes | Whether the sound feature is available.<br>**0**: The feature is not available.<br>**1**: The feature is available. |
| VIBRATE_STATUS | string | Yes | Yes | Whether the device vibrates for an event. This attribute is used inside the system.<br>**1**: The device vibrates for an event.<br>**0**: The device does not vibrate for an event.|
| HAPTIC_FEEDBACK_STATUS | string | Yes | Yes | Whether haptic feedback is enabled.<br>**true**: Haptic feedback is enabled.<br>**false**: Haptic feedback is disabled.|
## TTS
Provides data items for setting text-to-speech (TTS) information.
### Attributes
**System capability**: SystemCapability.Applications.settings.Core
| Name | Type | Readable| Writable| Description |
| ------------------- | ------ | ---- | ---- | ------------------------------------------------------------ |
| DEFAULT_TTS_PITCH | string | Yes | Yes | Default pitch of the TTS engine.<br>100 = 1x. If the value is set to **200**, the frequency is twice the normal sound frequency.|
| DEFAULT_TTS_RATE | string | Yes | Yes | Default voice rate of the TTS engine.<br>100 = 1x. |
| DEFAULT_TTS_SYNTH | string | Yes | Yes | Default TTS engine. |
| ENABLED_TTS_PLUGINS | string | Yes | Yes | List of activated plug-in packages used for TTS. Multiple plug-in packages are separated by spaces. |
## wireless
Provides data items for setting wireless network information.
### Attributes
**System capability**: SystemCapability.Applications.settings.Core
| Name | Type | Readable| Writable| Description |
| --------------------------------- | ------ | ---- | ---- | ------------------------------------------------------------ |
| BLUETOOTH_DISCOVER_ABILITY_STATUS | string | Yes | Yes | Whether the device can be discovered or connected by other devices through Bluetooth.<br>**0**: The device cannot be discovered or connected.<br>**1**: The device can be connected but cannot be discovered.<br>**2**: The device can be discovered and connected.|
| BLUETOOTH_DISCOVER_TIMEOUT | string | Yes | Yes | Duration for discovering a device through Bluetooth, in seconds.<br>After the duration expires, the device cannot be discovered through Bluetooth.|
| AIRPLANE_MODE_RADIOS | string | Yes | Yes | List of radio signals to be disabled when airplane mode is enabled.<br>Multiple radio signals are separated by commas (,). The list can include the following: **BLUETOOTH_RADIO**, **CELL_RADIO**, **NFC_RADIO**, and **WIFI_RADIO**.|
| BLUETOOTH_RADIO | string | Yes | No | A value of **AIRPLANE_MODE_RADIOS** to indicate that Bluetooth is disabled in airplane mode.|
| CELL_RADIO | string | Yes | No | A value of **AIRPLANE_MODE_RADIOS** to indicate that cellular radio is disabled in airplane mode.|
| NFC_RADIO | string | Yes | No | A value of **AIRPLANE_MODE_RADIOS** to indicate that NFC is disabled in airplane mode.|
| WIFI_RADIO | string | Yes | No | A value of **AIRPLANE_MODE_RADIOS** to indicate that Wi-Fi is disabled in airplane mode.|
| BLUETOOTH_STATUS | string | Yes | Yes | Whether Bluetooth is available.<br>**true**: Bluetooth is available.<br>**false**: Bluetooth is unavailable.|
| OWNER_LOCKDOWN_WIFI_CFG | string | Yes | Yes | Whether the Wi-Fi configuration created by the application of the device owner should be locked down.<br>**true**: The Wi-Fi configuration should be locked down.<br>**false**: The Wi-Fi configuration should not be locked down.|
| WIFI_DHCP_MAX_RETRY_COUNT | string | Yes | Yes | Maximum number of attempts to obtain an IP address from the DHCP server. |
| WIFI_TO_MOBILE_DATA_AWAKE_TIMEOUT | string | Yes | Yes | Maximum duration to hold a wake lock when waiting for the mobile data connection to establish after the Wi-Fi connection is disconnected. |
| WIFI_STATUS | string | Yes | Yes | Whether Wi-Fi is available.<br>**true**: Wi-Fi is available.<br>**false**: Wi-Fi is unavailable.|
| WIFI_WATCHDOG_STATUS | string | Yes | Yes | Whether Wi-Fi watchdog is available.<br>**true**: Wi-Fi watchdog is available.<br>**false**: Wi-Fi watchdog is unavailable.|
## setting.getURI
getURI(name: string, callback: AsyncCallback\<object>): void
Obtains the URI of a data item. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Applications.settings.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ------------------------------------------------------------ |
| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items|
| callback | AsyncCallback\<object> | Yes | Callback used to obtain the URI of the data item. |
**Example**
```js
settings.getURI(settings.display.SCREEN_BRIGHTNESS_STATUS, (uri) => {
console.log(`callback:uri -> ${JSON.stringify(uri)}`)
})
```
## setting.getURI
getURI(name: string): Promise\<object>
Obtains the URI of a data item. This API uses a promise to return the result.
**System capability**: SystemCapability.Applications.settings.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items|
**Return value**
| Type | Description |
| ---------------- | ------------------------------------ |
| Promise\<object> | Promise used to return the URI of the data item.|
**Example**
```js
settings.getURI(settings.display.SCREEN_BRIGHTNESS_STATUS).then((uri) => {
console.log(`promise:uri -> ${JSON.stringify(uri)}`)
})
```
## setting.getValue
getValue(dataAbilityHelper: DataAbilityHelper, name: string, callback: AsyncCallback\<object>): void
Obtains the value of a data item in the database. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Applications.settings.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ----------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ |
| dataAbilityHelper | [DataAbilityHelper](js-apis-dataAbilityHelper.md) | Yes | **DataAbilityHelper** class. |
| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br> - Existing data items in the database<br>- Custom data items|
| callback | AsyncCallback\<object> | Yes | Callback used to return the value of the data item. |
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
let uri = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS);
let helper = featureAbility.acquireDataAbilityHelper(uri);
settings.getValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, (err, value) => {
if (err) {
console.error(`Failed to get the setting. ${err.message} `);
return;
}
console.log(`callback:value -> ${JSON.stringify(value)}`)
});
```
## setting.getValue
getValue(dataAbilityHelper: DataAbilityHelper, name: string): Promise\<object>
Obtains the value of a data item in the database. This API uses a promise to return the result.
**System capability**: SystemCapability.Applications.settings.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ----------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ |
| dataAbilityHelper | [DataAbilityHelper](js-apis-dataAbilityHelper.md) | Yes | **DataAbilityHelper** class. |
| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br> - Existing data items in the database<br>- Custom data items|
**Return value**
| Type | Description |
| ---------------- | ----------------------------------- |
| Promise\<object> | Promise used to return the value of the data item.|
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
let uri = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS);
let helper = featureAbility.acquireDataAbilityHelper(uri);
settings.getValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS).then((value) => {
console.log(`promise:value -> ${JSON.stringify(value)}`)
});
```
## settings.setValue
setValue(dataAbilityHelper: DataAbilityHelper, name: string, value: object, callback: AsyncCallback\<boolean>): void
Sets the value for a data item. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Applications.settings.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ----------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ |
| dataAbilityHelper | [DataAbilityHelper](js-apis-dataAbilityHelper.md) | Yes | **DataAbilityHelper** class. |
| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items|
| value | object | Yes | Value of the data item. The value range varies by service. |
| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result. Returns **true** if the operation is successful; returns **false** otherwise. |
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
// Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the setValue API will update the value of the data item.)
let uri = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS);
let helper = featureAbility.acquireDataAbilityHelper(uri);
settings.setValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, '100', (status) => {
console.log('Callback return whether value is set.');
});
```
## settings.setValue
setValue(dataAbilityHelper: DataAbilityHelper, name: string, value: object): Promise\<boolean>
Sets the value for a data item. This API uses a promise to return the result.
**System API**: This is a system API.
**System capability**: SystemCapability.Applications.settings.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ----------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ |
| dataAbilityHelper | [DataAbilityHelper](js-apis-dataAbilityHelper.md) | Yes | **DataAbilityHelper** class. |
| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items|
| value | object | Yes | Value of the data item. The value range varies by service. |
**Return value**
| Type | Description |
| ----------------- | -------------------------------------------------- |
| Promise\<boolean> | Promise used to return the result. Returns **true** if the operation is successful; returns **false** otherwise.|
## settings.getUriSync **Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
// Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the setValue API will update the value of the data item.)
let uri = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS);
let helper = featureAbility.acquireDataAbilityHelper(uri);
settings.setValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, '100').then((status) => {
console.log('Callback return whether value is set.');
});
```
## settings.enableAirplaneMode
enableAirplaneMode(enable: boolean, callback: AsyncCallback\<void>): void
Enables or disables airplane mode. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Applications.settings.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ----------------------------------------------- |
| enable | boolean | Yes | Whether airplane mode is enabled. **true** means that airplane mode is enabled, and **false** means the opposite.|
| callback | AsyncCallback\<void> | Yes | Callback used to return the result. |
**Example**
```js
let isEnabled = true;
settings.enableAirplaneMode(isEnabled, (err) => {
if (err) {
console.log('Failed to enable AirplaneMode.');
return;
}
console.log('Return true if enable.');
})
```
## settings.enableAirplaneMode
enableAirplaneMode(enable: boolean): Promise\<void>
Enables or disables airplane mode. This API uses a promise to return the result.
**System capability**: SystemCapability.Applications.settings.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ----------------------------------------------- |
| enable | boolean | Yes | Whether airplane mode is enabled. **true** means that airplane mode is enabled, and **false** means the opposite.|
**Return value**
| Type | Description |
| -------------- | ------------------------- |
| Promise\<void> | Promise that returns no value.|
**Example**
```js
let isEnabled = true;
settingsenableAirplaneMode(isEnabled).then((err) => {
if (err) {
console.log('Failed to enable AirplaneMode.');
return;
}
console.log('Return true if enable.');
});
```
## settings.canShowFloating
canShowFloating(callback: AsyncCallback\<boolean>): void
Checks whether the application can be displayed in a floating window. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Applications.settings.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result.<br>Returns **true** if the application can be displayed in a floating window; returns **false** otherwise.|
**Example**
```js
settings.canShowFloating((status) => {
console.log('Checks whether a specified application can show as float window.');
});
```
## settings.canShowFloating
canShowFloating(): Promise\<boolean>
Checks whether the application can be displayed in a floating window. This API uses a promise to return the result.
**System capability**: SystemCapability.Applications.settings.Core
**Return value**
| Type | Description |
| ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | Promise used to return the result.<br>Returns **true** if the application can be displayed in a floating window; returns **false** otherwise.|
**Example**
```js
settings.canShowFloating().then((status) => {
console.log('Checks whether a specified application can show as float window.');
});
```
## settings.getUriSync<sup>8+</sup>
getUriSync(name: string): string getUriSync(name: string): string
...@@ -25,93 +485,89 @@ Obtains the URI of a data item. ...@@ -25,93 +485,89 @@ Obtains the URI of a data item.
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type | Mandatory| Description |
| -------- | -------- | -------- | -------- | | ------ | ------ | ---- | ------------------------------------------------------------ |
| name | string | Yes| Name of the target data item. Data items can be classified as follows:<br> <ul><li>Existing data items in the database, for example:<br></li> <ul><li>Brightness: 'settings.screen.brightness'<br> </li> <li>Time format: 'settings.time.format'<br> </li></ul> <li>Custom data items</li></ul>| | name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items|
**Return value** **Return value**
| Type| Description| | Type | Description |
| -------- | -------- | | ------ | ------------- |
| string | URI of the data item.| | string | URI of the data item.|
**Example** **Example**
```typescript ```js
// Obtain the URI of a data item. // Obtain the URI of a data item.
let urivar = settings.getUriSync('settings.screen.brightness'); let urivar = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS);
``` ```
## settings.getValueSync<sup>8+</sup>
## settings.getValueSync
getValueSync(dataAbilityHelper: DataAbilityHelper, name: string, defValue: string): string getValueSync(dataAbilityHelper: DataAbilityHelper, name: string, defValue: string): string
Obtains the value of a data item. Obtains the value of a data item. Unlike **getValue**, this API returns the result synchronously.
**System capability**: SystemCapability.Applications.settings.Core **System capability**: SystemCapability.Applications.settings.Core
**Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory| Description |
| dataAbilityHelper | [DataAbilityHelper](js-apis-dataAbilityHelper.md) | Yes| **DataAbilityHelper** class.| | ----------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ |
| name | string | Yes| Name of the target data item. Data items can be classified as follows:<br> <ul><li>Existing data items in the database, for example:<br></li> <ul><li>Brightness: 'settings.screen.brightness'<br> </li> <li>Time format: 'settings.time.format'<br> </li></ul> <li>Custom data items</li></ul>| | dataAbilityHelper | [DataAbilityHelper](js-apis-dataAbilityHelper.md) | Yes | **DataAbilityHelper** class. |
| defValue | string | Yes| Default value This parameter is user-defined. If it is not found in the database, the default value is returned.| | name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items|
| defValue | string | Yes | Default value, which is returned when the value of a data item is not found in the database. Set this attribute as needed.|
**Return value** **Return value**
| Type| Description| | Type | Description |
| -------- | -------- | | ------ | ---------------- |
| string | Value of the data item.| | string | Value of the data item.|
**Example** **Example**
```typescript ```js
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
// Obtain the value of 'settings.screen.brightness' (this data item already exists in the database). // Obtain the value of SCREEN_BRIGHTNESS_STATUS (this data item already exists in the database).
let brightness = 'settings.screen.brightness'; let uri = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS);
let uri = settings.getUriSync(brightness);
let helper = featureAbility.acquireDataAbilityHelper(uri); let helper = featureAbility.acquireDataAbilityHelper(uri);
let value = settings.getValueSync(helper, brightness, '10'); let value = settings.getValueSync(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, '10');
``` ```
## settings.setValueSync<sup>8+</sup>
## settings.setValueSync
setValueSync(dataAbilityHelper: DataAbilityHelper, name: string, value: string): boolean setValueSync(dataAbilityHelper: DataAbilityHelper, name: string, value: string): boolean
Sets the value of a data item. Sets the value for a data item. Unlike **setValue**, this API returns the result synchronously.
If the specified data item exists in the database, the **setValueSync** method updates the value of the data item. If the data item does not exist in the database, the **setValueSync** method inserts the data item into the database. If the specified data item exists in the database, the **setValueSync** method updates the value of the data item. If the data item does not exist in the database, the **setValueSync** method inserts the data item into the database.
**Required permissions**: ohos.permission.WRITE_SYSTEM_SETTING **Required permissions**: ohos.permission.MANAGE_SECUER_SETTINGS (available only to system applications)
**System capability**: SystemCapability.Applications.settings.Core **System capability**: SystemCapability.Applications.settings.Core
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name | Type | Mandatory| Description |
| -------- | -------- | -------- | -------- | | ----------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ |
| dataAbilityHelper | [DataAbilityHelper](js-apis-dataAbilityHelper.md) | Yes| **DataAbilityHelper** class.| | dataAbilityHelper | [DataAbilityHelper](js-apis-dataAbilityHelper.md) | Yes | **DataAbilityHelper** class. |
| name | string | Yes| Name of the target data item. Data items can be classified as follows:<br> <ul><li>Existing data items in the database, for example:<br></li> <ul><li>Brightness: 'settings.screen.brightness'<br> </li> <li>Time format: 'settings.time.format'<br> </li></ul> <li>Custom data items</li></ul>| | name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items|
| value | string | Yes| Value of the data item.| | value | string | Yes | Value of the data item. The value range varies by service. |
**Return value** **Return value**
| Type| Description| | Type | Description |
| -------- | -------- | | ------- | ------------------------------------------------------------ |
| boolean | Result indicating whether the value is set successfully. Returns **true** if the value is set successfully; returns **false** otherwise.| | boolean | Result indicating whether the value is set successfully. Returns **true** if the value is set successfully; returns **false** otherwise.|
**Example** **Example**
```typescript ```js
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
// Update the value of 'settings.screen.brightness'. (As this data item exists in the database, the setValueSync // Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the setValueSync API will update the value of the data item.)
method will update the value of the data item.) let uri = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS);
let brightness = 'settings.screen.brightness';
let uri = settings.getUriSync(brightness);
let helper = featureAbility.acquireDataAbilityHelper(uri); let helper = featureAbility.acquireDataAbilityHelper(uri);
let ret = settings.setValueSync(helper, brightness, '100'); let ret = settings.setValueSync(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, '100');
``` ```
\ No newline at end of file
en/application-dev/reference/arkui-ts/ts-basic-components-text.md
浏览文件 @ e20d2376
...@@ -2,16 +2,11 @@ ...@@ -2,16 +2,11 @@
The **\<Text>** component is used to display a piece of textual information. The **\<Text>** component is used to display a piece of textual information.
> **NOTE** > **NOTE**<br/>
> >
> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. > This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
## Required Permissions
None
## Child Components ## Child Components
This component can contain the [\<Span>](ts-basic-components-span.md) child component. This component can contain the [\<Span>](ts-basic-components-span.md) child component.
...@@ -22,34 +17,38 @@ This component can contain the [\<Span>](ts-basic-components-span.md) child comp ...@@ -22,34 +17,38 @@ This component can contain the [\<Span>](ts-basic-components-span.md) child comp
Text(content?: string | Resource) Text(content?: string | Resource)
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| content | string \| [Resource](ts-types.md#resource) | No| Text content. The content and style set for the **\<Text>** component do not take effect when it contains the **\<Span>** child component.<br>Default value: ' ' | | content | string \| [Resource](ts-types.md#resource) | No| Text content. The content and style set for the **\<Text>** component do not take effect when it contains the **\<Span>** child component.<br>Default value: **' '**|
## Attributes ## Attributes
In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
| Name| Type| Description|
| -------- | -------- | -------- | | Name | Type | Description |
| textAlign | [TextAlign](ts-appendix-enums.md#textalign) | Text alignment mode of multiple lines of text.<br/>Default value: **TextAlign.Start** | | ----------------------- | ----------------------------------- | ------------------------------------------- |
| textOverflow | {overflow: [TextOverflow](ts-appendix-enums.md#textoverflow)} | Display mode when the text is too long.<br/>Default value: **{overflow:&nbsp;TextOverflow.Clip}**<br>**NOTE**<br/>Text is truncated at the transition between words. To truncate text in the middle of a word, add **\u200B** between characters. | | textAlign | [TextAlign](ts-appendix-enums.md#textalign) | Horizontal alignment mode of the text.<br>Default value: **TextAlign.Start**|
| maxLines | number | Maximum number of lines in the text.<br>Default value: **Infinity** | | textOverflow | {overflow: [TextOverflow](ts-appendix-enums.md#textoverflow)} | Display mode when the text is too long.<br>Default value: **{overflow: TextOverflow.Clip}**<br>**NOTE**<br/>Text is clipped at the transition between words. To clip text in the middle of a word, add **\u200B** between characters.<br>This attribute must be used with `maxLines` to take effect.|
| lineHeight | string \| number \| [Resource](ts-types.md#resource) | Text line height. If the value is less than or equal to **0**, the line height is not limited and the font size is adaptive. If the value of the number type, the unit fp is used. | | maxLines | number | Maximum number of lines in the text.<br>Default value: **Infinity**<br>**NOTE**<br/>By default, text is automatically folded. If this attribute is specified, the text will not exceed the specified number of lines. If there is extra text, you can use **textOverflow** to specify how it is displayed.|
| decoration | {<br>type: [TextDecorationType](ts-appendix-enums.md#textdecorationtype),<br>color?: [ResourceColor](ts-types.md#resourcecolor8)<br>} | Style and color of the text decorative line.<br/>Default value: **{<br/>type: TextDecorationType.None,<br/>color: Color.Black<br/>}** | | lineHeight | string \| number \| [Resource](ts-types.md#resource) | Text line height. If the value is less than or equal to **0**, the line height is not limited and the font size is adaptive. If the value of the number type, the unit fp is used.|
| baselineOffset | number \| string | Offset of the text baseline. | | decoration | {<br>type: [TextDecorationType](ts-appendix-enums.md#textdecorationtype),<br>color?: [ResourceColor](ts-types.md#resourcecolor)<br>} | Style and color of the text decorative line.<br>Default value: **{<br>type: TextDecorationType.None,<br>color: Color.Black<br>}** |
| letterSpacing | number \| string | Letter spacing. | | baselineOffset | number \| string | Baseline offset of the text. The default value is **0**. |
| minFontSize | number \| string \| [Resource](ts-types.md#resource) | Minimum font size. | | letterSpacing | number \| string | Letter spacing. |
| maxFontSize | number \| string \| [Resource](ts-types.md#resource) | Maximum font size. | | minFontSize | number \| string \| [Resource](ts-types.md#resource) | Minimum font size. |
| textCase | [TextCase](ts-appendix-enums.md#textcase) | Text case.<br/>Default value: **TextCase.Normal** | | maxFontSize | number \| string \| [Resource](ts-types.md#resource) | Maximum font size. |
| textCase | [TextCase](ts-appendix-enums.md#textcase) | Text case.<br>Default value: **TextCase.Normal**|
> **NOTE** | copyOption<sup>9+</sup> | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Whether copy and paste is allowed.<br>Default value: **CopyOptions.None**|
> **NOTE**<br/>
> >
> The **\<Text>** component cannot contain both the text and the child component **\<Span>**. If both of them exist, only the content in **\<Span>** is displayed. > The **\<Text>** component cannot contain both the text and the child component **\<Span>**. If both of them exist, only the content in **\<Span>** is displayed.
## Example ## Example
### Example 1
Examples of using **textAlign**, **textOverflow**, **maxLines**, and **lineHeight**
```ts ```ts
// xxx.ets // xxx.ets
@Entry @Entry
...@@ -57,77 +56,184 @@ Text(content?: string | Resource) ...@@ -57,77 +56,184 @@ Text(content?: string | Resource)
struct TextExample1 { struct TextExample1 {
build() { build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) {
Text('lineHeight').fontSize(9).fontColor(0xCCCCCC) // Set the horizontal alignment mode for the text.
Text('This is the text with the line height set This is the text with the line height set This is the text with the line height set.') // Single-line text
.lineHeight(25).fontSize(12).border({ width: 1 }).padding(10) Text('textAlign').fontSize(9).fontColor(0xCCCCCC)
Text('TextAlign set to Center.')
.textAlign(TextAlign.Center)
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
Text('TextAlign set to Start.')
.textAlign(TextAlign.Start)
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
Text('TextAlign set to End.')
.textAlign(TextAlign.End)
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
// Multi-line text
Text('This is the text content with textAlign set to Center.')
.textAlign(TextAlign.Center)
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
Text('This is the text content with textAlign set to Start.')
.textAlign(TextAlign.Start)
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
Text('This is the text content with textAlign set to End.')
.textAlign(TextAlign.End)
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
Text('TextOverflow').fontSize(9).fontColor(0xCCCCCC)
Text('This is the setting of textOverflow to none text content This is the setting of textOverflow to none text content.') // Set the display mode when the text is too long.
Text('TextOverflow+maxLines').fontSize(9).fontColor(0xCCCCCC)
// Clip the text when the value of maxLines is exceeded.
Text('This is the setting of textOverflow to Clip text content This is the setting of textOverflow to None text content. This is the setting of textOverflow to Clip text content This is the setting of textOverflow to None text content.')
.textOverflow({ overflow: TextOverflow.None }) .textOverflow({ overflow: TextOverflow.None })
.fontSize(12).border({ width: 1 }).padding(10) .maxLines(1)
Text('This is the setting of textOverflow to Clip text content This is the setting of textOverflow to Clip text content.') .fontSize(12)
.textOverflow({ overflow: TextOverflow.Clip }) .border({ width: 1 })
.maxLines(1).fontSize(12).border({ width: 1 }).padding(10) .padding(10)
Text('This is set textOverflow to Ellipsis text content This is set textOverflow to Ellipsis text content.'.split('').join('\u200B'))
// Show an ellipsis (...) when the value of maxLines is exceeded.
Text('This is set textOverflow to Ellipsis text content This is set textOverflow to Ellipsis text content.'.split('')
.join('\u200B'))
.textOverflow({ overflow: TextOverflow.Ellipsis }) .textOverflow({ overflow: TextOverflow.Ellipsis })
.maxLines(1).fontSize(12).border({ width: 1 }).padding(10) .maxLines(1)
.fontSize(12)
.border({ width: 1 })
.padding(10)
Text('decoration').fontSize(9).fontColor(0xCCCCCC) Text('lineHeight').fontSize(9).fontColor(0xCCCCCC)
Text('This is the text content with the decoration set to Underline and the color set to Red.') Text('This is the text with the line height set. This is the text with the line height set.')
.decoration({ type: TextDecorationType.Underline, color: Color.Red })
.fontSize(12).border({ width: 1 }).padding(10)
Text('This is the text content with the decoration set to LineThrough and the color set to Red.')
.decoration({ type: TextDecorationType.LineThrough, color: Color.Red })
.fontSize(12).border({ width: 1 }).padding(10) .fontSize(12).border({ width: 1 }).padding(10)
Text('This is the text content with the decoration set to Overline and the color set to Red.') Text('This is the text with the line height set. This is the text with the line height set.')
.decoration({ type: TextDecorationType.Overline, color: Color.Red })
.fontSize(12).border({ width: 1 }).padding(10) .fontSize(12).border({ width: 1 }).padding(10)
.lineHeight(20)
}.height(600).width(350).padding({ left: 35, right: 35, top: 35 }) }.height(600).width(350).padding({ left: 35, right: 35, top: 35 })
} }
} }
``` ```
![textExp1](figures/textExp1.png)
![en-us_image_0000001257138337](figures/en-us_image_0000001257138337.gif) ### Example 2
Example of using **decoration**, **baselineOffset**, **letterSpacing**, and **textCase**:
```ts ```ts
// xxx.ets
@Entry @Entry
@Component @Component
struct TextExample2 { struct TextExample2 {
build() { build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) {
Text('decoration').fontSize(9).fontColor(0xCCCCCC)
Text('This is the text content with the decoration set to LineThrough and the color set to Red.')
.decoration({
type: TextDecorationType.LineThrough,
color: Color.Red
})
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
Text('This is the text content with the decoration set to Overline and the color set to Red.')
.decoration({
type: TextDecorationType.Overline,
color: Color.Red
})
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
Text('This is the text content with the decoration set to Underline and the color set to Red.')
.decoration({
type: TextDecorationType.Underline,
color: Color.Red
})
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
// Set the text baseline offset.
Text('baselineOffset').fontSize(9).fontColor(0xCCCCCC)
Text('This is the text content with baselineOffset 0.')
.baselineOffset(0)
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
Text('This is the text content with baselineOffset 30.')
.baselineOffset(30)
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
Text('This is the text content with baselineOffset -20.')
.baselineOffset(-20)
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
// Set the letter spacing.
Text('letterSpacing').fontSize(9).fontColor(0xCCCCCC)
Text('This is the text content with letterSpacing 0.')
.letterSpacing(0)
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
Text('This is the text content with letterSpacing 3.')
.letterSpacing(3)
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
Text('This is the text content with letterSpacing -1.')
.letterSpacing(-1)
.fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
Text('textCase').fontSize(9).fontColor(0xCCCCCC) Text('textCase').fontSize(9).fontColor(0xCCCCCC)
Text('This is the text content with textCase set to Normal.') Text('This is the text content with textCase set to Normal.')
.textCase(TextCase.Normal) .textCase(TextCase.Normal)
.fontSize(12).border({ width: 1 }).padding(10).width('100%') .fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
// Display the text in lowercase.
Text('This is the text content with textCase set to LowerCase.') Text('This is the text content with textCase set to LowerCase.')
.textCase(TextCase.LowerCase) .textCase(TextCase.LowerCase)
.fontSize(12).border({ width: 1 }).padding(10).width('100%') .fontSize(12)
.border({ width: 1 })
.padding(10)
.width('100%')
// Display the text in uppercase.
Text('This is the text content with textCase set to UpperCase.') Text('This is the text content with textCase set to UpperCase.')
.textCase(TextCase.UpperCase) .textCase(TextCase.UpperCase)
.fontSize(12).border({ width: 1 }).padding(10) .fontSize(12).border({ width: 1 }).padding(10)
Text('textAlign').fontSize(9).fontColor(0xCCCCCC)
Text('This is the text content with textAlign set to Center.')
.textAlign(TextAlign.Center)
.fontSize(12).border({ width: 1 }).padding(10).width('100%')
Text('This is the text content with textAlign set to Start.')
.textAlign(TextAlign.Start)
.fontSize(12).border({ width: 1 }).padding(10).width('100%')
Text('This is the text content with textAlign set to End.')
.textAlign(TextAlign.End)
.fontSize(12).border({ width: 1 }).padding(10).width('100%')
Text('baselineOffset').fontSize(9).fontColor(0xCCCCCC)
Text('This is the text content with baselineOffset set to 10.')
.baselineOffset(10).fontSize(12).border({ width: 1 }).padding(10).width('100%')
Text('This is the text content with baselineOffset set to 30.')
.baselineOffset(30).fontSize(12).border({ width: 1 }).padding(10).width('100%')
Text('This is the text content with baselineOffset set to -10.')
.baselineOffset(-10).fontSize(12).border({ width: 1 }).padding(10).width('100%')
}.height(700).width(350).padding({ left: 35, right: 35, top: 35 }) }.height(700).width(350).padding({ left: 35, right: 35, top: 35 })
} }
} }
``` ```
![textExp1](figures/textExp2.png)
![en-us_image_0000001257058391](figures/en-us_image_0000001257058391.gif)
en/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md
浏览文件 @ e20d2376
# Popup Control # Popup Control
You can bind a popup to a component, specifying its content, interaction logic, and display status.
> **NOTE** > **NOTE**
> >
> This attribute is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. > This attribute is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
## Required Permissions
None
## APIs ## APIs
| Name | Type | Default Value | Description | | Name | Type | Description |
| -------- | -------- | -------- | -------- | | ---------- | ------------------------------------- | --------------------------------------- |
| bindPopup | show:&nbsp;boolean,<br/>popup:&nbsp;PopupOptions\|&nbsp;CustomPopupOptions<sup>8+</sup> | - | Binds the popup to the component.<br/>**show**: whether to display the popup on the creation page by default. The default value is **false**.<br/>**popup**: parameters of the current popup. | | bindPopup | show: boolean,<br>popup: [PopupOptions](#popupoptions) \| [CustomPopupOptions](#custompopupoptions8)<sup>8+</sup> | Binds a popup to the component.<br>**show**: whether to show the popup. The default value is **false**, indicating that the popup is hidden.<br>**popup**: parameters of the popup.|
## PopupOptions ## PopupOptions
| Name | Type | Mandatory | Default Value | Description | | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | -------- | | -------------------------| ------------------------------------------------| -----| ----------------------------------------- |
| message | string | Yes | - | Content of the popup message. | | 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**. | | placementOnTop | boolean | No | Whether to display the popup above the component. The default value is **false**. |
| primaryButton | {<br/>value: string,<br/>action: () =&gt; void<br/>} | No | - | First button.<br/>**value**: text of the primary button in the popup.<br/>**action**: callback function for clicking the primary button. | | primaryButton | {<br>value: string,<br>action: () =&gt; void<br>} | No | Primary button.<br>**value**: text of the primary button in the popup.<br>**action**: callback for clicking the primary button.|
| secondaryButton | {<br/>value: string,<br/>action: () =&gt; void<br/>} | No | - | Second button.<br/>**value**: text of the secondary button in the popup.<br/>**action**: callback function for clicking the secondary button. | | secondaryButton | {<br>value: string,<br>action: () =&gt; void<br>} | No | Secondary button.<br>**value**: text of the secondary button in the popup.<br>**action**: callback for clicking the secondary button.|
| onStateChange | (event:{isVisible:&nbsp;boolean })&nbsp;=&gt;&nbsp;void | No | - | Callback for the popup status change event.<br>**isVisible**: visibility of the popup. | | onStateChange | (event: { isVisible: boolean }) =&gt; void | No | Callback for the popup status change event. The parameter **isVisible** indicates whether the popup is visible. |
## CustomPopupOptions<sup>8+</sup> ## CustomPopupOptions<sup>8+</sup>
| Name | Type | Mandatory | Default Value | Description |
| ------------- | ---------------------------------------------- | ---- | ---------------- | ------------------------------------------------------------ |
| builder | [CustomBuilder](ts-types.md#custombuilder8) | Yes | - | Builder of the tooltip content. |
| placement | [Placement](ts-appendix-enums.md#placement8) | 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 | [ResourceColor](ts-types.md#resourcecolor) | No | - | Color of the tooltip mask. |
| popupColor | [ResourceColor](ts-types.md#resourcecolor) | 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 |(event:{isVisible:&nbsp;boolean })&nbsp;=&gt;&nbsp;void | No | - | Callback for the popup status change event. The parameter **isVisible** indicates the visibility of the popup. |
| Name | Type | Mandatory | Description |
| -------------------------| ------------------------- | ---- | ---------------------------------------------------- |
| builder | [CustomBuilder](ts-types.md#custombuilder8) | Yes | Popup builder. |
| placement | [Placement](ts-appendix-enums.md#placement8) | No | Preferred position of the popup. If the set position is insufficient for holding the popup, it will be automatically adjusted.<br>Default value: **Placement.Bottom** |
| maskColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the popup mask. |
| popupColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the popup. |
| enableArrow | boolean | No | Whether to display an arrow.<br>Since API version 9, if the location set for the popup arrow is not large enough, the arrow will not be displayed. For example, if **placement** is set to **Left** and the popup height is less than the arrow width (32 vp), the arrow will not be displayed.<br>Default value: **true**|
| autoCancel | boolean | No | Whether to automatically close the popup when an operation is performed on the page.<br>Default value: **true** |
| onStateChange | (event: { isVisible: boolean }) =&gt; void | No | Callback for the popup status change event. The parameter **isVisible** indicates whether the popup is visible.|
## Example ## Example
```ts ```ts
// xxx.ets // xxx.ets
@Entry @Entry
@Component @Component
struct PopupExample { struct PopupExample {
@State noHandlePopup: boolean = false
@State handlePopup: boolean = false @State handlePopup: boolean = false
@State customPopup: boolean = false @State customPopup: boolean = false
// Popup builder
@Builder popupBuilder() { @Builder popupBuilder() {
Row({ space: 2 }) { Row({ space: 2 }) {
Image('/resource/ic_public_thumbsup.svg').width(24).height(24).margin({ left: -5 }) Image($r("app.media.image")).width(24).height(24).margin({ left: -5 })
Text('Custom Popup').fontSize(10) Text('Custom Popup').fontSize(10)
}.width(100).height(50).backgroundColor(Color.White) }.width(100).height(50).padding(5)
} }
build() { build() {
Flex({ direction: FlexDirection.Column }) { Flex({ direction: FlexDirection.Column }) {
Button('no handle popup') // PopupOptions for setting the popup
.onClick(() => { Button('PopupOptions')
this.noHandlePopup = !this.noHandlePopup
})
.bindPopup(this.noHandlePopup, {
message: 'content1 content1',
placementOnTop: false,
onStateChange: (e) => {
console.info(e.isVisible.toString())
if (!e.isVisible) {
this.noHandlePopup = false
}
}
})
.position({ x: 100, y: 50 })
Button('with handle popup')
.onClick(() => { .onClick(() => {
this.handlePopup = !this.handlePopup this.handlePopup = !this.handlePopup
}) })
.bindPopup(this.handlePopup, { .bindPopup(this.handlePopup, {
message: 'content2 content2', message: 'This is a popup with PopupOptions',
placementOnTop: true, placementOnTop: true,
primaryButton: { primaryButton: {
value: 'ok', value: 'confirm',
action: () => { action: () => {
this.handlePopup = !this.handlePopup this.handlePopup = !this.handlePopup
console.info('secondaryButton click') console.info('confirm Button click')
}
},
// Secondary button
secondaryButton: {
value: 'cancel',
action: () => {
this.handlePopup = !this.handlePopup;
console.info('cancel Button click')
} }
}, },
onStateChange: (e) => { onStateChange: (e) => {
console.info(e.isVisible.toString()) console.info(e.isVisible.toString())
if (!e.isVisible) {
this.handlePopup = false
}
} }
}) })
.position({ x: 100, y: 200 }) .position({ x: 100, y: 50 })
Button('custom popup') // CustomPopupOptions for setting the popup
Button('CustomPopupOptions')
.onClick(() => { .onClick(() => {
this.customPopup = !this.customPopup this.customPopup = !this.customPopup
}) })
.bindPopup(this.customPopup, { .bindPopup(this.customPopup, {
builder: this.popupBuilder, builder: this.popupBuilder,
placement: Placement.Bottom, placement: Placement.Top,
maskColor: 0x33000000, maskColor: 0x33000000,
popupColor: Color.White, popupColor: Color.Yellow,
enableArrow: true, enableArrow: true,
onStateChange: (e) => { onStateChange: (e) => {
if (!e.isVisible) { if (!e.isVisible) {
...@@ -114,10 +106,10 @@ struct PopupExample { ...@@ -114,10 +106,10 @@ struct PopupExample {
} }
} }
}) })
.position({ x: 100, y: 350 }) .position({ x: 80, y: 200 })
}.width('100%').padding({ top: 5 }) }.width('100%').padding({ top: 5 })
} }
} }
``` ```
![en-us_image_0000001212058458](figures/en-us_image_0000001212058458.gif) ![figures/popup.gif](figures/popup.gif)
en/application-dev/reference/arkui-ts/ts-universal-events-click.md
浏览文件 @ e20d2376
# Click Event # Click Event
A click event is triggered when a component is clicked.
> **NOTE** > **NOTE**
> >
> This event is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. > The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
## Required Permissions
None
## Events ## Events
| Name | Bubbling Supported | Description | | Name | Bubbling Supported| Description |
| -------- | -------- | -------- | | ---------------------------------------- | ---- | --------------------------------- |
| onClick(callback: (event?: ClickEvent) =&gt; void) | No | Called when a click event occurs. For details about the event parameters, see [ClickEvent](#clickevent). | | onClick(event: (event?: ClickEvent) =&gt; void) | No | Called when a click event occurs. For details about **event**, see **ClickEvent**.|
## ClickEvent ## ClickEvent
| Name | Type | Description |
| Name | Type | Description | | ------------------- | ------------------------------------ | -------------------------------------------------------- |
| -------- | -------- | -------- | | screenX | number | X coordinate of the click relative to the upper left corner of the application window. |
| screenX | number | X coordinate of the click relative to the left edge of the screen. | | screenY | number | Y coordinate of the click relative to the upper left corner of the application window. |
| screenY | number | Y coordinate of the click relative to the upper edge of the screen. | | x | number | X coordinate of the click relative to the upper left corner of the component being clicked. |
| x | number | X coordinate of the click relative to the left edge of the component being clicked. | | y | number | Y coordinate of the click relative to the upper left corner of the component being clicked. |
| y | number | Y coordinate of the click relative to the upper edge of the component being clicked. | | timestamp<sup>8+</sup> | number | Timestamp of the event. It is interval between the time when the event is triggered and the time when the system starts, in nanoseconds.|
| target<sup>8+</sup> | [EventTarget](#eventtarget8) | Target element that is clicked. | | target<sup>8+</sup> | [EventTarget](#eventtarget8) | Display area of the object that triggers the event.|
| timestamp | number | Timestamp of the event. | | source<sup>8+</sup> | [SourceType](ts-gesture-settings.md#sourcetype)| Event input device.|
## EventTarget<sup>8+</sup> ## EventTarget<sup>8+</sup>
| Name | Type | Description | | Name | Type | Description |
| -------- | -------- | -------- | | ---- | ------------------------- | ---------- |
| area | [Area](#area8) | Area information of the target element.| | area | [Area](ts-types.md#area8) | Area information of the target element.|
## Area<sup>8+</sup>
| Name | Type | Description |
| -------- | -------- | -------- |
| width | number | Width of the target element, in vp. |
| height | number | Height of the target element, in vp. |
| position | [Position](#position8) | Position of the upper left corner of the target element relative to that of the parent element. |
| globalPosition | [Position](#position8) | Position of the upper left corner of the target element relative to that of the page. |
## Position<sup>8+</sup>
| Name | Type | Description |
| -------- | -------- | -------- |
| x | number | X-coordinate, in vp. |
| y | number | Y-coordinate, in vp. |
## Example ## Example
```ts ```ts
// xxx.ets // xxx.ets
@Entry @Entry
...@@ -64,15 +43,25 @@ struct ClickExample { ...@@ -64,15 +43,25 @@ struct ClickExample {
build() { build() {
Column() { Column() {
Button('Click').backgroundColor(0x2788D9).width(100).height(40) Row({ space: 20 }) {
.onClick((event: ClickEvent) => { Button('Click').width(100).height(40)
console.info(this.text = 'Click Point:' + '\n screenX:' + event.screenX + '\n screenY:' + event.screenY .onClick((event: ClickEvent) => {
+ '\n x:' + event.x + '\n y:' + event.y + '\ntarget:' + '\n component globalPos:(' this.text = 'Click Point:' + '\n screenX:' + event.screenX + '\n screenY:' + event.screenY
+ event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\n width:' + '\n x:' + event.x + '\n y:' + event.y + '\ntarget:' + '\n component globalPos:('
+ event.target.area.width + '\n height:' + event.target.area.height) + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\n width:'
}) + event.target.area.width + '\n height:' + event.target.area.height + '\ntimestamp' + event.timestamp;
Text(this.text).padding(15) })
}.height(350).width('100%').padding(10) Button('Click').width(200).height(50)
.onClick((event: ClickEvent) => {
this.text = 'Click Point:' + '\n screenX:' + event.screenX + '\n screenY:' + event.screenY
+ '\n x:' + event.x + '\n y:' + event.y + '\ntarget:' + '\n component globalPos:('
+ event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\n width:'
+ event.target.area.width + '\n height:' + event.target.area.height + '\ntimestamp' + event.timestamp;
})
}.margin(20)
Text(this.text).margin(15)
}.width('100%')
} }
} }
``` ```
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或