@imengyu/vue3-context-menu 1.1.1 → 1.1.3

package/README.CN.md

@@ -17,7 +17,7 @@
 
 ### ❗ 重大升级
 
-版本 1.1.0 做了很大升级，可能会存在与之前版本不兼容的情况，如果出现问题，请安装 1.0.9 版本。
+版本 1.1.0 做了很大升级，如果您从之前的版本升级过来，可能会存在与之前版本不兼容的情况，你需要参考文档修改菜单的数据格式。如果出现问题，请安装 1.0.9 版本。
 
 ## 安装
 
@@ -42,9 +42,11 @@ createApp(App).use(ContextMenu)
 
 显示菜单有两种方式：
 
-第一种是函数模式，可以使用 `this.$contextmenu` 通过菜单数据显示一个右键菜单：
+第一种是函数模式，可以使用 `this.$contextmenu` 或者 `showContextMenu` 全局函数，通过菜单数据显示一个右键菜单：
 
 ```js
+import ContextMenu from '@imengyu/vue3-context-menu'
+
 onContextMenu(e : MouseEvent) {
   //prevent the browser's default menu
   e.preventDefault();
@@ -69,6 +71,9 @@ onContextMenu(e : MouseEvent) {
       },
     ]
   });
+
+  //这个函数与 this.$contextmenu 一致
+  ContextMenu.showContextMenu({ ... }); 
 }
 ```
 
@@ -95,30 +100,6 @@ onContextMenu(e : MouseEvent) {
 data() {
   return {
     show: false,
-    //For $contextmenu
-    options: {
-      items:[
-        {
-          label: "Copy",
-          onClick: () => {
-            document.execCommand('copy');
-          }
-        },
-        { label: "Paste", disabled: true },
-        {
-          label: "Print",
-          icon: 'icon-print',
-          onClick: () => {
-            document.execCommand('print');
-          }
-        },
-      ],
-      iconFontClass: 'iconfont',
-      customClass: "class-a",
-      minWidth: 230,
-      x: 0,
-      y: 0
-    },
     //For component
     optionsComopnent: {
       zIndex: 3,
@@ -140,9 +121,46 @@ methods: {
 
 ## 菜单图标
 
-菜单组件不提供任何图标，如果您想添加图标，推荐使用 [iconfont](http://iconfont.cn) 图标库，导入后填写 MenuItem 的 icon 属性，即可在菜单项前面显示图标。
+菜单组件不提供任何图标，如果您想添加图标，推荐使用 [iconfont](http://iconfont.cn) 图标库。
+
+### 字体图标
+
+使用 iconfont 图标库，导入字体后填写 `MenuItem` 的 `icon` 属性，即可在菜单项前面显示图标。
+
+* 如果字体名称不一样，可用 `MenuItem` 或者 `MenuOptions` 的 `iconFontClass` 属性指定其他字体。
+* 默认使用 `<i>` 元素来显示图标。
+
+### SVG 图标
+
+支持使用 svg symbol 来显示图标：
 
-*默认使用 `<i>` 元素来显示图标。*
+```html
+<svg viewBox="0 0 80 20" xmlns="http://www.w3.org/2000/svg">
+  <!-- Your icon -->
+  <symbol id="icon-multiply" viewBox="0 0 1024 1024">
+    <path d="M512 64C264.608 64 64 264.608 64 512c0 247.36 200.608 448 448 448 247.36 0 448-200.64 448-448 0-247.392-200.64-448-448-448z m158.4 651.552L512 557.312l-158.4 158.24-45.312-45.248L466.688 512l-158.304-158.4 45.312-45.312L512 466.688l158.4-158.4 45.28 45.312L557.312 512l158.368 158.4-45.28 45.152z" fill="#F74A21"></path>
+  </symbol>
+</svg>
+```
+
+```js
+this.$contextmenu({
+  items: [
+    { 
+      label: "Item with svg icon",
+      svgIcon: "#icon-multiply",
+      svgProps: {
+        fill: '#f60',
+      },
+    },
+  ],
+  //...省略
+} as MenuOptions);
+```
+
+> 注：使用 iconfont 库导出的图标库，会附带 `iconfont.js` ，你只需要在 html 中引入这个js，他会自动为你导入所有的 svg symbol，你可直接复制图标名称使用。
+
+### 自定义渲染
 
 你也可以通过菜单的插槽来完全自定义渲染图标，如：
 
@@ -174,6 +192,8 @@ methods: {
 在函数模式自定义图标：
 
 ```js
+import { h } from 'vue';
+
 { 
   label: "Item with custom icon render",
   icon: h('img', {
@@ -198,7 +218,7 @@ import '你的样式css文件路径.css'
 
 ## 自定义渲染
 
-菜单提供了一些插槽，允许你自定义渲染某些部分，具体您可以参考案例源码 [examples\views\BasicCustomize.vue](examples\views\BasicCustomize.vue) [examples\views\ComponentCustomize.vue](examples\views\ComponentCustomize.vue)。
+菜单提供了一些插槽，允许你自定义渲染某些部分，具体您可以参考案例源码 [examples/views/BasicCustomize.vue](examples/views/BasicCustomize.vue) [examples/views/ComponentCustomize.vue](examples/views/ComponentCustomize.vue)。
 
 ## API 参考
 
@@ -236,10 +256,14 @@ import '你的样式css文件路径.css'
 | 属性名 | 描述 | 类型 |
 | :----: | :----: | :----: |
 | theme | 菜单主题 | `'light' 'dark'` |
+| isOpen | 指示当前菜单子菜单是否处于打开状态 | `boolean` |
+| hasChildren | 指示当前菜单是否有子级菜单 | `boolean` |
 | onClick | 自定义元素的点击事件回调，它用于菜单内部事件处理，当自定义渲染时，请回调此函数，否则菜单无法正常响应事件 | - |
 | onMouseEnter | 自定义元素的鼠标移入事件回调，它用于菜单内部事件处理，当自定义渲染时，请回调此函数，否则菜单无法正常响应事件 | - |
 | ... | 其他参数与 `MenuItem` 一致 | - |
 
+---
+
 #### ContextMenuItem
 
 菜单条目组件。
@@ -250,6 +274,9 @@ import '你的样式css文件路径.css'
 | :----: | :----: | :----: | :----: |
 | label | 菜单项名称 | `string` | — |
 | icon | 菜单项图标 | `string` | — |
+| iconFontClass | 自定义图标字体类名 | `string` | — | `iconfont` |
+| svgIcon | 菜单项图标 svg，仅在 icon 为空时有效 | `string` | — | — |
+| svgProps | 当使用 svg 图标时，自定义 svg 标签属性 | `SVGAttributes` | — | — |
 | disabled | 是否禁用菜单项 | `boolean` | `false` |
 | clickableWhenHasChildren | 指定当本菜单下有子菜单时，点击当前菜单是否触发点击事件 | `boolean` | `false` |
 | clickClose | 点击当前菜单项是否自动关闭整个菜单 | `boolean` | `true` |
@@ -271,6 +298,8 @@ import '你的样式css文件路径.css'
 | :----: | :----: | :----: |
 | click | 点击菜单时触发此事件 | - |
 
+---
+
 #### ContextMenuGroup
 
 子菜单组件。
@@ -281,6 +310,9 @@ import '你的样式css文件路径.css'
 | :----: | :----: | :----: | :----: |
 | label | 菜单项名称 | `string` | — |
 | icon | 菜单项图标 | `string` | — |
+| iconFontClass | 自定义图标字体类名 | `string` | — | `iconfont` |
+| svgIcon | 菜单项图标 svg，仅在 icon 为空时有效 | `string` | — | — |
+| svgProps | 当使用 svg 图标时，自定义 svg 标签属性 | `SVGAttributes` | — | — |
 | disabled | 是否禁用菜单项 | `boolean` | `false` |
 | clickableWhenHasChildren | 指定当本菜单下有子菜单时，点击当前菜单是否触发点击事件 | `boolean` | `false` |
 | adjustSubMenuPosition | 是否在子菜单超出屏幕后进行自动调整 | `boolean` | `true` |
@@ -296,12 +328,35 @@ import '你的样式css文件路径.css'
 | :----: | :----: | :----: |
 | default | 子菜单渲染插槽 | - |
 
+---
+
 #### ContextMenuSperator
 
 菜单分隔符组件。
 
+---
+
 ### 函数模式：参数说明
 
+#### 全局函数
+
+* `ContextMenu.showContextMenu(options: MenuOptions, customSlots?: Record<string, Slot>)`
+
+  显示菜单.
+
+  | 参数 | 说明 |
+  | :----: | :----: |
+  | options | 菜单的数据 |
+  | customSlots | 这些插槽允许您自定义当前菜单的样式，这些插槽的名称与 [组件模式](#ContextMenu) 中的插槽名称相同 |
+
+* `ContextMenu.closeContextMenu()`
+
+  手动关闭当前打开的菜单.
+
+* `this.$contextmenu`
+
+  与 `ContextMenu.showContextMenu` 相同，但此函数注册到 Vue 全局属性中，可以在Vue实例中直接使用。
+
 #### MenuOptions
 
 | 属性 | 描述 | 类型 | 可选值 | 默认值 |
@@ -325,6 +380,9 @@ import '你的样式css文件路径.css'
 | :----: | :----: | :----: | :----: | :----: |
 | label | 菜单项名称，可传入VNode | `string` or `VNode` or `((label: string) => VNode)` | — | — |
 | icon | 菜单项图标，可传入VNode | `string` or `VNode` or `((icon: string) => VNode)` | — | — |
+| iconFontClass | 自定义图标字体类名 | `string` | — | `iconfont` |
+| svgIcon | 菜单项图标 svg，仅在 icon 为空时有效 | `string` | — | — |
+| svgProps | 当使用 svg 图标时，自定义 svg 标签属性 | `SVGAttributes` | — | — |
 | disabled | 是否禁用菜单项 | `boolean` | — | `false` |
 | adjustSubMenuPosition | 是否在子菜单超出屏幕后进行自动调整 | `boolean` | — | `true` |
 | clickableWhenHasChildren | 指定当本菜单下有子菜单时，点击当前菜单是否触发点击事件 | `boolean` | — | `false` |

package/README.md

@@ -44,9 +44,11 @@ createApp(App).use(ContextMenu)
 
 There are two ways to display menus:
 
-The first is the function mode. You can use  `this.$contextmenu` displays a menu through menu data:
+The first is the function mode. You can use  `this.$contextmenu` or `showContextMenu` global function displays a menu through menu data:
 
 ```js
+import ContextMenu from '@imengyu/vue3-context-menu'
+
 onContextMenu(e : MouseEvent) {
   //prevent the browser's default menu
   e.preventDefault();
@@ -71,6 +73,9 @@ onContextMenu(e : MouseEvent) {
       },
     ]
   });
+
+  //Same as this.$contextmenu
+  ContextMenu.showContextMenu({ ... }); 
 }
 ```
 
@@ -97,31 +102,6 @@ The second is the component mode. You can use the component and template to disp
 data() {
   return {
     show: false,
-    //For $contextmenu
-    options: {
-      items:[
-        {
-          label: "Copy",
-          onClick: () => {
-            document.execCommand('copy');
-          }
-        },
-        { label: "Paste", disabled: true },
-        {
-          label: "Print",
-          icon: 'icon-print',
-          onClick: () => {
-            document.execCommand('print');
-          }
-        },
-      ],
-      iconFontClass: 'iconfont',
-      customClass: "class-a",
-      minWidth: 230,
-      x: 0,
-      y: 0
-    },
-    //For component
     optionsComopnent: {
       zIndex: 3,
       minWidth: 230,
@@ -142,11 +122,50 @@ methods: {
 
 ## Menu icon
 
-The menu component does not provide any icons. If you want to add an icon, it is recommended to use [iconfont](http://iconfont.cn) Icon library. After importing, fill in the `icon` attribute of MenuItem to display the icon in front of the menu item.
+The menu component does not provide any icons. If you want to add an icon, it is recommended to use [iconfont](http://iconfont.cn) Icon library.
 
-*By default, the `<i>`  element is used to display icons*
+### Font icon
 
----
+Use iconfont library: After importing, fill in the `icon` attribute of `MenuItem` to display the icon in front of the menu item.
+
+* If the font names are different, you can specify other fonts by writing the `iconFontClass` attribute of `MenuItem` or `MenuOptions`.
+* By default, the `<i>`  element is used to display icons
+
+### SVG Icon
+
+Support the use of svg `<symbol>` to display icons:
+
+```html
+<svg viewBox="0 0 80 20" xmlns="http://www.w3.org/2000/svg">
+  <!-- Your icon -->
+  <symbol id="icon-multiply" viewBox="0 0 1024 1024">
+    <path d="M512 64C264.608 64 64 264.608 64 512c0 247.36 200.608 448 448 448 247.36 0 448-200.64 448-448 0-247.392-200.64-448-448-448z m158.4 651.552L512 557.312l-158.4 158.24-45.312-45.248L466.688 512l-158.304-158.4 45.312-45.312L512 466.688l158.4-158.4 45.28 45.312L557.312 512l158.368 158.4-45.28 45.152z" fill="#F74A21"></path>
+  </symbol>
+</svg>
+```
+
+```js
+//Function mode
+this.$contextmenu({
+  items: [
+    { 
+      label: "Item with svg icon",
+      svgIcon: "#icon-multiply",
+      svgProps: {
+        fill: '#f60',
+      },
+    },
+  ],
+  //...
+} as MenuOptions);
+```
+
+```js
+//Component mode
+<context-menu-item label="Item with svg icon" svgIcon="#icon-multiply" :svgProps="{ fill: '#f60' }" />
+```
+
+### Customize icon
 
 You can also completely customize the rendering icon through the slot of the menu, such as:
 
@@ -176,6 +195,8 @@ Customize the icon of the entire menu:
 Customize icon in function mode:
 
 ```js
+import { h } from 'vue';
+
 { 
   label: "Item with custom icon render",
   icon: h('img', {
@@ -199,7 +220,7 @@ import 'your-style-file-path.css'
 
 ## Customize
 
-The menu provides some slots that allow you to customize some parts of the rendering. For details, please refer to the example source code [examples\views\BasicCustomize.vue](examples\views\BasicCustomize.vue) [examples\views\ComponentCustomize.vue](examples\views\ComponentCustomize.vue)。
+The menu provides some slots that allow you to customize some parts of the rendering. For details, please refer to the example source code [examples/views/BasicCustomize.vue](examples/views/BasicCustomize.vue) [examples/views/ComponentCustomize.vue](examples/views/ComponentCustomize.vue)。
 
 ## API reference
 
@@ -237,10 +258,14 @@ Menu component.
 | Property | Description | Type |
 | :----: | :----: | :----: |
 | theme | Menu theme | `'light' 'dark'` |
+| isOpen | This value indicates whether the current menu submenu is open | `boolean` |
+| hasChildren | This value indicates whether the current menu has submenus | `boolean` |
 | onClick | Define the click event callback of the element, which is used for the internal event processing of the menu. When rendering item with slot, please call this function back, otherwise the menu cannot respond to the event normally | - |
 | onMouseEnter | Mouse in event callback of custom element. When rendering item with slot, please call this function back, otherwise the menu cannot respond to the event normally | - |
 | ... | Other arguments are same with `MenuItem` | - |
 
+---
+
 #### ContextMenuItem
 
 Menu item component.
@@ -251,6 +276,9 @@ Menu item component.
 | :----: | :----: | :----: | :----: |
 | label | The label of menu. | `string` | — |
 | icon | The icon for menu item. | `string` | — |
+| iconFontClass | Custom icon library font class name. | `string` | — | `iconfont` |
+| svgIcon | Display icons use svg symbol (`<use xlink:href="...">`) ， only valid when icon attribute is empty. | `string` | — | — |
+| svgProps | The user-defined attribute of the svg tag, which is valid when using `svgIcon`. | `SVGAttributes` | — | — |
 | disabled | Disable menu item? | `boolean` | `false` |
 | clickableWhenHasChildren | When there are subitems in this item, is it allowed to trigger its own click event? | `boolean` | `false` |
 | clickClose | Should close menu when Click this menu item ? | `boolean` | `true` |
@@ -272,6 +300,8 @@ Menu item component.
 | :----: | :----: | :----: |
 | click | This event is triggered when the click this menu item | - |
 
+---
+
 #### ContextMenuGroup
 
 Submenu component.
@@ -282,6 +312,9 @@ Submenu component.
 | :----: | :----: | :----: | :----: |
 | label | The label of menu. | `string` | — |
 | icon | The icon for menu item. | `string` | — |
+| iconFontClass | Custom icon library font class name. | `string` | — | `iconfont` |
+| svgIcon | Display icons use svg symbol (`<use xlink:href="...">`) ， only valid when icon attribute is empty. | `string` | — | — |
+| svgProps | The user-defined attribute of the svg tag, which is valid when using `svgIcon`. | `SVGAttributes` | — | — |
 | disabled | Disable menu item? | `boolean` | `false` |
 | clickableWhenHasChildren | When there are subitems in this item, is it allowed to trigger its own click event? | `boolean` | `false` |
 | adjustSubMenuPosition | Specifies should submenu adjust it position when the menu exceeds the screen.| `boolean` | `true` |
@@ -297,12 +330,35 @@ Submenu component.
 | :----: | :----: | :----: |
 | default | Submenu render slot | - |
 
+---
+
 #### ContextMenuSperator
 
 Menu separator component.
 
+---
+
 ### Function mode
 
+#### Global Function
+
+* `ContextMenu.showContextMenu(options: MenuOptions, customSlots?: Record<string, Slot>)`
+
+  Show context menu.
+
+  | Param | Description |
+  | :----: | :----: |
+  | options | The options of menu. |
+  | customSlots | These slots to allow you to customize the style of the current menu, the names of these slots are the same as those in the [component mode](#ContextMenu). |
+
+* `ContextMenu.closeContextMenu()`
+
+  Manually close the currently open context menu.
+
+* `this.$contextmenu`
+
+  Same as `ContextMenu.showContextMenu` but this function is registered to vue global property.
+
 #### MenuOptions
 
 | Property | Description | Type | Optional value | Default |
@@ -326,6 +382,9 @@ Menu separator component.
 | :----: | :----: | :----: | :----: | :----: |
 | label | The label of menu. | `string` or `VNode` or `((label: string) => VNode)` | — | — |
 | icon | The icon for menu item. | `string` or `VNode` or `((icon: string) => VNode)` | — | — |
+| iconFontClass | Custom icon library font class name. | `string` | — | `iconfont` |
+| svgIcon | Display icons use svg symbol (`<use xlink:href="...">`) ， only valid when icon attribute is empty. | `string` | — | — |
+| svgProps | The user-defined attribute of the svg tag, which is valid when using `svgIcon`. | `SVGAttributes` | — | — |
 | disabled | Disable menu item? | `boolean` | — | `false` |
 | adjustSubMenuPosition | Specifies should submenu adjust it position when the menu exceeds the screen. | `boolean` | — | `true` |
 | clickableWhenHasChildren | When there are subitems in this item, is it allowed to trigger its own click event? | `boolean` | — | `false` |

package/examples/index.html

@@ -6,8 +6,7 @@
     <meta name="viewport" content="width=device-width,initial-scale=1.0">
     <link rel="icon" href="<%= BASE_URL %>favicon.ico">
     <title><%= htmlWebpackPlugin.options.title %></title>
-    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.0.1/styles/default.min.css">
-    <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.0.1/highlight.min.js"></script>
+    <script src="https://imengyu.top/static/iconfont-small-test.js"></script>
   </head>
   <body>
     <noscript>
@@ -16,5 +15,7 @@
     <a href="https://github.com/imengyu/vue3-context-menu"><img style="position: absolute; top: 0; left: 0; border: 0; z-index: 100" src="https://camo.githubusercontent.com/82b228a3648bf44fc1163ef44c62fcc60081495e/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f6c6566745f7265645f6161303030302e706e67" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_left_red_aa0000.png"></a>
     <div id="app"></div>
     <!-- built files will be auto injected -->
+    <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.0.1/highlight.min.js"></script>
+    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.0.1/styles/default.min.css">
   </body>
 </html>

package/examples/views/BasicComponent.vue

@@ -87,7 +87,7 @@ export default defineComponent({
       hljs: {
         highlightAll: () => void
       }
-    }).hljs.highlightAll();
+    }).hljs?.highlightAll?.();
   },
   data() {
     return {

package/examples/views/BasicCustomize.vue

@@ -61,7 +61,7 @@ export default defineComponent({
       hljs: {
         highlightAll: () => void
       }
-    }).hljs.highlightAll();
+    }).hljs?.highlightAll?.();
   },
   methods: {
     onContextMenu(e : MouseEvent) {

package/examples/views/BasicUseage.vue

@@ -91,7 +91,7 @@ export default defineComponent({
       hljs: {
         highlightAll: () => void
       }
-    }).hljs.highlightAll();
+    }).hljs?.highlightAll?.();
   },
   methods: {
     test() {
@@ -140,7 +140,6 @@ export default defineComponent({
                   alert("You click Print");
                 } 
               },
-              
               { label: "View source", icon: "icon-terminal" },
               { label: "Inspect" }
             ],
@@ -206,6 +205,21 @@ export default defineComponent({
               },
             ]
           },
+          { 
+            label: 'Item with icon',
+            icon: "icon-reload-1",
+          },
+          { 
+            label: "Item with svg icon",
+            svgIcon: "#icon-clock",
+          },
+          { 
+            label: "Item with svg icon",
+            svgIcon: "#icon-multiply",
+            svgProps: {
+              fill: '#f60',
+            },
+          },
         ],
         iconFontClass: 'iconfont',
         customClass: "class-a",

package/index.d.ts

@@ -1,4 +1,4 @@
-import { App, Slot, VNode } from "vue";
+import { App, Slot, SVGAttributes, VNode } from "vue";
 
 declare module 'vue3-context-menu' {
 }
@@ -44,7 +44,7 @@ export declare interface MenuOptions {
    */
   customClass	?:	string,
   /**
-   * Custom icon library font class name.
+   * Custom icon library font class name. (global)
    */
   iconFontClass ?:	string,
   /**
@@ -73,6 +73,18 @@ export declare interface MenuItem {
    * The icon for menu item.
    */
   icon ?: string|VNode|((icon: string) => VNode),
+  /**
+   * Custom icon library font class name.
+   */
+  iconFontClass ?:	string,
+  /**
+   * Display icons use svg symbol (`<use xlink:href="...">`) ， only valid when icon attribute is empty.
+   */
+  svgIcon ?: string,
+  /**
+   * The user-defined attribute of the svg tag, which is valid when using `svgIcon`.
+   */
+  svgProps ?: SVGAttributes,
   /**
    * Disable menu item?
    */
@@ -125,6 +137,14 @@ export declare interface MenuItemRenderData extends Omit<MenuItem, 'children'|'c
    * Global theme
    */
   theme: 'light'|'dark',
+  /**
+   * This value indicates whether the current menu submenu is open
+   */
+  isOpen: boolean,
+  /**
+   * This value indicates whether the current menu has submenus
+   */
+  hasChildren: boolean,
   /**
    * Click event callback of custom element, which is used for menu internal event
    */