Skip to content

D
Docs

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

通知 161
Star 293
Fork 28
D
Docs
提交 e2c72f5a 编写于 作者: E ester.zhou
浏览文件
操作

update docs 

Signed-off-by: Nester.zhou <ester.zhou@huawei.com>
上级 fe4b7371
隐藏空白更改
内联 并排
Showing with 695 addition and 650 deletion
en/application-dev/reference/apis/js-apis-uitest.md
浏览文件 @ e2c72f5a
# UiTest
>**NOTE**
>**NOTE**<br>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 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.
## Modules to Import
......@@ -13,46 +12,27 @@ import {UiDriver,BY,MatchPattern} from '@ohos.uitest'
## By
The UiTest framework provides a wide range of UI component feature description APIs in the **By** class to filter and match components.
The API capabilities provided by the **By** class exhibit the following features:
The UiTest framework provides a wide range of UI component feature description APIs in the **By** class to filter and match components.<br>
The API capabilities provided by the **By** class exhibit the following features: <br>1. Allow one or more attributes as the match conditions. For example, you can specify both the **text** and **id** attributes to find the target component. <br>2. Provide multiple match patterns for component attributes. <br>3. Support absolute positioning and relative positioning for components. APIs such as [By.isBefore](#byisbefore) and [By.isAfter](#byisafter) can be used to specify the features of adjacent components to assist positioning. <br>All APIs provided in the **By** class are synchronous. You are advised to use the static constructor **BY** to create a **By** object in chain mode.
- Allows one or more attributes as the match conditions. For example, you can specify both the **text** and **id** attributes to find the target component.
- Provides multiple match patterns for component attributes.
- Supports absolute positioning and relative positioning for components. APIs such as **isBefore** and **isAfter** can be used to specify the features of adjacent components to assist positioning.
All APIs provided in the **By** class are synchronous. You are advised to use the static constructor **BY** to create a **By** object in chain mode, for example, **BY.text('123').type('button')**.
### enum MatchPattern
Enumerates the match patterns supported for component attributes.
**System capability**: SystemCapability.Test.UiTest
| Name | Value | Description |
| ----------- | ---- | ------------ |
| EQUALS | 0 | Equal to the given value. |
| CONTAINS | 1 | Contain the given value. |
| STARTS_WITH | 2 | Start with the given value.|
| ENDS_WITH | 3 | End with the given value.|
```js
BY.text('123').type('button')
```
### By.text
text(txt:string,pattern?:MatchPattern):By
text(txt: string, pattern?: MatchPattern): By
Specifies the text attribute of the target component. Multiple match patterns are supported.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------ | ---- | ---------------------------------- |
| txt | string | Yes | Component text, used to match the target component.|
| pattern | MatchPattern | No | Match pattern. The default value is **EQUALS**. |
| Name | Type | Mandatory| Description |
| ------- | ------------ | ---- | ------------------------------------------------- |
| txt | string | Yes | Component text, used to match the target component. |
| pattern | MatchPattern | No | Match pattern. The default value is [EQUALS](#matchpattern).|
**Return value**
......@@ -62,324 +42,291 @@ Specifies the text attribute of the target component. Multiple match patterns ar
**Example**
```
let by = BY.text('123') // Use the static constructor BY to create a By object and specify the text attribute
of the target component.
```js
let by = BY.text('123') // Use the static constructor BY to create a By object and specify the text attribute of the target component.
```
### By.key
key(key:string):By;
key(key: string): By
Specifies the key attribute of the target component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | --------------- |
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ----------------- |
| key | string | Yes | Component key.|
**Return value**
| Type| Description |
| ---- | -------------- |
| Type| Description |
| ---- | ---------------- |
| By | Returns the **By** object itself.|
**Example**
```
let by = BY.key('123') // Use the static constructor BY to create a By object and specify the key attribute
of the target component.
```js
let by = BY.key('123') // Use the static constructor BY to create a By object and specify the key attribute of the target component.
```
### By.id
id(id:number):By;
Specifies the ID property of the target component.
id(id: number): By
**Required permissions**: none
Specifies the ID attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------ |
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ---------------- |
| id | number | Yes | Component ID.|
**Return value**
| Type| Description |
| ---- | -------------- |
| Type| Description |
| ---- | ---------------- |
| By | Returns the **By** object itself.|
**Example**
```
let by = BY.id(123) // Use the static constructor BY to create a By object and specify the ID attribute
of the target component.
```js
let by = BY.id(123) // Use the static constructor BY to create a By object and specify the id attribute of the target component.
```
### By.type
type(tp:string):By;
Specifies the type property of the target component.
type(tp: string): By
**Required permissions**: none
Specifies the type attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------ |
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------- |
| tp | string | Yes | Component type.|
**Return value**
| Type| Description |
| ---- | -------------- |
| Type| Description |
| ---- | ---------------- |
| By | Returns the **By** object itself.|
**Example**
```
let by = BY.type('button') // Use the static constructor BY to create a By object and specify the type attribute
of the target component.
```js
let by = BY.type('button') // Use the static constructor BY to create a By object and specify the type attribute of the target component.
```
### By.clickable
clickable(b?:bool):By;
clickable(b?: bool): By
Specifies the clickable attribute of the target component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------------------ |
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | -------------------------------- |
| b | bool | No | Clickable status of the target component. The default value is **true**.|
**Return value**
| Type| Description |
| ---- | -------------- |
| Type| Description |
| ---- | ---------------- |
| By | Returns the **By** object itself.|
**Example**
```
let by = BY.clickable(true) // Use the static constructor BY to create a By object and specify the clickable attribute
of the target component.
```js
let by = BY.clickable(true) // Use the static constructor BY to create a By object and specify the clickable status attribute of the target component.
```
### By.scrollable
scrollable(b?:bool):By;
Specifies the scrollable attribute of the target component.
scrollable(b?: bool): By
**Required permissions**: none
Specifies the scrollable status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | -------------------------- |
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ---------------------------- |
| b | bool | No | Scrollable status of the target component. The default value is **true**.|
**Return value**
| Type| Description |
| ---- | -------------- |
| Type| Description |
| ---- | ---------------- |
| By | Returns the **By** object itself.|
**Example**
```
let by = BY.scrollable(true) // Use the static constructor BY to create a By object and specify the scrollable attribute
of the target component.
```js
let by = BY.scrollable(true) // Use the static constructor BY to create a By object and specify the scrollable status attribute of the target component.
```
### By.enabled
enabled(b?:bool):By;
enabled(b?: bool): By
Specifies the enable attribute of the target component.
**Required permissions**: none
Specifies the enabled status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ---------------------------- |
| b | bool | No | Enable status of the target component. The default value is **true**.|
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------------------ |
| b | bool | No | Enabled status of the target component. The default value is **true**.|
**Return value**
| Type| Description |
| ---- | -------------- |
| Type| Description |
| ---- | ---------------- |
| By | Returns the **By** object itself.|
**Example**
```
let by = BY.enabled(true) // Use the static constructor BY to create a By object and specify the enable attribute
of the target component.
```js
let by = BY.enabled(true) // Use the static constructor BY to create a By object and specify the enabled status attribute of the target component.
```
### By.focused
focused(b?:bool):By;
focused(b?: bool): By
Specifies the focused attribute of the target component.
**Required permissions**: none
Specifies the focused status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------------ |
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | -------------------------- |
| b | bool | No | Focused status of the target component. The default value is **true**.|
**Return value**
| Type| Description |
| ---- | -------------- |
| Type| Description |
| ---- | ---------------- |
| By | Returns the **By** object itself.|
**Example**
```
let by = BY.enabled(true) // Use the static constructor BY to create a By object and specify the focused attribute
of the target component.
```js
let by = BY.focused(true) // Use the static constructor BY to create a By object and specify the focused status attribute of the target component.
```
### By.selected
selected(b?:bool):By;
Specifies the selected attribute of the target component.
selected(b?: bool): By
**Required permissions**: none
Specifies the selected status attribute of the target component.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------------------ |
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | -------------------------------- |
| b | bool | No | Selected status of the target component. The default value is **true**.|
**Return value**
| Type| Description |
| ---- | -------------- |
| Type| Description |
| ---- | ---------------- |
| By | Returns the **By** object itself.|
**Example**
```
let by = BY.selected(true) // Use the static constructor BY to create a By object and specify the selected attribute
of the target component.
```js
let by = BY.selected(true) // Use the static constructor BY to create a By object and specify the selected status attribute of the target component.
```
### By.isBefore
isBefore(by:By):By;
isBefore(by: By): By
Specifies the attributes of the component before which the target component is located.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | -------------- |
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ---------------- |
| by | By | Yes | Attributes of the component before which the target component is located.|
**Return value**
| Type| Description |
| ---- | -------------- |
| Type| Description |
| ---- | ---------------- |
| By | Returns the **By** object itself.|
**Example**
```
let by = BY.isBefore(BY.text('123')) // Use the static constructor BY to create a By object and specify the attributes
of the component before which the target component is located.
```js
let by = BY.isBefore(BY.text('123')) // Use the static constructor BY to create a By object and specify the attributes of the component before which the target component is located.
```
### By.isAfter
isAfter(by:By):By;
isAfter(by: By): By
Specifies the attributes of the component after which the target component is located.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | -------------- |
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ---------------- |
| by | By | Yes | Attributes of the component before which the target component is located.|
**Return value**
| Type| Description |
| ---- | -------------- |
| Type| Description |
| ---- | ---------------- |
| By | Returns the **By** object itself.|
**Example**
```
let by = BY.isAfter(BY.text('123')) // Use the static constructor BY to create a By object and specify the attributes
of the component after which the target component is located.
```js
let by = BY.isAfter(BY.text('123')) // Use the static constructor BY to create a By object and specify the attributes of the component after which the target component is located.
```
## UiComponent
In **UiTest**, the **UiComponent** class represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection.
All APIs provided by this class use a promise to return the result and must be invoked using **await**.
All APIs provided in this class use a promise to return the result and must be invoked using **await**.
### UiComponent.click
click():Promise\<void>;
click(): Promise\<void>
Clicks this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
......@@ -389,37 +336,33 @@ async function demo() {
### UiComponent.doubleClick
doubleClick():Promise\<void>;
doubleClick(): Promise\<void>
Double-clicks this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
await buttont.doubleClick()
await button.doubleClick()
}
```
### UiComponent.longClick
longClick():Promise\<void>;
longClick(): Promise\<void>
Long-clicks this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
......@@ -429,23 +372,21 @@ async function demo() {
### UiComponent.getId
getId():Promise\<number>;
getId(): Promise\<number>
Obtains the ID of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------- | ------------------------- |
| Promise\<number>; | Promise used to return the component ID.|
| Type | Description |
| ---------------- | ------------------------------- |
| Promise\<number> | Promise used to return the ID of the component.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
......@@ -455,23 +396,21 @@ async function demo() {
### UiComponent.getKey
getKey():Promise\<string>;
getKey(): Promise\<string>
Obtains the key of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------- | -------------------------- |
| Promise\<string>; | Promise used to return the component key.|
| Type | Description |
| ---------------- | ------------------------------ |
| Promise\<string> | Promise used to return the key of the component.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
......@@ -481,23 +420,21 @@ async function demo() {
### UiComponent.getText
getText():Promise\<string>;
getText(): Promise\<string>
Obtains the text information of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------- | ------------------------------- |
| Promise\<string>; | Promise used to return the text information of the component.|
| Type | Description |
| ---------------- | --------------------------------- |
| Promise\<string> | Promise used to return the text information of the component.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
......@@ -507,23 +444,21 @@ async function demo() {
### UiComponent.getType
getType():Promise\<string>;
getType(): Promise\<string>
Obtains the type of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ---------------- | ------------------------------- |
| Promise\<string>; | Promise used to return the component type.|
| Type | Description |
| ---------------- | ----------------------------- |
| Promise\<string> | Promise used to return the type of the component.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
......@@ -533,23 +468,21 @@ async function demo() {
### UiComponent.isClickable
isClickable():Promise\<bool>;
isClickable(): Promise\<bool>
Obtains the clickable status of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| -------------- | ----------------------------------- |
| Promise\<bool>; | Promise used to return the clickable status of the component.|
| Type | Description |
| -------------- | ------------------------------------- |
| Promise\<bool> | Promise used to return the clickable status of the component.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
......@@ -564,23 +497,21 @@ async function demo() {
### UiComponent.isScrollable
isScrollable():Promise\<bool>;
isScrollable(): Promise\<bool>
Obtains the scrollable status of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| -------------- | ----------------------------------- |
| Promise\<bool>; | Promise used to return the scrollable status of the component.|
| Type | Description |
| -------------- | ------------------------------------- |
| Promise\<bool> | Promise used to return the scrollable status of the component.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let scrollBar = await driver.findComponent(BY.scrollable(true))
......@@ -596,23 +527,21 @@ async function demo() {
### UiComponent.isEnabled
isEnabled():Promise\<bool>;
Obtains the enable status of this component.
isEnabled(): Promise\<bool>
**Required permissions**: none
Obtains the enabled status of this component.
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\<bool>; | Promise used to return the enable status of the component.|
| Type | Description |
| -------------- | ------------------------------- |
| Promise\<bool> | Promise used to return the enabled status of the component.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
......@@ -628,23 +557,21 @@ async function demo() {
### UiComponent.isFocused
isFocused():Promise\<bool>;
isFocused(): Promise\<bool>
Obtains the focused status of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| -------------- | --------------------------------- |
| Promise\<bool>; | Promise used to return the focused status of the component.|
| Type | Description |
| -------------- | ----------------------------------- |
| Promise\<bool> | Promise used to return the focused status of the component.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
......@@ -659,23 +586,21 @@ async function demo() {
### UiComponent.isSelected
isSelected():Promise\<bool>;
isSelected(): Promise\<bool>
Obtains the selected status of this component.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| -------------- | ----------------------------------- |
| Promise\<bool>; | Promise used to return the selected status of the component.|
| Type | Description |
| -------------- | -------------------- |
| Promise\<bool> | Promise used to return the selected status of the component.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
......@@ -690,37 +615,33 @@ async function demo() {
### UiComponent.inputText
inputText(text: string):Promise\<void>;
inputText(text: string): Promise\<void>
Enters text into this component (available for text boxes).
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------- |
| text | string | Yes | Text to be entered to the component.|
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ---------------- |
| text | string | Yes | Text to enter.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
await button.inputText('next page')
let text = await driver.findComponent(BY.text('hello world'))
await text.inputText('123')
}
```
### UiComponent.scrollSearch
scrollSearch(by:By):Promise\<UiComponent>;
scrollSearch(by: By): Promise\<UiComponent>
Scrolls on this component to search for the target component (available for lists).
**Required permissions**: none
Scrolls on this component to search for the target component (applicable to component that support scrolling, such as **\<List>**).
**System capability**: SystemCapability.Test.UiTest
......@@ -732,16 +653,16 @@ Scrolls on this component to search for the target component (available for list
**Return value**
| Type | Description |
| --------------------- | ----------------------------------- |
| Promise\<UiComponent>; | Promise used to return the target component.|
| Type | Description |
| --------------------- | ------------------------------------- |
| Promise\<UiComponent> | Promise used to return the target component.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let scrollBar = await driver.findComponent(BY.scrollable(true))
let scrollBar = await driver.findComponent(BY.type('Scroll'))
let button = await scrollBar.scrollSearch(BY.text('next page'))
}
```
......@@ -753,23 +674,21 @@ All APIs provided by this class, except for **UiDriver.create()**, use a promise
### UiDriver.create
static create():UiDriver;
static create(): UiDriver
Creates a **UiDriver** object and returns the object created. This API is a static API.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Return value**
| Type | Description |
| ------- | ---------------------- |
| Type | Description |
| ------- | ------------------------ |
| UiDrive | Returns the **UiDriver** object created.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
}
......@@ -777,23 +696,21 @@ async function demo() {
### UiDriver.delayMs
delayMs(duration:number):Promise\<void>;
delayMs(duration: number): Promise\<void>
Delays this **UiDriver** object within the specified duration.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ---------- |
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ------------ |
| duration | number | Yes | Duration of time.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
await driver.delayMs(1000)
......@@ -802,29 +719,27 @@ async function demo() {
### UiDriver.findComponent
findComponent(by:By):Promise\<UiComponent>;
findComponent(by: By): Promise\<UiComponent>
Searches this **UiDriver** object for the target component that has the given attributes.
**Required permissions**: none
Searches this **UiDriver** object for the target component that matches the given attributes.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------ |
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | -------------------- |
| by | By | Yes | Attributes of the target component.|
**Return value**
| Type | Description |
| --------------------- | ------------------------------- |
| Promise\<UiComponent>; | Promise used to return the found component.|
| Type | Description |
| --------------------- | --------------------------------- |
| Promise\<UiComponent> | Promise used to return the found component.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.text('next page'))
......@@ -833,29 +748,27 @@ async function demo() {
### UiDriver.findComponents
findComponents(by:By):Promise\<Array\<UiComponent>>;
findComponents(by: By): Promise\<Array\<UiComponent>>
Searches this **UiDriver** object for all components that match the given attributes.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------ |
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | -------------------- |
| by | By | Yes | Attributes of the target component.|
**Return value**
| Type | Description |
| ---------------------------- | ------------------------------------- |
| Promise\<Array\<UiComponent>>; | Promise used to return a list of found components.|
| Type | Description |
| ----------------------------- | --------------------------------------- |
| Promise\<Array\<UiComponent>> | Promise used to return a list of found components.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
let buttonList = await driver.findComponents(BY.text('next page'))
......@@ -864,23 +777,21 @@ async function demo() {
### UiDriver.assertComponentExist
assertComponentExist(by:By):Promise\<void>;
assertComponentExist(by: By): Promise\<void>
Asserts that a component that matches the given attributes exists on the current page. If the component does not exist, the API throws a JS exception, causing the current test case to fail.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | ------------------ |
| Name| Type| Mandatory| Description |
| ------ | ---- | ---- | -------------------- |
| by | By | Yes | Attributes of the target component.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
await driver.assertComponentExist(BY.text('next page'))
......@@ -889,17 +800,15 @@ async function demo() {
### UiDriver.pressBack
pressBack():Promise\<void>;
pressBack(): Promise\<void>
Presses the Back button on this **UiDriver** object.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
await driver.pressBack()
......@@ -908,23 +817,21 @@ async function demo() {
### UiDriver.triggerKey
triggerKey(keyCode:number):Promise\<void>;
triggerKey(keyCode: number): Promise\<void>
Triggers the key of this **UiDriver** object that matches the given key code.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------ | ---- | --------- |
| Name | Type | Mandatory| Description |
| ------- | ------ | ---- | ------------- |
| keyCode | number | Yes | Key code.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
await driver.triggerKey(123)
......@@ -933,23 +840,22 @@ async function demo() {
### UiDriver.click
click(x:number,y:number):Promise\<void>;
click(x: number, y: number): Promise\<void>
Clicks a specific point of this **UiDriver** object based on the given coordinates.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------- | ---- | ------------------------------------------- |
| x,y | number,number | Yes | Coordinate information of a specific point in the (number,number) format.|
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | Yes | X coordinate of the target point.|
| y | number | Yes | Y coordinate of the target point.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
await driver.click(100,100)
......@@ -958,23 +864,22 @@ async function demo() {
### UiDriver.doubleClick
doubleClick(x:number,y:number):Promise\<void>;
doubleClick(x: number, y: number): Promise\<void>
Double-clicks a specific point of this **UiDriver** object based on the given coordinates.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------- | ---- | ------------------------------------------- |
| x,y | number,number | Yes | Coordinate information of a specific point in the (number,number) format.|
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | Yes | X coordinate of the target point.|
| y | number | Yes | Y coordinate of the target point.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
await driver.doubleClick(100,100)
......@@ -983,23 +888,22 @@ async function demo() {
### UiDriver.longClick
longClick(x:number,y:number):Promise\<void>;
longClick(x: number, y: number): Promise\<void>
Long-clicks a specific point of this **UiDriver** object based on the given coordinates.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------- | ---- | ------------------------------------------- |
| x,y | number,number | Yes | Coordinate information of a specific point in the (number,number) format.|
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | Yes | X coordinate of the target point.|
| y | number | Yes | Y coordinate of the target point.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
await driver.longClick(100,100)
......@@ -1008,24 +912,24 @@ async function demo() {
### UiDriver.swipe
swipe(startx:number,starty:number,endx:number,endy:number):Promise\<void>;
Swipes from the start point to the end point of this **UiDriver** object based on the given coordinates.
swipe(startx: number, starty: number, endx: number, endy: number): Promise\<void>
**Required permissions**: none
Swipes on this **UiDriver** object from the start point to the end point based on the given coordinates.
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| ------------- | ------------- | ---- | ------------------------------------------- |
| startx,starty | number,number | Yes | Coordinate information of the start point in the (number,number) format.|
| endx,endy | number,number | Yes | Coordinate information of the end point in the (number,number) format.|
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| startx | number | Yes | X coordinate of the start point.|
| starty | number | Yes | Y coordinate of the start point.|
| endx | number | Yes | X coordinate of the end point.|
| endy | number | Yes | Y coordinate of the end point.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
await driver.swipe(100,100,200,200)
......@@ -1034,25 +938,44 @@ async function demo() {
### UiDriver.screenCap
screenCap(savePath:string):Promise\<bool>;
screenCap(savePath: string): Promise\<bool>
Captures the current screen of this **UiDriver** object and saves it as a PNG image to the given save path.
**Required permissions**: none
**System capability**: SystemCapability.Test.UiTest
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ------------ |
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | -------------- |
| savePath | string | Yes | File save path.|
**Return value**
| Type | Description |
| -------------- | -------------------------------------- |
| Promise\<bool> | Promise used to return the operation result. The value **true** means that the operation is successful.|
**Example**
```
```js
async function demo() {
let driver = UiDriver.create()
await driver.screenCap('/local/tmp/')
}
```
## MatchPattern
Enumerates the match patterns supported for component attributes.
**System capability**: SystemCapability.Test.UiTest
| Name | Value | Description |
| ----------- | ---- | -------------- |
| EQUALS | 0 | Equal to the given value. |
| CONTAINS | 1 | Containing the given value. |
| STARTS_WITH | 2 | Starting from the given value.|
| ENDS_WITH | 3 | Ending with the given value.|
###
en/application-dev/reference/apis/js-apis-wallpaper.md
浏览文件 @ e2c72f5a
# Wallpaper
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br>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.
>
> **NOTE**<br>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
......@@ -29,18 +28,18 @@ Defines the wallpaper type.
getColors(wallpaperType: WallpaperType, callback: AsyncCallback&lt;Array&lt;RgbaColor&gt;&gt;): void
Obtains the main color information of the wallpaper of a specified type.
Obtains the main color information of the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| callback | AsyncCallback&lt;Array&lt;[RgbaColor](#rgbacolor)&gt;&gt; | Yes | Callback used to return the main color information of the wallpaper. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| callback | AsyncCallback&lt;Array&lt;[RgbaColor](#rgbacolor)&gt;&gt; | Yes | Callback used to return the main color information of the wallpaper. |
**Example**
- Example
```js
wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (error) {
......@@ -56,7 +55,7 @@ Obtains the main color information of the wallpaper of a specified type.
getColors(wallpaperType: WallpaperType): Promise&lt;Array&lt;RgbaColor&gt;&gt;
Obtains the main color information of the wallpaper of a specified type.
Obtains the main color information of the wallpaper of the specified type. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -74,20 +73,20 @@ Obtains the main color information of the wallpaper of a specified type.
**Example**
```js
wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getColors.`);
}).catch((error) => {
console.error(`failed to getColors because: ` + JSON.stringify(error));
});
```
```js
wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getColors.`);
}).catch((error) => {
console.error(`failed to getColors because: ` + JSON.stringify(error));
});
```
## wallpaper.getId
getId(wallpaperType: WallpaperType, callback: AsyncCallback&lt;number&gt;): void
Obtains the ID of the wallpaper of the specified type.
Obtains the ID of the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -100,25 +99,26 @@ Obtains the ID of the wallpaper of the specified type.
**Example**
```js
wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (error) {
console.error(`failed to getId because: ` + JSON.stringify(error));
return;
}
console.log(`success to getId: ` + JSON.stringify(data));
});
```
```js
wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (error) {
console.error(`failed to getId because: ` + JSON.stringify(error));
return;
}
console.log(`success to getId: ` + JSON.stringify(data));
});
```
## wallpaper.getId
getId(wallpaperType: WallpaperType): Promise&lt;number&gt;
Obtains the ID of the wallpaper of the specified type.
Obtains the ID of the wallpaper of the specified type. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
| Name | Type | Mandatory | Description |
......@@ -133,20 +133,20 @@ Obtains the ID of the wallpaper of the specified type.
**Example**
```js
wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getId: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to getId because: ` + JSON.stringify(error));
});
```
```js
wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getId: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to getId because: ` + JSON.stringify(error));
});
```
## wallpaper.getMinHeight
getMinHeight(callback: AsyncCallback&lt;number&gt;): void
Obtains the minimum height of the wallpaper.
Obtains the minimum height of this wallpaper. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -158,25 +158,26 @@ Obtains the minimum height of the wallpaper.
**Example**
```js
wallpaper.getMinHeight((error, data) => {
if (error) {
console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
return;
}
console.log(`success to getMinHeight: ` + JSON.stringify(data));
});
```
```js
wallpaper.getMinHeight((error, data) => {
if (error) {
console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
return;
}
console.log(`success to getMinHeight: ` + JSON.stringify(data));
});
```
## wallpaper.getMinHeight
getMinHeight(): Promise&lt;number&gt;
Obtains the minimum height of the wallpaper.
Obtains the minimum height of this wallpaper. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Wallpaper
**Return value**
| Type | Description |
......@@ -185,20 +186,20 @@ Obtains the minimum height of the wallpaper.
**Example**
```js
wallpaper.getMinHeight().then((data) => {
console.log(`success to getMinHeight: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
});
```
```js
wallpaper.getMinHeight().then((data) => {
console.log(`success to getMinHeight: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
});
```
## wallpaper.getMinWidth
getMinWidth(callback: AsyncCallback&lt;number&gt;): void
Obtains the minimum width of the wallpaper.
Obtains the minimum width of this wallpaper. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -210,22 +211,22 @@ Obtains the minimum width of the wallpaper.
**Example**
```js
wallpaper.getMinWidth((error, data) => {
if (error) {
console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
return;
}
console.log(`success to getMinWidth: ` + JSON.stringify(data));
});
```
```js
wallpaper.getMinWidth((error, data) => {
if (error) {
console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
return;
}
console.log(`success to getMinWidth: ` + JSON.stringify(data));
});
```
## wallpaper.getMinWidth
getMinWidth(): Promise&lt;number&gt;
Obtains the minimum width of the wallpaper.
Obtains the minimum width of this wallpaper. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -237,20 +238,20 @@ Obtains the minimum width of the wallpaper.
**Example**
```js
wallpaper.getMinWidth().then((data) => {
console.log(`success to getMinWidth: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
});
```
```js
wallpaper.getMinWidth().then((data) => {
console.log(`success to getMinWidth: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
});
```
## wallpaper.isChangePermitted
isChangePermitted(callback: AsyncCallback&lt;boolean&gt;): void
Checks whether to allow the application to change the wallpaper for the current user.
Checks whether to allow the application to change the wallpaper for the current user. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -258,26 +259,26 @@ Checks whether to allow the application to change the wallpaper for the current
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Callback used to return the queried result. Returns **true** if it is allowed; returns **false** otherwise. |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Returns **true** if the application is allowed to change the wallpaper for the current user; returns **false** otherwise. |
**Example**
```js
wallpaper.isChangePermitted((error, data) => {
if (error) {
console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
return;
}
console.log(`success to isChangePermitted: ` + JSON.stringify(data));
});
```
```js
wallpaper.isChangePermitted((error, data) => {
if (error) {
console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
return;
}
console.log(`success to isChangePermitted: ` + JSON.stringify(data));
});
```
## wallpaper.isChangePermitted
isChangePermitted(): Promise&lt;boolean&gt;
Checks whether to allow the application to change the wallpaper for the current user.
Checks whether to allow the application to change the wallpaper for the current user. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -285,24 +286,24 @@ Checks whether to allow the application to change the wallpaper for the current
| Type | Description |
| -------- | -------- |
| Promise&lt;boolean&gt; | Promise used to return whether to allow the application to change the wallpaper for the current user. Returns **true** if it is allowed; returns **false** otherwise. |
| Promise&lt;boolean&gt; | Returns **true** if the application is allowed to change the wallpaper for the current user; returns **false** otherwise. |
**Example**
```js
wallpaper.isChangePermitted().then((data) => {
console.log(`success to isChangePermitted: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
});
```
```js
wallpaper.isChangePermitted().then((data) => {
console.log(`success to isChangePermitted: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
});
```
## wallpaper.isOperationAllowed
isOperationAllowed(callback: AsyncCallback&lt;boolean&gt;): void
Checks whether the user is allowed to set wallpapers.
Checks whether the user is allowed to set wallpapers. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -310,26 +311,26 @@ Checks whether the user is allowed to set wallpapers.
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Callback used to return whether the user is allowed to set wallpapers. Returns **true** if it is allowed; returns **false** otherwise. |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Returns **true** if the user is allowed to set wallpapers; returns **false** otherwise. |
**Example**
```js
wallpaper.isOperationAllowed((error, data) => {
if (error) {
console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
return;
}
console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
});
```
```js
wallpaper.isOperationAllowed((error, data) => {
if (error) {
console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
return;
}
console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
});
```
## wallpaper.isOperationAllowed
isOperationAllowed(): Promise&lt;boolean&gt;
Checks whether the user is allowed to set wallpapers.
Checks whether the user is allowed to set wallpapers. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -337,26 +338,26 @@ Checks whether the user is allowed to set wallpapers.
| Type | Description |
| -------- | -------- |
| Promise&lt;boolean&gt; | Promise used to return whether the user is allowed to set wallpapers. Returns **true** if it is allowed; returns **false** otherwise. |
| Promise&lt;boolean&gt; | Returns **true** if the user is allowed to set wallpapers; returns **false** otherwise. |
**Example**
```js
wallpaper.isOperationAllowed().then((data) => {
console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
});
```
```js
wallpaper.isOperationAllowed().then((data) => {
console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
});
```
## wallpaper.reset
reset(wallpaperType: WallpaperType, callback: AsyncCallback&lt;void&gt;): void
Removes a wallpaper of the specified type and restores the default one.
Resets the wallpaper of the specified type to the default wallpaper. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.SET_WALLPAPER
**Required permissions**: ohos.permission.SET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -365,28 +366,28 @@ Removes a wallpaper of the specified type and restores the default one.
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. If the operation is successful, the result of removal is returned. Otherwise, error information is returned. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. If the operation is successful, the result is returned. Otherwise, error information is returned. |
**Example**
```js
wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (error) {
console.error(`failed to reset because: ` + JSON.stringify(error));
return;
}
console.log(`success to reset.`);
});
```
```js
wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (error) {
console.error(`failed to reset because: ` + JSON.stringify(error));
return;
}
console.log(`success to reset.`);
});
```
## wallpaper.reset
reset(wallpaperType: WallpaperType): Promise&lt;void&gt;
Removes a wallpaper of the specified type and restores the default one.
Resets the wallpaper of the specified type to the default wallpaper. This API uses a promise to return the result.
**Required permission**: ohos.permission.SET_WALLPAPER
**Required permissions**: ohos.permission.SET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -400,26 +401,26 @@ Removes a wallpaper of the specified type and restores the default one.
| Type | Description |
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result. If the operation is successful, the result of removal is returned. Otherwise, error information is returned. |
| Promise&lt;void&gt; | Promise used to return the result. If the operation is successful, the result is returned. Otherwise, error information is returned. |
**Example**
```js
wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to reset.`);
}).catch((error) => {
console.error(`failed to reset because: ` + JSON.stringify(error));
});
```
```js
wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to reset.`);
}).catch((error) => {
console.error(`failed to reset because: ` + JSON.stringify(error));
});
```
## wallpaper.setWallpaper
setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback&lt;void&gt;): void
Sets a specified source as the wallpaper of a specified type.
Sets a specified source as the wallpaper of a specified type. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.SET_WALLPAPER
**Required permissions**: ohos.permission.SET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -427,7 +428,7 @@ Sets a specified source as the wallpaper of a specified type.
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| source | string \| [PixelMap](js-apis-image.md#pixelmap7) | Yes | Uri path of the JPEG or PNG file, or bitmap of the PNG file. |
| source | string \| [PixelMap](js-apis-image.md#pixelmap7) | Yes | URI of a JPEG or PNG file, or bitmap of a PNG file. |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned. |
......@@ -471,9 +472,9 @@ imageSource.createPixelMap(opts).then((pixelMap) => {
setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise&lt;void&gt;
Sets a specified source as the wallpaper of a specified type.
Sets a specified source as the wallpaper of a specified type. This API uses a promise to return the result.
**Required permission**: ohos.permission.SET_WALLPAPER
**Required permissions**: ohos.permission.SET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -481,7 +482,7 @@ Sets a specified source as the wallpaper of a specified type.
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| source | string \| [PixelMap](js-apis-image.md#pixelmap7) | Yes | Uri path of the JPEG or PNG file, or bitmap of the PNG file. |
| source | string \| [PixelMap](js-apis-image.md#pixelmap7) | Yes | URI path of the JPEG or PNG file, or bitmap of the PNG file. |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
**Return value**
......@@ -525,7 +526,7 @@ imageSource.createPixelMap(opts).then((pixelMap) => {
getFile(wallpaperType: WallpaperType, callback: AsyncCallback&lt;number&gt;): void
Obtains the wallpaper of the specified type.
Obtains the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.SET_WALLPAPER and ohos.permission.READ_USER_STORAGE
......@@ -540,21 +541,21 @@ Obtains the wallpaper of the specified type.
**Example**
```js
wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (error) {
console.error(`failed to getFile because: ` + JSON.stringify(error));
return;
}
console.log(`success to getFile: ` + JSON.stringify(data));
});
```
```js
wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (error) {
console.error(`failed to getFile because: ` + JSON.stringify(error));
return;
}
console.log(`success to getFile: ` + JSON.stringify(data));
});
```
## wallpaper.getFile<sup>8+</sup>
getFile(wallpaperType: WallpaperType): Promise&lt;number&gt;
Obtains the wallpaper of the specified type.
Obtains the wallpaper of the specified type. This API uses a promise to return the result.
**Required permissions**: ohos.permission.GET_WALLPAPER and ohos.permission.READ_USER_STORAGE
......@@ -574,13 +575,75 @@ Obtains the wallpaper of the specified type.
**Example**
```js
wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getFile: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to getFile because: ` + JSON.stringify(error));
});
```
```js
wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getFile: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to getFile because: ` + JSON.stringify(error));
});
```
## wallpaper.getPixelMap
getPixelMap(wallpaperType: WallpaperType, callback: AsyncCallback&lt;image.PixelMap&gt;): void;
Obtains the pixel image for the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.GET_WALLPAPER and ohos.permission.READ_USER_STORAGE
**System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result. If the operation is successful, the result is returned. Otherwise, error information is returned.|
**Example**
```js
wallpaper.getPixelMap(WALLPAPER_SYSTEM, function (err, data) {
console.info('wallpaperXTS ===> testGetPixelMapCallbackSystem err : ' + JSON.stringify(err));
console.info('wallpaperXTS ===> testGetPixelMapCallbackSystem data : ' + JSON.stringify(data));
});
```
## wallpaper.getPixelMap
getPixelMap(wallpaperType: WallpaperType): Promise&lt;image.PixelMap&gt;
Obtains the pixel image for the wallpaper of the specified type. This API uses a promise to return the result.
**Required permissions**: ohos.permission.GET_WALLPAPER and ohos.permission.READ_USER_STORAGE
**System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result. If the operation is successful, the result is returned. Otherwise, error information is returned.|
**Example**
```js
wallpaper.getPixelMap(WALLPAPER_SYSTEM).then((data) => {
console.info('wallpaperXTS ===> testGetPixelMapPromiseSystem data : ' + data);
console.info('wallpaperXTS ===> testGetPixelMapPromiseSystem data : ' + JSON.stringify(data));
}).catch((err) => {
console.info('wallpaperXTS ===> testGetPixelMapPromiseSystem err : ' + err);
console.info('wallpaperXTS ===> testGetPixelMapPromiseSystem err : ' + JSON.stringify(err));
});
```
## wallpaper.on('colorChange')
......@@ -596,7 +659,7 @@ Subscribes to the wallpaper color change event.
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to subscribe to. The value **colorChange** indicates subscribing to the wallpaper color change event. |
| callback | function | Yes | Callback triggered when the wallpaper color changes. The wallpaper type and main colors are returned.<br/>- colors<br/> Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).<br/>- wallpaperType<br/> Wallpaper type. |
| callback | function | Yes | Callback triggered when the wallpaper color changes. The wallpaper type and main colors are returned.<br>- colors<br> Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).<br>- wallpaperType<br> Wallpaper type. |
**Example**
......@@ -621,7 +684,7 @@ Unsubscribes from the wallpaper color change event.
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to unsubscribe from. The value **colorChange** indicates unsubscribing from the wallpaper color change event. |
| callback | function | No | Callback for the wallpaper color change event. If this parameter is not specified, all callbacks corresponding to the wallpaper color change event are invoked.<br/>- colors<br/> Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).<br/>- wallpaperType<br/> Wallpaper type. |
| callback | function | No | Callback for the wallpaper color change event. If this parameter is not specified, all callbacks corresponding to the wallpaper color change event are invoked.<br>- colors<br> Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).<br>- wallpaperType<br> Wallpaper type. |
**Example**
......
en/application-dev/reference/arkui-js/js-components-basic-piece.md
浏览文件 @ e2c72f5a
......@@ -2,7 +2,7 @@
An entrance piece that can contain images and text. It is usually used to display receivers, for example, email recipients or message recipients.
## Child Component
## Child Components
None
......
en/application-dev/reference/arkui-js/js-components-basic-slider.md
浏览文件 @ e2c72f5a
......@@ -2,7 +2,7 @@
The **\<slider>** component is used to quickly adjust settings, such as volume and brightness.
## Child Component
## Child Components
Not supported
......
en/application-dev/reference/arkui-js/js-components-basic-switch.md
浏览文件 @ e2c72f5a
......@@ -6,7 +6,7 @@ The **\<switch>** component is used to enable or disable a function.
None
## Child Component
## Child Components
None
......
en/application-dev/reference/arkui-js/js-components-basic-textarea.md
浏览文件 @ e2c72f5a
......@@ -6,7 +6,7 @@ The **\<textarea>** component provides a text box to receive multi-line text inp
None
## Child Component
## Child Components
Not supported
......
en/application-dev/reference/arkui-js/js-components-media-video.md
浏览文件 @ e2c72f5a
# video
The **\<video>** component provides a video player.
> ![img](https://gitee.com/openharmony/docs/raw/OpenHarmony-3.1-Release/en/application-dev/public_sys-resources/icon-note.gif) **NOTE:**
> **NOTE**<br>
>
> - Configure the following information in the **config.json** file:
> - This component is supported since API version 4. Updates will be marked with a superscript to indicate their earliest API version.
>
> - Set **configChanges** under **abilities** in the **config.json** file to **orientation**.
> ```
> "configChanges": ["orientation"]
> "abilities": [
> {
> "configChanges": ["orientation"],
> ...
> }
> ]
> ```
## Required Permissions
The **\<Video>** component provides a video player.
## Child Component
## Child Components
Not supported
## Attributes
In addition to the attributes in [Universal Attributes](js-components-common-attributes.md), the following attributes are supported.
## Attributes
In addition to the [universal attributes](../arkui-js/js-components-common-attributes.md), the following attributes are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| muted | boolean | false | No| Whether the video is muted.|
| src | string | - | No| Path of the video content to play.|
| autoplay | boolean | false | No| Whether the video is played automatically after being rendered.|
| controls | boolean | true | No| Whether the control bar is displayed during video playback. If the value is set to **false**, the control bar is not displayed. The default value is **true**, indicating that the platform can either show or hide the control bar.|
| Name | Type | Default Value | Mandatory | Description |
| -------- | ------- | ------------- | --------- | ------------------------------------------------------------ |
| muted | boolean | false | No | Whether a video is muted. |
| src | string | - | No | Path of the video content to play. |
| autoplay | boolean | false | No | Whether a video is played automatically after being rendered. |
| controls | boolean | true | No | Whether the control bar is displayed during video playback. If the value is set to **false**, the control bar is not displayed. The default value is **true**, indicating that the platform can either show or hide the control bar. |
## Styles
In addition to the styles in [Universal Styles](js-components-common-styles.md), the following styles are supported.
| Name | Type | Default Value | Mandatory | Description |
| ---------- | ------ | ------------- | --------- | ------------------------------------------------------------ |
| object-fit | string | contain | No | Scaling type of the video source. If **poster** has been assigned a value, this configuration will affect the scaling type of the video poster. For details about available values, see [Table 1](js-components-media-video.md). |
In addition to the [universal styles](../arkui-js/js-components-common-styles.md), the following styles are supported.
**Table 1** object-fit description
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| object-fit | string | contain | No| Video scale type. If **poster** has been assigned a value, the setting of this style will affect the scaling type of the video poster. For details, see object-fit enums.|
**Table 1** object-fit enums
| Type| Description|
| -------- | -------- |
| fill | The image is resized to fill the display area, and its aspect ratio is not retained.|
| Type | Description |
| ---- | ------------------------------------------------------------ |
| fill | The video content is resized to fill the display area and its aspect ratio is not retained. |
## Events
In addition to the events in [Universal Events](js-components-common-events.md), the following events are supported.
In addition to the [universal events](../arkui-js/js-components-common-events.md), the following events are supported.
| Name| Parameter| Description|
| -------- | -------- | -------- |
| prepared | {&nbsp;duration:&nbsp;value&nbsp;}<sup>5+</sup> | Triggered when the video preparation is complete. The video duration (in seconds) is obtained from **duration**.|
| start | - | Triggered when the video is played.|
| pause | - | Triggered when the video playback is paused.|
| finish | - | Triggered when the video playback is finished.|
| error | - | Triggered when the video playback fails.|
| seeking | {&nbsp;currenttime:&nbsp;value&nbsp;} | Triggered to report the time (in seconds) when the progress bar is being dragged.|
| seeked | {&nbsp;currenttime:&nbsp;value&nbsp;} | Triggered to report the playback time (in seconds) when the user finishes dragging the progress bar.|
| timeupdate | {&nbsp;currenttime:&nbsp;value&nbsp;} | Triggered once per 250 ms when the playback progress changes. The unit of the current playback time is second.|
| Name | Parameter | Description |
| ---------- | ---------------------- | ------------------------------------------------------------ |
| prepared | { duration: value }5+ | Triggered when the video preparation is complete. The video duration (in seconds) is obtained from **duration**. |
| start | - | Triggered when a video is played. |
| pause | - | Triggered when a video is paused. |
| finish | - | Triggered when the video playback is finished. |
| error | - | Triggered when the playback fails. |
| seeking | { currenttime: value } | Triggered to report the time (in seconds) when the progress bar is being dragged. |
| seeked | { currenttime: value } | Triggered to report the playback time (in seconds) when the user finishes dragging the progress bar. |
| timeupdate | { currenttime: value } | Triggered once per 250 ms when the playback progress changes. The unit of the current playback time is second. |
## Methods
In addition to the methods in [Universal Methods](js-components-common-methods.md), the following methods are supported.
| Name | Type | Description |
| -------------- | ---------------------- | --------------------------------------------- |
| start | - | Starts playing a video. |
| pause | - | Pauses a video. |
| setCurrentTime | { currenttime: value } | Sets the video playback position, in seconds. |
> ![img](https://gitee.com/openharmony/docs/raw/OpenHarmony-3.1-Release/en/application-dev/public_sys-resources/icon-note.gif) **NOTE:** The methods in the above table can be called after the **attached** callback is invoked.
\ No newline at end of file
In addition to the [universal methods](../arkui-js/js-components-common-methods.md), the following methods are supported.
| Name| Parameter| Description|
| -------- | -------- | -------- |
| start | - | Starts playing a video.|
| pause | - | Pauses a video.|
| setCurrentTime | {&nbsp;currenttime:&nbsp;value&nbsp;} | Sets the video playback position, in seconds.|
> **NOTE**<br>
> The methods in the above table can be called after the **attached** callback is invoked.
## Example
```html
<!-- xxx.hml -->
<div class="container">
<video id='videoId' src='/common/myDeram.mp4' muted='false' autoplay='false'
controls='true' onprepared='preparedCallback' onstart='startCallback'
onpaues='pauesCallback' onfinish='finishCallback' onerror='errorCallback'
onseeking='seekingCallback' onseeked='seekedCallback'
ontimeupdate='timeupdateCallback'
style="object-fit:fit; width:80%; height:400px;"
onclick="change_start_pause">
</video>
</div>
```
```css
/* xxx.css */
.container {
justify-content: center;
align-items: center;
}
```
```js
// xxx.js
export default {
data: {
event:'',
seekingtime:'',
timeupdatetime:'',
seekedtime:'',
isStart: true,
duration: '',
},
preparedCallback:function(e){ this.event = 'Video successfully connected'; this.duration = e.duration;},
startCallback:function(){this.event = 'Playback starts.';},
pauseCallback:function(){this.event = 'Playback pauses.';},
finishCallback:function(){this.event = 'Playback ends.';},
errorCallback:function(){this.event = 'Playback error.';},
seekingCallback:function(e){ this.seekingtime = e.currenttime; },
timeupdateCallback:function(e){ this.timeupdatetime = e.currenttime;},
change_start_pause: function() {
if(this.isStart) {
this.$element('videoId').pause();
this.isStart = false;
} else {
this.$element('videoId').start();
this.isStart = true;
}
},
}
```
en/application-dev/reference/arkui-ts/ts-basic-components-image.md
浏览文件 @ e2c72f5a
# Image
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> **NOTE**
> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
The **&lt;Image&gt;** component is used to render and display images.
The **\<Image>** component is used to render and display images.
## Required Permissions
ohos.permission.INTERNET (using Internet images)
ohos.permission.INTERNET (to use Internet images)
## Child Components
......@@ -20,12 +20,12 @@ None
## APIs
Image(value: {uri: string | PixelMap})
Image(src: string | PixelMap | Resource)
- Parameters
| Name | Type | Mandatory | Default Value | Description |
| Name | Type | Mandatory | Default Value | Description |
| -------- | -------- | -------- | -------- | -------- |
| uri | string | Yes | - | Image URI. Both local and Internal URIs are supported. |
| src | string\| [PixelMap](../apis/js-apis-image.md#pixelmap7)\| [Resource](../../ui/ts-types.md#resource-type) | Yes | - | Image address, which can be the address of an Internet or a local image.<br/>\- The following image formats are supported: png, jpg, bmp, svg, gif.<br/>\- Base64 strings are supported. The value format is `data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data]`, where `[base64 data]` is a Base64 string. <br/>\- The value can also be a path starting with `dataability://`, which is used to access the image path provided by a Data ability. |
## Attributes
......@@ -34,43 +34,43 @@ Image(value: {uri: string | PixelMap})
| -------- | -------- | -------- | -------- |
| alt | string | - | Placeholder image displayed during loading. Both local and Internal URIs are supported. |
| objectFit | ImageFit | ImageFit.Cover | Image scale type. |
| objectRepeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat enums) | ImageRepeat.NoRepeat | Whether the image is repeated.<br/>> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br/>> - This attribute is not applicable to SVG images. |
| interpolation | ImageInterpolation | ImageInterpolation.None | Interpolation effect of the image. This attribute is valid only when the image is zoomed in.<br/>> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br/>> - This attribute is not applicable to SVG images.<br/>> <br/>> - This attribute is not applicable to a **PixelMap** object. |
| renderMode | ImageRenderMode | ImageRenderMode.Original | Rendering mode of the image.<br/>> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br/>> - This attribute is not applicable to SVG images. |
| objectRepeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat-enums) | ImageRepeat.NoRepeat | Whether the image is repeated.<br/>> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br/>> - 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.<br/>> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br/>> - This attribute is not applicable to SVG images.<br/>> <br/>> - This attribute is not applicable to a **PixelMap** object. |
| renderMode | ImageRenderMode | Original | Rendering mode of the image.<br/>> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br/>> - This attribute is not applicable to SVG images. |
| sourceSize | {<br/>width: number,<br/>height: number<br/>} | - | Decoding size of the image. The original image is decoded into an image of the specified size. If the value is of the number type, the unit px is used.<br/>> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br/>> This attribute is not applicable to a **PixelMap** object. |
| syncLoad<sup>8+</sup> | 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 enums
| Name | Description |
| 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 video content is resized to fill the display area while retaining its aspect ratio. |
| None | The original size is retained. Generally, this enum is used together with the **objectRepeat** attribute. |
| ScaleDown | The image content is displayed with its aspect ratio retained. The size is smaller than or equal to the original size. |
| 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 video content is resized to fill the display area while retaining its aspect ratio. |
| None | The original size is retained. Generally, this enum is used together with the **objectRepeat** attribute. |
| ScaleDown | The image content is displayed with its aspect ratio retained. The size is smaller than or equal to the original size. |
- ImageInterpolation enums
| Name | Description |
| Name | Description |
| -------- | -------- |
| None | Interpolation image data is not used. |
| High | The interpolation image data is used at the high level. The use of the interpolation image data may affect the image rendering speed. |
| Medium | The interpolation image data is used at the medium level. |
| Low | The interpolation image data is used at the low level. |
| None | Interpolation image data is not used. |
| High | The interpolation image data is used at the high level. The use of the interpolation image data may affect the image rendering speed. |
| Medium | The interpolation image data is used at the medium level. |
| Low | The interpolation image data is used at the low level. |
- ImageRenderMode enums
| Name | Description |
| Name | Description |
| -------- | -------- |
| Original | The image is rendered based on the original image, including the color. |
| Template | The image is rendered as a template image, and its color is ignored. |
| Original | The image is rendered based on the original image, including the color. |
| Template | The image is rendered as a template image, and its color is ignored. |
## Events
| Name | Description |
| Name | Description |
| -------- | -------- |
| onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number }) =&gt; void) | Triggered when an image is successfully loaded. The loaded image is returned. |
| onError(callback: (event?: { componentWidth: number, componentHeight: number }) =&gt; void) | An exception occurs during image loading. |
| onFinish(callback: () =&gt; void) | If the source file to be loaded is an SVG image, this callback is invoked when the SVG animation playback is complete. If the animation is an infinite loop, this callback is not triggered. |
| onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number }) =&gt; void) | Triggered when an image is successfully loaded. The loaded image is returned. |
| onError(callback: (event?: { componentWidth: number, componentHeight: number }) =&gt; void) | An exception occurs during image loading. |
| onFinish(callback: () =&gt; void) | If the source file to be loaded is an SVG image, this callback is invoked when the SVG animation playback is complete. If the animation is an infinite loop, this callback is not triggered. |
## Example
......
en/application-dev/reference/arkui-ts/ts-basic-components-search.md
浏览文件 @ e2c72f5a
# Search
> ![](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.
> **NOTE**<br>
> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
The **\<Search>** component provides an input area for users to search.
......@@ -10,7 +11,7 @@ None
## Child Components
None
Not supported
## APIs
......@@ -18,32 +19,33 @@ Search(options?: { value?: string; placeholder?: string; icon?: string; controll
- Parameters
| Name| Type| Mandatory| Default Value| Description|
| 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.|
| 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|
| 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.|
| 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. |
| copyOption<sup>9+</sup> | boolean\|[CopyOption](ts-basic-components-text.md) | true | Whether copy and paste is allowed. |
## Events
| Name| Description|
| 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.<br> -**value**: current text input.|
| onChange(callback: (value: string) => void) | Triggered when the input in the text box changes.<br> -**value**: current text input.|
| onCopy(callback: (value: string) => void) | Triggered when data is copied to the pasteboard.<br> -**value**: text copied.|
| onCut(callback: (value: string) => void) | Triggered when data is cut from the pasteboard.<br> -**value**: text cut.|
| onPaste(callback: (value: string) => void) | Triggered when data is pasted from the pasteboard.<br> -**value**: text pasted.|
| 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.<br> -**value**: current text input. |
| onChange(callback: (value: string) => void) | Triggered when the input in the text box changes.<br> -**value**: current text input. |
| onCopy(callback: (value: string) => void) | Triggered when data is copied to the pasteboard.<br> -**value**: text copied. |
| onCut(callback: (value: string) => void) | Triggered when data is cut from the pasteboard.<br> -**value**: text cut. |
| onPaste(callback: (value: string) => void) | Triggered when data is pasted from the pasteboard.<br> -**value**: text pasted. |
## SearchController
......@@ -55,21 +57,22 @@ controller: SearchController = new SearchController()
```
#### caretPosition
creatPosition(value: number): void
caretPosition(value: number): void
Sets the position of the caret.
- Parameters
| Name | Type | Mandatory | Default Value | Description |
| 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.|
| value | number | Yes | - | Length from the start of the text string to the position where the caret is located. |
## Example
```
```ts
// xxx.ets
@Entry
@Component
struct SearchExample {
......
en/application-dev/reference/arkui-ts/ts-basic-components-textarea.md
浏览文件 @ e2c72f5a
# TextArea
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
>
> **NOTE**<br>
> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
The **&lt;TextArea&gt;** component provides multi-line text input.
The **\<TextArea>** component provides multi-line text input.
## Required Permissions
......@@ -16,7 +15,7 @@ None
## Child Components
None
Not supported
## APIs
......@@ -27,7 +26,7 @@ TextArea(value?:{placeholder?: string controller?: TextAreaController})
| Name | Type | Mandatory | Default Value | Description |
| ----------------------- | ---------------------------------------- | --------- | ------------- | -------------------------------------- |
| placeholder | string | No | - | Text displayed when there is no input. |
| controller<sup>8+</sup> | [TextAreaController](#textareacontroller8) | No | - | Text area controller. |
| controller<sup>8+</sup> | [TextAreaController](#textareacontroller8) | No | - | Text area controller. |
## Attributes
......@@ -38,9 +37,10 @@ In addition to universal attributes, the following attributes are supported.
| ------------------------ | ---------------------------------------- | ------------- | ---------------------------------------- |
| placeholderColor | Color | - | Placeholder text color. |
| placeholderFont | {<br/>size?: number,<br/>weight?:number \| [FontWeight](ts-universal-attributes-text-style.md),<br/>family?: string,<br/>style?: [FontStyle](ts-universal-attributes-text-style.md)<br/>} | - | Placeholder text style.<br/>- **size**: font size. If the value is of the number type, the unit fp is used.<br/>- **weight**: font weight. For the number type, the value ranges from 100 to 900, at an interval of 100. The default value is **400**. A larger value indicates a larger font weight.<br/>- **family**: font family. Use commas (,) to separate multiple fonts, for example, **'Arial, sans-serif'**. The priority of the fonts is the sequence in which they are placed.<br/>- **style**: font style. |
| textAlign | TextAlign | Start | Sets the text horizontal alignment mode. |
| caretColor | Color | - | Sets the color of the cursor in the text box. |
| inputFilter<sup>8+</sup> | {<br/>value: [ResourceStr](../../ui/ts-types.md),<br/>error?: (value: string)<br/>} | - | Regular expression for input filtering. Only inputs that comply with the regular expression can be displayed. Other inputs are ignored. The specified regular expression can match single characters, but not strings. Example: ^(? =.\*\d)(? =.\*[a-z])(? =.\*[A-Z]).{8,10}$. Strong passwords containing 8 to 10 characters cannot be filtered.<br/>- **value**: indicates the regular expression to set.<br/>- **error**: returns the ignored content when regular expression matching fails. |
| textAlign | TextAlign | Start | Text horizontal alignment mode. |
| caretColor | Color | - | Color of the caret in the text box. |
| inputFilter<sup>8+</sup> | {<br/>value: [ResourceStr](../../ui/ts-types.md)<sup>8+</sup>,<br/>error?: (value:&nbsp;string)<br/>} | - | Regular expression for input filtering. Only inputs that comply with the regular expression can be displayed. Other inputs are ignored. The specified regular expression can match single characters, but not strings. Example: ^(? =.\*\d)(? =.\*[a-z])(? =.\*[A-Z]).{8,10}$. Strong passwords containing 8 to 10 characters cannot be filtered.<br/>- **value**: indicates the regular expression to set.<br/>- **error**: returns the ignored content when regular expression matching fails. |
| copyOption<sup>9+</sup> | boolean\|[CopyOption](ts-basic-components-text.md) | true | Whether copy and paste is allowed. |
- TextAlign enums
| Name | Description |
......@@ -77,9 +77,9 @@ caretPosition(value: number): void
Sets the position of the caret.
- Parameters
| Name | Type | Mandatory | Default Value | Description |
| ----- | ------ | --------- | ------------- | ---------------------------------------- |
| value | number | Yes | - | Length from the start of the string to the position where the input cursor is located. |
| 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. |
## Example
......@@ -88,7 +88,8 @@ Sets the position of the caret.
### Multi-line Text Input
```
```ts
// xxx.ets
@Entry
@Component
struct TextAreaExample1 {
......@@ -121,10 +122,10 @@ struct TextAreaExample1 {
![en-us_image_0000001256858399](figures/en-us_image_0000001256858399.gif)
### Setting the Input Cursor
### Setting the Caret
```
```ts
// xxx.ets
@Entry
@Component
struct TextAreaExample2 {
......
en/application-dev/reference/arkui-ts/ts-basic-components-textinput.md
浏览文件 @ e2c72f5a
......@@ -4,7 +4,7 @@
> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
The **&lt;TextInput&gt;** component provides single-line text input.
The **\<TextInput>** component provides single-line text input.
## Required Permissions
......@@ -14,7 +14,7 @@ None
## Child Components
None
Not supported
## APIs
......@@ -22,7 +22,7 @@ None
TextInput(value?:{placeholder?: string controller?: TextInputController})
- Parameters
| Name | Type | Mandatory | Default Value | Description |
| Name | Type | Mandatory | Default Value | Description |
| -------- | -------- | -------- | -------- | -------- |
| placeholder | string | No | - | Text displayed when there is no input. |
| controller<sup>8+</sup> | [TextInputController](#textinputcontroller8) | No | - | Text input controller. |
......@@ -40,19 +40,20 @@ In addition to universal attributes, the following attributes are supported.
| enterKeyType | EnterKeyType | EnterKeyType.Done | How the Enter key is labeled. |
| caretColor | Color | - | Color of the caret (also known as the text insertion cursor). |
| maxLength<sup>8+</sup> | number | - | Maximum number of characters in the text input. |
| inputFilter<sup>8+</sup> | {<br/>value: [ResourceStr](../../ui/ts-types.md)<sup>8+</sup>,<br/>error?: (value: string)<br/>} | - | Regular expression for input filtering. Only inputs that comply with the regular expression can be displayed. Other inputs are ignored. The specified regular expression can match single characters, but not strings. Example: ^(? =.\*\d)(? =.\*[a-z])(? =.\*[A-Z]).{8,10}$. Strong passwords containing 8 to 10 characters cannot be filtered.<br/>- **value**: indicates the regular expression to set.<br/>- **error**: returns the ignored content when regular expression matching fails. |
| inputFilter<sup>8+</sup> | {<br/>value: [ResourceStr](../../ui/ts-types.md)<sup>8+</sup>,<br/>error?: (value: string)<br/>} | - | Regular expression for input filtering. Only inputs that comply with the regular expression can be displayed. Other inputs are ignored. The specified regular expression can match single characters, but not strings. Example: ^(? =.\*\d)(? =.\*[a-z])(? =.\*[A-Z]).{8,10}$. Strong passwords containing 8 to 10 characters cannot be filtered.<br/>- **value**: regular expression to set.<br/>- **error**: error message containing the ignored content returned when regular expression matching fails. |
| copyOption<sup>9+</sup> | boolean\|[CopyOption](ts-basic-components-text.md) | true | Whether copy and paste is allowed. |
- EnterKeyType enums
| Name | Description |
| Name | Description |
| -------- | -------- |
| EnterKeyType.Go | The Enter key is labeled "Go." |
| EnterKeyType.Search | The Enter key is labeled "Search." |
| EnterKeyType.Send | The Enter key is labeled "Send." |
| EnterKeyType.Next | The Enter key is labeled "Next." |
| EnterKeyType.Done | The Enter key is labeled "Done." |
| EnterKeyType.Go | The Enter key is labeled **Go**. |
| EnterKeyType.Search | The Enter key is labeled **Search**. |
| EnterKeyType.Send | The Enter key is labeled **Send**. |
| EnterKeyType.Next | The Enter key is labeled **Next**. |
| EnterKeyType.Done | The Enter key is labeled **Done**. |
- InputType enums
| Name | Description |
| Name | Description |
| -------- | -------- |
| InputType.Normal | Normal input mode. |
| InputType.Password | Password input mode. |
......@@ -85,16 +86,16 @@ controller: TextInputController = new TextInputController()
```
#### caretPosition
### caretPosition
caretPosition(value: number): void
Sets the cursor in a specified position.
Sets the position of the caret.
- Parameters
| Name | Type | Mandatory | Default Value | Description |
| Name | Type | Mandatory | Default Value | Description |
| -------- | -------- | -------- | -------- | -------- |
| value | number | Yes | - | Position of the input cursor.<br/>**value**: indicates the length from the start of the string to the position where the input cursor is located. |
| value | number | Yes | - | Length from the start of the text string to the position where the caret is located. |
......@@ -103,8 +104,8 @@ Sets the cursor in a specified position.
### Single-line Text Input
```
```ts
// xxx.ets
@Entry
@Component
struct TextInputExample1 {
......@@ -136,10 +137,10 @@ struct TextInputExample1 {
![en-us_image_0000001212378402](figures/en-us_image_0000001212378402.gif)
### Setting the Input Cursor
### Setting the Caret
```
```ts
// xxx.ets
@Entry
@Component
struct TextInputExample2 {
......
en/application-dev/reference/arkui-ts/ts-components-canvas-canvas.md
浏览文件 @ e2c72f5a
# Canvas
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> **NOTE**
> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
......@@ -15,7 +15,7 @@ None
## Child Components
None
Not supported
## APIs
......@@ -37,9 +37,9 @@ Universal attributes are supported.
In addition to universal events, the following events are supported.
| Name | Parameter | Description |
| -------------------------------- | --------- | ---------------- |
| onReady(callback: () =&gt; void) | None | Triggered when . |
| Name | Parameter | Description |
| -------------------------------- | --------- | ----------------------------------------------- |
| onReady(callback: () =&gt; void) | None | Triggered when the canvas is ready for drawing. |
## Example
......
en/application-dev/reference/arkui-ts/ts-methods-custom-dialog-box.md
浏览文件 @ e2c72f5a
# Custom Dialog Box
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> **NOTE**<br>
> This method is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
......@@ -10,21 +10,22 @@ The **CustomDialogController** class is used to display a custom dialog box.
## APIs
CustomDialogController(value:{builder: CustomDialog, cancel?: () =&gt; void, autoCancel?: boolean, alignment?: DialogAlignment, offset?: Offset, customStyle?: boolean})
CustomDialogController(value:{builder: CustomDialog, cancel?: () =&gt; void, autoCancel?: boolean, alignment?: DialogAlignment, offset?: Offset, customStyle?: boolean})
- Parameters
| Name | Type | Mandatory | Default Value | Description |
| Name | Type | Mandatory | Default Value | Description |
| -------- | -------- | -------- | -------- | -------- |
| builder | [CustomDialog](../../ui/ts-component-based-customdialog.md) | Yes | - | Constructor of the custom dialog box content. |
| cancel | () =&gt; void | No | - | Callback invoked when the dialog box is closed after the overlay exits. |
| autoCancel | boolean | No | true | Whether to allow users to click the overlay to exit. |
| alignment | DialogAlignment | No | DialogAlignment.Default | Alignment mode of the dialog box in the vertical direction. |
| offset | {<br/>dx: Length \|[Resource](../../ui/ts-types.md#resource),<br/>dy: Length \|[Resource](../../ui/ts-types.md#resource)<br/>} | | | Offset of the dialog box relative to the alignment position. |
| offset | {<br/>dx: Length \|[Resource](../../ui/ts-types.md#resource),<br/>dy: Length \|[Resource](../../ui/ts-types.md#resource)<br/>} | No | - | Offset of the dialog box relative to the alignment position. |
| customStyle | boolean | No | false | Whether the style of the dialog box is customized. |
| gridCount<sup>8+</sup> | number | No | - | Count of grid columns occupied by the dialog box. |
- DialogAlignment enums
| Name | Description |
| Name | Description |
| -------- | -------- |
| Top | Aligns vertically to the top. |
| Center | Aligns vertically to the middle. |
......@@ -38,7 +39,7 @@ CustomDialogController(value:{builder: CustomDialog, cancel?: () =&gt; void, au
| BottomEnd<sup>8+</sup> | Bottom right alignment. |
### CustomDialogController
## CustomDialogController
### Objects to Import
......@@ -48,17 +49,14 @@ CustomDialogController(value:{builder: CustomDialog, cancel?: () =&gt; void, au
dialogController : CustomDialogController = new CustomDialogController(value:{builder: CustomDialog, cancel?: () => void, autoCancel?: boolean})
```
### dialogController.open
### open()
open(): void
Opens the content of the custom dialog box. If the content has been displayed, this API does not take effect.
### dialogController.close
### close
close(): void
Closes the custom dialog box. If the dialog box is closed, the setting does not take effect.
......@@ -67,7 +65,8 @@ Closes the custom dialog box. If the dialog box is closed, the setting does not
## Example
```
```ts
// xxx.ets
@CustomDialog
struct CustomDialogExample {
controller: CustomDialogController
......
en/application-dev/work-scheduler/work-scheduler-dev-guide.md
浏览文件 @ e2c72f5a
......@@ -22,15 +22,15 @@ import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility';
API | Description
---------------------------------------------------------|-----------------------------------------
function startWork(work: WorkInfo): boolean; | Starts a Work Scheduler task.
function stopWork(work: WorkInfo, needCancel?: boolean): boolean; | Stops a Work Scheduler task.
function getWorkStatus(workId: number, callback: AsyncCallback\<WorkInfo>): void;| Obtains the status of a Work Scheduler task. This method uses an asynchronous callback to return the result.
function getWorkStatus(workId: number): Promise\<WorkInfo>; | Obtains the status of a Work Scheduler task. This method uses a promise to return the result.
function obtainAllWorks(callback: AsyncCallback\<void>): Array\<WorkInfo>;| Obtains Work Scheduler tasks. This method uses an asynchronous callback to return the result.
function obtainAllWorks(): Promise<Array\<WorkInfo>>;| Obtains Work Scheduler tasks. This method uses a promise to return the result.
function stopAndClearWorks(): boolean;| Stops and clears Work Scheduler tasks.
function isLastWorkTimeOut(workId: number, callback: AsyncCallback\<void>): boolean;| Checks whether the last execution of the specified task has timed out. This method uses an asynchronous callback to return the result. It is applicable to repeated tasks.
function isLastWorkTimeOut(workId: number): Promise\<boolean>;| Checks whether the last execution of the specified task has timed out. This method uses a promise to return the result. It is applicable to repeated tasks.
startWork(work: WorkInfo): boolean | Starts a Work Scheduler task.
stopWork(work: WorkInfo, needCancel?: boolean): boolean | Stops a Work Scheduler task.
getWorkStatus(workId: number, callback: AsyncCallback\<WorkInfo>): void| Obtains the status of a Work Scheduler task. This method uses an asynchronous callback to return the result.
getWorkStatus(workId: number): Promise\<WorkInfo> | Obtains the status of a Work Scheduler task. This method uses a promise to return the result.
obtainAllWorks(callback: AsyncCallback\<void>): Array\<WorkInfo>| Obtains Work Scheduler tasks. This method uses an asynchronous callback to return the result.
obtainAllWorks(): Promise<Array\<WorkInfo>>| Obtains Work Scheduler tasks. This method uses a promise to return the result.
stopAndClearWorks(): boolean| Stops and clears Work Scheduler tasks.
isLastWorkTimeOut(workId: number, callback: AsyncCallback\<void>): boolean| Checks whether the last execution of the specified task has timed out. This method uses an asynchronous callback to return the result. It is applicable to repeated tasks.
isLastWorkTimeOut(workId: number): Promise\<boolean>| Checks whether the last execution of the specified task has timed out. This method uses a promise to return the result. It is applicable to repeated tasks.
**Table 2** WorkInfo parameters
......@@ -53,8 +53,8 @@ repeatCount |Number of repeat times.| number
API | Description
---------------------------------------------------------|-----------------------------------------
function onWorkStart(work: WorkInfo): void; | Triggered when the Work Scheduler task starts.
function onWorkStop(work: WorkInfo): void; | Triggered when the Work Scheduler task stops.
onWorkStart(work: WorkInfo): void | Triggered when the Work Scheduler task starts.
onWorkStop(work: WorkInfo): void | Triggered when the Work Scheduler task stops.
### How to Develop
......@@ -115,7 +115,7 @@ function onWorkStop(work: WorkInfo): void; | Triggered when the Work Scheduler t
workScheduler.getWorkStatus(50, (err, res) => {
if (err) {
console.info('workschedulerLog getWorkStatus failed, because:' + err.code);
console.info('workschedulerLog getWorkStatus failed, because:' + err.data);
} else {
for (let item in res) {
console.info('workschedulerLog getWorkStatuscallback success,' + item + ' is:' + res[item]);
......@@ -131,7 +131,7 @@ function onWorkStop(work: WorkInfo): void; | Triggered when the Work Scheduler t
console.info('workschedulerLog getWorkStatus success,' + item + ' is:' + res[item]);
}
}).catch((err) => {
console.info('workschedulerLog getWorkStatus failed, because:' + err.code);
console.info('workschedulerLog getWorkStatus failed, because:' + err.data);
})
......@@ -141,7 +141,7 @@ function onWorkStop(work: WorkInfo): void; | Triggered when the Work Scheduler t
workScheduler.obtainAllWorks((err, res) =>{
if (err) {
console.info('workschedulerLog obtainAllWorks failed, because:' + err.code);
console.info('workschedulerLog obtainAllWorks failed, because:' + err.data);
} else {
console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res));
}
......@@ -152,7 +152,7 @@ function onWorkStop(work: WorkInfo): void; | Triggered when the Work Scheduler t
workScheduler.obtainAllWorks().then((res) => {
console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res));
}).catch((err) => {
console.info('workschedulerLog obtainAllWorks failed, because:' + err.code);
console.info('workschedulerLog obtainAllWorks failed, because:' + err.data);
})
**Stopping and Clearing Work Scheduler Tasks**
......@@ -166,7 +166,7 @@ function onWorkStop(work: WorkInfo): void; | Triggered when the Work Scheduler t
workScheduler.isLastWorkTimeOut(500, (err, res) =>{
if (err) {
console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.code);
console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.data);
} else {
console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res);
}
......@@ -179,6 +179,6 @@ function onWorkStop(work: WorkInfo): void; | Triggered when the Work Scheduler t
console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res);
})
.catch(err => {
console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.code);
console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.data);
});
})
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或