ts-universal-attributes-popup.md 9.0 KB
Newer Older
Z
zengyawen 已提交
1
# Popup Control
Z
zengyawen 已提交
2

E
esterzhou 已提交
3
You can bind a popup to a component, specifying its content, interaction logic, and display status.
Z
zengyawen 已提交
4

5 6 7
>  **NOTE**
>
>  This attribute is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
Z
zengyawen 已提交
8 9


E
ester.zhou 已提交
10 11 12 13 14
## APIs


| Name          | Type                            | Description                                       |
| ---------- | ------------------------------------- | --------------------------------------- |
E
esterzhou 已提交
15
| bindPopup  | show: boolean,<br>popup: [PopupOptions](#popupoptions) \| [CustomPopupOptions](#custompopupoptions8)<sup>8+</sup> | Binds a popup to the component.<br>**show**: whether to show the popup. The default value is **false**, indicating that the popup is hidden.<br>**popup**: parameters of the popup.|
E
ester.zhou 已提交
16 17 18 19 20

## PopupOptions

| Name                     | Type                                               | Mandatory   | Description                                         |
| -------------------------| ------------------------------------------------| -----| ----------------------------------------- |
E
ester.zhou 已提交
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
| message                      | string                                                | Yes | Content of the popup message.                                    |
| placementOnTop               | boolean                                               | No  | Whether to display the popup above the component.<br/>Default value: **false**            |
| primaryButton                | {<br>value: string,<br>action: () =&gt; void<br>}     | No  | Primary button.<br>**value**: text of the primary button in the popup.<br>**action**: callback for clicking the primary button.|
| secondaryButton              | {<br>value: string,<br>action: () =&gt; void<br>}     | No  | Secondary button.<br>**value**: text of the secondary button in the popup.<br>**action**: callback for clicking the secondary button.|
| onStateChange                | (event: { isVisible: boolean }) =&gt; void            | No  | Callback for the popup status change event.<br/>**isVisible**: whether the popup is visible. |
| arrowOffset<sup>9+</sup>     | [Length](ts-types.md#length)                          | No  | Offset of the popup arrow relative to the popup. <br>When the arrow is at the top or bottom of the popup: The value **0** indicates that the arrow is located on the leftmost, and any other value indicates the distance from the arrow to the leftmost; the arrow is centered by default. <br/>When the arrow is on the left or right side of the popup: The value indicates the distance from the arrow to the top; the arrow is centered by default. <br/>When the popup is displayed on either edge of the screen, it will automatically deviate leftward or rightward to stay within the safe area. When the value is **0**, the arrow always points to the bound component. |
| showInSubWindow<sup>9+</sup> | boolean                                               | No  | Whether to show the popup in the subwindow. <br/>Default value: **false** |
| mask<sup>10+</sup>           | boolean \| [ResourceColor](ts-types.md#resourcecolor) | No  | Whether to apply a mask to the popup. The value **true** means to apply a transparent mask to the popup, **false** means not to apply a mask to the popup, and a color value means to apply a mask in the corresponding color to the popup.|
| messageOptions<sup>10+</sup> | [PopupMessageOptions](#popupmessageoptions10)         | No  | Parameters of the popup message.|
| targetSpace<sup>10+</sup>    | [Length](ts-types.md#length)                          | No  | Space between the popup and the target.|

## PopupMessageOptions<sup>10+</sup>

| Name     | Type                                      | Mandatory| Description                  |
| --------- | ------------------------------------------ | ---- | ---------------------- |
| textColor | [ResourceColor](ts-types.md#resourcecolor) | No  | Text color of the popup message.|
| font      | [Font](ts-types.md#Font)                   | No  | Font attributes of the popup message.|
E
ester.zhou 已提交
38 39 40 41
## CustomPopupOptions<sup>8+</sup>

| Name                      | Type                      | Mandatory    | Description                                                |
| -------------------------| ------------------------- | ---- | ---------------------------------------------------- |
E
ester.zhou 已提交
42 43 44
| builder                  | [CustomBuilder](ts-types.md#custombuilder8)  | Yes  | Popup builder.                                         |
| placement                | [Placement](ts-appendix-enums.md#placement8) | No  | Preferred position of the popup. If the set position is insufficient for holding the popup, it will be automatically adjusted.<br>Default value: **Placement.Bottom**    |
| popupColor               | [ResourceColor](ts-types.md#resourcecolor)  | No  | Color of the popup.                                              |
E
ester.zhou 已提交
45
| enableArrow              | boolean                                      | No  | Whether to display an arrow.<br>Since API version 9, if the position set for the popup is not large enough, the arrow will not be displayed. For example, if **placement** is set to **Left**, but the popup height (80 vp) is less than the sum of the arrow width (32 vp) and diameter of popup rounded corner (48 vp), the arrow will not be displayed.<br>Default value: **true**|
E
ester.zhou 已提交
46 47 48
| autoCancel               | boolean                                      | No  | Whether to automatically close the popup when an operation is performed on the page.<br>Default value: **true**                       |
| onStateChange            | (event: { isVisible: boolean }) =&gt; void | No   | Callback for the popup status change event.<br>**isVisible**: whether the popup is visible. |
| arrowOffset<sup>9+</sup>     | [Length](ts-types.md#length)                 | No  | Offset of the popup arrow relative to the popup. <br/>When the arrow is at the top or bottom of the popup: The value **0** indicates that the arrow is located on the leftmost, and any other value indicates the distance from the arrow to the leftmost; the arrow is centered by default. <br/>When the arrow is on the left or right side of the popup: The value indicates the distance from the arrow to the top; the arrow is centered by default. <br/>When the popup is displayed on either edge of the screen, it will automatically deviate leftward or rightward to stay within the safe area. When the value is **0**, the arrow always points to the bound component. |
E
ester.zhou 已提交
49
| showInSubWindow<sup>9+</sup> | boolean                                      | No  | Whether to show the popup in the subwindow.<br/>Default value: **false** |
E
ester.zhou 已提交
50
| mask<sup>10+</sup> | boolean \| [ResourceColor](ts-types.md#resourcecolor) | No| Whether to apply a mask to the popup. The value **true** means to apply a transparent mask to the popup, **false** means not to apply a mask to the popup, and a color value means to apply a mask in the corresponding color to the popup.|
E
ester.zhou 已提交
51
| targetSpace<sup>10+</sup> | [Length](ts-types.md#length) | No| Space between the popup and the target.|
Z
zengyawen 已提交
52

Z
zengyawen 已提交
53
## Example
54 55
```ts
// xxx.ets
Z
zengyawen 已提交
56 57 58 59
@Entry
@Component
struct PopupExample {
  @State handlePopup: boolean = false
Z
zengyawen 已提交
60 61
  @State customPopup: boolean = false

E
esterzhou 已提交
62
  // Popup builder
Z
zengyawen 已提交
63 64
  @Builder popupBuilder() {
    Row({ space: 2 }) {
E
esterzhou 已提交
65
      Image($r("app.media.image")).width(24).height(24).margin({ left: -5 })
66
      Text('Custom Popup').fontSize(10)
E
esterzhou 已提交
67
    }.width(100).height(50).padding(5)
Z
zengyawen 已提交
68
  }
Z
zengyawen 已提交
69 70

  build() {
Z
zengyawen 已提交
71
    Flex({ direction: FlexDirection.Column }) {
E
esterzhou 已提交
72 73
      // PopupOptions for setting the popup
      Button('PopupOptions')
Z
zengyawen 已提交
74 75 76 77
        .onClick(() => {
          this.handlePopup = !this.handlePopup
        })
        .bindPopup(this.handlePopup, {
E
esterzhou 已提交
78
          message: 'This is a popup with PopupOptions',
Z
zengyawen 已提交
79
          placementOnTop: true,
E
esterzhou 已提交
80
          showInSubWindow:false,
Z
zengyawen 已提交
81
          primaryButton: {
E
esterzhou 已提交
82
            value: 'confirm',
Z
zengyawen 已提交
83 84
            action: () => {
              this.handlePopup = !this.handlePopup
E
esterzhou 已提交
85 86 87 88 89 90 91
              console.info('confirm Button click')
            }
          },
          // Secondary button
          secondaryButton: {
            value: 'cancel',
            action: () => {
E
ester.zhou 已提交
92
              this.handlePopup = !this.handlePopup
E
esterzhou 已提交
93
              console.info('cancel Button click')
Z
zengyawen 已提交
94 95 96
            }
          },
          onStateChange: (e) => {
Z
zhaoxinyu 已提交
97
            console.info(JSON.stringify(e.isVisible))
E
esterzhou 已提交
98 99 100
            if (!e.isVisible) {
              this.handlePopup = false
            }
Z
zengyawen 已提交
101 102
          }
        })
E
esterzhou 已提交
103 104
        .position({ x: 100, y: 50 })

Z
zengyawen 已提交
105

E
esterzhou 已提交
106 107
      // CustomPopupOptions for setting the popup
      Button('CustomPopupOptions')
Z
zengyawen 已提交
108 109 110 111 112
        .onClick(() => {
          this.customPopup = !this.customPopup
        })
        .bindPopup(this.customPopup, {
          builder: this.popupBuilder,
E
esterzhou 已提交
113
          placement: Placement.Top,
E
ester.zhou 已提交
114
          mask: {color: 0x33000000},
E
esterzhou 已提交
115
          popupColor: Color.Yellow,
Z
zengyawen 已提交
116
          enableArrow: true,
E
esterzhou 已提交
117
          showInSubWindow: false,
Z
zengyawen 已提交
118 119 120 121 122 123
          onStateChange: (e) => {
            if (!e.isVisible) {
              this.customPopup = false
            }
          }
        })
E
esterzhou 已提交
124
        .position({ x: 80, y: 200 })
Z
zengyawen 已提交
125 126 127 128 129
    }.width('100%').padding({ top: 5 })
  }
}
```

E
esterzhou 已提交
130
![figures/popup.gif](figures/popup.gif)