• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Class (OverlayManager)
2
3提供绘制浮层的能力。
4
5> **说明：**
6>
7> - 本模块首批接口从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8>
9> - 本Class首批接口从API version 12开始支持。
10>
11> - 以下API需先使用UIContext中的[getOverlayManager()](arkts-apis-uicontext-uicontext.md#getoverlaymanager12)方法获取到OverlayManager对象，再通过该对象调用对应方法。
12>
13> - OverlayManager上节点的层级在Page页面层级之上，在Dialog、Popup、Menu、BindSheet、BindContentCover和Toast等之下。
14>
15> - OverlayManager上节点安全区域内外的绘制方式与Page一致，键盘避让方式与Page一致。
16>
17> - 与OverlayManager相关的属性推荐采用AppStorage来进行应用全局存储，以免切换页面后属性值发生变化从而导致业务错误。
18
19## addComponentContent<sup>12+</sup>
20
21addComponentContent(content: ComponentContent, index?: number): void
22
23在OverlayManager上新增指定节点。
24
25**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
26
27**系统能力：** SystemCapability.ArkUI.ArkUI.Full
28
29**参数：**
30
31| 参数名     | 类型                                       | 必填   | 说明          |
32| ------- | ---------------------------------------- | ---- | ----------- |
33| content | [ComponentContent](js-apis-arkui-ComponentContent.md) | 是    | 在OverlayManager上新增指定节点上添加此content。 <br>**说明：** <br/> 新增的节点默认处于页面居中，按层级堆叠。|
34| index | number | 否    | 新增节点在OverlayManager上的层级位置。<br>**说明：** <br/> 当index ≥ 0时，越大，ComponentContent的层级越高；若多个ComponentContent的index相同，ComponentContent添加的时间越晚层级越高。<br/> 当index < 0、index = null或index = undefined时，ComponentContent默认添加至最高层。<br/>当同一个ComponentContent被添加多次时，只保留最后一次添加的ComponentContent。
35
36**示例：**
37
38```ts
39import { ComponentContent, OverlayManager } from '@kit.ArkUI';
40
41class Params {
42  text: string = "";
43  offset: Position;
44
45  constructor(text: string, offset: Position) {
46    this.text = text;
47    this.offset = offset;
48  }
49}
50
51@Builder
52function builderText(params: Params) {
53  Column() {
54    Text(params.text)
55      .fontSize(30)
56      .fontWeight(FontWeight.Bold)
57  }.offset(params.offset)
58}
59
60@Entry
61@Component
62struct OverlayExample {
63  @State message: string = 'ComponentContent';
64  private uiContext: UIContext = this.getUIContext();
65  private overlayNode: OverlayManager = this.uiContext.getOverlayManager();
66  @StorageLink('contentArray') contentArray: ComponentContent<Params>[] = [];
67  @StorageLink('componentContentIndex') componentContentIndex: number = 0;
68  @StorageLink('arrayIndex') arrayIndex: number = 0;
69  @StorageLink("componentOffset") componentOffset: Position = { x: 0, y: 80 };
70
71  build() {
72    Column() {
73      Button("++componentContentIndex: " + this.componentContentIndex).onClick(() => {
74        ++this.componentContentIndex;
75      })
76      Button("--componentContentIndex: " + this.componentContentIndex).onClick(() => {
77        --this.componentContentIndex;
78      })
79      Button("增加ComponentContent" + this.contentArray.length).onClick(() => {
80        let componentContent = new ComponentContent(
81          this.uiContext, wrapBuilder<[Params]>(builderText),
82          new Params(this.message + (this.contentArray.length), this.componentOffset)
83        );
84        this.contentArray.push(componentContent);
85        this.overlayNode.addComponentContent(componentContent, this.componentContentIndex);
86      })
87      Button("++arrayIndex: " + this.arrayIndex).onClick(() => {
88        ++this.arrayIndex;
89      })
90      Button("--arrayIndex: " + this.arrayIndex).onClick(() => {
91        --this.arrayIndex;
92      })
93      Button("删除ComponentContent" + this.arrayIndex).onClick(() => {
94        if (this.arrayIndex >= 0 && this.arrayIndex < this.contentArray.length) {
95          let componentContent = this.contentArray.splice(this.arrayIndex, 1);
96          this.overlayNode.removeComponentContent(componentContent.pop());
97        } else {
98          console.info("arrayIndex有误");
99        }
100      })
101      Button("显示ComponentContent" + this.arrayIndex).onClick(() => {
102        if (this.arrayIndex >= 0 && this.arrayIndex < this.contentArray.length) {
103          let componentContent = this.contentArray[this.arrayIndex];
104          this.overlayNode.showComponentContent(componentContent);
105        } else {
106          console.info("arrayIndex有误");
107        }
108      })
109      Button("隐藏ComponentContent" + this.arrayIndex).onClick(() => {
110        if (this.arrayIndex >= 0 && this.arrayIndex < this.contentArray.length) {
111          let componentContent = this.contentArray[this.arrayIndex];
112          this.overlayNode.hideComponentContent(componentContent);
113        } else {
114          console.info("arrayIndex有误");
115        }
116      })
117      Button("显示所有ComponentContent").onClick(() => {
118        this.overlayNode.showAllComponentContents();
119      })
120      Button("隐藏所有ComponentContent").onClick(() => {
121        this.overlayNode.hideAllComponentContents();
122      })
123
124      Button("跳转页面").onClick(() => {
125        this.getUIContext().getRouter().pushUrl({
126          url: 'pages/Second'
127        });
128      })
129    }
130    .width('100%')
131    .height('100%')
132  }
133}
134```
135
136## addComponentContentWithOrder<sup>18+</sup>
137
138addComponentContentWithOrder(content: ComponentContent, levelOrder?: LevelOrder): void
139
140创建浮层节点时，指定显示顺序。
141
142支持在浮层节点创建时指定显示的顺序。
143
144**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
145
146**系统能力：** SystemCapability.ArkUI.ArkUI.Full
147
148**参数：**
149
150| 参数名     | 类型                                       | 必填   | 说明          |
151| ------- | ---------------------------------------- | ---- | ----------- |
152| content | [ComponentContent](js-apis-arkui-ComponentContent.md) | 是    | 在OverlayManager上新增指定节点上添加此content。 <br>**说明：** <br/> 新增的节点默认处于页面居中位置，按层级堆叠。|
153| levelOrder | [LevelOrder](js-apis-promptAction.md#levelorder18) | 否    | 新增浮层节点的显示顺序。<br />**说明：**<br />- 默认值：LevelOrder.clamp(0)|
154
155**示例：**
156
157该示例通过调用addComponentContentWithOrder接口，实现了按照指定显示顺序创建浮层节点的功能。
158
159```ts
160import { ComponentContent, PromptAction, LevelOrder, UIContext, OverlayManager } from '@kit.ArkUI';
161
162class Params {
163  text: string = "";
164  offset: Position;
165  constructor(text: string, offset: Position) {
166    this.text = text;
167    this.offset = offset;
168  }
169}
170@Builder
171function builderText(params: Params) {
172  Column() {
173    Text(params.text)
174      .fontSize(30)
175      .fontWeight(FontWeight.Bold)
176  }.offset(params.offset)
177}
178
179@Entry
180@Component
181struct Index {
182  @State message: string = '弹窗';
183  private ctx: UIContext = this.getUIContext();
184  private promptAction: PromptAction = this.ctx.getPromptAction();
185  private overlayNode: OverlayManager = this.ctx.getOverlayManager();
186  @StorageLink('contentArray') contentArray: ComponentContent<Params>[] = [];
187  @StorageLink('componentContentIndex') componentContentIndex: number = 0;
188  @StorageLink('arrayIndex') arrayIndex: number = 0;
189  @StorageLink("componentOffset") componentOffset: Position = { x: 0, y: 80 };
190
191  build() {
192    Row() {
193      Column({ space: 10 }) {
194        Button('OverlayManager下面弹窗')
195          .fontSize(20)
196          .onClick(() => {
197            let componentContent = new ComponentContent(
198              this.ctx, wrapBuilder<[Params]>(builderText),
199              new Params(this.message + (this.contentArray.length), this.componentOffset)
200            );
201            this.contentArray.push(componentContent);
202            this.overlayNode.addComponentContentWithOrder(componentContent, LevelOrder.clamp(100.1));
203            let topOrder: LevelOrder = this.promptAction.getTopOrder();
204            if (topOrder !== undefined) {
205              console.error('topOrder: ' + topOrder.getOrder());
206            }
207            let bottomOrder: LevelOrder = this.promptAction.getBottomOrder();
208            if (bottomOrder !== undefined) {
209              console.error('bottomOrder: ' + bottomOrder.getOrder());
210            }
211          })
212        Button('OverlayManager上面弹窗')
213          .fontSize(20)
214          .onClick(() => {
215            let componentContent = new ComponentContent(
216              this.ctx, wrapBuilder<[Params]>(builderText),
217              new Params(this.message + (this.contentArray.length), this.componentOffset)
218            );
219            this.contentArray.push(componentContent);
220            this.overlayNode.addComponentContentWithOrder(componentContent, LevelOrder.clamp(100.2));
221            let topOrder: LevelOrder = this.promptAction.getTopOrder();
222            if (topOrder !== undefined) {
223              console.error('topOrder: ' + topOrder.getOrder());
224            }
225            let bottomOrder: LevelOrder = this.promptAction.getBottomOrder();
226            if (bottomOrder !== undefined) {
227              console.error('bottomOrder: ' + bottomOrder.getOrder());
228            }
229          })
230      }.width('100%')
231    }.height('100%')
232  }
233}
234```
235
236## removeComponentContent<sup>12+</sup>
237
238removeComponentContent(content: ComponentContent): void
239
240删除overlay上的指定节点。
241
242**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
243
244**系统能力：** SystemCapability.ArkUI.ArkUI.Full
245
246**参数：**
247
248| 参数名     | 类型                                       | 必填   | 说明          |
249| ------- | ---------------------------------------- | ---- | ----------- |
250| content | [ComponentContent](js-apis-arkui-ComponentContent.md) | 是    | 在OverlayManager上删除此content。 |
251
252**示例：**
253
254请参考[addComponentContent示例](#addcomponentcontent12)。
255
256## showComponentContent<sup>12+</sup>
257
258showComponentContent(content: ComponentContent): void
259
260在OverlayManager上显示指定节点。
261
262**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
263
264**系统能力：** SystemCapability.ArkUI.ArkUI.Full
265
266**参数：**
267
268| 参数名     | 类型                                       | 必填   | 说明          |
269| ------- | ---------------------------------------- | ---- | ----------- |
270| content | [ComponentContent](js-apis-arkui-ComponentContent.md) | 是    | 在OverlayManager上显示此content。|
271
272**示例：**
273
274请参考[addComponentContent示例](#addcomponentcontent12)。
275
276## hideComponentContent<sup>12+</sup>
277
278hideComponentContent(content: ComponentContent): void
279
280隐藏OverlayManager上的指定节点。
281
282**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
283
284**系统能力：** SystemCapability.ArkUI.ArkUI.Full
285
286**参数：**
287
288| 参数名     | 类型                                       | 必填   | 说明          |
289| ------- | ---------------------------------------- | ---- | ----------- |
290| content | [ComponentContent](js-apis-arkui-ComponentContent.md) | 是    | 在OverlayManager上隐藏此content。 |
291
292**示例：**
293
294请参考[addComponentContent示例](#addcomponentcontent12)。
295
296## showAllComponentContents<sup>12+</sup>
297
298showAllComponentContents(): void
299
300显示OverlayManager上所有的ComponentContent。
301
302**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
303
304**系统能力：** SystemCapability.ArkUI.ArkUI.Full
305
306**示例：**
307
308请参考[addComponentContent示例](#addcomponentcontent12)。
309
310## hideAllComponentContents<sup>12+</sup>
311
312hideAllComponentContents(): void
313
314隐藏OverlayManager上的所有ComponentContent。
315
316**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
317
318**系统能力：** SystemCapability.ArkUI.ArkUI.Full
319
320**示例：**
321
322请参考[addComponentContent示例](#addcomponentcontent12)。
323