Cocos 2.x 扩展开发教程

一、Cocos扩展介绍

Cocos扩展可以让Cocos Creator用户定制和扩展编辑器的功能。这些扩展以包（package）的形式进行加载。

Cocos Creator 的扩展包沿用了 Node.js 社区的包设计方式，通过 package.json 描述文件来定义扩展包的内容和注册信息。

需要注意的是，Cocos Creator 2.x 系列和 Cocos Creator 3.x 系列的扩展不兼容，位置也不同，所以开发教程也不同。本文讲的是 Cocos Creator 2.x 系列扩展开发教程，Cocos Creator 3.x 系列放在下一篇。

官方开发教程在：扩展编辑器 · Cocos Creator

Cocos扩展的商店页面是 store.cocos.com/app ，可以在Cocos Creator IDE中直接打开。

图一 打开路径为：菜单 -> 扩展 -> 扩展商店

注：图二中的SmartAd试玩打包工具就是本文要讲的案例。

二、教程案例介绍

1. 案例背景

本案例介绍的扩展名叫SmartAd试玩打包工具，是一个Cocos打包试玩广告的扩展。

试玩广告是一种新兴广告类型，在近几年开始兴起。与传统广告格式（如图片和视频）不同，试玩广告对用户具有高度互动性，在广告展示时，可以与用户进行交互，使广告变得更丰富有趣。

这些广告能在 30 秒内吸引观众的注意力、展示游戏玩法并转化用户。即使在竞争激烈的市场中，它们也能提供低用户获取成本（CPI）、高转化率 (CVR) 和点击率 (CTR)。

试玩广告本质上是一个HTML网页，通过JS等技术响应用户操作，与用户产生互动。由于带宽和加载速度的原因，试玩广告一般对文件大小都有严格要求，大多数投放渠道的要求是不超过5M，且要求单文件，即所有资源都要在一个HTML中加载展示。

Cocos因为引擎的特性，非常适合用来制作试玩广告，但Cocos导出的工程是一个多文件目录，需要用专门的工具进行单文件打包，并接入各渠道的SDK，这是一个耗时耗力的过程。SmartAd平台开发了一个工具，可以一键完成Cocos工程导出试玩广告，为了更方便用户使用，因此需要开发一个Cocos Creator扩展，方便用户的使用。

关于试玩广告，如果你想了解更多可以阅读这篇文章：应用、游戏和品牌的新营销方式-试玩广告-帮助中心-SmartAd试玩广告制作平台

2. 扩展流程

本扩展的流程是：

3. 涉及到的知识点

• 扩展基本结构
• 多语言
• 扩展菜单添加
• 扩展面板UI编写
• UIKit的使用
• 扩展数据交互
• 文件上传
• 扩展打包上架

三、创建基本结构

在菜单上选择扩展->创建新扩展插件 -> 全局扩展（安装在用户目录下）即可创建一个扩展，这里名字用SartAdDemo

上面的操作，会在用户目录生成一个目录，结构如下：

这几个文件作用如下：

1. package.json

package.json是扩展定义，文件内容如下： `{

"name": "SmartAdDemo",

"version": "0.0.1",

"description": "The package template for getting started.",

"author": "Cocos Creator",

"main": "main.js",

"main-menu": {

"i18n:MAIN_MENU.package.title/SmartAdDemo/open": {

"message": "SmartAdDemo:open"

},

"i18n:MAIN_MENU.package.title/SmartAdDemo/hello": {

"message": "SmartAdDemo:say-hello"

}

},

"panel": {

"main": "panel/index.js",

"type": "dockable",

"title": "SmartAdDemo",

"width": 400,

"height": 300

}

}`

值分别表示：

• "name": 扩展名（只能全小写）

• "version": 扩展版本号

• "description": 扩展描述

• "author": 作者

• "main": 入口文件

• "main-menu": 菜单

• "panel": 面板

  • "main": 面板入口
  • "type": 面板类型
  • "title": 面板标题
  • "width": 面板宽度
  • "height": 面板高度

2. main.js

扩展的入口文件，在package.json中的main中引入

`'use strict';

module.exports = {

load () {

// execute when package loaded

},

unload () {

// execute when package unloaded

},

// register your ipc messages here

messages: {

'open' () {

// open entry panel registered in package.json

Editor.Panel.open('SmartAdDemo');

},

'say-hello' () {

Editor.log('Hello World!');

// send ipc message to panel

Editor.Ipc.sendToPanel('SmartAdDemo', 'SmartAdDemo:hello');

},

'clicked' () {

Editor.log('Button clicked!');

}

},

};`

值分别表示：

• load：扩展加载调用

• unload：扩展关闭调用

• messages：消息（IPC通信）

  • open：对应open菜单
  • say-hello：对应say-hello菜单
  • clicked：对应页面上按钮的点击事件

3. panel/index.js

面板入口文件，在package.json中引入： `// panel/index.js, this filename needs to match the one registered in package.json

Editor.Panel.extend({

// css style for panel

style: `

:host { margin: 5px; }

h2 { color: #f90; }

`,

// html template for panel

template: `

SmartAdDemo

---

---

Send To Main

`,

// element and variable binding

$: {

btn: '#btn',

label: '#label',

},

// method executed when template and styles are successfully loaded and initialized

ready () {

this.$btn.addEventListener('confirm', () => {

Editor.Ipc.sendToMain('SmartAdDemo:clicked');

});

},

// register your ipc messages here

messages: {

'SmartAdDemo:hello' (event) {

this.$label.innerText = 'Hello!';

}

}

});`

值分别表示：

• style：面板HTML样式
• templete：面板HTML模板
• $：面板HTML元素与JS变量绑定
• ready：当面板加载完后调用，相当于window.onready事件
• messages：ipc通信事件注册

四、多语言

1、方案

Cocos Creator编辑器扩展系统中内置了多语言方案，具本做法是在扩展包的目录下新建一个名叫 i18n 的文件夹，并为每种语言添加一个相应的 JavaScript 文件，作为键值映射数据。数据文件名应该和语言的代号一致，如 en.js 对应英语映射数据。

如：

`// en.js

module.exports = {

'search': 'Search',

'edit': 'Edit',

};

// zh.js

module.exports = {

'search': '搜索',

'edit': '编辑',

};`

2、在脚本中使用

在 JavaScript 脚本中，可以通过 Editor.T 接口获取当前语言对应的翻译后的文本，如： `// NOTE: my package name is "smartaddemo"

Editor.T('smartaddemo.search');在编辑器面板的模板定义文件里，也可以直接使用这个接口，如：// NOTE: my package name is "smartaddemo"

Editor.Panel.extend({

template: `

`

});`

3、在菜单中使用

在扩展包的 package.json 中注册菜单时可以用 i18n:${key} 的形式进行多语言翻译。

我们的扩展只需要一个打开，所以更改如下：

`{

"name": "SmartAdDemo",

"version": "0.0.1",

"description": "The package template for getting started.",

"author": "Cocos Creator",

"main": "main.js",

"main-menu": {

"i18n:MAIN_MENU.package.title/SmartAdDemo/i18n:SmartAdDemo.open": {

"message": "SmartAdDemo:open"

}

},

"panel": {

"main": "panel/index.js",

"type": "dockable",

"title": "SmartAdDemo",

"width": 400,

"height": 300

}

}`

对应的i18n文件如下： `// en.js

module.exports = {

'open': 'SmartAd Playable Ads Pack'

};

// zh.js

module.exports = {

'open': 'SmartAd试玩广告打包'

};`

五、扩展菜单添加

Cocos Creator 的主菜单是可以自由扩展的。扩展方法是在 package.json 文件中的 main-menu 字段里，加入自己的菜单路径和菜单设置选项。

我们这里只需要一个，所以配置如下： `{

"main-menu": {

"i18n:MAIN_MENU.package.title/i18n:smartaddemo.open": {

"message": "smartaddemo:open"

}

},

}`

效果如图：

六、扩展面板UI编写

1. 原型图

面板原型图如图：

2. 结构优化

为了让代码更具可读性，我们把面板分为html和css及js的方式，具体做法是在panel目录下创建index.html、index.css文件，并在index.js中引用。

目录如下：

3. 具体实现

index.html： `

欢迎使用SmartAd一键试玩广告打包工具

步骤一：添加SmartAd SDK(仅需一行代码，即可导出全渠道试玩广告)

步骤二：构建项目（选择Web Mobile平台）

查看教程文档或咨询人工客服

`

index.css： `body {

background: #fff;

}

:host {

margin: 5px;

}

h2 {

color: #fff;

text-align: center;

}

p {

font-size: 16px;

}

.btn_group {

text-align: center;

margin-top: 20px;

}

.button-item {

width: 130px;

height: 40px;

border-radius: 5px;

color: #fff;

}

#msg {

color: white;`

index.js： `const fs = require('fs');

// panel/index.js, this filename needs to match the one registered in package.json

Editor.Panel.extend({

// css style for panel

style: fs.readFileSync(Editor.url('packages://SmartAdDemo/panel/index.css')),

// html template for panel

template: fs.readFileSync(Editor.url('packages://SmartAdDemo/panel/index.html')),

// element and variable binding

$: {

cancel_btn: '#cancel_btn',

pack_btn: '#pack_btn',

help_link: '#help_link',

msg: '#msg'

},

// method executed when template and styles are successfully loaded and initialized

ready() {

},

});` 这里通过fs模块读取文件的方式引入html和css。

###4.运行效果

效果如图所示

七、UIKit的使用

1. UIKit介绍

Cocos Creator 为开发者提供了非常丰富的界面元素，称为UIKit，帮助开发者快速地开发面板界面。

目前常见的界面元素包括：

• ui-button
• ui-checkbox
• ui-color
• ui-input
• ui-select
• ui-slider
• ui-text-area

全部元素见：掌握 UI Kit · Cocos Creator

2. UIKit的使用

我们这里只用 ui-button 做演示，在html中的取消和打包按钮分别如下：

`取消

打包`

3. UIKit元素的获取

在面板上定义了uikit后，在js中通过$进行绑定： `$: {

cancel_btn: '#cancel_btn',

pack_btn: '#pack_btn'

}使用时直接用this.$cancel_btn`即可。

八、扩展数据交互

按照第2步中的流程，接下来的操作就是用户点击“打包”按钮，开始检测构建文件，并压缩上传。

1. 事件监听

我们先来绑定按钮的点击事件，通过 addEventListener方法即可给元素添加事件： `ready() {

this.$cancel_btn.addEventListener('confirm', () => {

Editor.Panel.close('smartaddemo');

});

this.$pack_btn.addEventListener('confirm', () => {

});

this.$help_link.addEventListener('click', () => {

});

},` 如上面的代码，我们分别给“取消”、“打包”和帮助文字添加了点击事件。

2. 调用其他模块

为了让代码更好地组织和阅读，我们把主要的逻辑写在扩展的 src/smartAd.js 中，这里实现了扩展的所有流程。

在面板的js中我们可以通过下面的方式对smartAd.js进行引用：

const smartAd = require(Editor.url('packages://SmartAdDemo/src/smartAd'));

在“打包”按钮中进行引用： `const _self = this;

this.$pack_btn.addEventListener('confirm', () => {

try {

smartAd.main(function msgCallback(msg) {

_self.$msg.innerHTML = msg;

});

} catch (e) {

Editor.log(e);

}

});`

九、文件上传

文件上传使用标准的HTTP POST请求就可以实现。

1. 构建form表单

我们这里用的是fs模块的 fs.createReadStream 方法来读取上传的文件，创建一个stream，上传文件的字段字是zip，示例如下： `function upload_zip(zip_file) {

let formData = {

zip: fs.createReadStream(zip_file),

};

}`

2. 发送POST请求

这里用的是 request 库，代码如下： `function request_i(params, callback) {

let headers = {

'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36',

'Content-type': 'application/json',

'sid': sid

}

params.headers = headers;

request.post(params, callback)

}`

十、打包

1. 最终的代码

最终的目录结构如下：

2. 第三方库

因为我们用到了压缩，所以需要引入第三方压缩库archiver，在package.json中引入： `{

"dependencies": {

"archiver": "^5.3.0"

}

}`

然后通过 npm install 进行安装

3. 打包

把扩展目录的所有文件（包含node_modules)压缩为ZIP格式，并命名为扩展名称，即可。

十一、上架

1. 注册Cocos开发者账号

访问 Cocos 开发者中心 注册账号并登录

2. 填写扩展信息

• 进入 商店 栏目，点击右上方的发布新资源；
• 然后进入资源类别页面，填写名称和类别 ，勾选已阅读协议；
• 在 资源介绍 页面填写相关信息；
• 在 定价 页面设置插件的售价，包括 CNY 和 USD 两种，如果免费请填写 0；
• 在 上传资源 页面上传插件扩展包资源并填写相关信息；

###3. 提交审核

填写完以上信息后，在 提交审核 页面点击 提交审核 按钮即可，一般3个工作日会有结果。

更详细的信息请参考：提交插件到商店 · Cocos Creator

十二、结束

好了，以上就是Cocos Creator 2.x 版扩展开发的相关内容，欢迎留言交流。