';

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

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

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

配置开发环境

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

  1. 打开到注册表(运行 regedit):
    CC 、CC 2014:HKEY_CURRENT_USER\Software\Adobe\CSXS.5
    CC 2015:HKEY_CURRENT_USER\Software\Adobe\CSXS.6
    CC 2015.5:HKEY_CURRENT_USER\Software\Adobe\CSXS.7
  2. 添加 字符串值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.jsCSInterface.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 版本或者用下面两个办法解决:

  1. 把下面代码设置成书签,并在控制台的页面打开它:
    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';})();
    
    

  2. 使用 CEF 的 Test app 来代替浏览器
    Aodobe 提供的下载:

    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.6HKEY_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 相关语句,把其都删除或注释掉,就能关闭扩展的持久化,让刷新更简单。