feat: menus.items支持传入false关闭菜单项

oh-my-live2d · Mar 21, 2024 · 8a75cf7 · 8a75cf7
1 parent 1f4d74a
commit 8a75cf7
Show file tree

Hide file tree

Showing 8 changed files with 591 additions and 268 deletions.
diff --git a/docs/documentation.json b/docs/documentation.json
diff --git a/docs/src/.vitepress/config.ts b/docs/src/.vitepress/config.ts
@@ -70,6 +70,10 @@ export default defineConfig({
             {
               text: '快速入门',
               link: '/guide/'
+            },
+            {
+              text: '加载模型',
+              link: '/guide/loadModel'
             }
           ]
         },

diff --git a/docs/src/guide/loadModel.md b/docs/src/guide/loadModel.md
@@ -0,0 +1,137 @@
+# 加载模型
+
+当您需要加载模型时, 您可以在 `oh-my-live2d` 中导入`loadOml2d` 方法, 当这个方法被调用时将根据您传入的[配置选项](/options/Options)来加载组件, 该方法返回 `Promise`, 这意味着它是一个异步函数, 所以您可以从函数返回值调用`then`方法来获取`oml2d`实例.
+
+当`then`方法被调用时, 表示所有组件和当前索引模型已全部加载完毕, 在这之后您就可以从 `oml2d` 实例对象中主动调用其暴露的方法.
+
+:::tip
+需要注意的时, `loadOml2d` 方法只允许被调用一次, 如果您调用了多次, 将永远采用最后一次被调用时传入的配置加载组件, 并且会卸载之前创建的元素保证body中只存在一个oml2d组件.
+
+```ts
+const main = async () => {
+  const oml2d1 = await loadoml2d({}); // 将被卸载, 且实例对象 oml2d1 不可用
+  const oml2d2 = await loadoml2d({}); // 将采用此配置重新加载, oml2d2 可用
+};
+
+main();
+```
+
+:::
+
+## 基本使用
+
+### ESM 方式:
+
+```ts
+import { loadOml2d } from 'oh-my-live2d';
+loadoml2d({
+  // ...options
+}).then((oml2d) => {
+  settimeout(() => {
+    oml2d.tipsMessage('hello world', 3000, 10);
+  }, 8000);
+});
+```
+
+为避免回调地狱, 可以使用`async`和`await`关键字:
+
+```ts
+const main = async () => {
+  const oml2d = await loadoml2d({
+    // ...options
+  });
+
+  settimeout(() => {
+    oml2d.tipsMessage('hello world', 3000, 10);
+  }, 8000);
+};
+
+main();
+```
+
+### CDN 方式:
+
+通过 CDN 方式导入时，所有成员变量都可以在 `OML2D` 命名空间下被使用。
+
+```html
+<script>
+  OML2D.loadOml2d({
+    // ...options
+  }).then((oml2d) => {
+    setTimeout(() => {
+      oml2d.tipsMessage('hello world', 3000, 10);
+    }, 8000);
+  });
+</script>
+```
+
+## oml2d 实例
+
+### 方法
+
+以下方法可在oml2d对象实例中被调用.
+
+---
+
+#### tipsMessage
+
+主动消息提示
+
+- 类型: `tipsMessage:(message: string , duration: number, priority: number) => void`
+- 参数说明
+
+| 参数     | 类型   | 描述     | 必须 | 默认值 |
+| -------- | ------ | -------- | ---- | ------ |
+| message  | string | 提示消息 | 是   | -      |
+| duration | number | 持续时间 | 否   | 3000   |
+| priority | number | 优先级   | 否   | 3      |
+
+- 示例:
+
+```ts
+oml2d.tipsMessage('hello world', 3000, 10);
+```
+
+---
+
+#### loadNextModel
+
+加载下一个模型, 调用时将循环切换模型, 返回 `Promise`, 当 `then` 被调用时表示模型所有资源已加载完毕
+
+- 类型: `loadNextModel(): Promise<void>`
+- 示例:
+
+```ts
+oml2d.loadNextModel().then(() => {
+  console.log('加载完毕');
+});
+```
+
+---
+
+#### reloadModel
+
+重新加载当前模型, 返回 `Promise`, 当 `then` 被调用时表示模型所有资源已加载完毕
+
+- 类型: `reloadModel(): Promise<void>`
+- 示例:
+
+```ts
+oml2d.loadNextModel().then(() => {
+  console.log('加载完毕');
+});
+```
+
+---
+
+#### switchStatus
+
+切换模型状态, 休息/活动
+
+- 类型:`switchStatus(): void`
+
+- 示例:
+
+```ts
+oml2d.switchStatus();
+```
diff --git a/docs/src/options/MenusOptions.md b/docs/src/options/MenusOptions.md
@@ -12,7 +12,82 @@
 
 ### items
 
-配置菜单项,
+- 类型: `Item[] | ((defaultItems: Item[]) => Item[]) | false`
+
+配置菜单项, 您可以通过这个选项配置菜单项, 该配置选项非常的灵活, 它可以是一个由 Item 类型组成的数组, 也可以是一个函数, 当值是一个数组时, 它将覆盖默认菜单项配置. 当值是一个函数时, 您可以从函数中拿到默认默认菜单项, 当值为false时将关闭整个菜单栏
+
+#### Item 类型描述:
+
+- id
+  - 类型: string
+  - 必须: 是
+  - 描述: 唯一键
+- title
+  - 类型: string
+  - 必须: 是
+  - 描述: 菜单项标题, 鼠标悬浮时提示此标题
+- icon
+
+  - 类型: string
+  - 必须: 是
+  - 描述: 菜单项图标, 这些默认图标您可以直接使用: ![](https://loclink-1259720482.cos.ap-beijing.myqcloud.com/image/202403211826251.png)
+    例如: icon: 'icon-like'
+
+    当然, 您还可以使用自定义图标, 前往 [阿里矢量图标库](https://www.iconfont.cn/) 生成 Symbol 类型的地址, 并在项目中引入后即可使用您自己的图标, 详细教程如下:
+
+    1. 选择您需要的图标并添加至项目
+       ![](https://loclink-1259720482.cos.ap-beijing.myqcloud.com/image/202403212001644.png)
+
+    2. 依次点击: 批量操作 - 全选 - 批量去色 , 这一步是必须的, 因为我们不需要图标默认携带颜色, 否则将无法自定义图标颜色
+       ![](https://loclink-1259720482.cos.ap-beijing.myqcloud.com/image/202403212008305.png)
+
+    3. 选择 Symbol 类型, 点击更新代码
+       ![](https://loclink-1259720482.cos.ap-beijing.myqcloud.com/image/202403212011851.png)
+
+    4. 点击复制代码, 或者你也可以选择下载至本地, 之后在项目中引入这个js文件即可, 以下是一个示例:
+
+```ts
+import '//at.alicdn.com/t/c/font_2679099_hchompi0roq.js';
+menus: {
+  items: [
+    {
+      id: 'github',
+      icon: 'github-fill',
+      title: '我的github',
+      onClick() {
+        window.open('https://github.com/hacxy');
+      }
+    }
+  ];
+}
+```
+
+- onClick
+  - 类型: ([oml2d](/guide/loadModel#oml2d-实例)) => void
+  - 必须: 否
+  - 描述: 定义菜单项点击事件, 函数中可以通过参数获取到[oml2d对象示例](/guide/loadModel#oml2d-实例), 方便您定制更多功能
+
+如果您不想完全覆盖默认的菜单项, 则可以传入一个函数, 从函数中可以拿到默认菜单项的配置,并返回 Item[] 供您按需添加:
+
+```ts
+  loadOml2d({
+     menus: {
+       items: (defaultItems) => {
+          return [
+            defaultItems[0],
+            defaultItems[1],
+           {
+             id: 'github'
+             title: '我的github'
+             icon: 'github-fill'
+             onClick: () => window.open('https://github.com/hacxy');
+           }
+         ]
+       }
+     }
+  })
+
+```
 
 ---
 

diff --git a/packages/oh-my-live2d/src/modules/menus.ts b/packages/oh-my-live2d/src/modules/menus.ts
@@ -58,8 +58,10 @@ export class Menus {
    * 创建
    */
   create(): void {
-    this.element = createElement({ id: ELEMENT_ID.menus, tagName: 'div', className: ELEMENT_ID.menus });
-    this.createMenuItem();
+    if (this.menuOptions.items) {
+      this.element = createElement({ id: ELEMENT_ID.menus, tagName: 'div', className: ELEMENT_ID.menus });
+      this.createMenuItem();
+    }
   }
 
   /**

diff --git a/packages/oh-my-live2d/src/modules/oml2d.ts b/packages/oh-my-live2d/src/modules/oml2d.ts
@@ -176,7 +176,9 @@ export class OhMyLive2D {
     this.registerModelEvent();
   }
 
-  // 切换状态. 休息/活动
+  /**
+   * 切换状态. 休息/活动
+   */
   switchStatus(): void {
     void this.stage.slideOut();
     this.tips.clear();
@@ -215,7 +217,10 @@ export class OhMyLive2D {
   }
 
   /**
-   * 提示消息
+   * 主动提示消息
+   * @param message 提示信息
+   * @param duration 持续时间  默认值: 3000
+   * @param priority  优先级 默认值: 3
    */
   tipsMessage(message: string, duration?: number, priority?: number): void {
     this.tips.notification(message, duration, priority);

diff --git a/packages/oh-my-live2d/src/types/menus.ts b/packages/oh-my-live2d/src/types/menus.ts
@@ -7,9 +7,78 @@ import { CommonStyleType, Item } from './common.js';
  */
 export interface MenusOptions {
   /**
-   * 配置菜单项,
+   * 配置菜单项, 您可以通过这个选项配置菜单项, 该配置选项非常的灵活, 它可以是一个由 Item 类型组成的数组, 也可以是一个函数, 当值是一个数组时, 它将覆盖默认菜单项配置. 当值是一个函数时, 您可以从函数中拿到默认默认菜单项, 当值为false时将关闭整个菜单栏
+   *
+   * #### Item 类型描述:
+   * - id
+   *   - 类型: string
+   *   - 必须: 是
+   *   - 描述: 唯一键
+   * - title
+   *   - 类型: string
+   *   - 必须: 是
+   *   - 描述: 菜单项标题, 鼠标悬浮时提示此标题
+   * - icon
+   *   - 类型: string
+   *   - 必须: 是
+   *   - 描述: 菜单项图标, 这些默认图标您可以直接使用:  ![](https://loclink-1259720482.cos.ap-beijing.myqcloud.com/image/202403211826251.png)
+   *     例如: icon: 'icon-like'
+   *
+   *     当然, 您还可以使用自定义图标, 前往 [阿里矢量图标库](https://www.iconfont.cn/) 生成 Symbol 类型的地址, 并在项目中引入后即可使用您自己的图标, 详细教程如下:
+   *
+   *     1. 选择您需要的图标并添加至项目
+   *      ![](https://loclink-1259720482.cos.ap-beijing.myqcloud.com/image/202403212001644.png)
+   *
+   *     2. 依次点击: 批量操作 - 全选 - 批量去色 , 这一步是必须的, 因为我们不需要图标默认携带颜色, 否则将无法自定义图标颜色
+   *     ![](https://loclink-1259720482.cos.ap-beijing.myqcloud.com/image/202403212008305.png)
+   *
+   *     3. 选择 Symbol 类型, 点击更新代码
+   *     ![](https://loclink-1259720482.cos.ap-beijing.myqcloud.com/image/202403212011851.png)
+   *
+   *     4. 点击复制代码, 或者你也可以选择下载至本地, 之后在项目中引入这个js文件即可, 以下是一个示例:
+   *    ```ts
+   *    import '//at.alicdn.com/t/c/font_2679099_hchompi0roq.js';
+   *    menus: {
+   *      items: [
+   *        {
+   *          id: 'github',
+   *          icon: 'github-fill',
+   *          title: '我的github',
+   *          onClick() {
+   *            window.open('https://github.com/hacxy');
+   *          }
+   *        }
+   *     ]
+   *    }
+   *    ```
+   * - onClick
+   *   - 类型: ([oml2d](/guide/loadModel#oml2d-实例)) => void
+   *   - 必须: 否
+   *   - 描述: 定义菜单项点击事件, 函数中可以通过参数获取到[oml2d对象示例](/guide/loadModel#oml2d-实例), 方便您定制更多功能
+   *
+   * 如果您不想完全覆盖默认的菜单项, 则可以传入一个函数, 从函数中可以拿到默认菜单项的配置,并返回 Item[] 供您按需添加:
+   * ```ts
+   *   loadOml2d({
+   *      menus: {
+   *        items: (defaultItems) => {
+   *           return [
+   *             defaultItems[0],
+   *             defaultItems[1],
+   *            {
+   *              id: 'github'
+   *              title: '我的github'
+   *              icon: 'github-fill'
+   *              onClick: () => window.open('https://github.com/hacxy');
+   *            }
+   *          ]
+   *        }
+   *      }
+   *   })
+   *
+   * ```
+   * @valueType Item[] | ((defaultItems: Item[]) => Item[]) | false
    */
-  items?: Item[] | ((defaultItems: Item[]) => Item[]);
+  items?: Item[] | ((defaultItems: Item[]) => Item[]) | false;
 
   /**
    * 配置菜单整体样式

diff --git a/tests/vite-app/src/main.ts b/tests/vite-app/src/main.ts
@@ -5,7 +5,7 @@ import './style.css';
 import '//at.alicdn.com/t/c/font_2679099_hchompi0roq.js';
 
 const foo = async () => {
-  const oml2d = await loadOml2d({
+  loadOml2d({
     // parentElement: el,
     importType: 'complete',
     mobileDisplay: true,
@@ -15,7 +15,11 @@ const foo = async () => {
         path: 'https://registry.npmmirror.com/oml2d-models/latest/files/models/shizuku/shizuku.model.json',
         scale: 0.2,
         motionPreloadStrategy: 'ALL',
-        volume: 0
+        position: [0, 100],
+        volume: 0,
+        stageStyle: {
+          height: 500
+        }
       },
       {
         path: 'https://registry.npmmirror.com/oml2d-models/latest/files/models/Senko_Normals/senko.model3.json',
@@ -58,7 +62,7 @@ const foo = async () => {
     }
   });
 
-  console.log(oml2d);
+  // console.log(oml2d);
   // oml2d.loadNextModel();
   // const oml2d2 = await loadOml2d({
   //   models: [