Adobe CEP 扩展开发教程「 1 」Hello World!

本篇会从配置 CEP 的开发环境开始讲解如何从零开始构建一个 CEP 扩展，还有关于扩展调试的方法。

配置开发环境

通常情况下宿主应用是不会运行未经签名扩展的，只有打包并签名才可以运行，这样我们就没法即时测试开发的扩展了，所以在开始之前，我们要打开开发者模式：

打开到注册表（运行 regedit）：
CC 、CC 2014：HKEY_CURRENT_USER\Software\Adobe\CSXS.5
CC 2015：HKEY_CURRENT_USER\Software\Adobe\CSXS.6CC 2015.5：HKEY_CURRENT_USER\Software\Adobe\CSXS.7
添加 字符串值 项 PlayerDebugMode，将值设置为 1
在注册表中添加 PlayerDebugMode 键值

这里提供 2 个 .reg 文件（针对 CSXS.6，也就是 CC2015，如果用于 CC2015.5 请用文本编辑器打开并把 CSXS.6 替换为 CSXS.7），在 Windows 下双击就能方便的开关开发者模式：

另外如果是 OS X 可以打开终端输入： defaults write com.adobe.CSXS.6 PlayerDebugMode 1 来打开开发者模式。同样如果是 CC2015.5 要把 CSXS.6 换成 CSXS.7

开始一个Hello World! 吧

想要快速的了解 CEP 扩展的工作方式和开发流程，最好的方法莫过于直接构建一个最简单的 CEP 的 Hello World! 扩展。再说一下，本教程是针对宿主应用是 Windows 下的 PhotoShop 的扩展来讲的，不过在 OS X 下开发的流程也是一样的，开发出来的 CEP 扩展也可以同时运行在 Windows 与 OS X 下的。
如果你已经对 CEP 扩展构件的基本方法有了一些了解，也可以跳过这一段。

建立一个工作目录

我们需要建立一个文件夹作为工作目录，名称可以随意，它需要放在下面某一个路径（你的宿主应用要是 CC 2015 以上）下，才会在宿主应用启动时被载入：

Windows 32 位：C:\Program Files\Common Files\Adobe\CEP\extensions\
Windows 64 位：C:\Program Files (x86)\Common Files\Adobe\CEP\extensions\
Windows 通用：C:\Users\系统用户名\AppData\Roaming\Adobe\CEP\extensions\
OS X：/Library/Application Support/Adobe/CEP/extensions/

一般的 CEP 扩展都会有下面这样的目录结构，用不同的文件夹存放不同类型的文件：

不过这些不是必须的，真正必须的是 CSXS 目录和里面存放的 manifest.xml 配置文件：

创建 manifest.xml 配置文件

manifest.xml 是一个 XML 格式的配置文件，里面有我们这个扩展的配置信息，包括扩展名称、版本、在什么宿主中运行、入口文件、尺寸等等等配置，后面我们还会详细介绍 manifest.xml。

我们在扩展工作目录中建立一个名为 CSXS 的文件夹，并在其中新建一个文本并命名为 manifest.xml ，并输入以下内容，保存为 UTF-8 编码：

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<ExtensionManifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ExtensionBundleId="com.nullice.helloworld" ExtensionBundleVersion="1.0" Version="6.0"> <!-- MAJOR-VERSION-UPDATE-MARKER -->
    <ExtensionList>
        <Extension Id="com.nullice.helloworld" Version="1.0"/> <!-- 设置扩展 ID-->
    </ExtensionList>

    <ExecutionEnvironment>
        <HostList> <!-- 设置扩展能在 11.0 版本之后 PhotoShop 中运行-->
            <Host Name="PHXS" Version="[11.0,99.9]"/>
            <Host Name="PHSP" Version="[11.0,99.9]"/>
        </HostList>

        <LocaleList>
            <Locale Code="All"/>
        </LocaleList>

        <RequiredRuntimeList>
            <RequiredRuntime Name="CSXS" Version="6.0"/> 
        </RequiredRuntimeList>
    </ExecutionEnvironment>

    <DispatchInfoList>
        <Extension Id="com.nullice.helloworld"> <!-- 为 com.nullice.helloworld 设置属性-->
            <DispatchInfo>
                <Resources>
                    <MainPath>./index.html</MainPath> <!-- 指定起始载入的网页-->
                    <ScriptPath>./jsx/main.jsx</ScriptPath> <!-- 指定用到的 JSX 文件-->
                </Resources>

                <Lifecycle>
                    <AutoVisible>true</AutoVisible> <!-- 设置扩展面板为可视-->
                    <StartOn>
                    </StartOn>
                </Lifecycle>

                <UI>
                    <Type>Panel</Type> <!-- 设置扩展显示为面板模式-->
                    <Menu>Hello world</Menu> <!-- 设置扩展标题-->
                    <Geometry>
                        <Size>  <!-- 设置扩展面板尺寸-->
                            <Height>300</Height>
                            <Width>300</Width>
                        </Size>
                        <MaxSize>
                            <Height>900</Height>
                            <Width>900</Width>
                        </MaxSize>
                        <MinSize>
                            <Height>300</Height>
                            <Width>300</Width>
                        </MinSize>
                    </Geometry>
                    <Icons>  <!-- 设置扩展面板尺寸-->
                        <Icon Type="Normal">./img/icon1.png</Icon>
                        <Icon Type="DarkNormal">./img/icon1.png</Icon>
                    </Icons>
                </UI>

            </DispatchInfo>
        </Extension>
    </DispatchInfoList>
</ExtensionManifest>

创建 HTML 页面

CEP 的用户界面使用的是 HTML ，也就是网页，在 manifest.xml 中定义了扩展的入口 HTML 文件。

在工作目录根目录建立一个文本命名为 index.html ，填入下面内容，保存为 UTF-8 编码：

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
  <meta http-equiv="content-type" content="text/html" charset="UTF-8">
  <link href="./css/styles.css" type="text/css" rel="stylesheet">
      <script type="text/javascript" src="./js/test.js"></script>
      <script type="text/javascript" src="./js/CSInterface.js"></script>
      <script type="text/javascript" src="./js/Vulcan.js"></script>
      <script type="text/javascript" src="./js/AgoraLib.js"></script>
  </head>

  <body style="background-color: #a2a1a3; text-align: center;" >
  <span style="font-family: '微软雅黑'; font-style: normal; font-weight: normal; font-size: 16pt; color: white"> CEP 6 开发教程 </span>
    <br>
    <br>
    <br>
    <span >
      <span style="font-family: 'Castellar'; font-style: normal; font-weight: normal; font-size: 34pt;"> Hello World ! </span>
    </span>
  <br>

  <input type="button" value="新建文档" onclick="pop()">

  </body>
</html>

可以在浏览器中预览这个 HTML 文件

在 HTML 文件中我们引入了一个 Javascript 文件，在工作目录根目录建立一个名为 js 的文件夹，并在其中新建文本 test.js ，填入下面内容，保存为 UTF-8 编码：

var pop = function ()
{
    var cs = new CSInterface();
    cs.evalScript("dodo()");
}

这 3 个是 Adobe 官方发布的库

HTML 中给一个按钮绑定了 test.js 中的一个方法 pop() 这个方法会实现一个简单的功能：在 PhotoShop 中新建一个文档。为了实现这个功能我们还需要一个执行ExtendScript 的 JSX 文件。
运行在 CEP VM 中的 JavaScript 无法直接调用 PhotoShop 的功能，所以我们会用 CSInterface.js 最为桥梁调用 JSX 。我们在 HTML 文件中已经引用了 CSInterface.js 。 CSInterface.js 需要放入你的工作目录中，它是 Adobe 官方发布的可以从官方获取。

可以看到我们在 JavaScript 中调用了 dodo() 方法（cs.evalScript("dodo()")），这个方法的实现在 manifest.xml 中定义的 jsx/main.jsx 文件。（实际上也可以直接在 JavaScript 中写 cs.evalScript(" app.documents.add()"); 来实现）
在工作目录根目录建立一个名为 jsx 的文件夹，并在其中新建文本 main.jsx ，填入下面内容，保存为 UTF-8 编码：

var dodo = function (info)
{
    app.documents.add();// 新建一个文档
}

完成

到此我们的扩展已经完成了，打开 PhotoShop 就可以打开这个扩展了

这是一个最简单的扩展示例了，它展示了如何构建 CEP 和运行一个 CEP 插件，如果没看明白，还可以下载这个 Hello World! 扩展：示例下载

调试

远程调试

远程调试是使用浏览器打开的调试页面来调试 CEP，与浏览器中用 F12 开发者工具调试网页是一样的，不过要注意的是，在浏览器窗口打开的是 CEF 的调试工具网页，而不是你浏览器自己的的开发者工具。

为你的扩展打开远程调试，要在你的插件目录中建立文件名为 .debug 的文本文件，由于点开头的文件不能直接建立，在 Windows 下可以通过命令行 "">.debug 建立。

.debug 文件

.debug 文件的内容示例如下：

<?xml version="1.0" encoding="UTF-8"?>
<ExtensionList>
    <Extension Id="com.adobe.CEPHTMLTEST.Panel1">
        <HostList>
            <Host Name="PHXS" Port="8000"/>
            <Host Name="IDSN" Port="8001"/>
        </HostList>
    </Extension>
   <Extension Id="com.adobe.CEPHTMLTEST.Panel2">
        <HostList>
            <Host Name="PHXS" Port="8100"/>
            <Host Name="IDSN" Port="8101"/>
        </HostList>
    </Extension>
</ExtensionList>

填写你的扩展 ID 和宿主名称并用 Port 指定端口号，在浏览器中用 http://localhost:端口号/ 就能访问扩展的远程调试页面了，例如：http://localhost:8080

调试使用的浏览器需要是 Chrome 。要注意的是CEP 6.1 (PhotoShop 6.1) 这个版本的调试工具有无法正常使用滚动条的 BUG ，当控制台内容过长时无法滚动，要正常使用需要使用 Chrome 41 版本或者用下面两个办法解决：

把下面代码设置成书签，并在控制台的页面打开它：
CEP6.1_DebugScrolling _Fix：

javascript:(function(){document.getElementById("console-messages").style.position='absolute';document.getElementById("console-messages").style.overflowY='scroll';document.getElementById("console-messages").style.height='90%';document.getElementById("console-messages").style.width='100%';document.getElementById("console-messages").style.top='30px';})();

使用 CEF 的 Test app 来代替浏览器
Aodobe 提供的下载：
- cefclient_win32
- cefclient_mac
CEP 6.1 也就是 CEF 3.2272.67 的 Test app ,可以在 cefbuilds.com 下载 CEF 官方编译版本。

ExtendScript 调试

要调试是执行 ExtendScript 需要使用 Adobe ExtendScript Toolkit CC，这个工具非常有用，在里面可以编辑 ExtendScript 并让其在指定的宿主应用中运行，而且重要的是可以通过 Data Browser 查看实时查看宿主应用的 DOM ：

有些无法用 Data Browser 直接查看的对象数据，也可以像下面这样用简单的代码来查看：

var str;
for (var i in app.activeDocument.measurementScale )
{
    str += i+":"+app.activeDocument.measurementScale [i] +"\n"
    }
alert (str)

另外在 Adobe ExtendScript Toolkit 的 Help 菜单中还有一个 Object Model Viewer 可以参看 ExtendScript 的对象模型文档：

HTTP Cookies

CEP 扩展的 HTTP Cookies 保存在：
CEP_5、6： C:\Users\USERNAME\AppData\Local\Temp\cep_cache\
CEP_4：C:\Users\USERNAME\AppData\Local\Temp\cep_cookies\
Cookie 的文件名规则是 HostID_HostVersion_ExtensionName，如PHXS_15.0.0_com.adobe.extension1

调试日志

插件的调试日志对插件测试很有用，在注册表中的
HKEY_CURRENT_USER\Software\Adobe\CSXS.6 或 HKEY_CURRENT_USER\Software\Adobe\CSXS.5 中的 LogLevel 项的值能够控制扩展脚本运行中产生日志的类型，

0 – 关（不生成日志）
1 – 错误（默认值日志记录）
2 – 警告
3 – 信息
4 – 调试
5 – 跟踪
6 – 所有

扩展日志文件将生产在：
C:\Users\%USERNAME%\AppData\Local\Temp

另外 Chromium 嵌入式框架的日志（Chromium Embedded Framework）生成在：
C:\Users\%USERNAME%\AppData\Local\Temp\cef_debug.log

刷新

开发的过程中，每做一次修改要想马上看到结果，就需要重新载入扩展，不同的 CEP 宿主应用有不同默认策略，在 PhotoShop 上，扩展默认是非持久性的，也就是说只要关闭并重新打开面板就可以，而 Illustrator 中扩展默认是持久性的，也就是在 Illustrator 启动时载入后就会一直运行，即是关闭面板再打开也无法重新载入，得要重启 Illustrator 才行。

所以对于 Illustrator 通常的办法是在远程调试的控制台中使用 closeExtension() 关闭扩展再打开。

 new CSInterface().closeExtension()

而对于 PhotoShop 扩展的汉化，由大多数扩展都是自己设置了持久性运行，所以也无法通过重新打开面板来刷新，这就需要去把扩展的持久化关掉:

在扩展的 js 文件中搜索 com.adobe.PhotoshopPersistent 相关语句，把其都删除或注释掉，就能关闭扩展的持久化，让刷新更简单。

浅藏的宝藏

Adobe CEP 扩展开发教程「 1 」Hello World!

从构建第一个 CEP 扩展开始吧

配置开发环境

开始一个Hello World! 吧

建立一个工作目录

创建 manifest.xml 配置文件

创建 HTML 页面

完成

调试

远程调试

ExtendScript 调试

HTTP Cookies

调试日志

刷新

配置开发环境

开始一个Hello World! 吧

建立一个工作目录

创建 manifest.xml 配置文件

创建 HTML 页面

完成

调试

远程调试

ExtendScript 调试

HTTP Cookies

调试日志

刷新

Adobe CEP 扩展开发教程 「 0 」

Adobe CEP 扩展开发教程 「 2 」CEP 技术概览

Adobe CEP 扩展开发教程「 0 」

Adobe CEP 扩展开发教程「 2 」CEP 技术概览