【一】 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 插件核心功能和原理
- 基于 Web 技术的界面开发:CEP 插件的界面使用 HTML、CSS 和 JavaScript 构建,开发者可以像开发网页一样设计 UI,且与原生界面无缝融合。
- ExtendScript 与应用交互:通过 Adobe ExtendScript(类似 JavaScript)与 After Effects 进行深层次的交互,允许插件操作项目中的图层、合成、效果等元素。
- Manifest 文件配置:每个 CEP 插件都有一个 manifest.xml 文件,用于声明扩展的元数据、扩展权限、跨域请求支持、支持的 Adobe 应用版本等信息。
- 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 文件的作用
- 与 After Effects 交互:
Extension.jsx
中的代码可以直接与 After Effects 的 API 进行交互,例如创建合成、添加固态层、操作图层等。 - 被 JavaScript 调用:通过
CSInterface.js
,可以在 HTML 文件中的 JavaScript 脚本中调用Extension.jsx
中的函数,从而实现界面和 Adobe 应用的联动。
5.2 示例代码
这个简单的 Extension.jsx
脚本创建了一个白色的固态层,函数可以从 JavaScript 中调用,并在 After Effects 中执行实际的操作。
// Extension.jsx
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("没有选中任何合成!");
}
}
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 中的函数
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); } }
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
允许开发者:
- 在 Adobe 应用程序和 HTML 扩展之间进行双向通信。
- 调用 ExtendScript 函数,并获取执行结果。
- 访问 Adobe 应用程序的一些本地信息,如版本、语言、操作系统等。
- 响应应用程序中的事件。
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 工作流程
- 用户点击按钮
Create Solid Layer
。 main.js
监听到按钮的点击事件,并通过evalScript()
调用 ExtendScript 文件中的createSolidLayer()
函数。createSolidLayer()
在 After Effects 中执行,并在当前合成中创建一个白色固态层。
8. index.html
和 main.css
负责扩展中所有可视的组件,比如按钮、输入框、文本及相应的样式。