1. 项目概述为什么我们需要一个可视化设置面板做Cocos Creator插件开发的朋友估计都经历过这个阶段辛辛苦苦写好了核心功能结果在配置环节卡住了。要么是让用户在package.json里手动编辑一堆晦涩的JSON字段要么就是写一个简陋的输入框用户填错了还得自己去翻控制台日志。这种体验别说用户了自己调试起来都头疼。尤其是当插件功能稍微复杂一点需要配置的项超过三个时这种“黑盒”式的配置方式就成了用户体验的“拦路虎”。我最近在重构一个老插件时就深刻体会到了这一点。插件有十几个可调参数之前全堆在一个JSON文件里每次测试新功能都得反复开关编辑器、修改配置、重启插件效率极低。更糟糕的是团队里其他美术和策划同事根本不敢碰这个插件因为“不知道这些数字改了会出什么效果怕弄坏项目”。这让我意识到一个插件的易用性很大程度上就体现在它的配置界面上。于是我花了些时间研究并实践了一套为Cocos Creator插件快速构建可视化设置面板的方案。核心目标就一个让配置过程变得所见即所得直观且无脑。最终我把它提炼成了一个可以“三步走”的标准化流程。无论你是插件开发新手还是想优化现有插件的老手这套方法都能让你在半小时内将一个零散的配置对象变成一个漂亮、易用、功能完整的可视化面板。这不仅仅是“美化界面”更是提升插件专业性、降低用户使用门槛、减少后期维护成本的关键一步。2. 核心思路与方案选型从JSON到UI的桥梁在动手之前我们先要搞清楚一个核心问题可视化设置面板的本质是什么我的理解是它是一个将插件的配置数据通常是JavaScript对象或JSON与Cocos Creator编辑器内置的UI控件进行双向绑定的系统。用户通过UI控件输入框、下拉菜单、滑块等修改数值这个修改能实时、准确地同步到底层的配置数据中反之当配置数据被加载或从外部修改时UI界面也要能立刻反映出最新的状态。基于这个理解我评估了Cocos Creator插件开发中几种常见的UI方案纯HTML/CSS/JS网页在插件面板中嵌入一个webview完全自主绘制UI。优点是自由度极高可以做出非常炫酷的界面。但缺点更明显开发成本高需要处理与编辑器主进程的通信IPC样式和交互与Cocos Creator编辑器本身格格不入体验割裂。ImGui等原生图形库性能好但需要编译原生模块跨平台部署复杂且与Cocos Creator的TypeScript/JavaScript生态结合不够顺畅。Cocos Creator编辑器扩展API这是官方提供的方案也是我最终选择的方案。它提供了一套基于UI模块的声明式UI构建方式其控件风格、布局逻辑与Cocos Creator编辑器本身完全一致。这意味着你的插件面板看起来、用起来都像是编辑器原生的一部分用户体验无缝衔接。更重要的是它天然运行在编辑器的渲染进程中可以直接访问和操作插件定义的数据和函数无需复杂的跨进程通信。所以我的方案核心就是深度利用Cocos Creator编辑器扩展API中的UI模块。这个模块提供了prop属性定义和asset资源定义的能力我们可以通过它用类似定义组件属性的方式来声明我们的配置项应该如何被渲染和编辑。注意这里说的UI模块不是游戏运行时用的cc.ui而是插件开发中Editor.UI或Editor.Panel相关的API。在Cocos Creator 2.x和3.x中具体的API名称和用法有细微差别但核心思想一致。本文的示例将以更通用的思路和Cocos Creator 3.x的API风格为主进行讲解并指出2.x中的关键差异点。3. 三步打造可视化面板从零到一的完整实操接下来就是最核心的“三步走”实操环节。我会以一个具体的插件需求为例假设我们要开发一个“场景自动备份”插件它需要配置三个参数备份间隔分钟一个整数。最大备份数量一个整数。启用自动备份一个布尔值。我们的目标是为这三个配置项生成一个可视化面板。3.1 第一步定义配置的数据结构Schema这是最重要的一步它决定了你的面板“长什么样”以及“如何工作”。我们需要在插件的package.json文件中或者在一个单独的脚本里定义配置的“模式”Schema。在Cocos Creator 3.x中我们通常在插件的入口脚本例如src/main.ts中通过Editor.Panel.extend或Editor.Profile等API来定义。但更清晰的做法是我们定义一个纯粹的配置对象和它的模式描述。首先在插件项目中创建一个配置文件比如src/config.ts// src/config.ts // 1. 定义配置数据的默认值也是一个完整的配置对象示例 export const defaultConfig { backupInterval: 10, // 备份间隔单位分钟 maxBackupCount: 30, // 最大备份文件数 enableAutoBackup: true, // 是否启用 }; // 2. 定义配置数据的类型接口用于TypeScript类型检查 export interface IBackupPluginConfig { backupInterval: number; maxBackupCount: number; enableAutoBackup: boolean; } // 3. 定义UI渲染的模式Schema // 这是连接数据和UI的关键 export const configSchema { backupInterval: { label: 备份间隔分钟, description: 每隔多少分钟自动备份一次当前场景, type: number, default: defaultConfig.backupInterval, min: 1, // 最小值 max: 1440, // 最大值24小时 step: 1, // 步进值 // 在Cocos Creator的UI系统中number类型默认可能渲染为输入框 // 我们可以通过ui属性指定更具体的控件但基础类型通常够用 }, maxBackupCount: { label: 最大备份数量, description: 最多保留多少个历史备份文件超过将自动删除最旧的, type: number, default: defaultConfig.maxBackupCount, min: 1, max: 1000, }, enableAutoBackup: { label: 启用自动备份, description: 勾选后插件将开始按照间隔自动备份, type: boolean, default: defaultConfig.enableAutoBackup, }, };关键点解析label: 显示在UI上的标签文字。description: 鼠标悬停时的提示文本对于解释参数用途非常重要。type: 核心属性决定了使用哪种基础UI控件。常见的有number,string,boolean,object等。对于number类型可以附加min,max,step等属性来约束输入范围。default: 该配置项的默认值。ui: 高级用法如果基础type不能满足你的需求比如你想把一个数字渲染成滑块或者一个字符串渲染成下拉框你可以通过ui属性指定一个自定义的UI组件名。这需要你提前注册自定义UI组件对于入门来说我们先使用基础类型。这个schema对象就像一个“蓝图”告诉Cocos Creator编辑器“我有一个配置对象它有三个属性分别应该用什么标签、什么控件、什么默认值来展示和编辑”。3.2 第二步创建面板并绑定Schema有了数据蓝图接下来就要创建承载这个蓝图的“画布”——也就是插件面板本身。在插件主入口文件例如src/main.ts中我们注册这个面板// src/main.ts import * as cc from cc; import { configSchema, defaultConfig } from ./config; // 定义一个全局变量来存储当前配置实际项目中应从持久化存储如localStorage或文件中读取 let currentConfig { ...defaultConfig }; // 1. 定义面板类 export class BackupSettingPanel extends cc.Editor.PanelBase { // 模板方法返回面板的HTML模板字符串 // 注意在Cocos Creator 3.x中更推荐使用template属性和render函数 // 这里为了概念清晰先展示一种简化的结构 static template div classplugin-panel header场景自动备份设置/header div classcontent !-- UI控件将根据schema自动生成在这里 -- ui-prop idprop-container classprop-container/ui-prop /div footer ui-button classbtn-save保存/ui-button ui-button classbtn-reset重置/ui-button /footer /div ; // 2. 面板渲染后执行 async run() { // 等待DOM就绪 await super.run(); // 获取存储配置的DOM容器 const propContainer this.shadowRoot?.querySelector(#prop-container); if (!propContainer) return; // 3. 核心操作将schema渲染到UI容器中 // 这里利用了Editor.UI模块的能力具体API名可能随版本变化 // 假设有一个 renderProperties 方法 cc.Editor.UI.renderProperties(propContainer, configSchema, currentConfig, (path, value) { // 回调函数当UI中任何属性被修改时触发 console.log(配置项 ${path} 被修改为:, value); // 更新内存中的配置 // 这里需要根据path来更新currentConfig中对应的属性可以使用lodash的set方法 // _.set(currentConfig, path, value); // 为了简单演示我们假设path就是顶层的属性名 (currentConfig as any)[path] value; }); // 4. 绑定按钮事件 const saveBtn this.shadowRoot?.querySelector(.btn-save); const resetBtn this.shadowRoot?.querySelector(.btn-reset); saveBtn?.addEventListener(confirm, () this.saveConfig()); resetBtn?.addEventListener(confirm, () this.resetConfig()); } // 保存配置到持久化存储 saveConfig() { console.log(保存配置:, currentConfig); // 实际项目中这里应该调用Editor.Profile.setConfig或写入本地文件 // cc.Editor.Profile.setConfig(backup-plugin, currentConfig); cc.Editor.Ipc.sendToMain(backup-plugin:save-config, currentConfig); cc.Editor.Dialog.info(提示, 配置已保存); } // 重置配置为默认值 resetConfig() { currentConfig { ...defaultConfig }; // 重置后需要重新渲染UI以反映默认值 // 一种方法是重新调用run()中的渲染逻辑或者更优的是触发UI更新 console.log(重置配置为默认值); this.run(); // 简单粗暴的重置方式实际应有更优雅的更新机制 } } // 5. 注册面板到编辑器 // 在插件启动时执行 export function load() { // 注册一个消息用于打开面板 cc.Editor.Ipc.sendToMain(backup-plugin:open-settings); } export function unload() {}实操要点与避坑指南面板模板上面的template是一个极度简化的示例。在真实项目中Cocos Creator 3.x的插件面板开发更接近于现代前端你可能需要编写一个ui-panel组件并在package.json的panels字段中声明。但无论形式如何变化核心逻辑不变准备一个容器将schema和data喂给一个渲染函数并监听变化回调。数据流注意currentConfig这个变量。它是在内存中的配置副本。UI的修改通过回调函数实时更新它。点击“保存”按钮时才将这个内存中的数据写入持久化存储如Editor.Profile或项目设置文件。这种设计避免了频繁的IO操作。版本差异Cocos Creator 2.x 和 3.x 的插件系统有较大差异。2.x 更依赖于在package.json中定义panel和contributions面板UI多直接写在HTML文件中。而3.x 更模块化提倡使用TypeScript和声明式UI。你需要根据你使用的Cocos Creator版本查阅对应的 编辑器扩展官方文档 来调整具体API。ui-prop组件示例中使用的ui-prop是一个特殊的容器组件它是编辑器UI系统的一部分专门用于根据schema动态生成一组表单控件。你需要确保在模板中正确引入了编辑器的UI组件库。3.3 第三步关联插件逻辑与面板配置面板做好了配置也能保存了最后一步就是让插件的核心功能能读取到这些配置。我们修改插件的主要功能脚本例如src/backup-manager.ts让它从持久化存储中读取配置// src/backup-manager.ts import { IBackupPluginConfig } from ./config; export class BackupManager { private config: IBackupPluginConfig; private timerId: number | null null; // 初始化时加载配置 async init() { await this.loadConfig(); this.applyConfig(); } // 从持久化存储加载配置 private async loadConfig() { // 方法1使用Editor.Profile (适用于编辑器全局配置) // this.config await cc.Editor.Profile.getConfig(backup-plugin) as IBackupPluginConfig; // 方法2通过Ipc从主进程获取如果配置保存在项目.settings文件夹中 // 这里模拟一个Ipc调用 this.config await new Promise((resolve) { cc.Editor.Ipc.sendToMain(backup-plugin:get-config, (config: IBackupPluginConfig) { resolve(config); }); }); // 如果找不到配置则使用默认值 if (!this.config) { const { defaultConfig } await import(./config); this.config { ...defaultConfig }; } console.log(备份管理器加载配置:, this.config); } // 应用配置例如根据配置启动或停止定时器 private applyConfig() { // 清除现有定时器 if (this.timerId ! null) { clearInterval(this.timerId); this.timerId null; } // 如果启用自动备份则创建新的定时器 if (this.config.enableAutoBackup this.config.backupInterval 0) { const intervalMs this.config.backupInterval * 60 * 1000; // 转换为毫秒 this.timerId setInterval(() { this.performBackup(); }, intervalMs) as unknown as number; // Node.js与浏览器环境类型差异 console.log(自动备份已启动间隔 ${this.config.backupInterval} 分钟); } else { console.log(自动备份未启用或间隔无效); } } // 执行备份的具体逻辑 private performBackup() { console.log([${new Date().toLocaleTimeString()}] 执行场景备份...); // 这里实现实际的备份逻辑例如 // 1. 获取当前场景路径 // 2. 复制场景文件到备份目录并加上时间戳 // 3. 清理超过 maxBackupCount 的旧备份 // cc.Editor.Ipc.sendToMain(backup-plugin:do-backup); } // 提供一个公共方法用于在配置更改后更新管理器 public updateConfig(newConfig: IBackupPluginConfig) { this.config { ...newConfig }; this.applyConfig(); // 重新应用新配置 } }然后在面板的saveConfig方法中不仅要将配置存盘还要通知功能模块更新// 在 src/main.ts 的 saveConfig 方法中补充 async saveConfig() { console.log(保存配置:, currentConfig); // 保存到持久化存储 // await cc.Editor.Profile.setConfig(backup-plugin, currentConfig); cc.Editor.Ipc.sendToMain(backup-plugin:save-config, currentConfig); // 通知备份管理器更新配置 cc.Editor.Ipc.sendToMain(backup-plugin:update-config, currentConfig); cc.Editor.Dialog.info(提示, 配置已保存并生效); }至此一个完整的“配置数据Schema - 可视化编辑面板 - 插件功能读取”的闭环就建立了。用户在前端面板上的每一次调整最终都能实时或通过保存按钮反馈到插件后台的运行逻辑中。4. 进阶技巧与常见问题排查掌握了基础三步法你已经可以应对大多数简单插件的配置需求。但在实际开发中你可能会遇到更复杂的情况。下面分享一些进阶技巧和踩坑经验。4.1 处理复杂数据类型与自定义控件基础类型数字、字符串、布尔往往不够用。比如你想让用户选择一个项目中的特定文件夹路径或者从一个资源列表里拖拽一个Prefab进来。解决方案使用asset类型或自定义ui组件。asset类型用于选择项目中的资源如场景、预制体、图片、脚本等。export const advancedSchema { targetScene: { label: 目标场景, type: asset, default: null, // 可以指定资源类型过滤器 assetType: scene, // 只允许选择场景文件 }, logoTexture: { label: Logo图片, type: asset, assetType: texture, } };渲染时这会变成一个带有点击按钮的资源选择框用户体验与编辑器内置的资源选择器完全一致。自定义ui组件当内置类型都无法满足时你可以注册自己的UI组件。首先定义一个自定义组件例如一个颜色选择器// 定义一个简单的颜色选择器组件概念示例 cc.Editor.UI.registerComponent(my-color-picker, { template: input typecolor :valuevalue inputonInput, props: [value], methods: { onInput(event) { this.$emit(change, event.target.value); } } });然后在schema中指定使用它export const advancedSchema { themeColor: { label: 主题颜色, type: string, // 底层数据类型还是字符串 default: #3498db, ui: { // 指定使用自定义组件来渲染 component: my-color-picker, } } };这种方式提供了极大的灵活性但复杂度也更高需要你熟悉编辑器扩展的UI组件开发规范。4.2 配置的分组与布局优化当配置项很多时全部平铺开来会非常混乱。我们可以对配置进行分组。在schema中我们可以通过嵌套对象来实现分组export const groupedSchema { // 基础设置组 basicSettings: { label: 基础设置, type: section, // 或者使用 group 等类型具体看编辑器UI支持 children: { enableAutoBackup: { label: 启用, type: boolean, default: true }, backupInterval: { label: 间隔(分钟), type: number, default: 10, min: 1 }, } }, // 高级设置组 advancedSettings: { label: 高级设置, type: section, children: { maxBackupCount: { label: 最大数量, type: number, default: 30, min: 1 }, backupPath: { label: 自定义路径, type: string, default: }, compressBackup: { label: 压缩备份, type: boolean, default: false }, } } };渲染时type: section或类似的属性通常会生成一个可折叠的分组面板使界面更加清晰。4.3 配置的持久化与多项目管理一个插件可能被用于多个不同的Cocos Creator项目每个项目的理想配置可能不同。因此将配置保存在项目本地而非编辑器全局是更专业的做法。推荐做法将配置保存在项目设置中。Cocos Creator提供了ProjectSettings机制在3.x中通常通过cc.settings或特定Ipc通道访问。你可以将插件的配置以JSON形式保存在项目的settings文件夹下的某个文件中例如project-name/settings/my-plugin.json。// 保存到项目设置 async saveToProjectSettings(config) { // 通过Ipc发送给主进程由主进程写入项目settings文件 await cc.Editor.Ipc.sendToMain(my-plugin:save-project-settings, config); } // 从项目设置读取 async loadFromProjectSettings() { const config await cc.Editor.Ipc.sendToMain(my-plugin:load-project-settings); return config || defaultConfig; }这样当用户在不同项目间切换时插件会自动加载对应项目的配置体验非常好。4.4 常见问题与排查清单面板打开是空白的检查浏览器开发者工具F12的Console面板是否有JavaScript错误。插件面板本质上是一个Web页面。检查package.json中panels的template或src路径是否正确。检查面板主类是否被正确注册和导出。Schema定义好了但UI没渲染出来检查确保schema对象的格式正确特别是type字段是编辑器支持的内置类型。检查渲染schema的容器DOM元素是否存在且唯一querySelector找到了正确的元素。检查渲染函数的调用时机是否正确通常在面板的ready或run生命周期中。修改UI后配置值没更新检查是否正确监听了UI控件的变化事件。对于动态生成的ui-prop确保在渲染时传入了正确的change回调函数。检查回调函数中的path和value参数是否正确。对于嵌套属性path可能是字符串如advancedSettings.compressBackup你需要用相应的方法如lodash.set来更新深层对象。配置保存了但插件重启后恢复了默认值检查保存配置的代码是否真的写入了持久化存储如Editor.Profile.setConfig或项目设置文件。console.log打印确认。检查插件初始化时读取配置的代码路径是否正确是否成功读到了之前保存的值。在Cocos Creator 2.x中如何实现核心思路一致但API不同。2.x中通常在package.json的contributions里定义profile配置模式然后在面板的HTML/JS中通过Editor.profile相关的API来获取和渲染配置。具体请查阅Cocos Creator 2.x的编辑器扩展文档。我个人在多次插件开发中最大的体会是可视化配置面板的投入产出比极高。初期多花一两天时间搭建好这个框架后期在功能迭代、参数调整、团队协作上节省的时间远超投入。它让插件从“开发者自用工具”变成了“团队友好型产品”是提升插件质量和专业度的不二法门。
Cocos Creator插件开发：三步构建可视化设置面板，告别JSON配置
1. 项目概述为什么我们需要一个可视化设置面板做Cocos Creator插件开发的朋友估计都经历过这个阶段辛辛苦苦写好了核心功能结果在配置环节卡住了。要么是让用户在package.json里手动编辑一堆晦涩的JSON字段要么就是写一个简陋的输入框用户填错了还得自己去翻控制台日志。这种体验别说用户了自己调试起来都头疼。尤其是当插件功能稍微复杂一点需要配置的项超过三个时这种“黑盒”式的配置方式就成了用户体验的“拦路虎”。我最近在重构一个老插件时就深刻体会到了这一点。插件有十几个可调参数之前全堆在一个JSON文件里每次测试新功能都得反复开关编辑器、修改配置、重启插件效率极低。更糟糕的是团队里其他美术和策划同事根本不敢碰这个插件因为“不知道这些数字改了会出什么效果怕弄坏项目”。这让我意识到一个插件的易用性很大程度上就体现在它的配置界面上。于是我花了些时间研究并实践了一套为Cocos Creator插件快速构建可视化设置面板的方案。核心目标就一个让配置过程变得所见即所得直观且无脑。最终我把它提炼成了一个可以“三步走”的标准化流程。无论你是插件开发新手还是想优化现有插件的老手这套方法都能让你在半小时内将一个零散的配置对象变成一个漂亮、易用、功能完整的可视化面板。这不仅仅是“美化界面”更是提升插件专业性、降低用户使用门槛、减少后期维护成本的关键一步。2. 核心思路与方案选型从JSON到UI的桥梁在动手之前我们先要搞清楚一个核心问题可视化设置面板的本质是什么我的理解是它是一个将插件的配置数据通常是JavaScript对象或JSON与Cocos Creator编辑器内置的UI控件进行双向绑定的系统。用户通过UI控件输入框、下拉菜单、滑块等修改数值这个修改能实时、准确地同步到底层的配置数据中反之当配置数据被加载或从外部修改时UI界面也要能立刻反映出最新的状态。基于这个理解我评估了Cocos Creator插件开发中几种常见的UI方案纯HTML/CSS/JS网页在插件面板中嵌入一个webview完全自主绘制UI。优点是自由度极高可以做出非常炫酷的界面。但缺点更明显开发成本高需要处理与编辑器主进程的通信IPC样式和交互与Cocos Creator编辑器本身格格不入体验割裂。ImGui等原生图形库性能好但需要编译原生模块跨平台部署复杂且与Cocos Creator的TypeScript/JavaScript生态结合不够顺畅。Cocos Creator编辑器扩展API这是官方提供的方案也是我最终选择的方案。它提供了一套基于UI模块的声明式UI构建方式其控件风格、布局逻辑与Cocos Creator编辑器本身完全一致。这意味着你的插件面板看起来、用起来都像是编辑器原生的一部分用户体验无缝衔接。更重要的是它天然运行在编辑器的渲染进程中可以直接访问和操作插件定义的数据和函数无需复杂的跨进程通信。所以我的方案核心就是深度利用Cocos Creator编辑器扩展API中的UI模块。这个模块提供了prop属性定义和asset资源定义的能力我们可以通过它用类似定义组件属性的方式来声明我们的配置项应该如何被渲染和编辑。注意这里说的UI模块不是游戏运行时用的cc.ui而是插件开发中Editor.UI或Editor.Panel相关的API。在Cocos Creator 2.x和3.x中具体的API名称和用法有细微差别但核心思想一致。本文的示例将以更通用的思路和Cocos Creator 3.x的API风格为主进行讲解并指出2.x中的关键差异点。3. 三步打造可视化面板从零到一的完整实操接下来就是最核心的“三步走”实操环节。我会以一个具体的插件需求为例假设我们要开发一个“场景自动备份”插件它需要配置三个参数备份间隔分钟一个整数。最大备份数量一个整数。启用自动备份一个布尔值。我们的目标是为这三个配置项生成一个可视化面板。3.1 第一步定义配置的数据结构Schema这是最重要的一步它决定了你的面板“长什么样”以及“如何工作”。我们需要在插件的package.json文件中或者在一个单独的脚本里定义配置的“模式”Schema。在Cocos Creator 3.x中我们通常在插件的入口脚本例如src/main.ts中通过Editor.Panel.extend或Editor.Profile等API来定义。但更清晰的做法是我们定义一个纯粹的配置对象和它的模式描述。首先在插件项目中创建一个配置文件比如src/config.ts// src/config.ts // 1. 定义配置数据的默认值也是一个完整的配置对象示例 export const defaultConfig { backupInterval: 10, // 备份间隔单位分钟 maxBackupCount: 30, // 最大备份文件数 enableAutoBackup: true, // 是否启用 }; // 2. 定义配置数据的类型接口用于TypeScript类型检查 export interface IBackupPluginConfig { backupInterval: number; maxBackupCount: number; enableAutoBackup: boolean; } // 3. 定义UI渲染的模式Schema // 这是连接数据和UI的关键 export const configSchema { backupInterval: { label: 备份间隔分钟, description: 每隔多少分钟自动备份一次当前场景, type: number, default: defaultConfig.backupInterval, min: 1, // 最小值 max: 1440, // 最大值24小时 step: 1, // 步进值 // 在Cocos Creator的UI系统中number类型默认可能渲染为输入框 // 我们可以通过ui属性指定更具体的控件但基础类型通常够用 }, maxBackupCount: { label: 最大备份数量, description: 最多保留多少个历史备份文件超过将自动删除最旧的, type: number, default: defaultConfig.maxBackupCount, min: 1, max: 1000, }, enableAutoBackup: { label: 启用自动备份, description: 勾选后插件将开始按照间隔自动备份, type: boolean, default: defaultConfig.enableAutoBackup, }, };关键点解析label: 显示在UI上的标签文字。description: 鼠标悬停时的提示文本对于解释参数用途非常重要。type: 核心属性决定了使用哪种基础UI控件。常见的有number,string,boolean,object等。对于number类型可以附加min,max,step等属性来约束输入范围。default: 该配置项的默认值。ui: 高级用法如果基础type不能满足你的需求比如你想把一个数字渲染成滑块或者一个字符串渲染成下拉框你可以通过ui属性指定一个自定义的UI组件名。这需要你提前注册自定义UI组件对于入门来说我们先使用基础类型。这个schema对象就像一个“蓝图”告诉Cocos Creator编辑器“我有一个配置对象它有三个属性分别应该用什么标签、什么控件、什么默认值来展示和编辑”。3.2 第二步创建面板并绑定Schema有了数据蓝图接下来就要创建承载这个蓝图的“画布”——也就是插件面板本身。在插件主入口文件例如src/main.ts中我们注册这个面板// src/main.ts import * as cc from cc; import { configSchema, defaultConfig } from ./config; // 定义一个全局变量来存储当前配置实际项目中应从持久化存储如localStorage或文件中读取 let currentConfig { ...defaultConfig }; // 1. 定义面板类 export class BackupSettingPanel extends cc.Editor.PanelBase { // 模板方法返回面板的HTML模板字符串 // 注意在Cocos Creator 3.x中更推荐使用template属性和render函数 // 这里为了概念清晰先展示一种简化的结构 static template div classplugin-panel header场景自动备份设置/header div classcontent !-- UI控件将根据schema自动生成在这里 -- ui-prop idprop-container classprop-container/ui-prop /div footer ui-button classbtn-save保存/ui-button ui-button classbtn-reset重置/ui-button /footer /div ; // 2. 面板渲染后执行 async run() { // 等待DOM就绪 await super.run(); // 获取存储配置的DOM容器 const propContainer this.shadowRoot?.querySelector(#prop-container); if (!propContainer) return; // 3. 核心操作将schema渲染到UI容器中 // 这里利用了Editor.UI模块的能力具体API名可能随版本变化 // 假设有一个 renderProperties 方法 cc.Editor.UI.renderProperties(propContainer, configSchema, currentConfig, (path, value) { // 回调函数当UI中任何属性被修改时触发 console.log(配置项 ${path} 被修改为:, value); // 更新内存中的配置 // 这里需要根据path来更新currentConfig中对应的属性可以使用lodash的set方法 // _.set(currentConfig, path, value); // 为了简单演示我们假设path就是顶层的属性名 (currentConfig as any)[path] value; }); // 4. 绑定按钮事件 const saveBtn this.shadowRoot?.querySelector(.btn-save); const resetBtn this.shadowRoot?.querySelector(.btn-reset); saveBtn?.addEventListener(confirm, () this.saveConfig()); resetBtn?.addEventListener(confirm, () this.resetConfig()); } // 保存配置到持久化存储 saveConfig() { console.log(保存配置:, currentConfig); // 实际项目中这里应该调用Editor.Profile.setConfig或写入本地文件 // cc.Editor.Profile.setConfig(backup-plugin, currentConfig); cc.Editor.Ipc.sendToMain(backup-plugin:save-config, currentConfig); cc.Editor.Dialog.info(提示, 配置已保存); } // 重置配置为默认值 resetConfig() { currentConfig { ...defaultConfig }; // 重置后需要重新渲染UI以反映默认值 // 一种方法是重新调用run()中的渲染逻辑或者更优的是触发UI更新 console.log(重置配置为默认值); this.run(); // 简单粗暴的重置方式实际应有更优雅的更新机制 } } // 5. 注册面板到编辑器 // 在插件启动时执行 export function load() { // 注册一个消息用于打开面板 cc.Editor.Ipc.sendToMain(backup-plugin:open-settings); } export function unload() {}实操要点与避坑指南面板模板上面的template是一个极度简化的示例。在真实项目中Cocos Creator 3.x的插件面板开发更接近于现代前端你可能需要编写一个ui-panel组件并在package.json的panels字段中声明。但无论形式如何变化核心逻辑不变准备一个容器将schema和data喂给一个渲染函数并监听变化回调。数据流注意currentConfig这个变量。它是在内存中的配置副本。UI的修改通过回调函数实时更新它。点击“保存”按钮时才将这个内存中的数据写入持久化存储如Editor.Profile或项目设置文件。这种设计避免了频繁的IO操作。版本差异Cocos Creator 2.x 和 3.x 的插件系统有较大差异。2.x 更依赖于在package.json中定义panel和contributions面板UI多直接写在HTML文件中。而3.x 更模块化提倡使用TypeScript和声明式UI。你需要根据你使用的Cocos Creator版本查阅对应的 编辑器扩展官方文档 来调整具体API。ui-prop组件示例中使用的ui-prop是一个特殊的容器组件它是编辑器UI系统的一部分专门用于根据schema动态生成一组表单控件。你需要确保在模板中正确引入了编辑器的UI组件库。3.3 第三步关联插件逻辑与面板配置面板做好了配置也能保存了最后一步就是让插件的核心功能能读取到这些配置。我们修改插件的主要功能脚本例如src/backup-manager.ts让它从持久化存储中读取配置// src/backup-manager.ts import { IBackupPluginConfig } from ./config; export class BackupManager { private config: IBackupPluginConfig; private timerId: number | null null; // 初始化时加载配置 async init() { await this.loadConfig(); this.applyConfig(); } // 从持久化存储加载配置 private async loadConfig() { // 方法1使用Editor.Profile (适用于编辑器全局配置) // this.config await cc.Editor.Profile.getConfig(backup-plugin) as IBackupPluginConfig; // 方法2通过Ipc从主进程获取如果配置保存在项目.settings文件夹中 // 这里模拟一个Ipc调用 this.config await new Promise((resolve) { cc.Editor.Ipc.sendToMain(backup-plugin:get-config, (config: IBackupPluginConfig) { resolve(config); }); }); // 如果找不到配置则使用默认值 if (!this.config) { const { defaultConfig } await import(./config); this.config { ...defaultConfig }; } console.log(备份管理器加载配置:, this.config); } // 应用配置例如根据配置启动或停止定时器 private applyConfig() { // 清除现有定时器 if (this.timerId ! null) { clearInterval(this.timerId); this.timerId null; } // 如果启用自动备份则创建新的定时器 if (this.config.enableAutoBackup this.config.backupInterval 0) { const intervalMs this.config.backupInterval * 60 * 1000; // 转换为毫秒 this.timerId setInterval(() { this.performBackup(); }, intervalMs) as unknown as number; // Node.js与浏览器环境类型差异 console.log(自动备份已启动间隔 ${this.config.backupInterval} 分钟); } else { console.log(自动备份未启用或间隔无效); } } // 执行备份的具体逻辑 private performBackup() { console.log([${new Date().toLocaleTimeString()}] 执行场景备份...); // 这里实现实际的备份逻辑例如 // 1. 获取当前场景路径 // 2. 复制场景文件到备份目录并加上时间戳 // 3. 清理超过 maxBackupCount 的旧备份 // cc.Editor.Ipc.sendToMain(backup-plugin:do-backup); } // 提供一个公共方法用于在配置更改后更新管理器 public updateConfig(newConfig: IBackupPluginConfig) { this.config { ...newConfig }; this.applyConfig(); // 重新应用新配置 } }然后在面板的saveConfig方法中不仅要将配置存盘还要通知功能模块更新// 在 src/main.ts 的 saveConfig 方法中补充 async saveConfig() { console.log(保存配置:, currentConfig); // 保存到持久化存储 // await cc.Editor.Profile.setConfig(backup-plugin, currentConfig); cc.Editor.Ipc.sendToMain(backup-plugin:save-config, currentConfig); // 通知备份管理器更新配置 cc.Editor.Ipc.sendToMain(backup-plugin:update-config, currentConfig); cc.Editor.Dialog.info(提示, 配置已保存并生效); }至此一个完整的“配置数据Schema - 可视化编辑面板 - 插件功能读取”的闭环就建立了。用户在前端面板上的每一次调整最终都能实时或通过保存按钮反馈到插件后台的运行逻辑中。4. 进阶技巧与常见问题排查掌握了基础三步法你已经可以应对大多数简单插件的配置需求。但在实际开发中你可能会遇到更复杂的情况。下面分享一些进阶技巧和踩坑经验。4.1 处理复杂数据类型与自定义控件基础类型数字、字符串、布尔往往不够用。比如你想让用户选择一个项目中的特定文件夹路径或者从一个资源列表里拖拽一个Prefab进来。解决方案使用asset类型或自定义ui组件。asset类型用于选择项目中的资源如场景、预制体、图片、脚本等。export const advancedSchema { targetScene: { label: 目标场景, type: asset, default: null, // 可以指定资源类型过滤器 assetType: scene, // 只允许选择场景文件 }, logoTexture: { label: Logo图片, type: asset, assetType: texture, } };渲染时这会变成一个带有点击按钮的资源选择框用户体验与编辑器内置的资源选择器完全一致。自定义ui组件当内置类型都无法满足时你可以注册自己的UI组件。首先定义一个自定义组件例如一个颜色选择器// 定义一个简单的颜色选择器组件概念示例 cc.Editor.UI.registerComponent(my-color-picker, { template: input typecolor :valuevalue inputonInput, props: [value], methods: { onInput(event) { this.$emit(change, event.target.value); } } });然后在schema中指定使用它export const advancedSchema { themeColor: { label: 主题颜色, type: string, // 底层数据类型还是字符串 default: #3498db, ui: { // 指定使用自定义组件来渲染 component: my-color-picker, } } };这种方式提供了极大的灵活性但复杂度也更高需要你熟悉编辑器扩展的UI组件开发规范。4.2 配置的分组与布局优化当配置项很多时全部平铺开来会非常混乱。我们可以对配置进行分组。在schema中我们可以通过嵌套对象来实现分组export const groupedSchema { // 基础设置组 basicSettings: { label: 基础设置, type: section, // 或者使用 group 等类型具体看编辑器UI支持 children: { enableAutoBackup: { label: 启用, type: boolean, default: true }, backupInterval: { label: 间隔(分钟), type: number, default: 10, min: 1 }, } }, // 高级设置组 advancedSettings: { label: 高级设置, type: section, children: { maxBackupCount: { label: 最大数量, type: number, default: 30, min: 1 }, backupPath: { label: 自定义路径, type: string, default: }, compressBackup: { label: 压缩备份, type: boolean, default: false }, } } };渲染时type: section或类似的属性通常会生成一个可折叠的分组面板使界面更加清晰。4.3 配置的持久化与多项目管理一个插件可能被用于多个不同的Cocos Creator项目每个项目的理想配置可能不同。因此将配置保存在项目本地而非编辑器全局是更专业的做法。推荐做法将配置保存在项目设置中。Cocos Creator提供了ProjectSettings机制在3.x中通常通过cc.settings或特定Ipc通道访问。你可以将插件的配置以JSON形式保存在项目的settings文件夹下的某个文件中例如project-name/settings/my-plugin.json。// 保存到项目设置 async saveToProjectSettings(config) { // 通过Ipc发送给主进程由主进程写入项目settings文件 await cc.Editor.Ipc.sendToMain(my-plugin:save-project-settings, config); } // 从项目设置读取 async loadFromProjectSettings() { const config await cc.Editor.Ipc.sendToMain(my-plugin:load-project-settings); return config || defaultConfig; }这样当用户在不同项目间切换时插件会自动加载对应项目的配置体验非常好。4.4 常见问题与排查清单面板打开是空白的检查浏览器开发者工具F12的Console面板是否有JavaScript错误。插件面板本质上是一个Web页面。检查package.json中panels的template或src路径是否正确。检查面板主类是否被正确注册和导出。Schema定义好了但UI没渲染出来检查确保schema对象的格式正确特别是type字段是编辑器支持的内置类型。检查渲染schema的容器DOM元素是否存在且唯一querySelector找到了正确的元素。检查渲染函数的调用时机是否正确通常在面板的ready或run生命周期中。修改UI后配置值没更新检查是否正确监听了UI控件的变化事件。对于动态生成的ui-prop确保在渲染时传入了正确的change回调函数。检查回调函数中的path和value参数是否正确。对于嵌套属性path可能是字符串如advancedSettings.compressBackup你需要用相应的方法如lodash.set来更新深层对象。配置保存了但插件重启后恢复了默认值检查保存配置的代码是否真的写入了持久化存储如Editor.Profile.setConfig或项目设置文件。console.log打印确认。检查插件初始化时读取配置的代码路径是否正确是否成功读到了之前保存的值。在Cocos Creator 2.x中如何实现核心思路一致但API不同。2.x中通常在package.json的contributions里定义profile配置模式然后在面板的HTML/JS中通过Editor.profile相关的API来获取和渲染配置。具体请查阅Cocos Creator 2.x的编辑器扩展文档。我个人在多次插件开发中最大的体会是可视化配置面板的投入产出比极高。初期多花一两天时间搭建好这个框架后期在功能迭代、参数调整、团队协作上节省的时间远超投入。它让插件从“开发者自用工具”变成了“团队友好型产品”是提升插件质量和专业度的不二法门。
