midival/core 项目版本迁移指南：从0.0.15到0.1.0的重大变更解析

前言

在软件开发过程中，随着功能的迭代和优化，API的变更在所难免。本文针对midival/core项目从0.0.15到0.1.0版本的重要变更进行详细解析，帮助开发者顺利完成版本迁移工作。我们将深入分析每个变更的技术细节及其影响范围。

版本0.1.0的重大变更

弯音轮(PitchBend)事件回调接口重构

变更内容： 在0.1.0版本中，MIDIValInput.onPitchBend方法的回调函数签名发生了重大变化。

旧版本(0.0.15及之前)： 回调函数接收一个简单的数值数组作为参数：

Callback<[number]>

新版本(0.1.0)： 回调函数现在接收一个结构化的PitchBend接口对象：

Callback<[PitchBend]>

其中PitchBend接口定义如下：

interface PitchBend {
    channel: number;  // MIDI通道信息
    value: number;    // 弯音轮数值
}

迁移建议：

1. 检查所有使用onPitchBend的地方
2. 将原来的数值访问方式改为访问对象属性
3. 如果需要通道信息，现在可以直接从参数中获取

示例修改：

// 旧版本
input.onPitchBend(([value]) => {
    console.log(`Pitch bend value: ${value}`);
});

// 新版本
input.onPitchBend(([{ channel, value }]) => {
    console.log(`Channel ${channel} pitch bend value: ${value}`);
});

版本0.0.15的重要改进

事件回调接口标准化

变更背景： 在0.0.15版本中，项目对各类MIDI事件回调接口进行了统一化处理，使API更加一致和易用。

1. onAll*方法参数标准化

变更内容： 所有onAll*方法(如onAllNoteOn, onAllControlChange等)不再将键值作为单独的第一个参数，而是与其他回调保持一致，第一个参数始终是MidiMessage或其派生接口。

影响范围：

• onAllNoteOn
• onAllNoteOff
• onAllControlChange
• onAllProgramChange

迁移建议： 检查所有使用这些方法的地方，移除对第一个单独参数的依赖，改为从消息对象中获取所需信息。

2. 控制变更(Control Change)事件增强

变更内容： onAllControlChange和onControlChange回调现在提供更结构化的参数，除了基本的MidiMessage接口外，还包含：

• control: 控制器编号
• value: 控制器值

优势： 开发者不再需要手动解析原始MIDI消息，可以直接访问这些常用属性。

3. 程序变更(Program Change)事件增强

变更内容： 类似地，onAllProgramChange和onProgramChange回调现在提供：

• program: 程序编号
• value: 程序值

4. 音符开/关(Note On/Off)事件增强

变更内容： 以下音符相关回调也进行了结构化改进：

• onAllNoteOn
• onAllNoteOff
• onNoteOn
• onNoteOff

现在这些回调提供：

• note: 音符编号
• velocity: 力度值

迁移策略建议

1. 逐步迁移：建议先升级到0.0.15版本，处理完API标准化变更后，再升级到0.1.0版本。

2. 全面测试：由于这些变更涉及核心事件处理逻辑，建议进行全面测试，特别是：

   • 所有MIDI事件处理回调
   • 依赖通道信息的逻辑
   • 参数解析相关代码

3. 利用TypeScript类型检查：新版本提供了更完善的类型定义，可以利用TypeScript编译器帮助发现需要修改的地方。

总结

midival/core项目在0.0.15和0.1.0版本中对事件回调系统进行了重要改进，主要变化包括：

1. 统一了回调参数结构，使API更加一致
2. 提供了更丰富的结构化事件数据
3. 增加了通道信息等有用字段
4. 改善了类型定义和开发体验

这些变更虽然需要一定的迁移工作，但将显著提高代码的可读性和可维护性。建议开发者根据本文指南逐步完成迁移，以充分利用新版本提供的改进功能。