OhMyLive2D

https://oml2d.hacxy.cn
Admin
OhMyLive2D is an out-of-the-box, highly customizable Live2D component for web browsers that supports...
Tokens:26,002
Snippets:261
Trust Score:4.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install hexo-oh-my-live2d plugin

Source: https://oml2d.hacxy.cn/guide/hexo.html

Installs the hexo-oh-my-live2d plugin via npm. Run this in your Hexo project root.

```sh
npm install hexo-oh-my-live2d
```

--------------------------------

### Install oh-my-live2d with npm, pnpm, or yarn

Source: https://oml2d.hacxy.cn/guide

Install the oh-my-live2d package using npm, pnpm, or yarn. These commands are presented as interchangeable package manager options.

```bash
npm install oh-my-live2d
```

```bash
pnpm add oh-my-live2d
```

```bash
yarn add oh-my-live2d
```

--------------------------------

### Configure OhMyLive2d in _config.yml

Source: https://oml2d.hacxy.cn/guide/hexo.html

Example _config.yml configuration for the hexo-oh-my-live2d plugin. Enables the widget, sets the CDN, defines models, and customizes tips. Many options are commented out; uncomment and adjust as needed. The message function uses axios to fetch a hitokoto line.

```yml
# _config.yml
OhMyLive2d:
  enable: true
  CDN: https://registry.npmmirror.com/oh-my-live2d/latest/files
  # CDN: https://registry.npmmirror.com/oh-my-live2d/0.13/files/dist/index.min.js
  option:
    # importType: 'cubism2' #  导入类型, 默认使用全量导入: complete , 可选值: complete, cubism2, cubism5
    libraryUrls: # 自定义 Cubism SDK 外部资源地址
      complete: https://registry.npmmirror.com/oh-my-live2d/latest/files/lib/complete.js
      cubism2: https://registry.npmmirror.com/oh-my-live2d/latest/files/lib/cubism2.js
      cubism5: https://registry.npmmirror.com/oh-my-live2d/latest/files/lib/cubism5.js
    # menus:
    # items: |
    #   (defaultItems)=>{
    #    return [
    #      ...defaultItems,
    #      {
    #        id: 'github',
    #        icon: 'github-fill',
    #        title: '我的github',
    #        onClick: ()=>window.open('https://github.com/hacxy')
    #      }
    #    ]
    #   }

    # items:
    #   - id: 'github'
    #     icon: 'github-fill'
    #     title: '我的github'
    #     onClick: ()=>window.open('https://github.com/hacxy')

    mobileDisplay: true # 是否在移动端显示
    models:
      - path: https://registry.npmmirror.com/live2d-widget-model-shizuku/1.0.5/files/assets/shizuku.model.json
        mobilePosition: [-10, 23] # 移动端时模型在舞台中的位置。 默认值: [0,0] [横坐标, 纵坐标]
        mobileScale: 0.1 # 移动端时模型的缩放比例 默认值: 0.1
        mobileStageStyle: # 移动端时舞台的样式
          width: 180
          height: 166
        motionPreloadStrategy: IDLE # 动作预加载策略 默认值: IDLE 可选值: ALL | IDLE | NONE
        position: [-10, 35] # 模型在舞台中的位置。 默认值: [0,0] [横坐标, 纵坐标]
        scale: 0.15 # 模型的缩放比例 默认值: 0.1
        # showHitAreaFrames: false # 是否显示点击区域 默认值: false
        stageStyle:
          width: 250
          height: 250
      - path: 'https://registry.npmmirror.com/live2d-widget-model-koharu/1.0.5/files/assets/koharu.model.json'
        scale: 0.12
        position: [0, 0]
        stageStyle:
          width: 250
        mobileScale: 0.08
        mobilePosition: [0, 0]
        mobileStageStyle: # 移动端时舞台的样式
          width: 180
      - path: 'https://registry.npmmirror.com/live2d-widget-model-haruto/1.0.5/files/assets/haruto.model.json'
        scale: 0.12
        position: [0, 0]
        mobileScale: 0.08
        mobilePosition: [0, 0]
        mobileStageStyle: # 移动端时舞台的样式
          width: 180
        stageStyle:
          width: 250
    parentElement: document.body #为组件提供一个父元素，如果未指定则默认挂载到 body 中
    primaryColor: 'var(--btn-bg)' # 主题色 支持变量
    sayHello: false # 是否在初始化阶段打印项目信息
    tips:
      style:
        width: 230
        height: 120
        left: calc(50% - 20px)
        top: -100px
      mobileStyle:
        width: 180
        height: 80
        left: calc(50% - 30px)
        top: -100px
      idleTips:
        interval: 15000
        # message:
        #   - 你好呀~
        #   - 欢迎来到我的小站~
        # 自定义提示语 需要 引入 axios 库 ,也可以使用其他方法
        message: |
          function(){
            return axios.get('https://v1.hitokoto.cn?c=i')
              .then(function (response) {
                return response.data.hitokoto ;
              })
              .catch(function (error) {
                console.error(error);
              });
          }
        # wordTheDay: true
        # 自定义  https://v1.hitokoto.cn  数据
        # wordTheDay: |
        #   function(wordTheDayData){
        #     return `${wordTheDayData.hitokoto}    by.${wordTheDayData.from}`;
        #   }
  # then: |
  #   (oml2d)=>{
  #     setTimeout(() => {
  #     oml2d.tipsMessage('hello world', 3000, 10);
  #   }, 8000);
  #   }
```

--------------------------------

### Accessing Oml2d instance properties

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dProperties.html

Example showing how to access the version, modelIndex, and options properties from an Oml2d instance.

```typescript
import { loadOml2d } from 'oh-my-live2d';
const oml2d = loadOml2d({
  // ...options
});
console.log(oml2d.version); // 当前组件版本号
console.log(oml2d.modelIndex); // 当前模型索引值
console.log(oml2d.options); // 当前配置选项
```

--------------------------------

### Install oh-my-live2d in VitePress

Source: https://oml2d.hacxy.cn/guide/vitepress.html

Install the oh-my-live2d package in a VitePress project. This is the first step for both the default theme and third-party theme integration.

```sh
npm install oh-my-live2d@latest
```

--------------------------------

### Update oh-my-live2d to latest with npm, pnpm, or yarn

Source: https://oml2d.hacxy.cn/guide

Update oh-my-live2d to the latest release by appending @latest to the install command. The same applies to plugins like vuepress.

```bash
npm install oh-my-live2d@latest
```

```bash
pnpm add oh-my-live2d@latest
```

```bash
yarn add oh-my-live2d@latest
```

--------------------------------

### startTipsIdle()

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dMethods.html

开始空闲消息播放器。

```APIDOC
## startTipsIdle()

### Description
开始空闲消息播放器。

### Method
startTipsIdle

### Parameters
无

### Return Type
void
```

--------------------------------

### CDN Import of loadOml2d

Source: https://oml2d.hacxy.cn/api/functions/loadOml2d.html

Demonstrates how to load the library via CDN and initialize it using the OML2D global object.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
    <script src="https://unpkg.com/oh-my-live2d@latest"></script>
  </head>
  <body>
    <script>
      OML2D.loadOml2d({
        // ...options
      });
    </script>
  </body>
</html>
```

--------------------------------

### TipsOptions

Source: https://oml2d.hacxy.cn/api/interfaces/TipsOptions.html

配置提示框样式和消息内容, 支持传入选项对象或返回选项对象的函数, 函数会在模型每次加载成功时被调用, 并传入当前模型选项和索引, 以便为不同模型提供不同配置。

```APIDOC
## TipsOptions

### Description
配置提示框样式和消息内容, 与菜单选项一样支持您传入选项对象或者返回选项对象的函数, 如果它是一个函数, 则会在模型每次加载成功时被调用, 调用时会传入当前模型选项以及当前模型的索引值, 这样您就可以根据这些信息来做判断, 为不同的模型提供不同的选项

### Usage

#### 基础用法

```ts
import { loadOml2d } from 'oh-my-live2d';
loadOml2d({
  tips: {
    // 在这里配置
  }
});
```

#### 为不同模型提供不同的提示配置

支持使用函数, 每当模型加载成功后函数就会被调用, 回调时会传入当前模型配置以及索引方便您根据这些信息来做判断, 返回类型为菜单选项

##### 判断模型索引值

```ts
import { loadOml2d } from 'oh-my-live2d';
loadOml2d({
  tips: (_, currentIndex) => {
    if (currentIndex === 0) {
      return {
        copyTips: {
          message: ['复制了啥?']
        },
        idleTips: {
          wordTheDay: true
        }
      };
    } else {
      return {
        idleTips: {
          wordTheDay: false
        }
      };
    }
  }
});
```

##### 判断模型名称

您还可以根据当前模型的选项值来判断, 当您选择使用这个方法时, 推荐您为每个模型命名, 之后您就可以在函数中拿到当前模型的名称, 方便后续判断:

```ts
import { loadOml2d } from 'oh-my-live2d';
const oml2d = loadOml2d({
  models: [
    {
      name: 'shizuku',
      path: 'https://registry.npmmirror.com/oml2d-models/latest/files/models/shizuku/shizuku.model.json'
    },
    {
      name: 'senko',
      path: 'https://registry.npmmirror.com/oml2d-models/latest/files/models/Senko_Normals/senko.model3.json'
    },
    {
      name: 'pio',
      path: 'https://registry.npmmirror.com/oml2d-models/latest/files/models/Pio/model.json'
    }
  ],
  menus: (currentModel) => {
    switch (currentModel.name) {
      case 'shizuku':
        return {
          copyTips: {
            message: [`${currentModel.name}: 复制了啥?`]
          },
          idleTips: {
            wordTheDay: true
          }
        };
      default:
        return {
          idleTips: {
            wordTheDay: false
          }
        };
    }
  }
});
```

### Options

#### copyTips?

> `optional` **copyTips** : `object`

复制网站文字内容时的提示

##### duration?

> `optional` **duration** : `number`

提示框持续时间, 单位 ms

默认值:

```ts
3000
```

##### message?

> `optional` **message** : `string`[]

播放的消息内容, 需要是一个字符串数组, 播放时会从中随机取出一条进行提示, 空数组则不播放

默认值:

```ts
['你复制了什么内容呢?记得注明出处哦~']
```

##### priority?

> `optional` **priority** : `number`

优先级, 高优先级消息将会覆盖低优先级的消息

默认值:

```ts
3
```

#### idleTips?

> `optional` **idleTips** : `object`

闲置状态下的提示

##### duration?

> `optional` **duration** : `number`

提示框持续时间, 单位 ms

默认值:

```ts
5000
```

##### interval?

> `optional` **interval** : `number`

闲置状态循环播放消息的间隔时间, 单位 ms

默认值:

```ts
10000
```

##### message?

> `optional` **message** : `string`[] | () => `Promise`<`string`>

##### priority?

> `optional` **priority** : `number`

优先级, 高优先级消息将会覆盖低优先级的消息

默认值:

```ts
2
```

##### wordTheDay?

> `optional` **wordTheDay** : `boolean` | (`wordTheDayData`: `WordTheDayData`) => `string`

是否开启每日一言, 默认为关闭状态, 开启后将从 https://v1.hitokoto.cn 发送网络请求, 并将请求到的随机信息作为闲置提示内容, 除了 boolean 类型之外, 它还支持您传入一个格式化函数, 这在您需要自定义消息格式时非常有用, 格式化函数的返回值必须是一个 string 类型, 其接收一个 wordTheDayData, 该参数包含了这次网络请求成功后的所有响应数据, 方便您处理格式化.

以下是一个示例:

```ts
{
  tips: {
    idleTips: {
      wordTheDay(wordTheDayData) {
        return `${wordTheDayData.hitokoto}    by.${wordTheDayData.from}`;
      }
    }
  }
}
```

TIP
开启后将接管闲置状态下 message 选项设定的值

默认值:

```ts
false
```

#### messageLine?

> `optional` **messageLine** : `number`

提示消息限制展示的行数, 默认3行, 超出将会在消息结尾加上省略号

默认值:

```ts
3
```

#### mobileStyle?

> `optional` **mobileStyle** : `CommonStyleType`

移动端时的提示框的内联样式, 支持传入CSS对象, 提示框的默认情况下, 始终与舞台保持水平居中, 默认宽度为舞台的60%, 最小高度为 100px, 内容默认垂直水平居中.

#### style?

> `optional` **style** : `CommonStyleType`

定义提示框内联样式, 支持传入CSS对象, 提示框的默认情况下, 始终与舞台保持水平居中, 默认宽度为舞台的60%, 最小高度为 100px, 内容默认垂直水平居中.
```

--------------------------------

### 在 .vuepress/config.js 中配置 oml2dPlugin

Source: https://oml2d.hacxy.cn/guide/vuepress.html

在 VuePress 配置文件中导入并注册 oml2dPlugin，配置模型路径、缩放、位置和舞台样式。

```js
import { oml2dPlugin } from 'vuepress-plugin-oh-my-live2d';

export default defineUserConfig({
  // ... other configs
  plugins: [
    oml2dPlugin({
      // 在这里配置选项
      models: [
        {
          path: 'https://cdn.jsdelivr.net/gh/Eikanya/Live2d-model/Live2D/Senko_Normals/senko.model3.json',
          scale: 0.12,
          position: [-10, 50],
          stageStyle: {
            width: 350
          }
        }
      ]
    })

    //  ...other plugins
  ]
});
```

--------------------------------

### 基础用法：配置 tips 选项

Source: https://oml2d.hacxy.cn/api/interfaces/TipsOptions.html

在 loadOml2d 中传入 tips 选项对象，用于配置提示框。

```typescript
import { loadOml2d } from 'oh-my-live2d';
loadOml2d({
  tips: {
    // 在这里配置
  }
});
```

--------------------------------

### loadOml2d

Source: https://oml2d.hacxy.cn/api/interfaces/Options.html

Initializes the OhMyLive2D component with the provided configuration options. This is the main entry point for using the library.

```APIDOC
## loadOml2d

### Description
Initializes the OhMyLive2D component with the provided configuration options. This is the main entry point for using the library.

### Usage
```ts
import { loadOml2d } from 'oh-my-live2d';
loadOml2d({
  // configuration options
});
```

### Parameters
#### Options Object
- **dockedPosition** ("left" | "right") - Optional - Component docking position. Affects status bar, stage, and menu. Default: "left". When "left", stage and status bar are left-aligned, menu is right-aligned (and vice versa).
- **initialStatus** ("sleep" | "active") - Optional - Initial status of the component on first visit. Default: "active".
- **menus** (MenusOptions | (currentModel: ModelOptions, modelIndex: number) => MenusOptions) - Optional - Menu configuration. See menu options.
- **mobileDisplay** (boolean) - Optional - Whether to display on mobile devices. Default: false.
- **models** (ModelOptions[]) - Optional - Array of model configuration objects. Default: [].
- **parentElement** (HTMLElement) - Optional - Parent element for the component. Default: document.body.
- **primaryColor** (string) - Optional - Theme color affecting all modules. Default: '#38B0DE'.
- **sayHello** (boolean) - Optional - Whether to print project info during initialization. Default: true.
- **stageStyle** (CommonStyleType) - Optional - Common stage style for all models. Lower priority than model-specific stage style.
- **statusBar** (StatusBarOptions) - Optional - Status bar options. See status bar options.
- **tips** (TipsOptions | (currentModel: ModelOptions, modelIndex: number) => TipsOptions) - Optional - Custom tip box style and content. See tip options.
- **transitionTime** (number) - Optional - Transition animation duration for component entry and exit, in ms. Default: 1000.

### Deprecated Options
- **importType** (string) - Deprecated - No longer used; will be removed in next version.
- **libraryUrls** (object) - Deprecated - SDK is built-in; will be removed in next version. Contains: complete (string), cubism2 (string), cubism5 (string).
```

--------------------------------

### loadOml2d(options: Options): Oml2dProperties & Oml2dMethods & Oml2dEvents

Source: https://oml2d.hacxy.cn/api/functions/loadOml2d.html

Loads the Live2D component with the given options and returns an instance object with all methods, properties, and events.

```APIDOC
## loadOml2d(options: Options): Oml2dProperties & Oml2dMethods & Oml2dEvents

### Description
Loads the Live2D component based on the provided configuration options. Returns an instance object containing all methods, properties, and events for the component.

### Method
loadOml2d

### Parameters
- **options** (`Options`) - Required - Configuration options for loading the component.

### Return Value
`Oml2dProperties` & `Oml2dMethods` & `Oml2dEvents` - An instance object containing properties, methods, and events for the component.

### Usage
Call with a configuration option. The call is synchronous and can be invoked multiple times, each returning a new instance.

#### ESM Import
```ts
import { loadOml2d } from 'oh-my-live2d';
loadOml2d({
  // ...options
});
```

#### CDN Import
```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
    <script src="https://unpkg.com/oh-my-live2d@latest"></script>
  </head>
  <body>
    <script>
      OML2D.loadOml2d({
        // ...options
      });
    </script>
  </body>
</html>
```
```

--------------------------------

### Load oh-my-live2d via CDN with OML2D.loadOml2d

Source: https://oml2d.hacxy.cn/

Use this HTML snippet to quickly load oh-my-live2d via CDN and display a Live2D model. It includes the script tag from unpkg and calls OML2D.loadOml2d with a model configuration specifying the model path, position, scale, and stage height.

```html
<script src="https://unpkg.com/oh-my-live2d@latest"></script>
<script>
  OML2D.loadOml2d({
    models: [
      {
        path: 'https://model.oml2d.com/HK416-1-normal/model.json',
        position: [0, 60],
        scale: 0.08,
        stageStyle: {
          height: 450
        }
      }
    ]
  });
</script>
```

--------------------------------

### onLoad() 监听模型加载事件

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dEvents.html

监听模型加载事件，回调接收状态参数 'loading' | 'success' | 'fail'。加载成功不代表舞台可见，如需在舞台完全可见时触发操作，请使用 onStageSlideIn 事件。

```ts
import { loadOml2d } from 'oh-my-live2d';
const oml2d = loadOml2d({
  // ...options
});

// 监听模型加载完成事件
oml2d.onLoad((status) => {
  switch (status) {
    case 'success':
      console.log('加载成功');
      return;
    case 'fail':
      console.log('加载失败');
      return;
    case 'loading':
      console.log('正在加载中');
      return;
  }
});
```

--------------------------------

### 安装 vuepress-plugin-oh-my-live2d 插件

Source: https://oml2d.hacxy.cn/guide/vuepress.html

使用 npm 安装最新版本的 vuepress-plugin-oh-my-live2d 插件。

```sh
npm install vuepress-plugin-oh-my-live2d@latest
```

--------------------------------

### statusBarOpen(content?: string, color?: string)

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dMethods.html

弹出状态条并保持打开状态。

```APIDOC
## statusBarOpen(content?: string, color?: string)

### Description
弹出状态条并保持打开状态。

### Method
statusBarOpen

### Parameters
- **content** (string) - Optional - 状态条内容
- **color** (string) - Optional - 状态条颜色

### Return Type
void
```

--------------------------------

### 配置 statusBar 选项

Source: https://oml2d.hacxy.cn/api/interfaces/StatusBarOptions.html

在 loadOml2d 的 statusBar 配置对象中设置状态条选项。

```ts
import { loadOml2d } from 'oh-my-live2d';
loadOml2d({
  statusBar: {
    // 在这里进行配置
  }
});
```

--------------------------------

### onLoad()

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dEvents.html

模型加载事件，加载成功不代表舞台可见，如果需要在舞台完全可见时触发，请在 onStageSlideIn 事件中执行操作。

```APIDOC
## onLoad()

### Description
模型加载事件，加载成功不代表舞台可见，如果需要在舞台完全可见时触发，请在 onStageSlideIn 事件中执行操作。

### Method
onLoad

### Parameters
#### Parameters
- **fn** (`(status: "loading" | "success" | "fail") => void | Promise<void>`) - Required - 加载结束的回调，回调时会传入加载状态：'loading' | 'success' | 'fail'。
  - loading: 正在加载模型
  - success: 加载成功
  - fail: 加载失败

### Return Value
`void`

### Example
```ts
import { loadOml2d } from 'oh-my-live2d';
const oml2d = loadOml2d({
  // ...options
});
oml2d.onLoad((status) => {
  switch (status) {
    case 'success':
      console.log('加载成功');
      return;
    case 'fail':
      console.log('加载失败');
      return;
    case 'loading':
      console.log('正在加载中');
      return;
  }
});
```
```

--------------------------------

### loadNextModel()

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dMethods.html

加载下一个模型。

```APIDOC
## loadNextModel()

### Description
加载下一个模型。

### Method
loadNextModel

### Parameters
无

### Return Type
Promise<void>
```

--------------------------------

### idleTips.priority 默认值

Source: https://oml2d.hacxy.cn/api/interfaces/TipsOptions.html

idleTips.priority 的默认值为 2。

```typescript
2
```

--------------------------------

### Integrate oh-my-live2d in default theme via enhanceApp

Source: https://oml2d.hacxy.cn/guide/vitepress.html

Create a .vitepress/theme/index.js file that extends the default theme and dynamically loads oh-my-live2d in the enhanceApp hook. The import.meta.env.SSR check ensures the code only runs in the browser, not during server-side rendering.

```js
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme';

export default {
  ...DefaultTheme,
  async enhanceApp() {
    if (!import.meta.env.SSR) {
      const { loadOml2d } = await import('oh-my-live2d');
      loadOml2d({
        models: [
          {
            path: 'https://cdn.jsdelivr.net/gh/Eikanya/Live2d-model/Live2D/Senko_Normals/senko.model3.json'
          }
        ]
      });
    }
  }
};
```

--------------------------------

### ModelOptions

Source: https://oml2d.hacxy.cn/api/interfaces/ModelOptions.html

模型选项接收一个有模型选项对象组成的数组, 您可以通过这个选项来配置模型地址来源以及缩放比例、舞台大小等。

```APIDOC
## ModelOptions

### Description
配置模型地址来源以及缩放比例、舞台大小等。

### Properties
- **anchor** (`[number, number]`) - Optional - 设置模型在舞台中的锚点位置。默认值: `[0,0]`
- **mobilePosition** (`[number, number]`) - Optional - 移动端时模型在舞台中的位置。x: 横坐标, y: 纵坐标。默认值: `[0,0]`
- **mobileScale** (`number`) - Optional - 移动端时模型的缩放比例。默认值: `0.1`
- **mobileStageStyle** (`CommonStyleType`) - Optional - 移动端舞台的样式, 支持传入CSS对象, 传入的样式将通过内联样式作用于舞台元素, 舞台的默认宽高将自适应模型的宽高, 舞台内Canvas元素的宽高始终与舞台保持一致, 仅在移动端生效。
- **motionPreloadStrategy** (`"ALL" | "IDLE" | "NONE"`) - Optional - 动作预加载策略。默认值: `IDLE`
- **name** (`string`) - Optional - 模型的唯一标识, 当您需要判断当前模型时会非常有用。
- **path** (`string | string[]`) - Required - 模型的 json 文件 url 地址, 必填项, 当 path 为数组时, 表示该模型有一系列皮肤可以切换。
- **position** (`[number, number]`) - Optional - 模型在舞台中的位置。x: 横坐标, y: 纵坐标。默认值: `[0,0]`
- **rotation** (`number`) - Optional - 模型的旋转角度, 单位:度 (0-360)。默认值: `0`
- **scale** (`number`) - Optional - 模型的缩放比例。默认值: `0.1`
- **showHitAreaFrames** (`boolean`) - Optional - 是否显示该模型的点击区域框, 该选项是为了方便您预览和调试模型的可点击区域, 当这个选项为true时,将显示该模型的所有可点击区域, 点击区域的大小与位置取决于模型本身。
- **stageStyle** (`CommonStyleType`) - Optional - 定义舞台样式, 支持传入CSS对象, 传入的样式将通过内联样式作用于舞台元素, 舞台的默认宽高将自适应模型的宽高, 舞台内Canvas元素的宽高始终与舞台保持一致。
- **volume** (`number`) - Optional - 模型播放声音的音量, 声音与动作一起播放, 如果模型存在声音资源的话, 值为 0-1 之间的number类型, 0为静音。默认值: `0.5`

### Usage Example
```ts
import { loadOml2d } from 'oh-my-live2d';
loadOml2d({
  models: [
    {
      path: 'https://model.oml2d.com/Senko_Normals/senko.model3.json',
      position: [-10, 20]
    }
  ]
});
```
```

--------------------------------

### loadNextModelClothes()

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dMethods.html

加载当前模型的下一个衣服，即切换同个角色的不同模型。

```APIDOC
## loadNextModelClothes()

### Description
加载当前模型的下一个衣服，即切换同个角色的不同模型。

### Method
loadNextModelClothes

### Parameters
无

### Return Type
Promise<void>
```

--------------------------------

### motionPreloadStrategy 默认值

Source: https://oml2d.hacxy.cn/api/interfaces/ModelOptions.html

motionPreloadStrategy 选项的默认值，表示动作预加载策略为 IDLE。

```ts
IDLE
```

--------------------------------

### 使用内置默认图标

Source: https://oml2d.hacxy.cn/guide/icon.html

展示如何在loadOml2d配置中设置statusBar的loadingIcon以及menus中的各项图标。

```typescript
import { loadOml2d } from 'oh-my-live2d';
const oml2d = loadoml2d({
  // ... other options
  statusBar: {
    loadingIcon: 'icon-loading'
  },
  menus: {
    items: [
      {
        id: 'Rest',
        icon: 'icon-rest', 
        title: '休息',
        onClick(oml2d): void {
          // actions ...
        }
      },
      {
        id: 'SwitchModel',
        icon: 'icon-switch', 
        title: '切换模型',
        onClick(oml2d): void {
          // actions ...
        }
      },
      {
        id: 'About',
        icon: 'icon-about', 
        title: '关于',
        onClick(): void {
          void oml2d.loadNextModel();
        }
      }
    ],
    x
  }
});
```

--------------------------------

### 根据模型名称提供不同提示配置

Source: https://oml2d.hacxy.cn/api/interfaces/TipsOptions.html

使用函数作为 tips 选项，根据 currentModel.name 判断模型名称，返回不同的提示配置。

```typescript
import { loadOml2d } from 'oh-my-live2d';
const oml2d = loadOml2d({
  models: [
    {
      name: 'shizuku',
      path: 'https://registry.npmmirror.com/oml2d-models/latest/files/models/shizuku/shizuku.model.json'
    },
    {
      name: 'senko',
      path: 'https://registry.npmmirror.com/oml2d-models/latest/files/models/Senko_Normals/senko.model3.json'
    },
    {
      name: 'pio',
      path: 'https://registry.npmmirror.com/oml2d-models/latest/files/models/Pio/model.json'
    }
  ],
  menus: (currentModel) => {
    switch (currentModel.name) {
      case 'shizuku':
        return {
          copyTips: {
            message: [`${currentModel.name}: 复制了啥?`]
          },
          idleTips: {
            wordTheDay: true
          }
        };
      default:
        return {
          idleTips: {
            wordTheDay: false
          }
        };
    }
  }
});
```

--------------------------------

### sayHello 默认值

Source: https://oml2d.hacxy.cn/api/interfaces/Options.html

sayHello 选项的默认值，表示默认在初始化阶段打印项目信息。

```ts
true
```

--------------------------------

### statusBarPopup(content?: string, delay?: number, color?: string)

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dMethods.html

弹出状态条，一段时间后自动收起。

```APIDOC
## statusBarPopup(content?: string, delay?: number, color?: string)

### Description
弹出状态条，一段时间后自动收起。

### Method
statusBarPopup

### Parameters
- **content** (string) - Optional - 状态条内容
- **delay** (number) - Optional - 延迟时间，单位：毫秒
- **color** (string) - Optional - 状态条颜色

### Return Type
void
```

--------------------------------

### 根据模型索引值提供不同提示配置

Source: https://oml2d.hacxy.cn/api/interfaces/TipsOptions.html

使用函数作为 tips 选项，根据 currentIndex 判断模型索引，返回不同的提示配置。

```typescript
import { loadOml2d } from 'oh-my-live2d';
loadOml2d({
  tips: (_, currentIndex) => {
    if (currentIndex === 0) {
      return {
        copyTips: {
          message: ['复制了啥?']
        },
        idleTips: {
          wordTheDay: true
        }
      };
    } else {
      return {
        idleTips: {
          wordTheDay: false
        }
      };
    }
  }
});
```

--------------------------------

### tipsMessage(message: string, duration: number, priority: number)

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dMethods.html

提示信息。

```APIDOC
## tipsMessage(message: string, duration: number, priority: number)

### Description
提示信息。

### Method
tipsMessage

### Parameters
- **message** (string) - Required - 提示信息
- **duration** (number) - Required - 提示持续时间，单位：毫秒
- **priority** (number) - Required - 提示优先级，数字越大优先级越高

### Return Type
void
```

--------------------------------

### loadRandomModel()

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dMethods.html

加载随机模型。

```APIDOC
## loadRandomModel()

### Description
加载随机模型。

### Method
loadRandomModel

### Parameters
无

### Return Type
Promise<void>
```

--------------------------------

### Create useOml2d hook for custom theme integration

Source: https://oml2d.hacxy.cn/guide/vitepress.html

Define a useOml2d hook that dynamically imports and loads oh-my-live2d in the onMounted lifecycle hook. The oml2dOptions can be customized to fetch theme-specific configuration.

```ts
import { onMounted } from 'vue';
// 可以编写一个获取主题里配置的 oml2d 配置的方法
// import { useOml2dOptions } from 'xxx'

export function useOml2d() {
  // const oml2dOptions = useOml2dOptions()
  // 配置可以根据主题的实际情况进行获取，这里写一个默认的
  const oml2dOptions = {
    models: [
      {
        path: 'https://cdn.jsdelivr.net/gh/Eikanya/Live2d-model/Live2D/Senko_Normals/senko.model3.json'
      }
    ]
  };
  onMounted(async () => {
    if (oml2dOptions) {
      const { loadOml2d } = await import('oh-my-live2d');
      loadOml2d(oml2dOptions);
    }
  });
}
```

--------------------------------

### 使用 loadOml2d 配置模型选项

Source: https://oml2d.hacxy.cn/api/interfaces/ModelOptions.html

配置模型选项数组以加载模型。path 为必填项，可指定模型 JSON 的 URL；position 为可选，设置模型在舞台中的位置。

```ts
import { loadOml2d } from 'oh-my-live2d';
loadOml2d({
  models: [
    // 在这里进行配置
    {
      path: 'https://model.oml2d.com/Senko_Normals/senko.model3.json',
      position: [-10, 20]
    }
  ]
});
```

--------------------------------

### 在 Vite 项目中配置 oml2d 插件

Source: https://oml2d.hacxy.cn/guide/vite.html

在 Vite 配置文件中引入并配置 oml2d 插件，包含模型和提示设置。

```ts
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vite';
import { oml2d } from 'vite-plugin-oh-my-live2d';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vue(),
    oml2d({
      models: [
        {
          path: 'https://registry.npmmirror.com/oml2d-models/latest/files/models/Senko_Normals/senko.model3.json',
          position: [-10, 20]
        },
        {
          path: 'https://registry.npmmirror.com/oml2d-models/latest/files/models/Pio/model.json',
          scale: 0.4,
          position: [0, 50],
          stageStyle: {
            height: 300
          }
        }
      ],

      tips: {
        idleTips: {
          wordTheDay: (wordTheDayData) => {
            return wordTheDayData.hitokoto;
          }
        }
      }
    })
  ]
});
```

--------------------------------

### statusBarClose(content?: string, delay?: number, color?: string)

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dMethods.html

关闭状态条。

```APIDOC
## statusBarClose(content?: string, delay?: number, color?: string)

### Description
关闭状态条。

### Method
statusBarClose

### Parameters
- **content** (string) - Optional - 状态条内容
- **delay** (number) - Optional - 延迟时间，单位：毫秒
- **color** (string) - Optional - 状态条颜色

### Return Type
void
```

--------------------------------

### setStatusBarClickEvent(fn: () => void | Promise<void>)

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dMethods.html

设置状态条点击事件。

```APIDOC
## setStatusBarClickEvent(fn: () => void | Promise<void>)

### Description
设置状态条点击事件。

### Method
setStatusBarClickEvent

### Parameters
- **fn** (() => void | Promise<void>) - Required - 点击事件回调

### Return Type
void
```

--------------------------------

### loadSuccessMessage 默认值

Source: https://oml2d.hacxy.cn/api/interfaces/StatusBarOptions.html

loadSuccessMessage 选项的默认值为 '加载成功'。

```ts
'加载成功'
```

--------------------------------

### Create Layout.vue with useOml2d for third-party theme

Source: https://oml2d.hacxy.cn/guide/vitepress.html

Create a Layout.vue component that re-exports the theme's Layout and calls useOml2d in the onMounted hook. This is the recommended approach for third-party themes like @sugarat/theme.

```vue
<script setup lang="ts">
import { onMounted } from 'vue';
// 这里拿到主题提供的Layout, 并在 `template` 中挂载
import BlogTheme from '@sugarat/theme';
const Layout = BlogTheme.Layout;

onMounted(async () => {
  // 在这里动态导入 `oh-my-live2d`, 并调用 `loadOml2d` 方法
  const { loadOml2d } = await import('oh-my-live2d');

  // 在这里使用
  loadOml2d({
    // ... configure
    models: [
      {
        path: 'https://cdn.jsdelivr.net/gh/Eikanya/Live2d-model/Live2D/Senko_Normals/senko.model3.json'
      }
    ]
  });
});
</script>

<template>
  <Layout />
</template>
```

--------------------------------

### loadOml2d 基本用法

Source: https://oml2d.hacxy.cn/api/interfaces/Options.html

导入并调用 loadOml2d 函数，传入配置对象以初始化组件。配置项在注释位置填写。

```ts
import { loadOml2d } from 'oh-my-live2d';
loadOml2d({
  // 在这里进行配置
});
```

--------------------------------

### 安装 vite-plugin-oh-my-live2d

Source: https://oml2d.hacxy.cn/guide/vite.html

使用 npm 安装 vite-plugin-oh-my-live2d 插件。

```sh
npm install vite-plugin-oh-my-live2d
```

--------------------------------

### clearTips()

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dMethods.html

清除当前正在提示的消息，并停止空闲消息播放器。

```APIDOC
## clearTips()

### Description
清除当前正在提示的消息，并停止空闲消息播放器。

### Method
clearTips

### Parameters
无

### Return Type
void
```

--------------------------------

### copyTips.priority 默认值

Source: https://oml2d.hacxy.cn/api/interfaces/TipsOptions.html

copyTips.priority 的默认值为 3。

```typescript
3
```

--------------------------------

### ESM Import of loadOml2d

Source: https://oml2d.hacxy.cn/api/functions/loadOml2d.html

Demonstrates how to import and call the loadOml2d function using ESM syntax.

```typescript
import { loadOml2d } from 'oh-my-live2d';
loadOml2d({
  // ...options
});
```

--------------------------------

### onStageSlideIn()

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dEvents.html

舞台完全滑入事件。

```APIDOC
## onStageSlideIn()

### Description
舞台完全滑入事件。

### Method
onStageSlideIn

### Parameters
#### Parameters
- **fn** (`() => void | Promise<void>`) - Required - 事件回调

### Return Value
`void`

### Example
```ts
import { loadOml2d } from 'oh-my-live2d';
const oml2d = loadOml2d({
  // ...options
});
oml2d.onStageSlideIn(() => {
  // ...code
});
```
```

--------------------------------

### cat-black model configuration

Source: https://oml2d.hacxy.cn/guide/models.html

Configuration for the cat-black model. Sets scale to 0.15, position to [0, 20], and stage height to 350.

```json
{
  "path": "https://model.oml2d.com/cat-black/model.json",
  "scale": 0.15,
  "position": [0, 20],
  "stageStyle": {
    "height": 350
  }
}
```

--------------------------------

### transitionTime 默认值

Source: https://oml2d.hacxy.cn/api/interfaces/StatusBarOptions.html

transitionTime 选项的默认值为 800，单位毫秒。

```ts
800
```

--------------------------------

### stopTipsIdle()

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dMethods.html

停止空闲消息播放器。

```APIDOC
## stopTipsIdle()

### Description
停止空闲消息播放器。

### Method
stopTipsIdle

### Parameters
无

### Return Type
void
```

--------------------------------

### loadingIcon 默认值

Source: https://oml2d.hacxy.cn/api/interfaces/StatusBarOptions.html

loadingIcon 选项的默认值为 'icon-loading'。

```ts
icon-loading
```

--------------------------------

### 通过实例对象调用方法示例

Source: https://oml2d.hacxy.cn/api/interfaces/Oml2dMethods.html

展示如何通过 loadOml2d 返回的实例对象调用方法，例如加载下一个模型。

```typescript
import { loadOml2d } from 'oh-my-live2d';
const oml2d = loadOml2d({
  // ...options
});

// 加载下一个模型
oml2d.loadNextModel().then(() => {
  console.log('切换成功');
});
```

--------------------------------

### transitionTime 默认值

Source: https://oml2d.hacxy.cn/api/interfaces/Options.html

transitionTime 选项的默认值，表示过渡动画时长为 1000 毫秒。

```ts
1000
```
Tokens:
Raw