🚀 效果预览

在线预览

• Demo 演示：https://live2d.evgo2017.com

本地预览

git clone https://github.com/evgo2017/live2d-widget.git
cd ./live2d-widget
npm install
npm run dev

✨ 特性

• 🚀 无框架依赖：纯原生 JavaScript 编写，不依赖 Vue、React 等任何框架。
• 📦 极简轻量：支持 ESM 和 UMD 引入方式，打包产物经过高度优化。
• 🔌 开箱即用：默认提供右下角悬浮模式，样式独立前缀。
• 🛠 交互丰富：内置一言（Hitokoto）、切换模型、随机服装、拍照、消息提示等功能。
• ⚡️ 响应式配置：提供 config() 方法更新状态，无需手动操作 DOM。

� 安装与使用

方案 1：UMD 引入 (传统 HTML 项目)

优势：直接在浏览器中打开 HTML 即可看到效果。

<!-- 1. 引入样式 (可选，JS 内部也会自动处理) -->
<link rel="stylesheet" href="./live2d-widget.css">

<!-- 2. 引入脚本 -->
<script src="./live2d-widget.umd.js"></script>

<!-- 3. 初始化 -->
<script>
    const widget = new Live2dWidget({
        el: document.body,
        model: ['Potion-Maker/Pio', 'school-2017-costume-yellow']
    });
</script>

方案 2：ES Module 引入 (现代 Web 项目)

import Live2dWidget from 'live2d-widget'
import 'live2d-widget/dist/live2d-widget.css'

const widget = new Live2dWidget({
    el: document.querySelector('#app'),
    size: 280,
    direction: 'left'
});

---

⚙️ 配置参数 (Options)

配置项	含义	类型	默认值
apiPath	核心地址，请求此 API 加载模型数据	String	见 apiPath 说明
model	默认显示的 [模型号, 服装ID]	Array	['Potion-Maker/Pio', 'school-2017-costume-yellow']
width/height/size	模型的宽度/高度/统一缩放尺寸	Number	0 / 0 / 255
direction	模型停靠方位 (left / right)	String	right
tipPosition	提示框位置 (top / bottom)	String	top
tips	自定义交互提示语配置	Object	详见源码 tips.js
speechApi	语音接口，点击对话图标时请求的 API 地址	String	https://v1.hitokoto.cn
speechContentFormat	内容格式化函数，解析 API 返回的数据	Function	格式化 Hitokoto 等返回的数据
customId	Canvas 元素的识别 ID	String	live2d-widget-main

动态更新参数 (API)

你可以通过 widget.config() 实时修改挂件状态，而无需页面重载：

// 修改尺寸
widget.config({ size: 400 });

// 切换位置
widget.config({ direction: 'left' });

// 更换模型
widget.config({ model: ['Potion-Maker/Lala', 'default-costume'] });

📡 核心参数 apiPath

1. 方法一：项目本地集成（推荐：避开第三方接口失效） 将 live2d-static-api 的 indexes 放入项目的 public 目录：

   apiPath="./live2d-static-api/indexes"

2. 方法二：CDN 模式（开箱即用）

   apiPath="https://cdn.jsdelivr.net/npm/live2d-static-api@latest/indexes/"

---

最后

系列项目：evgo2017/vue-live2d 、evgo2017/live2d-static-api

https://github-readme-stats.vercel.app/api/pin/?username=evgo2017&repo=vue-live2d

https://github-readme-stats.vercel.app/api/pin/?username=evgo2017&repo=live2d-static-api

📄 开源协议

MIT License © 2026 evgo2017