@imengyu/vue3-context-menu 1.0.9 → 1.1.0

package/README.CN.md

@@ -1,45 +1,54 @@
 
-vue3-context-menu
----
+# vue3-context-menu
+
 一个使用 Vue3 制作的简洁美观简单的右键菜单组件
 
 ![截图](https://raw.githubusercontent.com/imengyu/vue3-context-menu/main/screenshot/first.png)
 
 ---
 
-[查看演示](https://imengyu.top/pages/vue3-context-menu-demo/) 
+[查看在线演示](https://imengyu.top/pages/vue3-context-menu-demo/)
 
----
+## 特性
 
-### 安装
+* 简洁易用，体积小
+* 提供组件模式和函数模式，调用方便
+* 可自定义
 
-```
+### ❗ 重大升级
+
+版本 1.1.0 做了很大升级，可能会存在与之前版本不兼容的情况，如果出现问题，请安装 1.0.9 版本。
+
+## 安装
+
+```shell
 npm install -save @imengyu/vue3-context-menu
 ```
 
-### 使用
+## 使用
+
+使用前建议您查看 [examples](examples/) 源码，它提供了多种详细的使用方法，可能会对您的使用很有帮助 😀.
+
+### 导入组件
 
-导入组件：
 ```js
 import '@imengyu/vue3-context-menu/lib/vue3-context-menu.css'
 import ContextMenu from '@imengyu/vue3-context-menu'
 
-createApp(App)
-  .use(ContextMenu)     
+createApp(App).use(ContextMenu)     
 ```
 
-```html
-<div class="box" @contextmenu="onContextMenu($event)">
-  Right click to show contextmenu.
-</div>
-```
+### 显示菜单
+
+显示菜单有两种方式：
+
+第一种是函数模式，可以使用 `this.$contextmenu` 通过菜单数据显示一个右键菜单：
 
-显示菜单：
 ```js
 onContextMenu(e : MouseEvent) {
   //prevent the browser's default menu
   e.preventDefault();
-  //shou our menu
+  //shou your menu
   this.$contextmenu({
     x: e.x,
     y: e.y,
@@ -63,16 +72,30 @@ onContextMenu(e : MouseEvent) {
 }
 ```
 
-同样，也可以使用组件模式显示菜单：
+第二种是组件模式，可以使用vue组件显示菜单：
 
 ```html
-<context-menu v-model:show="show" :options="options" />
+<context-menu
+  v-model:show="show"
+  :options="optionsComopnent"
+>
+  <context-menu-item label="Simple item" @click="onMenuClick(1)" />
+  <context-menu-sperator /><!--use this to add sperator-->
+  <context-menu-group label="Menu with child">
+    <context-menu-item label="Item1" @click="onMenuClick(2)" />
+    <context-menu-item label="Item2" @click="onMenuClick(3)" />
+    <context-menu-group label="Child with v-for 50">
+      <context-menu-item v-for="index of 50" :key="index" :label="'Item3-'+index" @click="onLoopMenuClick(index)" />
+    </context-menu-group>
+  </context-menu-group>
+</context-menu>
 ```
 
 ```js
 data() {
   return {
     show: false,
+    //For $contextmenu
     options: {
       items:[
         {
@@ -95,25 +118,33 @@ data() {
       minWidth: 230,
       x: 0,
       y: 0
-    }
+    },
+    //For component
+    optionsComopnent: {
+      zIndex: 3,
+      minWidth: 230,
+      x: 500,
+      y: 200
+    },
   }
 },
 methods: {
   onButtonClick(e : MouseEvent) {
-    //显示菜单
+    //显示组件菜单
     this.show = true;
     this.options.x = e.x;
     this.options.y = e.y;
   },
 }
 ```
-### 菜单图标
+
+## 菜单图标
 
 菜单组件不提供任何图标，如果您想添加图标，推荐使用 [iconfont](http://iconfont.cn) 图标库，导入后填写 MenuItem 的 icon 属性，即可在菜单项前面显示图标。
 
 *默认使用 `<i>` 元素来显示图标。*
 
-### 自定义样式
+## 自定义样式
 
 如果觉得菜单样式不好看，可以重写css样式，所有的css样式定义都在 `/src/ContextSubMenu.vue` 中。你可以将所有样式复制出来，按需修改，存放在你的文件中。然后在导入的地方覆盖默认样式：
 
@@ -122,7 +153,113 @@ import '@imengyu/vue3-context-menu/lib/vue3-context-menu.css'
 import '你的样式css文件路径.css'
 ```
 
-### 参数说明
+## 自定义渲染
+
+菜单提供了一些插槽，允许你自定义渲染某些部分，具体您可以参考案例源码 [examples\views\BasicCustomize.vue](examples\views\BasicCustomize.vue) [examples\views\ComponentCustomize.vue](examples\views\ComponentCustomize.vue)。
+
+## API 参考
+
+### 组件模式：组件属性与说明
+
+#### ContextMenu
+
+菜单主体组件。
+
+##### Props
+
+| 属性 | 描述 | 类型 | 默认值 |
+| :----: | :----: | :----: | :----: |
+| show(v-model) | 是否显示菜单 | `boolean` | — |
+| options | 菜单相关定义 | `MenuOptions` | — |
+
+##### Events
+
+| 事件名 | 描述 | 参数 |
+| :----: | :----: | :----: |
+| close | 菜单关闭时触发此事件 | - |
+
+##### Slots
+
+| 插槽名 | 描述 | 参数 |
+| :----: | :----: | :----: |
+| itemRender | 当前菜单全局条目渲染插槽 | MenuItemRenderData |
+| itemIconRender | 当前菜单全局图标渲染插槽 | MenuItemRenderData |
+| itemLabelRender | 当前菜单全局文字渲染插槽 | MenuItemRenderData |
+| itemRightArrowRender | 当前菜单全局右侧箭头渲染插槽 | MenuItemRenderData |
+| speratorRender | 当前菜单分隔符渲染插槽 | - |
+
+##### MenuItemRenderData 结构
+
+| 属性名 | 描述 | 类型 |
+| :----: | :----: | :----: |
+| theme | 菜单主题 | `'light' 'dark'` |
+| onClick | 自定义元素的点击事件回调，它用于菜单内部事件处理，当自定义渲染时，请回调此函数，否则菜单无法正常响应事件 | - |
+| onMouseEnter | 自定义元素的鼠标移入事件回调，它用于菜单内部事件处理，当自定义渲染时，请回调此函数，否则菜单无法正常响应事件 | - |
+| ... | 其他参数与 `MenuItem` 一致 | - |
+
+#### ContextMenuItem
+
+菜单条目组件。
+
+##### Props
+
+| 属性 | 描述 | 类型 | 默认值 |
+| :----: | :----: | :----: | :----: |
+| label | 菜单项名称 | `string` | — |
+| icon | 菜单项图标 | `string` | — |
+| disabled | 是否禁用菜单项 | `boolean` | `false` |
+| clickableWhenHasChildren | 指定当本菜单下有子菜单时，点击当前菜单是否触发点击事件 | `boolean` | `false` |
+| clickClose | 点击当前菜单项是否自动关闭整个菜单 | `boolean` | `true` |
+| divided | 是否显示分割线 | `boolean` | `false` |
+| customClass | 自定义子菜单class | `string` | — |
+| onClick | 菜单项点击事件 | `Function()` | — |
+
+##### Slots
+
+| 插槽名 | 描述 | 参数 |
+| :----: | :----: | :----: |
+| default | 当前条目整体渲染插槽 | - |
+| icon | 图标渲染插槽 | - |
+| label | 文字渲染插槽 | - |
+| rightArrow | 右侧箭头渲染插槽 | - |
+
+##### Click
+
+| 事件名 | 描述 | 参数 |
+| :----: | :----: | :----: |
+| click | 点击菜单时触发此事件 | - |
+
+#### ContextMenuGroup
+
+子菜单组件。
+
+##### Props
+
+| 属性 | 描述 | 类型 | 默认值 |
+| :----: | :----: | :----: | :----: |
+| label | 菜单项名称 | `string` | — |
+| icon | 菜单项图标 | `string` | — |
+| disabled | 是否禁用菜单项 | `boolean` | `false` |
+| clickableWhenHasChildren | 指定当本菜单下有子菜单时，点击当前菜单是否触发点击事件 | `boolean` | `false` |
+| adjustSubMenuPosition | 是否在子菜单超出屏幕后进行自动调整 | `boolean` | `true` |
+| clickClose | 点击当前菜单项是否自动关闭整个菜单 | `boolean` | `true` |
+| divided | 是否显示分割线 | `boolean` | `false` |
+| customClass | 自定义子菜单class | `string` | — |
+| minWidth | 子菜单最小宽度 | `number` | `100` |
+| maxWidth | 子菜单最大宽度 | `number` | `600` |
+| onClick | 菜单项点击事件 | `Function()` | — |
+
+##### Slots
+
+| 插槽名 | 描述 | 参数 |
+| :----: | :----: | :----: |
+| default | 子菜单渲染插槽 | - |
+
+#### ContextMenuSperator
+
+菜单分隔符组件。
+
+### 函数模式：参数说明
 
 #### MenuOptions
 
@@ -138,17 +275,22 @@ import '你的样式css文件路径.css'
 | customClass | 自定义菜单类名 | `string` | — | — |
 | minWidth | 主菜单最小宽度 | `number` | — | `100` |
 | maxWidth | 主菜单最大宽度 | `number` | — | `600` |
+| theme | 菜单的主题 | `string` | `'light' 'dark'` | `light` |
 
 #### MenuItem
 
 | 属性 | 描述 | 类型 | 可选值 | 默认值 |
 | :----: | :----: | :----: | :----: | :----: |
-| label | 菜单项名称 | `string` | — | — |
-| icon | 菜单项图标 | `string` | — | — |
+| label | 菜单项名称，可传入VNode | `string|VNode|((label: string) => VNode)` | — | — |
+| icon | 菜单项图标，可传入VNode | `string|VNode|((icon: string) => VNode)` | — | — |
 | disabled | 是否禁用菜单项 | `boolean` | — | `false` |
+| adjustSubMenuPosition | 是否在子菜单超出屏幕后进行自动调整 | `boolean` | — | `true` |
+| clickableWhenHasChildren | 指定当本菜单下有子菜单时，点击当前菜单是否触发点击事件 | `boolean` | — | `false` |
+| clickClose | 点击当前菜单项是否自动关闭整个菜单 | `boolean` | — | `true` |
 | divided | 是否显示分割线 | `boolean` | — | `false` |
 | customClass | 自定义子菜单class | `string` | — | — |
 | minWidth | 子菜单最小宽度 | `number` | — | `100` |
 | maxWidth | 子菜单最大宽度 | `number` | — | `600` |
 | onClick | 菜单项点击事件 | `Function()` | — | — |
-| children | 子菜单结构信息 | `MenuItem[]` | — | — |
+| customRender | 菜单项整体自定义渲染回调 | `VNode|((item: MenuItemRenderData) => VNode)` | — | — |
+| children | 子菜单结构信息 | `MenuItem[]` | — | — |

package/README.md

@@ -9,9 +9,17 @@ A context menu component for Vue3
 
 ---
 
-[View Demo](https://imengyu.top/pages/vue3-context-menu-demo/)
+[Click here View online Demo](https://imengyu.top/pages/vue3-context-menu-demo/)
 
----
+## features
+
+* Simple and easy to use, small size
+* Provide component mode and function mode
+* Customizable
+
+### ❗ Upgrade Note 
+
+Version 1.1.0 has been greatly upgraded and may be incompatible with the previous version. If there is a problem, please install version 1.0.9.
 
 ### Install
 
@@ -19,30 +27,30 @@ A context menu component for Vue3
 npm install -save @imengyu/vue3-context-menu
 ```
 
-### Useage
+## Useage
+
+It is recommended that you check the [examples source code](examples/) before use. It provides a variety of detailed usage methods, which may be very helpful to you. 😀
+
+### Import
 
-Import vue3-context-menu in main.js:
 ```js
 import '@imengyu/vue3-context-menu/lib/vue3-context-menu.css'
 import ContextMenu from '@imengyu/vue3-context-menu'
 
-createApp(App)
-  .use(ContextMenu)     
+createApp(App).use(ContextMenu)     
 ```
 
-Add events to the elements that you want show contextmenu: 
-```html
-<div class="box" @contextmenu="onContextMenu($event)">
-  Right click to show contextmenu.
-</div>
-```
+### Show menu
+
+There are two ways to display menus:
+
+The first is the function mode. You can use  `this.$contextmenu` displays a menu through menu data:
 
-Then show your menu:
 ```js
 onContextMenu(e : MouseEvent) {
   //prevent the browser's default menu
   e.preventDefault();
-  //shou our menu
+  //shou your menu
   this.$contextmenu({
     x: e.x,
     y: e.y,
@@ -66,16 +74,30 @@ onContextMenu(e : MouseEvent) {
 }
 ```
 
-Similarly, you can use component to display the menu:
+The second is the component mode. You can use the component and template to display the menu:
 
 ```html
-<context-menu v-model:show="show" :options="options" />
+<context-menu
+  v-model:show="show"
+  :options="optionsComopnent"
+>
+  <context-menu-item label="Simple item" @click="onMenuClick(1)" />
+  <context-menu-sperator /><!--use this to add sperator-->
+  <context-menu-group label="Menu with child">
+    <context-menu-item label="Item1" @click="onMenuClick(2)" />
+    <context-menu-item label="Item2" @click="onMenuClick(3)" />
+    <context-menu-group label="Child with v-for 50">
+      <context-menu-item v-for="index of 50" :key="index" :label="'Item3-'+index" @click="onLoopMenuClick(index)" />
+    </context-menu-group>
+  </context-menu-group>
+</context-menu>
 ```
 
 ```js
 data() {
   return {
     show: false,
+    //For $contextmenu
     options: {
       items:[
         {
@@ -98,12 +120,19 @@ data() {
       minWidth: 230,
       x: 0,
       y: 0
-    }
+    },
+    //For component
+    optionsComopnent: {
+      zIndex: 3,
+      minWidth: 230,
+      x: 500,
+      y: 200
+    },
   }
 },
 methods: {
   onButtonClick(e : MouseEvent) {
-    //Show menu
+    //显示组件菜单
     this.show = true;
     this.options.x = e.x;
     this.options.y = e.y;
@@ -111,11 +140,132 @@ methods: {
 }
 ```
 
-### Parameter description
+## 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.
+
+*By default, the `<i>`  element is used to display icons*
+
+## Custom style
+
+If you think the menu style is not good-looking, you can rewrite the CSS style. All CSS style definitions are in `/src/ContextSubMenu.vue`. You can copy all the styles, modify them as needed, and store them in your file. Then overwrite the default style where you import:
+
+```js
+import '@imengyu/vue3-context-menu/lib/vue3-context-menu.css'
+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)。
+
+## API reference
+
+### Component mode: component properties and description
+
+#### ContextMenu
+
+Menu component.
+
+##### Props
+
+| Attribute | Description | Type | Default |
+| :----: | :----: | :----: | :----: |
+| show(v-model) | Controls whether the menu is displayed | `boolean` | — |
+| options | Menu options, See [MenuOptions](#MenuOptions) | `MenuOptions` | — |
+
+##### Events
+
+| Event name | Description | Arguments |
+| :----: | :----: | :----: |
+| close | This event is triggered when the menu is closed | - |
+
+##### Slots
+
+| Slot name | Description | Arguments |
+| :----: | :----: | :----: |
+| itemRender | Global menu item render slot | MenuItemRenderData |
+| itemIconRender | Global menu item icon render slot | MenuItemRenderData |
+| itemLabelRender | Global menu item label render slot  | MenuItemRenderData |
+| itemRightArrowRender | Global menu item right arrow render slot  | MenuItemRenderData |
+| speratorRender | Global menu sperator render slot  | - |
+
+##### `MenuItemRenderData`
+
+| Property | Description | Type |
+| :----: | :----: | :----: |
+| theme | Menu theme | `'light' 'dark'` |
+| 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.
+
+##### Props
+
+| Property | Description | Type | Default |
+| :----: | :----: | :----: | :----: |
+| label | The label of menu. | `string` | — |
+| icon | The icon for menu item. | `string` | — |
+| 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` |
+| divided | Is this menu item separated from the menu item below? | `boolean` | `false` |
+| customClass | Custom submenu class. | `string` | — |
+| onClick | Menu item click event handler. | `Function()` | — |
+
+##### Slots
+
+| Slot name | Description | Arguments |
+| :----: | :----: | :----: |
+| default | Rendering slot for the current menu | - |
+| icon | Icon rendering slot | - |
+| label | Label rendering slot | - |
+| rightArrow | Right Arrow rendering slot | - |
+
+##### Click
+
+| Event name | Description | Arguments |
+| :----: | :----: | :----: |
+| click | This event is triggered when the click this menu item | - |
+
+#### ContextMenuGroup
+
+Submenu component.
+
+##### Props
+
+| Property | Description | Type | Default |
+| :----: | :----: | :----: | :----: |
+| label | The label of menu. | `string` | — |
+| icon | The icon for menu item. | `string` | — |
+| 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` |
+| clickClose | Should close menu when Click this menu item ? | `boolean` | `true` |
+| divided | Is this menu item separated from the menu item below? | `boolean` | `false` |
+| customClass | Custom submenu class. | `string` | — |
+| minWidth | Submenu minimum width (in pixels). | `number` | `100` |
+| maxWidth | Submenu maximum width (in pixels). | `number` | `600` |
+| onClick | Menu item click event handler. | `Function()` | — |
+
+##### Slots
+
+| Slot name | Description | Arguments |
+| :----: | :----: | :----: |
+| default | Submenu render slot | - |
+
+#### ContextMenuSperator
+
+Menu separator component.
+
+### Function mode
 
 #### MenuOptions
 
-| Attribute | description | type | optional value | default value|
+| Property | Description | Type | Optional value | Default |
 | :----: | :----: | :----: | :----: | :----: |
 | items | The items for this menu. | `MenuItem[]` | — | — |
 | x | Menu display x position. | `number` | — | `0` |
@@ -127,17 +277,22 @@ methods: {
 | customClass | Custom menu class. | `string` | — | — |
 | minWidth | Minimum width of main menu (in pixels) | `number` | — | `100` |
 | maxWidth | Maximum width of main menu (in pixels) | `number` | — | `600` |
+| theme | Menu theme | `string` | `'light' 'dark'` | `light` |
 
 #### MenuItem
 
-| Attribute | description | type | optional value | default value|
+| Property | Description | Type | Optional value | Default |
 | :----: | :----: | :----: | :----: | :----: |
-| label | The label of menu. | `string` | — | — |
-| icon | The icon for menu item. | `string` | — | — |
+| label | The label of menu. | `string|VNode|((label: string) => VNode)` | — | — |
+| icon | The icon for menu item. | `string|VNode|((icon: string) => VNode)` | — | — |
 | 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` |
+| clickClose | Should close menu when Click this menu item ? | `boolean` | — | `true` |
 | divided | Is this menu item separated from the menu item below? | `boolean` | — | `false` |
 | customClass | Custom submenu class. | `string` | — | — |
 | minWidth | Submenu minimum width (in pixels). | `number` | — | `100` |
 | maxWidth | Submenu maximum width (in pixels). | `number` | — | `600` |
 | onClick | Menu item click event handler. | `Function()` | — | — |
+| customRender | A custom render callback that allows you to customize the rendering of the current item. | `VNode|((item: MenuItemRenderData) => VNode)` | — | — |
 | children | Submenu items. | `MenuItem[]` | — | — |