From 626c2bc64d0ef1b37dcf70f2bed074c954267484 Mon Sep 17 00:00:00 2001 From: kuiwu Date: Thu, 7 Sep 2023 11:43:54 +0800 Subject: [PATCH] chore: add submenus docs --- docs/extension/contributes/menubars.zh.md | 2 +- docs/extension/contributes/submenus.en.md | 114 +++++++++++++++++++++ docs/extension/contributes/submenus.zh.md | 116 ++++++++++++++++++++++ 3 files changed, 231 insertions(+), 1 deletion(-) create mode 100644 docs/extension/contributes/submenus.en.md create mode 100644 docs/extension/contributes/submenus.zh.md diff --git a/docs/extension/contributes/menubars.zh.md b/docs/extension/contributes/menubars.zh.md index 04eb955d..6a08f7c1 100644 --- a/docs/extension/contributes/menubars.zh.md +++ b/docs/extension/contributes/menubars.zh.md @@ -55,4 +55,4 @@ interface IContributedMenubarItem { ![Sample](https://img.alicdn.com/imgextra/i2/O1CN01VLQjCz1iP598hWLQO_!!6000000004404-2-tps-1000-397.png) -其余菜单注册，可见：[Menus 贡献点](https://code.visualstudio.com/api/references/contribution-points#contributes.menus) +常规菜单注册，可见：[Menus 贡献点](https://code.visualstudio.com/api/references/contribution-points#contributes.menus) diff --git a/docs/extension/contributes/submenus.en.md b/docs/extension/contributes/submenus.en.md new file mode 100644 index 00000000..37629e94 --- /dev/null +++ b/docs/extension/contributes/submenus.en.md @@ -0,0 +1,114 @@ +--- +id: submenus +title: SubMenus +slug: submenus +order: 3 +--- + +> Contribute submenu items via `sumiContributes` + +When you need to register a secondary menu, you can register your menubar item through the `sumiContributes` field in `package.json`, where the data structure is as follows: + +```typescript +interface IContributedSubmenuItem { + id: string; // As the menu-id of submenu-id, you can contribute menu items here through menus + title: string; // display text + group?: string; + icon: { + light: string; + dark: string; + }; +} +``` + +Among them, id, title and icon are required items, and group is an optional item, which is used to define the grouping of the menu. + +## Example + +Use the below contributes: + +```json +{ + "sumiContributes": { + "submenus": { + "git_clone_menubar": [ + { + "id": "my_submenu_1", + "title": "%command.init%" + } + ], + "tabbar/bottom/common": [ + { + "id": "my_submenu_2", + "title": "%command.openRepository%", + "group": "navigation", + "icon": { + "light": "resources/icons/light/git.svg", + "dark": "resources/icons/dark/git.svg" + } + } + ], + "settings/icon/menu": [ + { + "id": "my_submenu_3", + "title": "%command.openRepository%", + "group": "navigation" + } + ] + }, + "menubars": [ + { + "id": "git_clone_menubar", + "title": "%command.clone%", + "order": 10 + } + ], + "menus": { + "git_clone_menubar": [ + { + "command": "git.init", + "group": "navigation", + "when": "config.git.enabled && !scmProvider && gitOpenRepositoryCount == 0 && workspaceFolderCount != 0" + } + ], + "my_submenu_1": [ + { + "command": "git.close", + "group": "navigation" + } + ], + "my_submenu_2": [ + { + "command": "git.commit", + "group": "navigation", + "when": "scmProvider == git" + } + ], + "my_submenu_3": [ + { + "command": "git.stageAll", + "group": "1_modification" + } + ] + } + } +} +``` + +The registration effect under `tabbar/common/bottom` position in the bottom panel: + +![Bottom](https://img.alicdn.com/imgextra/i3/O1CN01yBuGjj1CwS88iXbih_!!6000000000145-2-tps-364-346.png) + +Set the registration effect under the position of the button `settings/icon/menu`: + +![Settings](https://img.alicdn.com/imgextra/i4/O1CN011kzOGr1fzm26GGINk_!!6000000004078-2-tps-400-216.png) + +Registration effect under `tabbar/bottom/common` position in the top TabBar area: + +![TabBar](https://img.alicdn.com/imgextra/i1/O1CN01smMtJR1krb2T7rYs9_!!6000000004737-0-tps-500-675.jpg) + +Actual business application effect (custom registration point): + +![Custom](https://img.alicdn.com/imgextra/i1/O1CN0110UjX71G8JELfZ9sT_!!6000000000577-2-tps-710-400.png) + +General menu registration, see: [Menus Contribution Points](https://code.visualstudio.com/api/references/contribution-points#contributes.menus) diff --git a/docs/extension/contributes/submenus.zh.md b/docs/extension/contributes/submenus.zh.md new file mode 100644 index 00000000..3124edeb --- /dev/null +++ b/docs/extension/contributes/submenus.zh.md @@ -0,0 +1,116 @@ +--- +id: submenus +title: SubMenus +slug: submenus +order: 3 +--- + +> 通过 `sumiContributes`  贡献 子菜单(submenu) 项 + +## 如何注册 + +需要注册二级菜单时，可以通过 `package.json` 中的  `sumiContributes`  字段来注册你的 menubar 项，其中数据结构如下： + +```typescript +interface IContributedSubmenuItem { + id: string; // 作为 submenu-id 的 menu-id, 后续可通过 menus 往这里贡献菜单项 + title: string; // 展示的文案 + group?: string; + icon: { + light: string; + dark: string; + }; +} +``` + +其中 id 、title 和 icon 是必填项，group 是选填项，用于定义菜单的分组。 + +### 案例展示 + +以下面注册为例 + +```json +{ + "sumiContributes": { + "submenus": { + "git_clone_menubar": [ + { + "id": "my_submenu_1", + "title": "%command.init%" + } + ], + "tabbar/bottom/common": [ + { + "id": "my_submenu_2", + "title": "%command.openRepository%", + "group": "navigation", + "icon": { + "light": "resources/icons/light/git.svg", + "dark": "resources/icons/dark/git.svg" + } + } + ], + "settings/icon/menu": [ + { + "id": "my_submenu_3", + "title": "%command.openRepository%", + "group": "navigation" + } + ] + }, + "menubars": [ + { + "id": "git_clone_menubar", + "title": "%command.clone%", + "order": 10 + } + ], + "menus": { + "git_clone_menubar": [ + { + "command": "git.init", + "group": "navigation", + "when": "config.git.enabled && !scmProvider && gitOpenRepositoryCount == 0 && workspaceFolderCount != 0" + } + ], + "my_submenu_1": [ + { + "command": "git.close", + "group": "navigation" + } + ], + "my_submenu_2": [ + { + "command": "git.commit", + "group": "navigation", + "when": "scmProvider == git" + } + ], + "my_submenu_3": [ + { + "command": "git.stageAll", + "group": "1_modification" + } + ] + } + } +} +``` + +底部面板 `tabbar/common/bottom` 位置下的注册效果： + +![Bottom](https://img.alicdn.com/imgextra/i3/O1CN01yBuGjj1CwS88iXbih_!!6000000000145-2-tps-364-346.png) + +设置按钮 `settings/icon/menu`  位置下的注册效果： + +![Settings](https://img.alicdn.com/imgextra/i4/O1CN011kzOGr1fzm26GGINk_!!6000000004078-2-tps-400-216.png) + +顶部 TabBar 区域 `tabbar/bottom/common` 位置下的注册效果： + +![TabBar](https://img.alicdn.com/imgextra/i1/O1CN01smMtJR1krb2T7rYs9_!!6000000004737-0-tps-500-675.jpg) + +实际业务应用效果（自定义注册点）： + +![Custom](https://img.alicdn.com/imgextra/i1/O1CN0110UjX71G8JELfZ9sT_!!6000000000577-2-tps-710-400.png) + +常规菜单注册，可见：[Menus 贡献点](https://code.visualstudio.com/api/references/contribution-points#contributes.menus)