提交 7015c61a 编写于 作者: E ester.zhou

update docs

Signed-off-by: Nester.zhou <ester.zhou@huawei.com>
上级 b482f8a1
......@@ -556,7 +556,7 @@ Obtains all notification slots. This API uses an asynchronous callback to return
| Name | Readable| Writable| Type | Mandatory| Description |
| -------- | ---- | --- | --------------------------------- | ---- | -------------------- |
| callback | Yes | No | AsyncCallback\<[NotificationSlot](#notificationslot)\> | Yes | Callback used to return the result.|
| callback | Yes | No | AsyncCallback\<Array\<[NotificationSlot](#notificationslot)\>\> | Yes | Callback used to return the result.|
**Example**
......@@ -3765,7 +3765,7 @@ Notification.subscribe(subscriber, subscribeCallback);
| desc | Yes | Yes | string | No | Notification slot description. |
| badgeFlag | Yes | Yes | boolean | No | Whether to display the badge. |
| bypassDnd | Yes | Yes | boolean | No | Whether to bypass the DND mode in the system. |
| lockscreenVisibility | Yes | Yes | boolean | No | Mode for displaying the notification on the lock screen. |
| lockscreenVisibility | Yes | Yes | number | No | Mode for displaying the notification on the lock screen. |
| vibrationEnabled | Yes | Yes | boolean | No | Whether vibration is supported for the notification. |
| sound | Yes | Yes | string | No | Notification alert tone. |
| lightEnabled | Yes | Yes | boolean | No | Whether the indicator blinks for the notification. |
......
# Pasteboard
The **pasteboard** module provides the pasteboard management client and pasteboard server. The pasteboard management client manages pasteboard APIs. Specifically, it provides pasteboard APIs in JavaScript for applications, creates pasteboard data on the application framework side, and requests the pasteboard SA to create, delete, query, convert text, and configure pasteboards. The pasteboard server manages pasteboard events as well as the pasteboard SA lifecycle, providing support for the copy and paste functions of the system.
> **NOTE**<br>The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> **NOTE**
>
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
......@@ -461,10 +463,10 @@ The pasteboard supports a maximum number of 128 data records.
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addTextRecord("good");
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addTextRecord("good");
```
### addHtmlRecord<sup>7+</sup>
......@@ -1037,13 +1039,13 @@ Checks whether the system pasteboard contains content. This API uses a promise t
**Example**
```js
systemPasteboard.hasPasteData().then((data) => {
console.info('Operation succeeded. ' + JSON.stringify(data));
}).catch((error) => {
console.error('failed to hasPasteData because ' + JSON.stringify(error));
});
```
```js
systemPasteboard.hasPasteData().then((data) => {
console.info('success hasPasteData : ' + JSON.stringify(data));
}).catch((error) => {
console.error('failed to hasPasteData because ' + JSON.stringify(error));
});
```
### clear<sup>7+</sup>
......
# Wallpaper
The **wallpaper** module is part of the theme framework and provides the system-level wallpaper management service in OpenHarmony. You can use the APIs of this module to show, set, and switch between wallpapers.
> **NOTE**
>
......
......@@ -49,7 +49,9 @@ RichText\(content:string\)
## Example
```
You can preview how this component looks on a real device. The preview is not yet available in the DevEco Studio Previewer.
```ts
// xxx.ets
@Entry
@Component
struct RichTextExample {
......
# XComponent
> **NOTE**<br>
> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
The **\<XComponent>** can accept and display the EGL/OpenGLES and media data input.
The **\<XComponent>** can accept and display the EGL/OpenGL ES and media data input.
## Required Permissions
......@@ -17,22 +18,34 @@
XComponent\(value: {id: string, type: string, libraryname?: string, controller?: XComponentController}\)
- Name
| Name | Type | Mandatory | Description |
| ----------- | --------------------------------------- | --------- | ------------------------------------------------------------ |
| id | string | Yes | Unique ID of the component. The value can contain a maximum of 128 characters. |
| type | string | Yes | Type of the component. The options are as follows:<br>- **surface**: The content of this component is displayed individually, without being combined with that of other components.<br>- **component**: The content of this component is displayed after having been combined with that of other components. |
| libraryname | string | No | Name of the dynamic library generated after compilation at the application native layer. |
| controller | [XComponentController](#XComponentController) | No | Controller bound to the component, which can be used to invoke methods of the component. |
**Parameters**
| Name | Type | Mandatory | Description |
| --------- | ------ | ---- | ----- |
| id | string | Yes | Unique ID of the component. The value can contain a maximum of 128 characters.|
| type | string | Yes | Type of the component. The options are as follows:<br>-**surface**: The content of this component is displayed individually, without being combined with that of other components.<br>-**component**: The content of this component is displayed after having been combined with that of other components.|
| libraryname | string | No | Name of the dynamic library generated after compilation at the application native layer.|
| controller | [XComponentcontroller](#xcomponentcontroller) | No | Controller bound to the component, which can be used to invoke methods of the component.|
## Events
| Name | Description |
| ------------------------------- | ------------------------ |
| onLoad(context?: object) => void | Triggered when the plug-in is loaded. |
| onDestroy() => void | Triggered when the plug-in is destroyed. |
### onLoad
onLoad(callback: (event?: object) => void )
Triggered when the plug-in is loaded.
**Parameters**
| Name | Type | Mandatory | Description |
| ------------- | ------ | ---- | ----------------------- |
| event | object | No | Context of the **\<XComponent>** object. The APIs contained in the context are defined at the C++ layer by developers.|
### onDestroy
onDestroy(event: () => void )
Triggered when the plug-in is destroyed.
## XComponentController
......@@ -50,11 +63,13 @@ getXComponentSurfaceId(): string
Obtains the ID of the surface held by the **\<XComponent>**. The ID can be used for @ohos interfaces, such as camera-related interfaces.
- Return value
**System API**: This is a system API.
| Type | Description |
| ------ | --------------------------- |
| string | ID of the surface held by the **\<XComponent>**. |
**Return value**
| Type | Description |
| ------ | ----------------------- |
| string | ID of the surface held by the **\<XComponent>**.|
### setXComponentSurfaceSize
......@@ -62,12 +77,14 @@ setXComponentSurfaceSize(value: {surfaceWidth: number, surfaceHeight: number}):
Sets the width and height of the surface held by the **\<XComponent>**.
- Parameters
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Default Value | Description |
| ------------- | -------- | ---- | ------ | ----------------------------- |
| surfaceWidth | number | Yes | - | Width of the surface held by the **\<XComponent>**. |
| surfaceHeight | number | Yes | - | Height of the surface held by the **\<XComponent>**. |
| Name | Type | Mandatory | Description |
| ------------- | ------ | ---- | ----------------------- |
| surfaceWidth | number | Yes | Width of the surface held by the **\<XComponent>**.|
| surfaceHeight | number | Yes | Height of the surface held by the **\<XComponent>**.|
### getXComponentContext
......@@ -75,15 +92,16 @@ getXComponentContext(): Object
Obtains the context of an **\<XComponent>** object.
- Return value
**Return value**
| Type | Description |
| ------ | ------------------------------------------------------------ |
| Object | Context of an **\<XComponent>** object. The APIs contained in the context are defined by developers. |
| Type | Description |
| ------ | ---------------------------------------- |
| Object | Context of the **\<XComponent>** object. The APIs contained in the context are defined by developers.|
## Example
Provide a surface-type **\<XComponent>** to support capabilities such as camera preview.
Provide a surface-type **\<XComponent>** to support capabilities such as camera preview.
You can preview how this component looks on a real device. The preview is not yet available in the DevEco Studio Previewer.
```ts
// xxx.ets
......
# Component ID
**id** identifies a component uniquely within an application. This module provides APIs for obtaining the attributes of or sending events to the component with the specified ID.
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Required Permissions
......@@ -12,93 +14,250 @@ None
## Attributes
| Name | Type | Default Value | Description |
| Name| Type| Default Value| Description|
| -------- | -------- | -------- | -------- |
| id | string | '' | Unique ID of the component. The uniqueness is ensured by the user. |
| id | string | '' | Unique ID you assigned to the component.|
## APIs
### getInspectorByKey
### getInspectorByKey<sup>9+</sup>
getInspectorByKey(id: string): string
Obtains all attributes of the component with the specified ID, excluding the information about child components.
- Parameters
| Name | Type | Mandatory | Default Value | Description |
| Name| Type| Mandatory| Default Value| Description|
| -------- | -------- | -------- | -------- | -------- |
| id | string | Yes | - | ID of the component whose attributes are to be obtained. |
| id | string | Yes| - | ID of the component whose attributes are to be obtained.|
- Return value
| Type | Description |
| Type| Description|
| -------- | -------- |
| string | JSON string of the component attribute list. |
| string | JSON string of the component attribute list.|
### getInspectorTree<sup>9+</sup>
### sendEventByKey
getInspectorTree(): string
Obtains the component tree and component attributes.
- Return value
| Type | Description |
| ------ | ---------------------------------- |
| string | JSON string of the component tree and component attribute list.|
### sendEventByKey<sup>9+</sup>
sendEventByKey(id: string, action: number, params: string): boolean
Sends an event to the component with the specified ID.
- Parameters
| Name | Type | Mandatory | Default Value | Description |
| Name| Type| Mandatory| Default Value| Description|
| -------- | -------- | -------- | -------- | -------- |
| id | string | Yes | - | ID of the component for which the event is to be sent. |
| action | number | Yes | - | Type of the event to be sent. The options are as follows:<br/>- Click event: 10.<br/>- LongClick: 11. |
| params | string | Yes | - | Event parameters. If there is no parameter, pass an empty string **""**. |
| id | string | Yes| - | ID of the component to which the event is to be sent.|
| action | number | Yes| - | Type of the event to be sent. The options are as follows:<br>- **10**: click event.<br>- **11**: long-click event.|
| params | string | Yes| - | Event parameters. If there is no parameter, pass an empty string **""**.|
- Return value
| Type | Description |
| Type| Description|
| -------- | -------- |
| boolean | Returns **false** if the component with the specified ID cannot be found; returns **true** otherwise. |
| boolean | Returns **true** if the component with the specified ID is found; returns **false** otherwise.|
### sendTouchEvent<sup>9+</sup>
sendTouchEvent(event: TouchObject): boolean
Sends a touch event.
- Parameters
| Name | Type | Mandatory| Default Value| Description |
| ----- | ----------- | ---- | ------ | ------------------------------------------------------------ |
| event | TouchObject | Yes | - | Location where a touch event is triggered. For details, see [TouchEvent](ts-universal-events-touch.md#touchevent).|
- Return value
| Type | Description |
| ------- | ------------------------------------------- |
| boolean | Returns **true** if the event is sent successfully; returns **false** otherwise.|
### sendKeyEvent<sup>9+</sup>
sendKeyEvent(event: KeyEvent): boolean
Sends a key event.
- Parameters
| Name | Type | Mandatory| Default Value| Description |
| ----- | -------- | ---- | ------ | ------------------------------------------------------------ |
| event | KeyEvent | Yes | - | Key event. For details, see [KeyEvent](ts-universal-events-key.md#keyevent).|
- Return value
| Type | Description |
| ------- | --------------------------------------------- |
| boolean | Returns **true** if the event is sent successfully; returns **false** otherwise.|
### sendMouseEvent<sup>9+</sup>
sendMouseEvent(event: MouseEvent): boolean
Sends a mouse event.
- Parameters
| Name | Type | Mandatory| Default Value| Description |
| ----- | ---------- | ---- | ------ | ------------------------------------------------------------ |
| event | MouseEvent | Yes | - | Mouse event. For details, see [MouseEvent](ts-universal-mouse-key.md#mouseevent).|
- Return value
| Type | Description |
| ------- | --------------------------------------------- |
| boolean | Returns **true** if the event is sent successfully; returns **false** otherwise.|
## Example
```
```ts
// xxx.ets
class Utils {
static rect_left;
static rect_top;
static rect_right;
static rect_bottom;
static rect_value;
static getComponentRect(key) {
let strJson = getInspectorByKey(key);
let obj = JSON.parse(strJson);
console.info("[getInspectorByKey] current component obj is: " + JSON.stringify(obj));
let rectInfo = JSON.parse('[' + obj.$rect + ']')
console.info("[getInspectorByKey] rectInfo is: " + rectInfo);
this.rect_left = JSON.parse('[' + rectInfo[0] + ']')[0]
this.rect_top = JSON.parse('[' + rectInfo[0] + ']')[1]
this.rect_right = JSON.parse('[' + rectInfo[1] + ']')[0]
this.rect_bottom = JSON.parse('[' + rectInfo[1] + ']')[1]
return this.rect_value = {
"left": this.rect_left, "top": this.rect_top, "right": this.rect_right, "bottom": this.rect_bottom
}
}
}
@Entry
@Component
struct IdExample {
@State text: string = ''
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Button() {
Text('click')
.fontSize(25)
.fontWeight(FontWeight.Bold)
}
.type(ButtonType.Capsule)
.margin({
top: 20
}).onClick(() => {
Text('onKeyTab').fontSize(25).fontWeight(FontWeight.Bold)
}.margin({ top: 20 }).backgroundColor('#0D9FFB')
.onKeyEvent(() => {
this.text = "onKeyTab"
})
Button() {
Text('click to start').fontSize(25).fontWeight(FontWeight.Bold)
}.margin({ top: 20 })
.onClick(() => {
console.info(getInspectorByKey("click"))
console.info(getInspectorTree())
this.text = "Button 'click to start' is clicked"
setTimeout(() => {
sendEventByKey("longclick", 11, "")
sendEventByKey("longClick", 11, "")
}, 2000)
}).id('click')
Button() {
Text('longclick')
.fontSize(25)
.fontWeight(FontWeight.Bold)
}
.type(ButtonType.Capsule)
.margin({
top: 20
})
.backgroundColor('#0D9FFB')
Text('longClick').fontSize(25).fontWeight(FontWeight.Bold)
}.margin({ top: 20 }).backgroundColor('#0D9FFB')
.gesture(
LongPressGesture().onActionEnd(() => {
console.info('long clicked')
}))
.id('longclick')
LongPressGesture().onActionEnd(() => {
console.info('long clicked')
this.text = "Button 'longClick' is longclicked"
setTimeout(() => {
let rect = Utils.getComponentRect('onTouch')
let touchPoint: TouchObject = {
id: 1,
x: rect.left + (rect.right - rect.left) / 2,
y: rect.top + (rect.bottom - rect.top) / 2,
type: TouchType.Down,
screenX: rect.left + (rect.right - rect.left) / 2,
screenY: rect.left + (rect.right - rect.left) / 2,
}
sendTouchEvent(touchPoint)
touchPoint.type = TouchType.Up
sendTouchEvent(touchPoint)
}, 2000)
})).id('longClick')
Button() {
Text('onTouch').fontSize(25).fontWeight(FontWeight.Bold)
}.type(ButtonType.Capsule).margin({ top: 20 })
.onClick(() => {
console.info('onTouch is clicked')
this.text = "Button 'onTouch' is clicked"
setTimeout(() => {
let rect = Utils.getComponentRect('onMouse')
let mouseEvent: MouseEvent = {
button: MouseButton.Left,
action: MouseAction.Press,
x: rect.left + (rect.right - rect.left) / 2,
y: rect.top + (rect.bottom - rect.top) / 2,
screenX: rect.left + (rect.right - rect.left) / 2,
screenY: rect.top + (rect.bottom - rect.top) / 2,
timestamp: 1,
target: {
area: {
width: 1,
height: 1,
position: {
x: 1,
y: 1
},
globalPosition: {
x: 1,
y: 1
}
}
},
source: SourceType.Mouse
}
sendMouseEvent(mouseEvent)
}, 2000)
}).id('onTouch')
Button() {
Text('onMouse').fontSize(25).fontWeight(FontWeight.Bold)
}.margin({ top: 20 }).backgroundColor('#0D9FFB')
.onMouse(() => {
console.info('onMouse')
this.text = "Button 'onMouse' in onMouse"
setTimeout(() => {
let keyEvent: KeyEvent = {
type: KeyType.Down,
keyCode: 2049,
keyText: 'tab',
keySource: 4,
deviceId: 0,
metaKey: 0,
timestamp: 0
}
sendKeyEvent(keyEvent)
}, 2000)
}).id('onMouse')
Text(this.text).fontSize(25).padding(15)
}
.width('100%')
.height('100%')
.width('100%').height('100%')
}
}
```
# Z-order Control
The **zIndex** attribute sets the z-order of a component in the stacking context.
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> **NOTE**
> This attribute is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
......@@ -13,15 +14,16 @@ None
## Attributes
| Name | Type | Default Value | Description |
| Name | Type | Default Value | Description |
| -------- | -------- | -------- | -------- |
| zIndex | number | 0 | Hierarchy of sibling components in a container. A larger z-order value indicates a higher display level. |
| zIndex | number | 0 | Hierarchy of sibling components in a container. A larger value indicates a higher display level. |
## Example
```
```ts
// xxx.ets
@Entry
@Component
struct ZIndexExample {
......@@ -38,7 +40,7 @@ struct ZIndexExample {
Text('third child, zIndex(1)')
.size({width: '70%', height: '50%'}).backgroundColor(0xc1cbac).align(Alignment.TopStart)
.zIndex(1)
}
}.width('100%').height(200)
}.width('100%').height(200)
}
}
......
# Event Configuration
You can use event methods to configure events supported by components.
You can use event methods to configure events supported by components. Since API version 9, you can obtain the context associated with the current component from the callback. For details, see [Obtaining the Context on an eTS Page](../ability/context-userguide.md).
- Example of using a lambda expression to configure the event of a component:
```ts
// Counter is a private data variable defined in the component.
Button('add counter')
......@@ -15,8 +13,7 @@ You can use event methods to configure events supported by components.
```
- When using an anonymous function expression to configure the event of a component, bind must be used to ensure that the contained components are referenced by this in the function body.
- When using an anonymous function expression to configure the event of a component, **bind** must be used to ensure that the contained components are referenced by **this** in the function body.
```ts
// Counter is a private data variable defined in the component.
Button('add counter')
......@@ -27,14 +24,13 @@ You can use event methods to configure events supported by components.
- Example of using a component's member function to configure the event of the component:
```ts
myClickHandler(): void {
// do something
}
...
Button('add counter')
.onClick(this.myClickHandler)
```
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册