Adobe CEP | 目录结构及各文件解析

1. AE CEP

AE CEP（Adobe Common Extensibility Platform）是 Adobe 提供的一种跨产品插件开发平台，允许开发者使用 Web 技术（HTML、CSS、JavaScript）开发跨 Adobe 应用的扩展插件。CEP 插件支持 After Effects、Premiere Pro、Illustrator 等 Adobe 应用，并通过 ExtendScript 或 Adobe 的 API 与这些应用程序进行交互。

2. AE CEP 插件核心功能和原理

1. 基于 Web 技术的界面开发：CEP 插件的界面使用 HTML、CSS 和 JavaScript 构建，开发者可以像开发网页一样设计 UI，且与原生界面无缝融合。

2. ExtendScript 与应用交互：通过 Adobe ExtendScript（类似 JavaScript）与 After Effects 进行深层次的交互，允许插件操作项目中的图层、合成、效果等元素。

3. Manifest 文件配置：每个 CEP 插件都有一个 manifest.xml 文件，用于声明扩展的元数据、扩展权限、跨域请求支持、支持的 Adobe 应用版本等信息。

4. CSInterface.js 库：CEP 提供的 CSInterface.js 是 JavaScript 文件，负责插件与 Adobe 应用程序之间的通信。它允许通过 JavaScript 来调用 ExtendScript 代码或与 After Effects 进行交互。

3. 最简目录结构

HelloWorld/│
├── CSXS/                   // 必须的文件夹，用于存放 manifest.xml│   └── manifest.xml        // Manifest 文件，声明扩展的元数据、兼容性及入口文件│
├── Extension.jsx           // ExtendScript 文件，处理 After Effects 的操作逻辑，如创建图层、合成等│
├── CSInterface.js          // CEP 提供的接口库，用于在 JavaScript 和 ExtendScript 之间进行通信│
├── index.html              // 插件的主 HTML 文件，定义扩展的界面结构和内容│
├── main.js                 // 主 JavaScript 文件，处理界面的交互逻辑，监听用户操作并调用 ExtendScript│
└── style.css               // 样式文件，用于定义插件界面的样式，如按钮和文本的布局

4. manifest.xml 解析

这是扩展插件的配置文件，必须存在，它指定了扩展的 ID、版本、Adobe 支持的应用以及扩展入口（如 index.html）。

示例：

<?xml version="1.0" encoding="UTF-8"?><ExtensionManifest Version="7.0" ExtensionBundleId="com.yourname.helloworld" ExtensionBundleVersion="1.0.0" ExtensionBundleName="HelloWorld">
  <!-- 定义扩展列表 -->
  <ExtensionList>
    <Extension Id="com.yourname.helloworld.panel" Version="1.0.0" />
  </ExtensionList>

  <!-- 定义执行环境 -->
  <ExecutionEnvironment>
    <HostList>
      <!-- 支持 After Effects，版本范围为 0.0 到 99.9 -->
      <Host Name="AEFT" Version="[0.0,99.9]" />
    </HostList>
    <LocaleList>
      <Locale Code="All" />  <!-- 支持所有语言区域 -->
    </LocaleList>
    <RequiredRuntimeList>
      <RequiredRuntime Name="CSXS" Version="10.0" />  <!-- CSXS 10.0 版本 -->
    </RequiredRuntimeList>
  </ExecutionEnvironment>

  <!-- 定义扩展的调度信息 -->
  <DispatchInfoList>
    <Extension Id="com.yourname.helloworld.panel">
      <DispatchInfo>
        <Resources>
          <MainPath>./index.html</MainPath>  <!-- 指定扩展的主 HTML 文件 -->
        </Resources>
        <Lifecycle>
          <AutoVisible>true</AutoVisible>  <!-- 扩展自动可见 -->
        </Lifecycle>
        <UI>
          <Type>Panel</Type>  <!-- 定义扩展类型为面板 -->
          <Menu>HelloWorld</Menu>  <!-- 在 AE 的菜单中显示为 HelloWorld -->
          <Geometry>
            <Size>
              <Width>300</Width>  <!-- 面板宽度 300px -->
              <Height>200</Height> <!-- 面板高度 200px -->
            </Size>
          </Geometry>
        </UI>
      </DispatchInfo>
    </Extension>
  </DispatchInfoList>  

  <!-- 启用 CEF 的 Node.js 支持 -->
  <CEF>
      <EnableNodeJS>true</EnableNodeJS>  <!-- 启用 Node.js，增强功能拓展 -->
  </CEF></ExtensionManifest>

4.1 ExtensionBundleId 和插件文件夹名称保持一致

• 推荐一致：虽然 ExtensionBundleId 不强制要求和文件夹名称完全一致，但保持一致可以提高插件的可维护性和可读性。

• 建议命名规则：通常采用反向域名命名法，例如：com.yourcompany.pluginname。这种方式有助于避免与其他插件的 ID 冲突。

示例：

• 插件文件夹名称为：HelloWorld

• ExtensionBundleId 应为：com.yourcompany.helloworld

<ExtensionManifest Version="7.0" ExtensionBundleId="com.yourcompany.helloworld" ExtensionBundleVersion="1.0.0" ExtensionBundleName="HelloWorld">

4.2 Extension Id 唯一性

• 每个插件的 Extension Id 必须是唯一的，且与 manifest.xml 的 ExtensionBundleId 保持一致性。这样可以确保不会和其他扩展产生冲突。

示例：

<ExtensionList>
  <Extension Id="com.yourcompany.helloworld.panel" Version="1.0.0" /></ExtensionList>

4.3 Version 格式正确

• ExtensionBundleVersion 和 Extension Id 的 Version 必须使用标准的版本号格式，例如：1.0.0 或 2.1.5。

示例：

<ExtensionBundleVersion="1.0.0">

4.4 HostList 中指定兼容的 Adobe 应用

• HostList 中指定插件所支持的 Adobe 应用。After Effects 的缩写是 AEFT，其他应用如 Premiere Pro 是 PPRO。

• Version="[0.0,99.9]" 定义了插件支持的应用版本范围。建议保留较大的版本范围，以支持更多版本的 Adobe 软件。

示例：

<HostList>
  <Host Name="AEFT" Version="[0.0,99.9]" />  <!-- After Effects -->
  <Host Name="PPRO" Version="[13.0,99.9]" />  <!-- Premiere Pro --></HostList>

4.5 MainPath 路径正确

• MainPath 指向插件的入口 HTML 文件，路径必须是相对于 manifest.xml 的相对路径。如果路径错误，插件界面无法正常加载。

示例：

<MainPath>./index.html</MainPath>  <!-- 相对于 manifest.xml -->

4.6 ScriptPath 和 CEFCommandLine 可选

• 在简单的扩展中，ScriptPath 和 CEFCommandLine 可以省略。ScriptPath 主要用于加载额外的 JavaScript 文件，CEFCommandLine 用于指定 Chromium Embedded Framework 的命令行参数（如跨域访问）。

• 只有当需要文件访问、跨域请求时，才需要 --allow-file-access-from-files 参数。

示例：

<Resources>
  <MainPath>./index.html</MainPath>
  <!-- 如果需要跨域访问，则启用下面的参数 -->
  <CEFCommandLine>
    <Parameter>--allow-file-access-from-files</Parameter>
  </CEFCommandLine></Resources>

4.7 UI 中的 Type 和 Menu

• Type 通常为 Panel，表示这是一个面板插件，也可以是 ModalDialog 或 Custom。

• Menu 是插件在 Adobe 应用菜单栏中显示的名称，建议使用简洁且易懂的名称。

示例：

<UI>
  <Type>Panel</Type>
  <Menu>HelloWorld</Menu>  <!-- Adobe 菜单中显示为 HelloWorld --></UI>

4.8 确保 Node.js 启用

• 如果插件需要使用 Node.js 功能，需要在 manifest.xml 中启用 Node.js。

示例：

<CEF>
  <EnableNodeJS>true</EnableNodeJS>  <!-- 启用 Node.js 支持 --></CEF>

4.9 文件权限和跨域访问

• 如果插件需要进行跨域请求，必须在 manifest.xml 中通过 CEFCommandLine 添加 --allow-file-access-from-files 参数。此外，确保插件的 HTML 和 JS 文件的路径和命名正确，以免插件无法访问所需文件。

示例：

<CEFCommandLine>
  <Parameter>--allow-file-access-from-files</Parameter></CEFCommandLine>

4.10 AutoVisible 和 Geometry 设置

• AutoVisible 设置为 true 可以让扩展在启动时自动显示。

• Geometry 设置定义了扩展面板的宽度和高度，需根据实际 UI 设计进行合理设置。

示例：

<AutoVisible>true</AutoVisible><Geometry>
  <Size>
    <Width>300</Width>
    <Height>200</Height>
  </Size></Geometry>

5. Extension.jsx 文件的作用

Extension.jsx 是 Adobe ExtendScript 文件，通常用于 Adobe CEP 插件中，用来与 Adobe 应用程序（如 After Effects、Premiere Pro 等）进行交互。ExtendScript 是 Adobe 基于 ECMAScript（类似于 JavaScript）开发的脚本语言，用于控制 Adobe 软件的各种操作，如创建合成、修改图层、添加效果等。

在一个 CEP 插件中，Extension.jsx 通常负责实现 Adobe 应用中的具体功能，通过 JavaScript 或 HTML 界面来调用这些 ExtendScript 函数。

5.1 ExtendScript 文件的作用

1. 与 After Effects 交互：Extension.jsx 中的代码可以直接与 After Effects 的 API 进行交互，例如创建合成、添加固态层、操作图层等。

2. 被 JavaScript 调用：通过 CSInterface.js，可以在 HTML 文件中的 JavaScript 脚本中调用 Extension.jsx 中的函数，从而实现界面和 Adobe 应用的联动。

5.2 示例代码

这个简单的 Extension.jsx 脚本创建了一个白色的固态层，函数可以从 JavaScript 中调用，并在 After Effects 中执行实际的操作。

// Extension.jsxfunction createSolidLayer() {
    var comp = app.project.activeItem;  // 获取当前活动的合成
    if (comp && comp instanceof CompItem) {
        comp.layers.addSolid([1, 1, 1], "White Solid", 1920, 1080, 1, 10);  // 添加一个白色固态层
    } else {
        alert("没有选中任何合成！");
    }}

5.3 兼容性

• ExtendScript 是 Adobe 特定的脚本语言，虽然类似 JavaScript，但并不是完全一致。要注意和标准 JavaScript 的一些语法差异。

• 不要使用在 JavaScript 中常见的浏览器对象（如 window 或 document），因为 ExtendScript 运行在 Adobe 应用的上下文中，而非浏览器环境。

5.4 与 JavaScript 的调用方式

• ExtendScript 文件通过 evalScript() 方法从 JavaScript 调用：

  var csInterface = new CSInterface();csInterface.evalScript('createSolidLayer()');  // 调用 ExtendScript 中的函数

  JavaScript

  复制

5.5 错误处理

• 在 ExtendScript 中，应考虑到可能的错误和异常情况，使用 try/catch 来捕获异常，以防止脚本崩溃。

  function createSolidLayer() {
      try {
          var comp = app.project.activeItem;
          if (comp && comp instanceof CompItem) {
              comp.layers.addSolid([1, 1, 1], "White Solid", 1920, 1080, 1, 10);
          } else {
              throw new Error("没有选中合成！");
          }
      } catch (e) {
          alert("出现错误：" + e.message);
      }}

  JavaScript

  复制

5.6 After Effects API

• ExtendScript 依赖 Adobe 提供的 API，因此开发时要参考 Adobe 官方的 After Effects Scripting Guide，了解不同操作的 API。

5.7 性能和优化

• 当处理复杂的项目（如创建大量图层、合成）时，尽量减少不必要的操作，因为复杂的 ExtendScript 操作可能会降低 After Effects 的性能。

6. CSInterface.js 介绍及使用指南

CSInterface.js 是 Adobe CEP 插件开发中用于实现 JavaScript 与 Adobe 应用（如 After Effects、Premiere Pro 等）通信的重要库。它提供了一组 API，帮助开发者在 HTML/CSS/JS 编写的前端界面和 Adobe 后台的 ExtendScript 之间进行交互。

6.1 CSInterface.js 作用

CSInterface.js 允许开发者：

1. 在 Adobe 应用程序和 HTML 扩展之间进行双向通信。

2. 调用 ExtendScript 函数，并获取执行结果。

3. 访问 Adobe 应用程序的一些本地信息，如版本、语言、操作系统等。

4. 响应应用程序中的事件。

6.2 加载 CSInterface.js

在 HTML 文件中引用 CSInterface.js，可以从 Adobe CEP 官方 GitHub 仓库中获取它：Adobe CEP GitHub 仓库

<script src="CSInterface.js"></script>

这会将 CSInterface 对象引入到页面中，从而可以使用它来调用相关的 API。

6.3 创建 CSInterface 实例

在 JavaScript 文件中创建一个 CSInterface 的实例，用于调用它的 API：

var csInterface = new CSInterface();

6.4 调用 ExtendScript

通过 evalScript() 方法，可以从 JavaScript 调用 ExtendScript 文件中的函数。

// 调用 ExtendScript 函数csInterface.evalScript('createSolidLayer()', function(result) {
    console.log("Result from ExtendScript:", result);});

在这个示例中，createSolidLayer() 是 ExtendScript 文件中的函数，执行完后会返回结果。

6.5 监听 Adobe 应用事件

你还可以使用 CSInterface 监听 Adobe 应用程序中的某些事件，如项目打开或关闭：

csInterface.addEventListener('documentAfterActivate', function(event) {
    console.log('A document was activated:', event);});

7. main.js 监听用户操作并调用 ExtendScript

在 Adobe CEP 插件中，main.js 文件的主要作用是处理用户界面中的交互操作（如按钮点击），并调用 ExtendScript 来执行实际的 Adobe 应用操作。通过使用 CSInterface.js 提供的 API，main.js 可以监听用户操作，并通过 evalScript() 方法调用 ExtendScript。

以下是一个简单的示例，演示如何在 main.js 文件中监听用户的按钮点击事件，并调用 ExtendScript 文件中的函数。

在 index.html 中创建按钮

在您的 index.html 文件中创建一个按钮，当用户点击它时将调用 main.js 进行处理：

<!DOCTYPE html><html lang="en"><head>
    <meta charset="UTF-8">
    <title>Hello World CEP Extension</title>
    <script src="CSInterface.js"></script>
    <script src="main.js"></script> <!-- 引入 main.js 文件 --></head><body>
    <button id="createSolidButton">Create Solid Layer</button></body></html>

编写 main.js

在 main.js 文件中，您可以使用以下代码来监听按钮的点击事件，并调用 ExtendScript。

// 创建 CSInterface 实例var csInterface = new CSInterface();// 等待页面加载完成后绑定事件监听器window.onload = function() {
    // 选择按钮
    var createSolidButton = document.getElementById("createSolidButton");
    
    // 监听按钮点击事件
    createSolidButton.addEventListener("click", function() {
        // 调用 ExtendScript 中的 createSolidLayer 函数
        csInterface.evalScript('createSolidLayer()', function(result) {
            console.log("ExtendScript 执行结果: ", result);
        });
    });};

编写 extendScript.jsx

在 extendScript.jsx 中编写 ExtendScript 函数，以在 After Effects 中创建一个固态层：

// ExtendScript: 创建白色固态层function createSolidLayer() {
    var comp = app.project.activeItem; // 获取当前活动的合成
    if (comp && comp instanceof CompItem) {
        // 添加一个白色固态层
        comp.layers.addSolid([1, 1, 1], "White Solid", 1920, 1080, 1, 10);
    } else {
        alert("没有选中合成！");
    }}

7.1 调用 evalScript()

evalScript() 是 CSInterface.js 中最重要的 API，用于在 JavaScript 和 ExtendScript 之间进行交互。在上面的例子中，evalScript() 调用了 ExtendScript 文件中的 createSolidLayer() 函数，并执行了 After Effects 中的相应操作。

7.2 工作流程

1. 用户点击按钮 Create Solid Layer。

2. main.js 监听到按钮的点击事件，并通过 evalScript() 调用 ExtendScript 文件中的 createSolidLayer() 函数。

3. createSolidLayer() 在 After Effects 中执行，并在当前合成中创建一个白色固态层。

8. index.html 和 main.css

负责扩展中所有可视的组件，比如按钮、输入框、文本及相应的样式。