1# Popup控制 2 3给组件绑定popup弹窗，并设置弹窗内容，交互逻辑和显示状态。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 接口 11 12 13| 名称 | 参数类型 | 描述 | 14| --------- | ---------------------------------------- | ---------------------------------------- | 15| bindPopup | show: boolean,<br/>popup: [PopupOptions](#popupoptions类型说明) \| [CustomPopupOptions](#custompopupoptions8类型说明)<sup>8+</sup> | 给组件绑定Popup弹窗，设置参数show为true弹出弹框。<br/>show: 弹窗显示状态，默认值为false，隐藏弹窗。popup弹窗必须等待页面全部构建完成才能展示，因此show不能在页面构建中设置为true，否则会导致popup弹窗显示位置及形状错误。<br/>popup: 配置当前弹窗提示的参数。 | 16 17## PopupOptions类型说明 18 19| 名称 | 类型 | 必填 | 描述 | 20| ------------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 21| message | string | 是 | 弹窗信息内容。 | 22| placementOnTop<sup>(deprecated)</sup> | boolean | 否 | 是否在组件上方显示，默认值为false。<br />**说明：**<br />从 API version 10 开始废弃，建议使用`placement`替代。 | 23| primaryButton | {<br/>value: string,<br/>action: () => void<br/>} | 否 | 第一个按钮。<br/>value: 弹窗里主按钮的文本。<br/>action: 点击主按钮的回调函数。 | 24| secondaryButton | {<br/>value: string,<br/>action: () => void<br/>} | 否 | 第二个按钮。<br/>value: 弹窗里辅助按钮的文本。<br/>action: 点击辅助按钮的回调函数。 | 25| onStateChange | (event: { isVisible: boolean }) => void | 否 | 弹窗状态变化事件回调，参数isVisible为弹窗当前的显示状态。 | 26| arrowOffset<sup>9+</sup> | [Length](ts-types.md#length) | 否 | popup箭头在弹窗处的偏移。箭头在气泡上下方时，数值为0表示箭头居最左侧，偏移量为箭头至最左侧的距离，默认居中。箭头在气泡左右侧时，偏移量为箭头至最上侧的距离，默认居中。如果显示在屏幕边缘，气泡会自动左右偏移，数值为0时箭头始终指向绑定组件。 | 27| showInSubWindow<sup>9+</sup> | boolean | 否 | 是否在子窗口显示气泡，默认值为false。 | 28| mask<sup>10+</sup> | boolean \| [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置气泡是否有遮罩层及遮罩颜色。如果设置为false，则没有遮罩层；如果设置为true，则设置有遮罩层并且颜色为透明色；如果设置为Color，则为遮罩层的颜色。 | 29| messageOptions<sup>10+</sup> | [PopupMessageOptions](#popupmessageoptions10) | 否 | 设置弹窗信息文本参数。 | 30| targetSpace<sup>10+</sup> | [Length](ts-types.md#length) | 否 | 设置popup与目标的间隙。 | 31| placement<sup>10+</sup> | [Placement](ts-appendix-enums.md#placement8) | 否 | 设置popup组件相对于目标的显示位置，默认值为Placement.Bottom。<br />如果同时设置了`placementOnTop`和`placement`，则以`placement`的设置生效。 | 32| offset<sup>10+</sup> | [Position](ts-types.md#position8) | 否 | 设置popup组件相对于placement设置的显示位置的偏移。<br />**说明：**<br />不支持设置百分比。 | 33| enableArrow<sup>10+</sup> | boolean | 否 | 设置是否显示箭头。<br/>默认值：true | 34 35## PopupMessageOptions<sup>10+</sup>类型说明 36 37| 名称 | 类型 | 必填 | 描述 | 38| --------- | ---------------------------------------- | ---- | ----------- | 39| textColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置弹窗信息文本颜色。 | 40| font | [Font](ts-types.md#Font) | 否 | 设置弹窗信息字体属性。 | 41## CustomPopupOptions<sup>8+</sup>类型说明 42 43| 名称 | 类型 | 必填 | 描述 | 44| ---------------------------- | ---------------------------------------- | ---- | ---------------------------------------- | 45| builder | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 提示气泡内容的构造器。<br />**说明：**<br />popup为通用属性，自定义popup中不支持再次弹出popup。对builder下的第一层容器组件不支持使用position属性，如果使用将导致气泡不显示。 | 46| placement | [Placement](ts-appendix-enums.md#placement8) | 否 | 气泡组件优先显示的位置，当前位置显示不下时，会自动调整位置。<br/>默认值：Placement.Bottom | 47| popupColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 提示气泡的颜色。<br/>默认值：'#4d4d4d' | 48| enableArrow | boolean | 否 | 是否显示箭头。<br/>从API Version 9开始，如果箭头所在方位侧的气泡长度不足以显示下箭头，则会默认不显示箭头。比如：placement设置为Left，此时如果气泡高度小于箭头的宽度（32vp）与气泡圆角两倍（48vp）之和（80vp），则实际不会显示箭头。<br/>默认值：true | 49| autoCancel | boolean | 否 | 页面有操作时，是否自动关闭气泡。<br/>默认值：true | 50| onStateChange | (event: { isVisible: boolean }) => void | 否 | 弹窗状态变化事件回调，参数为弹窗当前的显示状态。 | 51| arrowOffset<sup>9+</sup> | [Length](ts-types.md#length) | 否 | popup箭头在弹窗处的偏移。箭头在气泡上下方时，数值为0表示箭头居最左侧，偏移量为箭头至最左侧的距离，默认居中。箭头在气泡左右侧时，偏移量为箭头至最上侧的距离，默认居中。如果显示在屏幕边缘，气泡会自动左右偏移，数值为0时箭头始终指向绑定组件。 | 52| showInSubWindow<sup>9+</sup> | boolean | 否 | 是否在子窗口显示气泡，默认值为false。 | 53| maskColor<sup>(deprecated)</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置气泡遮罩层颜色。<br />**说明：**<br />从 API version 10 开始废弃，建议使用`mask`替代。 | 54| mask<sup>10+</sup> | boolean \| [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置气泡是否有遮罩层及遮罩颜色。如果设置为false，则没有遮罩层；如果设置为true，则设置有遮罩层并且颜色为透明色；如果设置为Color，则为遮罩层的颜色。 | 55| targetSpace<sup>10+</sup> | [Length](ts-types.md#length) | 否 | 设置popup与目标的间隙。 | 56| offset<sup>10+</sup> | [Position](ts-types.md#position8) | 否 | 设置popup组件相对于placement设置的显示位置的偏移。<br />**说明：**<br />不支持设置百分比。 | 57 58## 示例 59 60### 示例1 61 62```ts 63// xxx.ets 64@Entry 65@Component 66struct PopupExample { 67 @State handlePopup: boolean = false 68 @State customPopup: boolean = false 69 70 // popup构造器定义弹框内容 71 @Builder popupBuilder() { 72 Row({ space: 2 }) { 73 Image($r("app.media.image")).width(24).height(24).margin({ left: -5 }) 74 Text('Custom Popup').fontSize(10) 75 }.width(100).height(50).padding(5) 76 } 77 78 build() { 79 Flex({ direction: FlexDirection.Column }) { 80 // PopupOptions 类型设置弹框内容 81 Button('PopupOptions') 82 .onClick(() => { 83 this.handlePopup = !this.handlePopup 84 }) 85 .bindPopup(this.handlePopup, { 86 message: 'This is a popup with PopupOptions', 87 placementOnTop: true, 88 showInSubWindow:false, 89 primaryButton: { 90 value: 'confirm', 91 action: () => { 92 this.handlePopup = !this.handlePopup 93 console.info('confirm Button click') 94 } 95 }, 96 // 第二个按钮 97 secondaryButton: { 98 value: 'cancel', 99 action: () => { 100 this.handlePopup = !this.handlePopup 101 console.info('cancel Button click') 102 } 103 }, 104 onStateChange: (e) => { 105 console.info(JSON.stringify(e.isVisible)) 106 if (!e.isVisible) { 107 this.handlePopup = false 108 } 109 } 110 }) 111 .position({ x: 100, y: 50 }) 112 113 114 // CustomPopupOptions 类型设置弹框内容 115 Button('CustomPopupOptions') 116 .onClick(() => { 117 this.customPopup = !this.customPopup 118 }) 119 .bindPopup(this.customPopup, { 120 builder: this.popupBuilder, 121 placement: Placement.Top, 122 mask: {color:'0x33000000'}, 123 popupColor: Color.Yellow, 124 enableArrow: true, 125 showInSubWindow: false, 126 onStateChange: (e) => { 127 if (!e.isVisible) { 128 this.customPopup = false 129 } 130 } 131 }) 132 .position({ x: 80, y: 200 }) 133 }.width('100%').padding({ top: 5 }) 134 } 135} 136``` 137 138 139 140### 示例2 141 142```ts 143// xxx.ets 144@Entry 145@Component 146struct PopupExample { 147 @State handlePopup: boolean = false 148 149 build() { 150 Column() { 151 Button('PopupOptions') 152 .onClick(() => { 153 this.handlePopup = !this.handlePopup 154 }) 155 .bindPopup(this.handlePopup, { 156 message: 'This is a popup with PopupOptions', 157 messageOptions: { 158 textColor: Color.Red, 159 font: { 160 size: '14vp', 161 style: FontStyle.Italic, 162 weight: FontWeight.Bolder 163 } 164 }, 165 placement: Placement.Bottom, 166 enableArrow: false, 167 targetSpace: '15vp', 168 onStateChange: (e) => { 169 console.info(JSON.stringify(e.isVisible)) 170 if (!e.isVisible) { 171 this.handlePopup = false 172 } 173 } 174 }) 175 }.margin(20) 176 } 177} 178``` 179 180 181 182### 示例3 183 184```ts 185// xxx.ets 186@Entry 187@Component 188struct PopupExample { 189 @State customPopup: boolean = false 190 191 // popup构造器定义弹框内容 192 @Builder popupBuilder() { 193 Row() { 194 Text('Custom Popup Message').fontSize(10) 195 }.height(50).padding(5) 196 } 197 198 build() { 199 Column() { 200 // CustomPopupOptions 类型设置弹框内容 201 Button('CustomPopupOptions') 202 .onClick(() => { 203 this.customPopup = !this.customPopup 204 }) 205 .bindPopup(this.customPopup, { 206 builder: this.popupBuilder, 207 targetSpace: '15vp', 208 enableArrow: false, 209 onStateChange: (e) => { 210 if (!e.isVisible) { 211 this.customPopup = false 212 } 213 } 214 }) 215 }.margin(20) 216 } 217} 218``` 219 220 221
