Live2D Widget 本地离线API配置与换装功能实现

项目背景

Live2D Widget 是一个基于 Web 的 Live2D 看板娘组件，能够为网站添加动态的 Live2D 角色。该项目支持通过 CDN 或本地 API 方式加载模型资源，并提供了丰富的交互功能。

本地离线API配置

在最新版本的 Live2D Widget 中，开发者可以通过两种方式配置模型资源：

1. cdnPath：直接指定模型资源的本地路径
2. apiPath：通过后端API动态获取模型信息

对于需要在本地离线环境中使用的场景，cdnPath 是更简单的选择。用户只需将模型文件放置在本地服务器指定目录，然后在配置中设置正确的路径即可。

换装功能实现

Live2D 模型通常支持换装(texture switching)功能，允许角色在不同纹理之间切换。在 Live2D Widget 中，这一功能最初仅支持通过 apiPath 方式实现，但在最新更新中已扩展支持 cdnPath 方式。

技术实现细节

项目通过以下关键代码实现换装功能：

1. 模型加载时检查可用纹理：

const textures = await (apiMode 
    ? this.loadTexturesFromAPI(modelName, modelId) 
    : this.loadTexturesFromCDN(modelName));

2. 从CDN加载纹理的实现：

async loadTexturesFromCDN(modelName) {
    // 构造纹理路径并检查可用性
    const texturePaths = [
        `textures/texture_00.png`,
        `textures/texture_01.png`,
        // 更多纹理路径...
    ];
    
    const availableTextures = [];
    for (const path of texturePaths) {
        if (await this.checkTextureExists(path)) {
            availableTextures.push(path);
        }
    }
    return availableTextures;
}

最佳实践建议

1. 目录结构：建议将模型文件和纹理文件组织在统一目录下，例如：

   /live2d_models/
       /my_model/
           model.json
           /textures/
               texture_00.png
               texture_01.png
   

2. 配置示例：

new Live2DWidget({
    cdnPath: "/live2d_models/my_model/",
    // 其他配置...
});

3. 纹理命名规范：建议采用一致的命名规则(如texture_00.png, texture_01.png)以便自动检测。

注意事项

1. 虽然 cdnPath 方式现在支持换装功能，但 apiPath 方式仍然提供更多高级功能。

2. 本地使用时需要确保服务器正确配置了MIME类型，特别是对于.json和.png文件。

3. 纹理切换功能依赖于模型本身的支持，并非所有Live2D模型都实现了多纹理功能。

通过以上配置，开发者可以轻松地在本地离线环境中使用Live2D Widget，并享受完整的换装功能体验。