Home > SYS_HeaderMenu > insertSystemHeaderMenuItem

SYS_HeaderMenu.insertSystemHeaderMenuItem() method

This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Insert a system header menu item at the specified position

Signature

function insertSystemHeaderMenuItem(
	env: ESYS_HeaderMenuEnvironment,
	id: Array<string>,
	props: {
		title: string;
		registerFn?: undefined | string;
		menuItems?:
			undefined | (null | ISYS_HeaderMenuSub2MenuItem | ISYS_HeaderMenuSub1MenuItem)[];
		insertDividerBefore?: undefined | false | true;
		insertDividerAfter?: undefined | false | true;
		insertBefore?: undefined | string;
		crossDividerWhenInsert?: undefined | false | true;
	},
): Promise<string | undefined>;

Parameters

Parameter	Type	Description
env	ESYS_HeaderMenuEnvironment	Environment
id	Array<string>	Menu item ID tree. It will match menu items by hierarchy in array order and use the last element of the array as the ID of the menu item to insert
props	{ title: string; registerFn?: undefined | string; menuItems?: undefined | (null | ISYS_HeaderMenuSub2MenuItem | ISYS_HeaderMenuSub1MenuItem)[]; insertDividerBefore?: undefined | false | true; insertDividerAfter?: undefined | false | true; insertBefore?: undefined | string; crossDividerWhenInsert?: undefined | false | true }	Other parameters

Returns

Promise<string | undefined>

The ID of the header menu item. Whether a separator is inserted does not affect the return value of the operation. The IDs of sub-items in menuItems are not included

Remarks

This API adds a sub-menu under an existing system first-level menu. First-level menus cannot be added or modified. The id array should contain at least 2 values

This API forces the ID of the newly created system header menu to include the extension UUID. For example, an input id = 'example' will be automatically rewritten to e143d88179874e7f851cc890cd22fc71|example. To remove this menu later, enter the rewritten name

This API cannot add any sub-menu under the **Advanced** menu

Sub-menus added by this API are placed at the end of the original menu by default, unless the props.insertBefore parameter is specified

Note: This API requires the user to enable the extension external interaction permission, if not enabled, it will always throw Error

Non-public API usage notice: This API is provided as-is without additional documentation for parameters. Parameters may be changed in a breaking manner in any version without notice.

Example

// 1. 在 PCB 环境的 工具（Tools）菜单下插入子菜单项，并带上两个三级菜单项
const menuId = await eda.sys_HeaderMenu.insertSystemHeaderMenuItem('pcb', ['Tools', '嘉立创示例_扩展工具'], {
	title: '嘉立创示例 扩展工具',
	menuItems: [
		{ id: '嘉立创示例_打开面板', title: '打开扩展面板' },
		{ id: '嘉立创示例_扩展设置', title: '扩展设置' },
	],
});

// 2. 输出重写后的菜单 ID（真实扩展中通过 registerFn 指定点击回调）
console.log('插入的菜单 ID：', menuId);

// 3. 移除刚插入的菜单项还原菜单栏（同一 ID 重复插入会返回 undefined，
// 自建自删保证案例可重复运行）
const removed = await eda.sys_HeaderMenu.removeSystemHeaderMenuItem(['Tools', menuId]);
console.log('移除结果：', removed);