• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Global Menus Independent of UI Components (openMenu)
2
3The [Menu](arkts-popup-and-menu-components-menu.md) component is a great option for creating menus, but it relies on a bound UI component to work. Since API version 18, however, the global API [openMenu](../reference/apis-arkui/js-apis-arkui-UIContext.md#openmenu18) offers a more flexible solution. This API can be used directly or encapsulated in scenarios where no bound UI components are available, making it ideal for use cases such as event callbacks or when integrating with external systems.
4
5## Displaying a Menu
6
7To display a menu, call the [openMenu](../reference/apis-arkui/js-apis-arkui-UIContext.md#openmenu18) API. Here's a basic example:
8
9   ```ts
10   promptAction.openMenu(contentNode, { id: targetId }, {
11     enableArrow: true
12   })
13     .then(() => {
14       console.info('openMenu success');
15     })
16     .catch((err: BusinessError) => {
17       console.info('openMenu error: ' + err.code + ' ' + err.message);
18     })
19   ```
20
21### Creating a ComponentContent Instance
22
23   When using **openMenu**, you need to provide a [ComponentContent](../reference/apis-arkui/js-apis-arkui-ComponentContent.md) instance to define the menu content. **wrapBuilder(buildText)** encapsulates the custom component, and **new Params(this.message)** is the input parameter for the custom component. This parameter is optional and can be a basic data type.
24
25   ```ts
26   private contentNode: ComponentContent<Object> = new ComponentContent(uiContext, wrapBuilder(buildText), this.message);
27   ```
28
29   If your **wrapBuilder** includes other components (such as [Popup](../reference/apis-arkui/arkui-ts/ohos-arkui-advanced-Popup.md#popup) or [Chip](../reference/apis-arkui/arkui-ts/ohos-arkui-advanced-Chip.md#chip)), the [ComponentContent](../reference/apis-arkui/js-apis-arkui-ComponentContent.md#componentcontent-1) constructor must include four parameters, and the **options** parameter must be **{ nestingBuilderSupported: true }**.
30
31   ```ts
32   @Builder
33   export function buildText(params: Params) {
34     Menu({
35       // Set the icon for the menu.
36       icon: {
37         image: $r('app.media.app_icon'),
38         width: 32,
39         height: 32,
40         fillColor: Color.White,
41         borderRadius: 10
42       } as MenuIconOptions,
43       // Set the text content.
44       title: {
45         text: `This is a Menu title 1`,
46         fontSize: 20,
47         fontColor: Color.Black,
48         fontWeight: FontWeight.Normal
49       } as MenuTextOptions,
50       // Set the text content.
51       message: {
52         text: `This is a Menu message 1`,
53         fontSize: 15,
54         fontColor: Color.Black
55       } as MenuTextOptions,
56       // Set the buttons.
57       buttons: [{
58         text: 'confirm',
59         action: () => {
60           console.info('confirm button click')
61         },
62         fontSize: 15,
63         fontColor: Color.Black,
64       },
65         {
66           text: 'cancel',
67           action: () => {
68             console.info('cancel button click')
69           },
70           fontSize: 15,
71           fontColor: Color.Black
72         },] as [MenuButtonOptions?, MenuButtonOptions?]
73     })
74   }
75
76   let contentNode: ComponentContent<Object> = new ComponentContent(uiContext, wrapBuilder(buildText), this.message, { nestingBuilderSupported: true });
77   ```
78
79
80### Providing Bound Component Information
81
82   When calling **openMenu**, you must provide the [TargetInfo](../reference/apis-arkui/js-apis-arkui-UIContext.md#targetinfo18) of the bound component. Without a valid target, the menu won't display.
83
84   ```ts
85   let frameNode: FrameNode | null = this.ctx.getFrameNodeByUniqueId(this.getUniqueId());
86   let targetId = frameNode?.getChild(0)?.getUniqueId();
87   ```
88
89### Customizing the Menu Style
90
91   When calling **openMenu**, you can customize the menu style using [MenuOptions](../reference/apis-arkui/arkui-ts/ts-universal-attributes-menu.md#menuoptions10). Note that the **title** property is not effective, and the **preview** parameter supports only the **MenuPreviewMode** type.
92
93   ```ts
94   private options: MenuOptions = { enableArrow: true, placement: Placement.Bottom };
95   ```
96
97## Updating the Menu Style
98
99To update the menu style, use the [updateMenu](../reference/apis-arkui/js-apis-arkui-UIContext.md#updatemenu18) API. You can update the style fully or incrementally. However, certain properties, including **showInSubWindow**, **preview**, **previewAnimationOptions**, **transition**, **onAppear**, **aboutToAppear**, **onDisappear**, and **aboutToDisappear**, cannot be updated.
100
101   ```ts
102   promptAction.updateMenu(contentNode, {
103     enableArrow: false
104   }, true)
105     .then(() => {
106       console.info('updateMenu success');
107     })
108     .catch((err: BusinessError) => {
109       console.info('updateMenu error: ' + err.code + ' ' + err.message);
110     })
111   ```
112
113## Closing the Menu
114
115To close the menu, call the [closeMenu](../reference/apis-arkui/js-apis-arkui-UIContext.md#closemenu18) API.
116
117   ```ts
118   promptAction.closeMenu(contentNode)
119     .then(() => {
120       console.info('openMenu success');
121     })
122    .catch((err: BusinessError) => {
123      console.info('openMenu error: ' + err.code + ' ' + err.message);
124    })
125   ```
126
127> **NOTE**
128>
129> The [updateMenu](../reference/apis-arkui/js-apis-arkui-UIContext.md#updatemenu18) and [closeMenu](../reference/apis-arkui/js-apis-arkui-UIContext.md#closemenu18) APIs rely on the content to identify the menu. Therefore, you must maintain the content instance throughout the menu's lifecycle.
130
131## Using the Global Menu in HAR Packages
132
133You can encapsulate a menu using the [HAR](../quick-start/har-package.md) package to provide display, update, and close capabilities.
134
135For details about how to invoke these capabilities, see [Using the Global Popup in HAR Packages](./arkts-popup-and-menu-components-uicontext-popup.md#using-the-global-popup-in-har-packages).
136