看板娘配置 - PengXing's Blog

概述#

pioConfig.ts 文件用于配置网站中的看板娘功能，支持 Spine 和 Live2D 两种类型的看板娘模型。

配置类型#

1. Spine 看板娘配置#

Spine 是一种2D骨骼动画技术，适合制作轻量级的看板娘动画。

基本配置结构#

1
interface SpineModelConfig {
2
  enable: boolean;                    // 是否启用
3
  model: {
4
    path: string;                    // 模型文件路径
5
    scale: number;                   // 缩放比例
6
    x: number;                       // X轴偏移
7
    y: number;                       // Y轴偏移
8
  };
9
  position: {
10
    corner: string;                  // 显示位置
11
    offsetX: number;                 // X轴偏移
12
    offsetY: number;                 // Y轴偏移
13
  };
14
  size: {
15
    width: number;                   // 容器宽度
16
    height: number;                  // 容器高度
17
  };
18
  interactive: {
19
    enabled: boolean;                // 是否启用交互
20
    clickAnimations: string[];       // 点击动画列表
21
    clickMessages: string[];         // 点击消息列表
22
    messageDisplayTime: number;      // 消息显示时间
23
    idleAnimations: string[];        // 待机动画列表
24
    idleInterval: number;            // 待机动画间隔
25
  };
26
  responsive: {
27
    hideOnMobile: boolean;           // 移动端是否隐藏
28
    mobileBreakpoint: number;        // 移动端断点
29
  };
30
  zIndex: number;                    // 层级
31
  opacity: number;                   // 透明度
32
}

配置示例#

1
export const spineModelConfig: SpineModelConfig = {
2
  enable: true,
3
  model: {
4
    path: "/pio/models/spine/firefly/1310.json",
5
    scale: 1.0,
6
    x: 0,
7
    y: 0,
8
  },
9
  position: {
10
    corner: "bottom-left",
11
    offsetX: 0,
12
    offsetY: 0,
13
  },
14
  size: {
15
    width: 250,
16
    height: 280,
17
  },
18
  interactive: {
19
    enabled: true,
20
    clickAnimations: [
21
      "emoji_0", "emoji_1", "emoji_2",
22
      "emoji_3", "emoji_4", "emoji_5", "emoji_6"
23
    ],
24
    clickMessages: [
25
      "你好呀！我是流萤~",
26
      "今天也要加油哦！✨",
27
      "想要一起去看星空吗？🌟"
28
    ],
29
    messageDisplayTime: 3000,
30
    idleAnimations: ["idle", "emoji_0", "emoji_1"],
31
    idleInterval: 8000,
32
  },
33
  responsive: {
34
    hideOnMobile: true,
35
    mobileBreakpoint: 768,
36
  },
37
  zIndex: 1000,
38
  opacity: 1.0,
39
};

2. Live2D 看板娘配置#

Live2D 是一种更高级的2D角色动画技术，提供更丰富的表情和动作。

基本配置结构#

1
interface Live2DModelConfig {
2
  enable: boolean;                    // 是否启用
3
  model: {
4
    path: string;                    // 模型文件路径
5
  };
6
  position: {
7
    corner: string;                  // 显示位置
8
    offsetX: number;                 // X轴偏移
9
    offsetY: number;                 // Y轴偏移
10
  };
11
  size: {
12
    width: number;                   // 容器宽度
13
    height: number;                  // 容器高度
14
  };
15
  interactive: {
16
    enabled: boolean;                // 是否启用交互
17
    clickMessages: string[];         // 点击消息列表
18
    messageDisplayTime: number;      // 消息显示时间
19
  };
20
  responsive: {
21
    hideOnMobile: boolean;           // 移动端是否隐藏
22
    mobileBreakpoint: number;        // 移动端断点
23
  };
24
}

配置示例#

1
export const live2dModelConfig: Live2DModelConfig = {
2
  enable: false,
3
  model: {
4
    path: "/pio/models/live2d/snow_miku/model.json",
5
  },
6
  position: {
7
    corner: "bottom-right",
8
    offsetX: 0,
9
    offsetY: 0,
10
  },
11
  size: {
12
    width: 230,
13
    height: 280,
14
  },
15
  interactive: {
16
    enabled: true,
17
    clickMessages: [
18
      "你好！我是Miku~",
19
      "有什么需要帮助的吗？",
20
      "今天天气真不错呢！"
21
    ],
22
    messageDisplayTime: 3000,
23
  },
24
  responsive: {
25
    hideOnMobile: true,
26
    mobileBreakpoint: 768,
27
  },
28
};

配置选项详解#

位置配置 (position)#

显示位置 (corner)#

值	说明
`"bottom-left"`	左下角
`"bottom-right"`	右下角
`"top-left"`	左上角
`"top-right"`	右上角

偏移设置#

1
position: {
2
  corner: "bottom-right",
3
  offsetX: 20,  // 距离右边缘20px
4
  offsetY: 20,  // 距离底部20px
5
}

尺寸配置 (size)#

1
size: {
2
  width: 250,   // 容器宽度（像素）
3
  height: 280,  // 容器高度（像素）
4
}

注意事项：

尺寸过大会影响页面性能
建议根据模型实际大小调整
移动端会自动缩放

交互配置 (interactive)#

点击动画 (clickAnimations)#

1
clickAnimations: [
2
  "emoji_0",    // 动画名称1
3
  "emoji_1",    // 动画名称2
4
  "emoji_2"     // 动画名称3
5
]

说明：

动画名称必须与模型文件中的动画名称一致
点击时会随机播放其中一个动画
可以添加多个动画增加趣味性

点击消息 (clickMessages)#

1
clickMessages: [
2
  "你好呀！我是流萤~",
3
  "今天也要加油哦！✨",
4
  "想要一起去看星空吗？🌟"
5
]

说明：

点击时会随机显示一条消息
支持emoji表情
消息会显示在模型旁边

待机动画 (idleAnimations)#

1
idleAnimations: [
2
  "idle",      // 基础待机动画
3
  "emoji_0",   // 其他待机动画
4
  "emoji_1"
5
]

说明：

模型空闲时会循环播放这些动画
建议包含一个基础的idle动画
可以添加多个动画增加变化

响应式配置 (responsive)#

1
responsive: {
2
  hideOnMobile: true,        // 移动端隐藏
3
  mobileBreakpoint: 768,     // 移动端断点（像素）
4
}

断点说明：

屏幕宽度小于断点值时视为移动端
移动端可以隐藏看板娘以节省空间
建议断点设置为768px

模型文件管理#

文件结构#

1
public/pio/models/
2
├── spine/                    # Spine模型目录
3
│   └── haoyang/             # 具体模型目录
4
│       ├── 1310.json        # 模型配置文件
5
│       ├── 1310.atlas       # 图集文件
6
│       └── 1310.png         # 纹理图片
7
└── live2d/                  # Live2D模型目录
8
    └── snow_miku/           # 具体模型目录
9
        ├── model.json       # 模型配置文件
10
        └── textures/        # 纹理目录
11
            └── *.png        # 纹理图片

模型文件获取#

Spine 模型#

从官方商店购买或下载免费模型
导出为JSON格式
确保包含.atlas和.png文件

Live2D 模型#

从官方商店购买或下载免费模型
确保包含model.json文件
整理纹理文件到textures目录

实现代码#

复制看板娘文件#

夸克网盘：https://pan.quark.cn/s/c9afe5235080

新建 pioConfig.ts 文件#

如果没有把 src/config.ts 模块化，那么不需要新建 pioConfig.ts 文件，直接把 spineModelConfig 或live2dModelConfig 写入到 config.ts 中就行

1
import type { SpineModelConfig, Live2DModelConfig } from "../types/config";
2

3
// Spine 看板娘配置
4
export const spineModelConfig: SpineModelConfig = {
5
  enable: true, // 启用 Spine 看板娘
6
  model: {
7
    // Spine模型文件路径
8
    path: "/pio/models/spine/haoyang/1310.json",
9
    scale: 1.0, // 模型缩放比例
10
    x: 0, // X轴偏移
11
    y: 0, // Y轴偏移
12
  },
13
  position: {
14
    // 显示位置 bottom-left，bottom-right，top-left，top-right，注意：在右下角可能会挡住返回顶部按钮
15
    corner: "bottom-left",
16
    offsetX: 0, // 距离右边缘0px
17
    offsetY: 0, // 距离底部0px
18
  },
19
  size: {
20
    width: 135, // 容器宽度
21
    height: 165, // 容器高度
22
  },
23
  interactive: {
24
    enabled: true, // 启用交互功能
25
    clickAnimations: [
26
      "emoji_0",
27
      "emoji_1",
28
      "emoji_2",
29
      "emoji_3",
30
      "emoji_4",
31
      "emoji_5",
32
      "emoji_6",
33
    ], // 点击时随机播放的动画列表
34
    clickMessages: [
35
      "你好呀！我是鹏星~",
36
      "今天也要加油哦！✨",
37
      "想要一起去看星空吗？🌟",
38
      "记得要好好休息呢~",
39
      "有什么想对我说的吗？💫",
40
      "让我们一起探索未知的世界吧！🚀",
41
      "每一颗星星都有自己的故事~⭐",
42
      "希望能带给你温暖和快乐！💖",
43
    ], // 点击时随机显示的文字消息
44
    messageDisplayTime: 3000, // 文字显示时间（毫秒）
45
    idleAnimations: ["idle", "emoji_0", "emoji_1", "emoji_3", "emoji_4"], // 待机动画列表
46
    idleInterval: 8000, // 待机动画切换间隔（8秒）
47
  },
48
  responsive: {
49
    hideOnMobile: true, // 在移动端隐藏
50
    mobileBreakpoint: 768, // 移动端断点
51
  },
52
  zIndex: 1000, // 层级
53
  opacity: 1.0, // 完全不透明
54
};
55

56
// Live2D 看板娘配置
57
export const live2dModelConfig: Live2DModelConfig = {
58
  enable: false, // 启用 Live2D 看板娘
59
  model: {
60
    // Live2D模型文件路径
61
    path: "/pio/models/live2d/snow_miku/model.json",
62
    // path: "/pio/models/live2d/illyasviel/illyasviel.model.json",
63
  },
64
  position: {
65
    // 显示位置 bottom-left，bottom-right，top-left，top-right，注意：在右下角可能会挡住返回顶部按钮
66
    corner: "bottom-left", // 显示位置
67
    offsetX: 0, // 距离边缘20px
68
    offsetY: 0, // 距离底部20px
69
  },
70
  size: {
71
    width: 135, // 容器宽度
72
    height: 165, // 容器高度
73
  },
74
  interactive: {
75
    enabled: true, // 启用交互功能
76
    // motions 和 expressions 将从模型 JSON 文件中自动读取
77
    clickMessages: [
78
      "你好！我是鹏星~",
79
      "有什么需要帮助的吗？",
80
      "今天天气真不错呢！",
81
      "要不要一起玩游戏？",
82
      "记得按时休息哦！",
83
    ], // 点击时随机显示的文字消息
84
    messageDisplayTime: 3000, // 文字显示时间（毫秒）
85
  },
86
  responsive: {
87
    hideOnMobile: true, // 在移动端隐藏
88
    mobileBreakpoint: 768, // 移动端断点
89
  },
90
};

新增src\types\config.ts看板娘类别#

1
// Spine 看板娘配置
2
export type SpineModelConfig = {
3
  enable: boolean; // 是否启用 Spine 看板娘
4
  model: {
5
    path: string; // 模型文件路径 (.json)
6
    scale?: number; // 模型缩放比例，默认1.0
7
    x?: number; // X轴偏移，默认0
8
    y?: number; // Y轴偏移，默认0
9
  };
10
  position: {
11
    corner: "bottom-left" | "bottom-right" | "top-left" | "top-right"; // 显示位置
12
    offsetX?: number; // 水平偏移量，默认20px
13
    offsetY?: number; // 垂直偏移量，默认20px
14
  };
15
  size: {
16
    width?: number; // 容器宽度，默认280px
17
    height?: number; // 容器高度，默认400px
18
  };
19
  interactive?: {
20
    enabled?: boolean; // 是否启用交互功能，默认true
21
    clickAnimations?: string[]; // 点击时随机播放的动画列表
22
    clickMessages?: string[]; // 点击时随机显示的文字消息
23
    messageDisplayTime?: number; // 文字显示时间（毫秒），默认3000
24
    idleAnimations?: string[]; // 待机动画列表
25
    idleInterval?: number; // 待机动画切换间隔（毫秒），默认10000
26
  };
27
  responsive?: {
28
    hideOnMobile?: boolean; // 是否在移动端隐藏，默认false
29
    mobileBreakpoint?: number; // 移动端断点，默认768px
30
  };
31
  zIndex?: number; // 层级，默认1000
32
  opacity?: number; // 透明度，0-1，默认1.0
33
  };
34

35
  // Live2D 看板娘配置
36
  export type Live2DModelConfig = {
37
  enable: boolean; // 是否启用 Live2D 看板娘
38
  model: {
39
    path: string; // 模型文件夹路径或model3.json文件路径
40
  };
41
  position?: {
42
    corner?: "bottom-left" | "bottom-right" | "top-left" | "top-right"; // 显示位置，默认bottom-right
43
    offsetX?: number; // 水平偏移量，默认20px
44
    offsetY?: number; // 垂直偏移量，默认20px
45
  };
46
  size?: {
47
    width?: number; // 容器宽度，默认280px
48
    height?: number; // 容器高度，默认250px
49
  };
50
  interactive?: {
51
    enabled?: boolean; // 是否启用交互功能，默认true
52
    // motions 和 expressions 将从模型 JSON 文件中自动读取
53
    clickMessages?: string[]; // 点击时随机显示的文字消息
54
    messageDisplayTime?: number; // 文字显示时间（毫秒），默认3000
55
  };
56
  responsive?: {
57
    hideOnMobile?: boolean; // 是否在移动端隐藏，默认false
58
    mobileBreakpoint?: number; // 移动端断点，默认768px
59
  };
60
  };

新建src\components\widget\PioMessageBox.astro#

1
---
2
// 消息框公共组件
3
// 用于Live2D和Spine模型的消息显示
4
---
5

6
<script>
7
    // 全局变量，跟踪当前显示的消息容器和隐藏定时器
8
    let currentMessageContainer: HTMLDivElement | null = null;
9
    let hideMessageTimer: number | null = null;
10

11
    // 消息显示函数
12
    export function showMessage(message: string, options: { containerId?: string; displayTime?: number } = {}) {
13
      // 防止空消息或重复调用
14
      if (!message || !message.trim()) {
15
        return;
16
      }
17

18
      // 立即清除之前的消息
19
      if (currentMessageContainer) {
20
        if (hideMessageTimer !== null) {
21
          clearTimeout(hideMessageTimer);
22
        }
23
        if (currentMessageContainer.parentNode) {
24
          currentMessageContainer.parentNode.removeChild(currentMessageContainer);
25
        }
26
        currentMessageContainer = null;
27
      }
28

29
      // 确保DOM中没有残留的消息容器
30
      const existingMessages = document.querySelectorAll(
31
        ".model-message-container"
32
      );
33
      existingMessages.forEach((msg) => {
34
        if (msg.parentNode) {
35
          msg.parentNode.removeChild(msg);
36
        }
37
      });
38

39
      // 检测暗色主题
40
      const isDarkMode =
41
        document.documentElement.classList.contains("dark") ||
42
        window.matchMedia("(prefers-color-scheme: dark)").matches;
43

44
      // 创建消息容器
45
      const messageContainer = document.createElement("div");
46
      messageContainer.className = "model-message-container";
47

48
      // 创建消息元素
49
      const messageEl = document.createElement("div");
50
      messageEl.className = "model-message";
51
      messageEl.textContent = message;
52

53
      // 创建箭头元素
54
      const arrowEl = document.createElement("div");
55
      arrowEl.className = "model-message-arrow";
56

57
      // 设置容器样式
58
      Object.assign(messageContainer.style, {
59
        position: "fixed",
60
        zIndex: "1001",
61
        pointerEvents: "none",
62
        opacity: "0",
63
        transform: "translateY(15px) translateX(-50%) scale(0.9)",
64
        transition: "all 0.4s cubic-bezier(0.34, 1.56, 0.64, 1)",
65
      });
66

67
      // 设置消息框美化样式（支持暗色主题）
68
      const messageStyles = {
69
        position: "relative",
70
        background: isDarkMode
71
          ? "linear-gradient(135deg, rgba(45, 55, 72, 0.95), rgba(26, 32, 44, 0.9))"
72
          : "linear-gradient(135deg, rgba(255, 255, 255, 0.95), rgba(240, 248, 255, 0.9))",
73
        color: isDarkMode ? "#e2e8f0" : "#2c3e50",
74
        padding: "12px 16px",
75
        borderRadius: "16px",
76
        fontSize: "14px",
77
        fontWeight: "500",
78
        fontFamily:
79
          '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
80
        maxWidth: "240px",
81
        minWidth: "100px",
82
        wordWrap: "break-word",
83
        textAlign: "center",
84
        whiteSpace: "pre-wrap",
85
        boxShadow: isDarkMode
86
          ? "0 8px 32px rgba(0, 0, 0, 0.3), 0 2px 8px rgba(0, 0, 0, 0.2)"
87
          : "0 8px 32px rgba(0, 0, 0, 0.12), 0 2px 8px rgba(0, 0, 0, 0.08)",
88
        border: isDarkMode
89
          ? "1px solid rgba(255, 255, 255, 0.1)"
90
          : "1px solid rgba(255, 255, 255, 0.6)",
91
        backdropFilter: "blur(12px)",
92
        letterSpacing: "0.3px",
93
        lineHeight: "1.4",
94
      };
95
      Object.assign(messageEl.style, messageStyles);
96

97
      // 设置箭头样式（居中显示）
98
      Object.assign(arrowEl.style, {
99
        position: "absolute",
100
        top: "100%",
101
        left: "50%",
102
        transform: "translateX(-50%)", // 箭头居中
103
        width: "0",
104
        height: "0",
105
        borderLeft: "8px solid transparent",
106
        borderRight: "8px solid transparent",
107
        borderTop: isDarkMode
108
          ? "8px solid rgba(45, 55, 72, 0.95)"
109
          : "8px solid rgba(255, 255, 255, 0.95)",
110
        filter: "drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1))",
111
      });
112

113
      // 组装消息框元素
114
      messageEl.appendChild(arrowEl);
115
      messageContainer.appendChild(messageEl);
116

117
      // 添加到页面并保存引用
118
      document.body.appendChild(messageContainer);
119
      currentMessageContainer = messageContainer;
120

121
      // 将消息显示在模型头顶居中
122
      const container = document.getElementById(options.containerId || "model-container");
123
      if (container) {
124
        const rect = container.getBoundingClientRect();
125

126
        // 消息框居中显示在模型上方
127
        const containerCenterX = rect.left + rect.width / 2;
128

129
        // 使用估算的消息框尺寸进行初步定位
130
        const estimatedMessageWidth = 240; // 使用maxWidth作为估算
131
        const estimatedMessageHeight = 60; // 估算高度
132
        const screenPadding = 10; // 距离屏幕边缘的最小距离
133

134
        // 计算消息框的实际位置（考虑translateX(-50%)的影响）
135
        let messageX = containerCenterX;
136
        let messageY = rect.top - estimatedMessageHeight - 25; // 距离模型顶部25px
137

138
        // 屏幕边界检查 - 水平方向
139
        const minX = screenPadding + estimatedMessageWidth / 2; // 考虑translateX(-50%)
140
        const maxX =
141
          window.innerWidth - screenPadding - estimatedMessageWidth / 2;
142

143
        if (messageX < minX) {
144
          messageX = minX;
145
        } else if (messageX > maxX) {
146
          messageX = maxX;
147
        }
148

149
        // 屏幕边界检查 - 垂直方向
150
        const minY = screenPadding;
151
        const maxY = window.innerHeight - estimatedMessageHeight - screenPadding;
152

153
        if (messageY < minY) {
154
          // 如果上方空间不够，显示在模型下方
155
          messageY = rect.bottom + 25;
156
          // 调整箭头方向（显示在下方）
157
          arrowEl.style.top = "0";
158
          arrowEl.style.bottom = "auto";
159
          arrowEl.style.borderTop = "none";
160
          arrowEl.style.borderBottom = isDarkMode
161
            ? "8px solid rgba(45, 55, 72, 0.95)"
162
            : "8px solid rgba(255, 255, 255, 0.95)";
163
        } else if (messageY > maxY) {
164
          messageY = maxY;
165
        }
166

167
        // 设置位置
168
        messageContainer.style.left = messageX + "px";
169
        messageContainer.style.top = messageY + "px";
170

171
        // 在消息框渲染后，进行精确的边界调整
172
        setTimeout(() => {
173
          const actualMessageRect = messageContainer.getBoundingClientRect();
174
          const actualWidth = actualMessageRect.width;
175
          const actualHeight = actualMessageRect.height;
176

177
          // 重新计算水平位置
178
          let adjustedX = containerCenterX;
179
          const actualMinX = screenPadding + actualWidth / 2;
180
          const actualMaxX = window.innerWidth - screenPadding - actualWidth / 2;
181

182
          if (adjustedX < actualMinX) {
183
            adjustedX = actualMinX;
184
          } else if (adjustedX > actualMaxX) {
185
            adjustedX = actualMaxX;
186
          }
187

188
          // 重新计算垂直位置
189
          let adjustedY = rect.top - actualHeight - 25;
190
          const actualMinY = screenPadding;
191
          const actualMaxY = window.innerHeight - actualHeight - screenPadding;
192
          let isAboveModel = true; // 标记消息框是否在模型上方
193

194
          if (adjustedY < actualMinY) {
195
            adjustedY = rect.bottom + 25;
196
            isAboveModel = false;
197
          } else if (adjustedY > actualMaxY) {
198
            adjustedY = actualMaxY;
199
          }
200

201
          // 计算箭头应该指向的位置（模型中心）
202
          const modelCenterX = rect.left + rect.width / 2;
203
          const messageCenterX = adjustedX; // 消息框中心位置
204
          const arrowOffsetX = modelCenterX - messageCenterX; // 箭头相对于消息框中心的偏移
205

206
          // 限制箭头偏移范围，避免超出消息框边界
207
          const maxOffset = actualWidth / 2 - 20; // 留出20px边距
208
          const clampedOffsetX = Math.max(
209
            -maxOffset,
210
            Math.min(maxOffset, arrowOffsetX)
211
          );
212

213
          // 根据最终位置调整箭头方向和位置
214
          if (isAboveModel) {
215
            // 消息框在模型上方，箭头向下
216
            Object.assign(arrowEl.style, {
217
              position: "absolute",
218
              top: "100%",
219
              left: "50%",
220
              bottom: "auto",
221
              transform: `translateX(calc(-50% + ${clampedOffsetX}px))`,
222
              width: "0",
223
              height: "0",
224
              borderLeft: "8px solid transparent",
225
              borderRight: "8px solid transparent",
226
              borderTop: isDarkMode
227
                ? "8px solid rgba(45, 55, 72, 0.95)"
228
                : "8px solid rgba(255, 255, 255, 0.95)",
229
              borderBottom: "none",
230
              filter: "drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1))",
231
            });
232
          } else {
233
            // 消息框在模型下方，箭头向上
234
            Object.assign(arrowEl.style, {
235
              position: "absolute",
236
              top: "0",
237
              left: "50%",
238
              bottom: "auto",
239
              transform: `translateX(calc(-50% + ${clampedOffsetX}px))`,
240
              width: "0",
241
              height: "0",
242
              borderLeft: "8px solid transparent",
243
              borderRight: "8px solid transparent",
244
              borderTop: "none",
245
              borderBottom: isDarkMode
246
                ? "8px solid rgba(45, 55, 72, 0.95)"
247
                : "8px solid rgba(255, 255, 255, 0.95)",
248
              filter: "drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1))",
249
            });
250
          }
251

252
          // 应用调整后的位置
253
          messageContainer.style.left = adjustedX + "px";
254
          messageContainer.style.top = adjustedY + "px";
255
        }, 50); // 增加延迟确保消息框完全渲染
256
      }
257

258
      // 显示动画
259
      setTimeout(() => {
260
        messageContainer.style.opacity = "1";
261
        messageContainer.style.transform =
262
          "translateY(0) translateX(-50%) scale(1)";
263
      }, 100); // 延迟到边界调整完成后
264

265
      // 自动隐藏
266
      const displayTime = options.displayTime || 3000;
267
      hideMessageTimer = window.setTimeout(() => {
268
        messageContainer.style.opacity = "0";
269
        messageContainer.style.transform =
270
          "translateY(-15px) translateX(-50%) scale(0.95)";
271
        setTimeout(() => {
272
          if (messageContainer.parentNode) {
273
            messageContainer.parentNode.removeChild(messageContainer);
274
          }
275
          // 清除引用
276
          if (currentMessageContainer === messageContainer) {
277
            currentMessageContainer = null;
278
          }
279
        }, 400);
280
      }, displayTime);
281
    }
282

283
    // 清理消息函数
284
    export function clearMessage() {
285
      if (currentMessageContainer) {
286
        if (hideMessageTimer !== null) {
287
          clearTimeout(hideMessageTimer);
288
        }
289
        if (currentMessageContainer.parentNode) {
290
          currentMessageContainer.parentNode.removeChild(currentMessageContainer);
291
        }
292
        currentMessageContainer = null;
293
      }
294

295
      // 清理所有消息容器
296
      const existingMessages = document.querySelectorAll(
297
        ".model-message-container"
298
      );
299
      existingMessages.forEach((msg) => {
300
        if (msg.parentNode) {
301
          msg.parentNode.removeChild(msg);
302
        }
303
      });
304
    }
305

306
    // 将函数暴露到全局作用域
307
    (window as any).showModelMessage = showMessage;
308
    (window as any).clearModelMessage = clearMessage;
309
  </script>

新建src\components\widget\Live2DWidget.astro#

1
---
2
import type { Live2DModelConfig } from "@/types/config";
3
import MessageBox from "./PioMessageBox.astro";
4
import { url } from "@/utils/url-utils";
5

6
interface Props {
7
  config: Live2DModelConfig;
8
}
9

10
const { config } = Astro.props;
11

12
// 获取位置和尺寸配置
13
const position = config.position || {
14
  corner: "bottom-right" as const,
15
  offsetX: 20,
16
  offsetY: 20,
17
};
18
const size = config.size || { width: 280, height: 250 };
19
---
20

21
<div
22
  id="live2d-widget"
23
  class="live2d-widget"
24
  style={`
25
    width: ${size.width}px;
26
    height: ${size.height}px;
27
    ${position.corner?.includes("right") ? "right" : "left"}: ${position.offsetX}px;
28
    ${position.corner?.includes("top") ? "top" : "bottom"}: ${position.offsetY}px;
29
  `}
30
>
31
  <canvas id="live2d-canvas" width={size.width} height={size.height}></canvas>
32
</div>
33

34
<!-- 引入消息框组件 -->
35
<MessageBox />
36

37
<script define:vars={{ config, modelPath: url(config.model.path), sdkPath: url("/pio/static/live2d-sdk/live2d.min.js") }}>
38
  let modelData = null;
39
  let motionGroups = {};
40
  let hitAreas = {};
41
  let currentMotionGroup = "idle";
42
  let currentMotionIndex = 0;
43

44
  // Use loadlive2d function from the working project
45
  function initLive2D() {
46
    if (!window.loadlive2d) {
47
      console.error("loadlive2d function not available");
48
      return;
49
    }
50

51
    if (!config.model || !config.model.path) {
52
      console.error("No model path configured");
53
      return;
54
    }
55

56
    const modelPath = modelPath;
57

58
    // Load model data first to get motion groups and hit areas
59
    fetch(modelPath)
60
      .then((response) => response.json())
61
      .then((data) => {
62
        modelData = data;
63
        motionGroups = data.motions || {};
64
        hitAreas = data.hit_areas_custom || data.hit_areas || {};
65

66
        console.log("Loaded model data:", {
67
          motionGroups: Object.keys(motionGroups),
68
          hitAreas: Object.keys(hitAreas),
69
        });
70

71
        // Load the model using loadlive2d
72
        window.loadlive2d("live2d-canvas", modelPath);
73

74
        // Setup interactions after a delay to ensure model is loaded
75
        setTimeout(() => {
76
          setupInteractions();
77
        }, 2000);
78
      })
79
      .catch((error) => {
80
        console.error("Failed to load model data:", error);
81
      });
82
  }
83

84
  // Setup click interactions and drag functionality
85
  function setupInteractions() {
86
    const canvas = document.getElementById("live2d-canvas");
87
    const container = document.getElementById("live2d-widget");
88
    if (!canvas || !container) return;
89

90
    canvas.addEventListener("click", handleClick);
91

92
    // 添加拖拽功能
93
    let isDragging = false;
94
    let dragStart = { x: 0, y: 0 };
95
    let containerStart = { x: 0, y: 0 };
96

97
    // 鼠标事件
98
    container.addEventListener("mousedown", (e) => {
99
      if (e.button !== 0) return; // 只响应左键
100
      isDragging = true;
101
      dragStart = { x: e.clientX, y: e.clientY };
102

103
      const rect = container.getBoundingClientRect();
104
      containerStart = { x: rect.left, y: rect.top };
105

106
      container.style.cursor = "grabbing";
107
      e.preventDefault();
108
    });
109

110
    document.addEventListener("mousemove", (e) => {
111
      if (!isDragging) return;
112

113
      const deltaX = e.clientX - dragStart.x;
114
      const deltaY = e.clientY - dragStart.y;
115

116
      const newX = containerStart.x + deltaX;
117
      const newY = containerStart.y + deltaY;
118

119
      // 边界检查
120
      const maxX = window.innerWidth - container.offsetWidth;
121
      const maxY = window.innerHeight - container.offsetHeight;
122

123
      const clampedX = Math.max(0, Math.min(newX, maxX));
124
      const clampedY = Math.max(0, Math.min(newY, maxY));
125

126
      container.style.left = clampedX + "px";
127
      container.style.right = "auto";
128
      container.style.top = clampedY + "px";
129
      container.style.bottom = "auto";
130
    });
131

132
    document.addEventListener("mouseup", () => {
133
      if (isDragging) {
134
        isDragging = false;
135
        container.style.cursor = "grab";
136
      }
137
    });
138

139
    // 触摸事件（移动端支持）
140
    container.addEventListener("touchstart", (e) => {
141
      if (e.touches.length !== 1) return;
142
      isDragging = true;
143
      const touch = e.touches[0];
144
      dragStart = { x: touch.clientX, y: touch.clientY };
145

146
      const rect = container.getBoundingClientRect();
147
      containerStart = { x: rect.left, y: rect.top };
148

149
      e.preventDefault();
150
    });
151

152
    document.addEventListener("touchmove", (e) => {
153
      if (!isDragging || e.touches.length !== 1) return;
154

155
      const touch = e.touches[0];
156
      const deltaX = touch.clientX - dragStart.x;
157
      const deltaY = touch.clientY - dragStart.y;
158

159
      const newX = containerStart.x + deltaX;
160
      const newY = containerStart.y + deltaY;
161

162
      // 边界检查
163
      const maxX = window.innerWidth - container.offsetWidth;
164
      const maxY = window.innerHeight - container.offsetHeight;
165

166
      const clampedX = Math.max(0, Math.min(newX, maxX));
167
      const clampedY = Math.max(0, Math.min(newY, maxY));
168

169
      container.style.left = clampedX + "px";
170
      container.style.right = "auto";
171
      container.style.top = clampedY + "px";
172
      container.style.bottom = "auto";
173

174
      e.preventDefault();
175
    });
176

177
    document.addEventListener("touchend", () => {
178
      isDragging = false;
179
    });
180

181
    // 设置初始光标样式
182
    container.style.cursor = "grab";
183

184
    // 窗口大小变化时重新检查边界
185
    window.addEventListener("resize", () => {
186
      const rect = container.getBoundingClientRect();
187
      const maxX = window.innerWidth - container.offsetWidth;
188
      const maxY = window.innerHeight - container.offsetHeight;
189

190
      if (rect.left > maxX) {
191
        container.style.left = maxX + "px";
192
        container.style.right = "auto";
193
      }
194
      if (rect.top > maxY) {
195
        container.style.top = maxY + "px";
196
        container.style.bottom = "auto";
197
      }
198
    });
199

200
    console.log("Live2D interactions and drag functionality setup complete");
201
  }
202

203
  // Handle click events
204
  function handleClick(event) {
205
    if (!motionGroups || Object.keys(motionGroups).length === 0) {
206
      console.log("No motion groups available");
207
      return;
208
    }
209

210
    const rect = event.target.getBoundingClientRect();
211
    const x = event.clientX - rect.left;
212
    const y = event.clientY - rect.top;
213

214
    // Convert to normalized coordinates
215
    const normalizedX = (x / rect.width) * 2 - 1;
216
    const normalizedY = -((y / rect.height) * 2 - 1);
217

218
    console.log("Click at:", { x: normalizedX, y: normalizedY });
219

220
    // Determine which motion to play based on hit areas
221
    let motionGroup = "tap_body"; // default
222

223
    // Check head area
224
    if (hitAreas.head_x && hitAreas.head_y) {
225
      const [headXMin, headXMax] = hitAreas.head_x;
226
      const [headYMin, headYMax] = hitAreas.head_y;
227

228
      if (
229
        normalizedX >= headXMin &&
230
        normalizedX <= headXMax &&
231
        normalizedY >= headYMin &&
232
        normalizedY <= headYMax
233
      ) {
234
        motionGroup = "flick_head";
235
        console.log("Head area clicked - playing flick_head motion");
236
      }
237
    }
238

239
    // Check body area (if not head)
240
    if (motionGroup === "tap_body" && hitAreas.body_x && hitAreas.body_y) {
241
      const [bodyXMin, bodyXMax] = hitAreas.body_x;
242
      const [bodyYMin, bodyYMax] = hitAreas.body_y;
243

244
      if (
245
        normalizedX >= bodyXMin &&
246
        normalizedX <= bodyXMax &&
247
        normalizedY >= bodyYMin &&
248
        normalizedY <= bodyYMax
249
      ) {
250
        console.log("Body area clicked - playing tap_body motion");
251
      }
252
    }
253

254
    // Play motion
255
    playMotion(motionGroup);
256

257
    // Show message
258
    showMessage();
259
  }
260

261
  // 消息框功能已移至公共组件 MessageBox.astro
262

263
  // Show random message using the common MessageBox component
264
  function showMessage() {
265
    const messages = config.interactive?.clickMessages || [
266
      "你好！伊利雅~",
267
      "有什么需要帮助的吗？",
268
      "今天天气真不错呢！",
269
      "要不要一起玩游戏？",
270
      "记得按时休息哦！",
271
    ];
272

273
    const randomMessage = messages[Math.floor(Math.random() * messages.length)];
274

275
    // 使用公共消息框组件
276
    if (window.showModelMessage) {
277
      window.showModelMessage(randomMessage, {
278
        containerId: "live2d-widget",
279
        displayTime: config.interactive?.messageDisplayTime || 3000
280
      });
281
    }
282
  }
283

284
  // Play motion from a specific group
285
  function playMotion(groupName) {
286
    if (!motionGroups[groupName] || motionGroups[groupName].length === 0) {
287
      console.log(`No motions available for group: ${groupName}`);
288
      // Fallback to any available motion group
289
      const availableGroups = Object.keys(motionGroups).filter(
290
        (key) => motionGroups[key].length > 0
291
      );
292
      if (availableGroups.length > 0) {
293
        groupName = availableGroups[0];
294
        console.log(`Using fallback group: ${groupName}`);
295
      } else {
296
        return;
297
      }
298
    }
299

300
    const motions = motionGroups[groupName];
301
    let motionIndex;
302

303
    if (groupName === currentMotionGroup) {
304
      // Cycle through motions in the same group
305
      currentMotionIndex = (currentMotionIndex + 1) % motions.length;
306
      motionIndex = currentMotionIndex;
307
    } else {
308
      // Random motion from new group
309
      motionIndex = Math.floor(Math.random() * motions.length);
310
      currentMotionIndex = motionIndex;
311
    }
312

313
    currentMotionGroup = groupName;
314

315
    console.log(`Playing motion ${motionIndex} from group ${groupName}`);
316

317
    // Trigger motion change by reloading model with different parameters
318
    // This is a workaround since we can't directly control motions in loadlive2d
319
    const canvas = document.getElementById("live2d-canvas");
320
    if (canvas && window.loadlive2d) {
321
      // Add motion info to canvas data for potential future use
322
      canvas.dataset.currentMotionGroup = groupName;
323
      canvas.dataset.currentMotionIndex = motionIndex;
324

325
      // Trigger a visual feedback
326
      canvas.style.transform = "scale(1.05)";
327
      setTimeout(() => {
328
        canvas.style.transform = "scale(1)";
329
      }, 150);
330
    }
331
  }
332

333
  // Load Live2D and initialize
334
  function loadLive2DSDK() {
335
    // 检查移动端显示设置，如果隐藏则不加载运行时
336
    if (
337
      config.responsive?.hideOnMobile &&
338
      window.innerWidth <= (config.responsive.mobileBreakpoint || 768)
339
    ) {
340
      console.log("📱 Mobile device detected, skipping Live2D model initialization");
341
      const widget = document.getElementById("live2d-widget");
342
      if (widget) widget.style.display = "none";
343
      return;
344
    }
345

346
    // Check if Live2D SDK is already loaded
347
    if (window.loadlive2d) {
348
      initLive2D();
349
      return;
350
    }
351

352
    // Load Live2D SDK
353
    const script = document.createElement("script");
354
    script.src = sdkPath;
355
    script.onload = () => {
356
      // Wait a bit for the SDK to initialize
357
      setTimeout(() => {
358
        if (window.loadlive2d) {
359
          initLive2D();
360
        } else {
361
          console.error("loadlive2d function not found after loading SDK");
362
        }
363
      }, 100);
364
    };
365
    script.onerror = () => {
366
      console.error("Failed to load Live2D SDK");
367
    };
368
    document.head.appendChild(script);
369
  }
370

371
  // Handle responsive display
372
  function handleResponsive() {
373
    const widget = document.getElementById("live2d-widget");
374
    if (!widget) return;
375

376
    const responsive = config.responsive;
377
    if (responsive?.hideOnMobile) {
378
      const breakpoint = responsive.mobileBreakpoint || 768;
379
      if (window.innerWidth <= breakpoint) {
380
        widget.style.display = "none";
381
      } else {
382
        widget.style.display = "block";
383
      }
384
    }
385
  }
386

387
  // Initialize when ready (only once)
388
  if (document.readyState === "loading") {
389
    document.addEventListener("DOMContentLoaded", () => {
390
      // 检查是否已经初始化
391
      if (!window.live2dModelInitialized) {
392
        loadLive2DSDK();
393
        window.live2dModelInitialized = true;
394
      }
395
      handleResponsive();
396
    });
397
  } else {
398
    // 检查是否已经初始化
399
    if (!window.live2dModelInitialized) {
400
      loadLive2DSDK();
401
      window.live2dModelInitialized = true;
402
    }
403
    handleResponsive();
404
  }
405

406
  // Handle window resize for responsive behavior
407
  window.addEventListener("resize", handleResponsive);
408

409
  // 监听 Swup 页面切换事件（如果使用了 Swup）
410
  if (typeof window.swup !== "undefined" && window.swup.hooks) {
411
    window.swup.hooks.on("content:replace", () => {
412
      // 只更新响应式显示，不重新创建模型
413
      setTimeout(() => {
414
        handleResponsive();
415
      }, 100);
416
    });
417
  } else {
418
    // 如果 Swup 还未加载，监听启用事件
419
    document.addEventListener("swup:enable", () => {
420
      if (window.swup && window.swup.hooks) {
421
        window.swup.hooks.on("content:replace", () => {
422
          setTimeout(() => {
423
            handleResponsive();
424
          }, 100);
425
        });
426
      }
427
    });
428
  }
429
</script>
430

431
<style>
432
  .live2d-widget {
433
    position: fixed;
434
    z-index: 999;
435
    pointer-events: auto; /* 启用指针事件以支持拖拽 */
436
    cursor: grab; /* 默认显示拖拽光标 */
437
  }
438

439
  #live2d-canvas {
440
    pointer-events: auto;
441
    cursor: pointer;
442
    transition: all 0.3s ease;
443
    width: 100%;
444
    height: 100%;
445
  }
446

447
  .live2d-widget:hover #live2d-canvas {
448
    opacity: 1;
449
  }
450

451
  /* 拖拽时的光标样式 */
452
  .live2d-widget:active {
453
    cursor: grabbing;
454
  }
455
</style>

新建src\components\widget\SpineModel.astro#

1
---
2
import { spineModelConfig } from "@/config/pioConfig";
3
import MessageBox from "./PioMessageBox.astro";
4
import { url } from "@/utils/url-utils";
5
---
6

7
<!-- Spine Web Player CSS 将在 script 中动态加载 -->{
8
  spineModelConfig.enable && (
9
    <div
10
      id="spine-model-container"
11
      style={`
12
      position: fixed;
13
      ${spineModelConfig.position.corner.includes("right") ? "right" : "left"}: ${spineModelConfig.position.offsetX}px;
14
      ${spineModelConfig.position.corner.includes("top") ? "top" : "bottom"}: ${spineModelConfig.position.offsetY}px;
15
      width: ${spineModelConfig.size.width}px;
16
      height: ${spineModelConfig.size.height}px;
17
      pointer-events: auto;
18
      z-index: 1000;
19
    `}
20
    >
21
      <div id="spine-player-container" style="width: 100%; height: 100%;" />
22
      <div id="spine-error" style="display: none;" />
23
    </div>
24
  )
25
}
26

27
<!-- 引入消息框组件 -->
28
<MessageBox />
29

30
<script define:vars={{ spineModelConfig, modelPath: url(spineModelConfig.model.path), atlasPath: url(spineModelConfig.model.path.replace(".json", ".atlas")), cssPath: url("/pio/static/spine-player.min.css"), jsPath: url("/pio/static/spine-player.min.js") }}>
31
  // 动态加载 Spine CSS（带本地备用）
32
  function loadSpineCSS() {
33
    if (!spineModelConfig.enable) return;
34

35
    // 检查是否已经加载
36
    const existingLink = document.querySelector('link[href*="spine-player"]');
37
    if (existingLink) return;
38

39
    // 首先尝试加载 CDN CSS
40
    const cdnLink = document.createElement("link");
41
    cdnLink.rel = "stylesheet";
42
    cdnLink.href =
43
      "https://unpkg.com/@esotericsoftware/spine-player@4.2.*/dist/spine-player.min.css";
44

45
    // 监听加载失败事件，自动回退到本地文件
46
    cdnLink.onerror = function () {
47
      console.warn("⚠️ Spine CSS CDN failed, trying local fallback...");
48

49
      // 移除失败的 CDN link
50
      if (cdnLink.parentNode) {
51
        cdnLink.parentNode.removeChild(cdnLink);
52
      }
53

54
      // 创建本地备用 CSS link
55
      const localLink = document.createElement("link");
56
      localLink.rel = "stylesheet";
57
      localLink.href = cssPath;
58
      localLink.onerror = function () {
59
        console.error("❌ Failed to load Spine CSS");
60
      };
61

62
      document.head.appendChild(localLink);
63
    };
64

65
    document.head.appendChild(cdnLink);
66
  }
67

68
  // 消息框功能已移至公共组件 MessageBox.astro
69
  let isClickProcessing = false; // 防止重复点击的标志
70
  let lastClickTime = 0; // 记录最后一次点击时间
71

72
  // 全局变量，防止重复初始化
73
  window.spineModelInitialized = window.spineModelInitialized || false;
74
  window.spinePlayerInstance = window.spinePlayerInstance || null;
75

76
  // 消息显示函数 - 使用公共消息框组件
77
  function showMessage(message) {
78
    // 使用公共消息框组件
79
    if (window.showModelMessage) {
80
      window.showModelMessage(message, {
81
        containerId: "spine-model-container",
82
        displayTime: spineModelConfig.interactive.messageDisplayTime || 3000
83
      });
84
    }
85
  }
86

87
  // 更新响应式显示
88
  function updateResponsiveDisplay() {
89
    if (!spineModelConfig.enable) return;
90

91
    const container = document.getElementById("spine-model-container");
92
    if (!container) return;
93

94
    // 检查移动端显示设置
95
    if (
96
      spineModelConfig.responsive.hideOnMobile &&
97
      window.innerWidth <= spineModelConfig.responsive.mobileBreakpoint
98
    ) {
99
      container.style.display = "none";
100
    } else {
101
      container.style.display = "block";
102
    }
103
  }
104

105
  // 清理函数
106
  function cleanupSpineModel() {
107
    console.log("🧹 Cleaning up existing Spine model...");
108

109
    // 清理消息显示（使用公共组件）
110
    if (window.clearModelMessage) {
111
      window.clearModelMessage();
112
    }
113

114
    // 清理现有的播放器实例
115
    if (window.spinePlayerInstance) {
116
      try {
117
        if (window.spinePlayerInstance.dispose) {
118
          window.spinePlayerInstance.dispose();
119
        }
120
      } catch (e) {
121
        console.warn("Error disposing spine player:", e);
122
      }
123
      window.spinePlayerInstance = null;
124
    }
125

126
    // 清理容器内容
127
    const playerContainer = document.getElementById("spine-player-container");
128
    if (playerContainer) {
129
      playerContainer.innerHTML = "";
130
    }
131

132
    // 重置初始化标志
133
    window.spineModelInitialized = false;
134
  }
135

136
  async function initSpineModel() {
137
    if (!spineModelConfig.enable) return;
138

139
    // 检查移动端显示设置，如果隐藏则不加载运行时
140
    if (
141
      spineModelConfig.responsive.hideOnMobile &&
142
      window.innerWidth <= spineModelConfig.responsive.mobileBreakpoint
143
    ) {
144
      console.log("📱 Mobile device detected, skipping Spine model initialization");
145
      const container = document.getElementById("spine-model-container");
146
      if (container) container.style.display = "none";
147
      return;
148
    }
149

150
    // 检查是否已经初始化
151
    if (window.spineModelInitialized) {
152
      console.log("⏭️ Spine model already initialized, skipping...");
153
      return;
154
    }
155

156
    console.log("🎯 Initializing Spine Model...");
157

158
    // 先清理可能存在的旧实例
159
    cleanupSpineModel();
160

161
    // 首先加载 CSS
162
    loadSpineCSS();
163

164
    // 加载 Spine Web Player 运行时
165
    const loadSpineRuntime = () => {
166
      return new Promise((resolve, reject) => {
167
        if (typeof window.spine !== "undefined") {
168
          console.log("✅ Spine runtime already loaded");
169
          resolve();
170
          return;
171
        }
172

173
        console.log("📦 Loading Spine runtime...");
174
        const script = document.createElement("script");
175
        script.src =
176
          "https://unpkg.com/@esotericsoftware/spine-player@4.2.*/dist/iife/spine-player.min.js";
177
        script.onload = () => {
178
          console.log("✅ Spine runtime loaded from CDN");
179
          resolve();
180
        };
181
        script.onerror = (error) => {
182
          console.warn("⚠️ CDN failed, trying local fallback...");
183

184
          // 尝试本地回退
185
          const fallbackScript = document.createElement("script");
186
          fallbackScript.src = jsPath;
187
          fallbackScript.onload = () => {
188
            console.log("✅ Spine runtime loaded from local fallback");
189
            resolve();
190
          };
191
          fallbackScript.onerror = () => {
192
            reject(new Error("Failed to load Spine runtime"));
193
          };
194
          document.head.appendChild(fallbackScript);
195
        };
196
        document.head.appendChild(script);
197
      });
198
    };
199

200
    // 等待 Spine 库加载
201
    const waitForSpine = () => {
202
      return new Promise((resolve, reject) => {
203
        let attempts = 0;
204
        const maxAttempts = 50;
205

206
        const check = () => {
207
          attempts++;
208
          if (typeof window.spine !== "undefined" && window.spine.SpinePlayer) {
209
            console.log("✅ Spine runtime loaded");
210
            resolve();
211
          } else if (attempts >= maxAttempts) {
212
            reject(new Error("Spine runtime loading timeout"));
213
          } else {
214
            setTimeout(check, 100);
215
          }
216
        };
217
        check();
218
      });
219
    };
220

221
    try {
222
      // 首先加载 Spine 运行时
223
      await loadSpineRuntime();
224

225
      // 然后等待 Spine 对象可用
226
      await waitForSpine();
227

228
      // 标记为已初始化
229
      window.spineModelInitialized = true;
230

231
      // 创建 SpinePlayer
232
      const player = new window.spine.SpinePlayer("spine-player-container", {
233
        skeleton: modelPath,
234
        atlas: atlasPath,
235
        animation: "idle",
236
        backgroundColor: "#00000000", // 透明背景
237
        showControls: false, // 隐藏控件
238
        alpha: true,
239
        premultipliedAlpha: false,
240
        success: (player) => {
241
          console.log("🎉 Spine model loaded successfully!");
242

243
          // 保存播放器实例引用
244
          window.spinePlayerInstance = player;
245

246
          // 初始化完成后设置默认姿态
247
          setTimeout(() => {
248
            if (player.skeleton) {
249
              try {
250
                player.skeleton.updateWorldTransform();
251
                player.skeleton.setToSetupPose();
252
              } catch (e) {
253
                console.warn("Error positioning skeleton:", e);
254
              }
255
            }
256
          }, 500);
257

258
          // 设置交互功能
259
          if (spineModelConfig.interactive.enabled) {
260
            const canvas = document.querySelector(
261
              "#spine-player-container canvas"
262
            );
263
            if (canvas) {
264
              canvas.addEventListener("click", () => {
265
                // 防抖处理：防止重复点击
266
                const currentTime = Date.now();
267
                if (isClickProcessing || currentTime - lastClickTime < 500) {
268
                  return; // 500ms 内重复点击忽略
269
                }
270

271
                isClickProcessing = true;
272
                lastClickTime = currentTime;
273

274
                // 随机播放点击动画
275
                const clickAnims =
276
                  spineModelConfig.interactive.clickAnimations ||
277
                  (spineModelConfig.interactive.clickAnimation
278
                    ? [spineModelConfig.interactive.clickAnimation]
279
                    : []);
280

281
                if (clickAnims.length > 0) {
282
                  try {
283
                    const randomClickAnim =
284
                      clickAnims[Math.floor(Math.random() * clickAnims.length)];
285
                    player.setAnimation(randomClickAnim, false);
286

287
                    // 动画播放完成后回到待机状态
288
                    setTimeout(() => {
289
                      const idleAnims =
290
                        spineModelConfig.interactive.idleAnimations;
291
                      const randomIdle =
292
                        idleAnims[Math.floor(Math.random() * idleAnims.length)];
293
                      player.setAnimation(randomIdle, true);
294
                    }, 2000);
295
                  } catch (e) {
296
                    console.warn("Failed to play click animation:", e);
297
                  }
298
                }
299

300
                // 显示随机消息
301
                const messages = spineModelConfig.interactive.clickMessages;
302
                if (messages && messages.length > 0) {
303
                  const randomMessage =
304
                    messages[Math.floor(Math.random() * messages.length)];
305
                  showMessage(randomMessage);
306
                }
307

308
                // 500ms 后重置防抖标志
309
                setTimeout(() => {
310
                  isClickProcessing = false;
311
                }, 500);
312
              });
313

314
              // 设置待机动画循环
315
              if (spineModelConfig.interactive.idleAnimations.length > 1) {
316
                setInterval(() => {
317
                  try {
318
                    const idleAnims =
319
                      spineModelConfig.interactive.idleAnimations;
320
                    const randomIdle =
321
                      idleAnims[Math.floor(Math.random() * idleAnims.length)];
322
                    player.setAnimation(randomIdle, true);
323
                  } catch (e) {
324
                    console.warn("Failed to play idle animation:", e);
325
                  }
326
                }, spineModelConfig.interactive.idleInterval);
327
              }
328
            }
329
          }
330

331
          // 添加拖拽功能
332
          const container = document.getElementById("spine-model-container");
333
          if (container) {
334
            let isDragging = false;
335
            let dragStart = { x: 0, y: 0 };
336
            let containerStart = { x: 0, y: 0 };
337

338
            // 鼠标事件
339
            container.addEventListener("mousedown", (e) => {
340
              if (e.button !== 0) return; // 只响应左键
341
              isDragging = true;
342
              dragStart = { x: e.clientX, y: e.clientY };
343

344
              const rect = container.getBoundingClientRect();
345
              containerStart = { x: rect.left, y: rect.top };
346

347
              container.style.cursor = "grabbing";
348
              e.preventDefault();
349
            });
350

351
            document.addEventListener("mousemove", (e) => {
352
              if (!isDragging) return;
353

354
              const deltaX = e.clientX - dragStart.x;
355
              const deltaY = e.clientY - dragStart.y;
356

357
              const newX = containerStart.x + deltaX;
358
              const newY = containerStart.y + deltaY;
359

360
              // 边界检查
361
              const maxX = window.innerWidth - container.offsetWidth;
362
              const maxY = window.innerHeight - container.offsetHeight;
363

364
              const clampedX = Math.max(0, Math.min(newX, maxX));
365
              const clampedY = Math.max(0, Math.min(newY, maxY));
366

367
              container.style.left = clampedX + "px";
368
              container.style.right = "auto";
369
              container.style.top = clampedY + "px";
370
              container.style.bottom = "auto";
371
            });
372

373
            document.addEventListener("mouseup", () => {
374
              if (isDragging) {
375
                isDragging = false;
376
                container.style.cursor = "grab";
377
              }
378
            });
379

380
            // 触摸事件（移动端支持）
381
            container.addEventListener("touchstart", (e) => {
382
              if (e.touches.length !== 1) return;
383
              isDragging = true;
384
              const touch = e.touches[0];
385
              dragStart = { x: touch.clientX, y: touch.clientY };
386

387
              const rect = container.getBoundingClientRect();
388
              containerStart = { x: rect.left, y: rect.top };
389

390
              e.preventDefault();
391
            });
392

393
            document.addEventListener("touchmove", (e) => {
394
              if (!isDragging || e.touches.length !== 1) return;
395

396
              const touch = e.touches[0];
397
              const deltaX = touch.clientX - dragStart.x;
398
              const deltaY = touch.clientY - dragStart.y;
399

400
              const newX = containerStart.x + deltaX;
401
              const newY = containerStart.y + deltaY;
402

403
              // 边界检查
404
              const maxX = window.innerWidth - container.offsetWidth;
405
              const maxY = window.innerHeight - container.offsetHeight;
406

407
              const clampedX = Math.max(0, Math.min(newX, maxX));
408
              const clampedY = Math.max(0, Math.min(newY, maxY));
409

410
              container.style.left = clampedX + "px";
411
              container.style.right = "auto";
412
              container.style.top = clampedY + "px";
413
              container.style.bottom = "auto";
414

415
              e.preventDefault();
416
            });
417

418
            document.addEventListener("touchend", () => {
419
              isDragging = false;
420
            });
421

422
            // 设置初始光标样式
423
            container.style.cursor = "grab";
424

425
            // 窗口大小变化时重新检查边界
426
            window.addEventListener("resize", () => {
427
              const rect = container.getBoundingClientRect();
428
              const maxX = window.innerWidth - container.offsetWidth;
429
              const maxY = window.innerHeight - container.offsetHeight;
430

431
              if (rect.left > maxX) {
432
                container.style.left = maxX + "px";
433
                container.style.right = "auto";
434
              }
435
              if (rect.top > maxY) {
436
                container.style.top = maxY + "px";
437
                container.style.bottom = "auto";
438
              }
439
            });
440
          }
441

442
          console.log("✅ Spine model setup complete!");
443
        },
444
        error: (player, reason) => {
445
          console.error("❌ Spine model loading error:", reason);
446

447
          const errorDiv = document.getElementById("spine-error");
448
          if (errorDiv) {
449
            errorDiv.style.display = "block";
450
            errorDiv.innerHTML = `
451
              <div style="color: #ff4444; padding: 20px; text-align: center; font-size: 14px;">
452
                <div>⚠️ Spine 模型加载失败</div>
453
                <div style="font-size: 12px; margin-top: 8px; color: #888;">${reason}</div>
454
              </div>
455
            `;
456
          }
457

458
          const canvas = document.getElementById("spine-canvas");
459
          if (canvas) canvas.style.display = "none";
460
        },
461
      });
462
    } catch (error) {
463
      console.error("Spine model initialization error:", error);
464

465
      // 重置初始化标志，允许重试
466
      window.spineModelInitialized = false;
467

468
      const errorDiv = document.getElementById("spine-error");
469
      if (errorDiv) {
470
        errorDiv.style.display = "block";
471
        errorDiv.innerHTML = `
472
          <div style="color: #ff4444; padding: 20px; text-align: center; font-size: 14px;">
473
            <div>⚠️ Spine 运行时加载失败</div>
474
            <div style="font-size: 12px; margin-top: 8px; color: #888;">${error instanceof Error ? error.message : "未知错误"}</div>
475
          </div>
476
        `;
477
      }
478
    }
479
  }
480

481
  // 监听页面卸载事件，清理资源
482
  window.addEventListener("beforeunload", cleanupSpineModel);
483

484
  // 监听 Swup 页面切换事件（如果使用了 Swup）
485
  if (typeof window.swup !== "undefined" && window.swup.hooks) {
486
    window.swup.hooks.on("content:replace", () => {
487
      // 只更新响应式显示，不重新创建模型
488
      setTimeout(() => {
489
        updateResponsiveDisplay();
490
      }, 100);
491
    });
492
  }
493

494
  // 监听 popstate 事件（浏览器前进后退）
495
  window.addEventListener("popstate", () => {
496
    setTimeout(() => {
497
      updateResponsiveDisplay();
498
    }, 100);
499
  });
500

501
  // 监听窗口大小变化
502
  window.addEventListener("resize", updateResponsiveDisplay);
503

504
  // 页面加载完成后初始化（只初始化一次）
505
  if (document.readyState === "loading") {
506
    document.addEventListener("DOMContentLoaded", initSpineModel);
507
  } else {
508
    initSpineModel();
509
  }
510
</script>

修改src\layouts\MainGridLayout.astro#

1
---
2
 // 。。。。省略
3
import SpineModel from "@components/widget/SpineModel.astro";
4
import Live2DWidget from "@components/widget/Live2DWidget.astro";
5
import TOC from "../components/widget/TOC.astro";
6
import { siteConfig,live2dModelConfig } from "../config";
7
import {
8
  BANNER_HEIGHT,
9
  BANNER_HEIGHT_EXTEND,
10
  MAIN_PANEL_OVERLAPS_BANNER_HEIGHT,
11
} from "../constants/constants";
12
import Layout from "./Layout.astro";
13

14
---
15

16
<Layout title={title} banner={banner} description={description} lang={lang} setOGTypeArticle={setOGTypeArticle}>
17

18
// 。。。。省略
19

20
<!-- Main content -->
21
<div class="absolute w-full z-30 pointer-events-none" style={`top: ${mainPanelTop}`}>
22
            <div class="footer col-span-2 onload-animation block lg:hidden">
23
                <Footer></Footer>
24
            </div>
25
        </div>
26
    <!-- 直接搜 BackToTop -->
27
        <BackToTop></BackToTop>
28

29
        <SpineModel></SpineModel>
30
        {live2dModelConfig.enable && <Live2DWidget config={live2dModelConfig} />}
31
    </div>
32
</div>
33
        <!-- #toc needs to exist for Swup to work normally -->
34
        {!siteConfig.toc.enable && <div id="toc"></div>}
35
    </div>
36
</div>
37
</Layout>

性能优化建议#

1. 模型选择#

1
// 选择轻量级模型
2
model: {
3
  path: "/pio/models/spine/simple-model.json", // 简单模型
4
  scale: 0.8,  // 适当缩小
5
}

2. 动画控制#

1
interactive: {
2
  idleInterval: 10000,  // 增加待机动画间隔
3
  clickAnimations: ["simple_click"], // 减少点击动画数量
4
}

3. 响应式设置#

1
responsive: {
2
  hideOnMobile: true,        // 移动端隐藏
3
  mobileBreakpoint: 1024,    // 提高断点
4
}

常见问题#

Q: 看板娘不显示怎么办？#

A: 检查以下项目：

enable 是否设置为 true
模型文件路径是否正确
模型文件是否完整
浏览器控制台是否有错误

Q: 如何更换看板娘模型？#

A: 修改 model.path 路径：

1
model: {
2
  path: "/pio/models/spine/new-model/model.json",
3
}

Q: 如何调整看板娘大小？#

A: 修改 size 配置：

1
size: {
2
  width: 200,   // 调整宽度
3
  height: 250,  // 调整高度
4
}

Q: 如何添加更多点击消息？#

A: 在 clickMessages 数组中添加：

1
clickMessages: [
2
  "原有消息1",
3
  "原有消息2",
4
  "新消息1",  // 添加新消息
5
  "新消息2",  // 添加新消息
6
]

注意事项#

性能考虑：看板娘会增加页面加载时间，建议在移动端隐藏
文件大小：模型文件较大，建议压缩纹理图片
浏览器兼容：某些旧浏览器可能不支持WebGL
版权问题：使用模型时注意版权许可
用户体验：避免过于频繁的动画影响阅读体验

高级配置#

自定义动画序列#

1
interactive: {
2
  clickAnimations: [
3
    "wave",      // 挥手动画
4
    "jump",      // 跳跃动画
5
    "dance",     // 舞蹈动画
6
    "sleep"      // 睡觉动画
7
  ],
8
  idleAnimations: [
9
    "idle",      // 基础待机
10
    "blink",     // 眨眼
11
    "look_around" // 四处张望
12
  ],
13
}

动态消息系统#

1
clickMessages: [
2
  "现在是${new Date().getHours()}点哦~",
3
  "今天天气${weather}呢！",
4
  "欢迎第${visitCount}次访问！"
5
]

条件显示#

1
// 根据时间显示不同消息
2
const getTimeMessage = () => {
3
  const hour = new Date().getHours();
4
  if (hour < 12) return "早上好！";
5
  if (hour < 18) return "下午好！";
6
  return "晚上好！";
7
};

公告

概述#

配置类型#

1. Spine 看板娘配置#

基本配置结构#

配置示例#

2. Live2D 看板娘配置#

基本配置结构#

配置示例#

配置选项详解#

位置配置 (position)#

显示位置 (corner)#

偏移设置#

尺寸配置 (size)#

交互配置 (interactive)#

点击动画 (clickAnimations)#

点击消息 (clickMessages)#

待机动画 (idleAnimations)#

响应式配置 (responsive)#

模型文件管理#

文件结构#

模型文件获取#

Spine 模型#

Live2D 模型#

实现代码#

复制看板娘文件#

新建 pioConfig.ts 文件#

新增src\types\config.ts看板娘类别#

新建src\components\widget\PioMessageBox.astro#

新建src\components\widget\Live2DWidget.astro#

新建src\components\widget\SpineModel.astro#

修改src\layouts\MainGridLayout.astro#

性能优化建议#

1. 模型选择#

2. 动画控制#

3. 响应式设置#

常见问题#

Q: 看板娘不显示怎么办？#

Q: 如何更换看板娘模型？#

Q: 如何调整看板娘大小？#

Q: 如何添加更多点击消息？#

注意事项#

高级配置#

自定义动画序列#

动态消息系统#

条件显示#