MuseScore 宏扩展Macros开发指南用纯脚本自动化制谱操作【免费下载链接】MuseScoreMuseScore is an open source and free music notation software. For support, contribution, bug reports, visit MuseScore.org. Fork and make pull requests!项目地址: https://gitcode.com/gh_mirrors/mu/MuseScore宏扩展Macros是 MuseScore 4 扩展体系中一种没有用户界面、只有脚本的扩展类型适合把重复性制谱操作封装成一条命令一键执行。本文以仓库 docs/apidocs_static/tutorials/4_macros.md 为核心骨架结合share/extensions/目录下官方自带的多个宏扩展示例完整讲解清单文件manifest.json的编写、默认入口函数机制、MuseApi 服务调用方式以及如何通过 Engraving API 读写乐谱数据帮助你在不改动源代码的前提下快速上手宏开发。什么是宏扩展Macros在 MuseScore 的扩展模型中扩展被分为多种类型其中宏扩展macros与其他类型的关键区别在于没有 UI宏扩展不提供任何面板、对话框或工具栏窗口只有一个脚本文件在后台执行用于自动化宏的典型用途是把一组反复操作例如批量设置音符颜色、遍历小节并修改属性、导出统计信息打包成一个动作通过工具栏按钮或应用菜单触发以.js为脚本载体宏扩展的脚本文件是 JavaScript.js在 manifest 中通过type: macros显式声明。与之相对仓库 share/extensions/example1/manifest.json 中展示的type: form扩展则使用Main.qml提供完整界面而 share/extensions/apitests/manifest.json 还展示了type: composite复合扩展——同一个扩展包里可以同时挂载 form 类型动作和 macros 类型动作。宏扩展是其中最轻量、最贴近脚本即功能理念的一种形态。第一步编写清单文件 manifest.json宏扩展的清单文件需要声明扩展的uri、type以及actions数组。文档给出的最小示例结构如下{ uri: musescore://extensions/example1, type: macros, actions: [ { path: main.js } ] }对照仓库中真实的宏扩展 share/extensions/quickstart/manifest.json可以看到同样的最小结构{ uri: musescore://extensions/dev/quickstart, type: macros, title: Quick start, description: This is a development extension for API research., actions: [ { path: main.js } ] }当actions中的动作只有path而没有func时脚本加载后默认调用名为main的函数详见下一节。如果希望一个扩展暴露多个可独立触发的宏动作就需要在actions数组中为每个动作补充完整的元信息。仓库 share/extensions/example2/manifest.json 是官方提供的最完整范例{ uri: musescore://extensions/dev/example_2, type: macros, title: Example 2 (default), actions: [ { code: save, title: Save, icon: SAVE, show_on_toolbar: true, show_on_appmenu: false, path: main.js, func: save }, { code: open, title: Open, icon: OPEN_FILE, show_on_toolbar: true, show_on_appmenu: false, path: main.js, func: open } ] }该示例各字段的用途可以总结如下字段说明示例值uri扩展的唯一标识全局不可重复通常使用musescore://extensions/...命名空间musescore://extensions/dev/example_2type扩展类型宏扩展固定为macrosmacrostitle扩展标题会显示在扩展管理界面Example 2 (default)description扩展描述可选This is a development extension for API research.actions动作数组宏扩展的每个动作对应脚本中的一个函数见下方说明actions[].code动作的内部标识码用于命令路由save/openactions[].title动作对外显示的名称Save/Openactions[].icon图标名称取值来自 MuseScore 内置图标集SAVE/OPEN_FILE/PLUS/MINUSactions[].show_on_toolbar是否显示在工具栏true/falseactions[].show_on_appmenu是否显示在应用菜单true/falseactions[].path脚本文件路径相对于扩展目录main.jsactions[].func要调用的脚本内函数名不指定则默认调用mainsave/open需要特别注意的是func与path是解耦的。同一个main.js里可以定义多个函数每个 action 通过path指定脚本、通过func指定要执行的函数。例如上面的 manifest 中两个 action 都指向main.js但分别执行save和open两个不同的函数。第二步编写宏脚本 main.js脚本文件使用 CommonJS 风格加载 MuseScore 提供的服务模块文档给出的示例脚本如下const Log require(MuseApi.Log); const Interactive require(MuseApi.Interactive); function main() { Log.info(called main from example 2) Interactive.info(Quick start, called main from example 2) }这段脚本对应两个核心知识点入口函数约定只要 manifest 的 action 中没有指定funcMuseScore 就会默认调用脚本中的main函数。仓库 share/extensions/quickstart/main.js 与文档示例完全一致再次印证了这一约定。MuseApi 服务注入通过require(MuseApi.Log)引入日志服务、require(MuseApi.Interactive)引入交互服务。Log.info()把信息写入日志Interactive.info(title, message)则会弹出一个信息对话框。关于两种 API 访问风格观察仓库中不同示例可以发现宏脚本存在两种等效的 API 访问方式模块导入式文档与 quickstart 采用const Log require(MuseApi.Log);后调用Log.info(...)全局对象式share/extensions/example2/main.js 采用api.log.info(...)、api.interactive.info(...)的形式直接调用。share/extensions/apitests/macros.js 则同时混合了两种风格并用一行console.log对比验证了两者的等价性const Log require(MuseApi.Log); const Interactive require(MuseApi.Interactive); const Engraving require(MuseApi.Engraving); const Element Engraving.Element; function main() { Log.info(macros.js) const score api.engraving.curScore; const measure score.firstMeasure; console.log(measure.type:, measure.type , Element.Measure:, Element.MEASURE , api.engraving.Element.MEASURE:, api.engraving.Element.MEASURE , Engraving.Element.MEASURE:, Engraving.Element.MEASURE ) ... }无论采用哪种写法返回的都是同一套服务对象你可以按团队编码习惯任选其一但建议在同一个扩展内保持一致。多动作宏的完整示例结合 share/extensions/example2/main.js一个包含默认入口和多个可绑定动作的完整宏脚本是这样的function main() { api.log.info(called main from example 2) api.interactive.info(Example 2, called MAIN from example 2) } function save() { api.log.info(called save from example 2) api.interactive.info(Example 2, called SAVE from example 2) } function open() { api.log.info(called open from example 2) api.interactive.info(Example 2, called OPEN from example 2) }其中main对应不指定func的动作或直接运行扩展时的默认行为save、open则分别对应 manifest 中func: save、func: open的两个动作。第三步在宏中操作乐谱数据Engraving API宏的价值不只在于弹提示框。通过MuseApi.Engraving模块宏可以读取并操作当前乐谱。以 share/extensions/apitests/macros.js 为例它展示了如何拿到当前乐谱并访问第一个小节const score api.engraving.curScore; // 当前活动的乐谱对象 const measure score.firstMeasure; // 乐谱的第一个小节 console.log(measure.hideWhenEmpty:, measure.hideWhenEmpty); if (measure.type Element.MEASURE) { console.log(this is measure) Interactive.info(Macros, This is a measure.) }这段代码背后蕴含的调用链是api.engraving.curScore返回当前文档窗口中的乐谱Score对象其能力对应源码模块src/engraving/api/下对记谱模型engraving DOM的封装score.firstMeasure返回第一个小节对象measure.type用于判断元素类型并与Element.MEASURE常量做比较宏脚本据此可以实现遍历所有小节 → 按类型判断 → 修改属性这类典型的批量自动化逻辑。仓库 share/extensions/colornotes/main.js 正是把这种能力用于实际场景的代表通过宏脚本批量给选中音符着色是官方自带宏中少见的改变乐谱内容的实用示例。官方 apitests 扩展share/extensions/apitests/manifest.json则把form与macros两种动作放在同一个复合扩展中方便你对照学习。安装与运行宏扩展在开发或使用宏扩展时请遵循以下流程仓库是只读的以下均为查看与运行层面的操作放置扩展将包含manifest.json与脚本文件的整个目录放入 MuseScore 的扩展目录Extensions 目录例如仓库中官方示例所在的share/extensions/布局启用扩展在 MuseScore 的扩展Extensions管理界面中启用对应扩展启用的前提是 manifest 中type: macros与uri已正确声明触发动作根据 manifest 中的show_on_toolbar/show_on_appmenu配置宏动作会出现在工具栏或应用菜单中点击即可执行pathfunc指定的脚本函数观察输出Log.info/console.log的输出进入日志系统Interactive.info弹出对话框调试时可利用这两种手段确认脚本执行路径。编写宏扩展的实用建议结合文档约定与仓库中的官方示例总结几条实战建议默认入口要兜底即使所有 action 都显式指定了func也建议保留一个main函数作为默认入口如 share/extensions/example2/main.js便于快速验证扩展是否正常加载动作粒度要小一个宏动作只做一件事多个独立任务拆成多个 action各自指定code、title、icon与func让用户能在工具栏上按需触发善用ui_contextcomposite类型扩展如 apitests可混合 form 与 macros 动作需要弹窗配置时用 form 动作需要后台执行时用 macros 动作各取所长谨慎修改乐谱宏脚本直接操作当前乐谱curScore时修改是不可预览的涉及批量改动前先在小样张上验证逻辑保持单一文件依赖path是相对扩展目录的路径尽量把所有函数放在同一个.js文件中减少清单与脚本之间的路径映射出错概率。小结宏扩展是 MuseScore 4 中以脚本自动化制谱的官方通道在 manifest 中声明type: macros与actionspath 可选func在.js脚本中通过MuseApi服务Log、Interactive、Engraving等执行逻辑即可实现无界面、可反复触发的自动化操作。从 share/extensions/quickstart 的最小示例起步参考 share/extensions/example2 的多动作写法再到 share/extensions/apitests/macros.js 的乐谱数据访问你可以在不改动 MuseScore 源码的前提下把重复性工作逐步沉淀为属于自己的宏工具箱。【免费下载链接】MuseScoreMuseScore is an open source and free music notation software. For support, contribution, bug reports, visit MuseScore.org. Fork and make pull requests!项目地址: https://gitcode.com/gh_mirrors/mu/MuseScore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考