# var-ai-cep

**Repository Path**: divib/var-ai-cep

## Basic Information

- **Project Name**: var-ai-cep
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-09-30
- **Last Updated**: 2024-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<img src="src/js/assets/bolt-cep.svg" alt="Bolt CEP" title="Bolt CEP" width="400" />

一个闪电般快速的样板，用于在 React 、Vue 或 Svelte 中构建基于 Vite + TypeScript + Sass 构建的 Adobe CEP 扩展

_完整的博客文章:_ https://hyperbrew.co/blog/bolt-cep-build-extensions-faster/

### 运行插件要求
- 你需要手动将[AIHostAdapter.aip](https://github.com/Adobe-CEP/CEP-Resources/tree/master/CEP_11.x/AIHostAdapter) C++ 插件添加到Illustrator安装目录`Adobe Illustrator 20XX/Plug-ins/Extensions/`，CEP 事件通信才能使用。

### 开发环境要求

- [Node.js](https://nodejs.org/en) 16 或更高版本
- [Yarn](https://yarnpkg.com/getting-started/install) 1.x.x aka classic (ensure by running `yarn set version classic`)


### 兼容性

- [Adobe CC Apps](https://www.adobe.com/creativecloud/desktop-app.html) 版本 2022 或更高版本
- Windows & Mac Intel
- Mac Arm64 (M1 / M2) require special setup ([more details](#misc-troubleshooting))


## 快速开始

`yarn create bolt-cep`

- Create Extension

`cd myApp`

- CD into Directory

`yarn`

- Installs all dependencies

`yarn build`

- Runs initial build
- Creates cep folder structure
- Creates symlink to extensions folder

`yarn dev`

- Runs in dev mode with HMR Hot-reloading.
- Both JS and ExtendScript folders re-build on changes
- Viewable in browser via localhost:3000/panel/
  - (e.g. http://localhost:3000/main/, http://localhost:3000/settings/, etc. (see [Panel Structure](#cep-panel-structure) to set up multiple panels)))

`yarn serve`

- Serve files after running `yarn build`
- Viewable in browser via localhost:5000/panel/
  - (e.g. http://localhost:5000/main/, http://localhost:5000/settings/, etc. (see [Panel Structure](#cep-panel-structure) to set up multiple panels)))

`yarn zxp`

- Builds and bundles your project into a zxp for publishing in the `dist/zxp` folder

`yarn zip`

- Bundles your zxp and specified assets to a zip archive in the `dist/zip` folder

---

## Config

Update your CEP build and package settings in `cep.config.ts` safely typed

Start building your app in `src/js/main/index(.tsx or .vue or .svelte)`

Write ExtendScript code in `src/jsx/main.ts`

---

## CEP 面板结构

每个面板都被视为自己的页面，使用共享代码以提高效率。样板目前带有 2 个面板，`main`和`settings`。这些在 `cep.config.ts` 中配置。

每个面板都可以在各自的文件夹中进行编辑：

```
src
 └─ js
    ├─ main
    │   ├─ index.html
    |   └─ index.tsx
    └─ settings
        ├─ index.html
        └─ index.tsx
```

要添加面板，请在 `cep.config.ts` 中向面板对象添加一个项目，然后复制文件夹结构并根据需要进行调整。

---

## ExtendScript

ExtendScript 可以用 ES6 编写，并且为了兼容性，可以编译成单个 ES3 文件。

默认情况下包含 JSON 2，并且使用 include 指令添加的任何外部 JS 库也将被捆绑：

```js
// @include './lib/library.js'
```

特定于应用程序的代码按应用程序名称拆分为模块，以便进行类型安全的开发，如 `index.ts` 所示。

```
aftereffects >> aeft/aeft.ts
illustrator >> ilst/ilst.ts
animate >> anim/anim.ts
```

在每个单独的模块中编写特定于应用程序的函数，每个应用程序都需要这些函数。

要添加对其他主机应用程序的支持，请执行以下操作：

- Add additional app module files (aeft.ts, anim.ts, etc).
- Extend the main `switch()` in `scr/jsx/index.ts` with your additional.
- Add the host to your `cep.config.ts` file.

---

## 从 CEP JavaScript 调用 ExtendScript

所有 ExtendScript 函数都在后台附加到面板的命名空间中，以避免在使用 `evalTS()` 和 `evalES()` 时出现命名空间冲突。

我们现在引入了一种新的和改进的端到端类型安全方式，可以使用 `evalTS()` 从 CEP 与 ExtendScript 交互。此函数从
ExtendScript 函数并处理结果的字符串化和分析，因此您的开发人员交互可以尽可能简单。

如 `main.tsx` 所示，可以通过传递函数名称后跟参数来使用 `evalTS()` 调用 ExtendScript 函数。

CEP

```js
evalTS("myFunc", "test").then((res) => {
  console.log(res);
});

evalTS("myFuncObj", { height: 90, width: 100 }).then((res) => {
  console.log(res.x);
  console.log(res.y);
});
```

ExtendScript

```js
export const myFunc = (str: string) => {
  return str;
};

export const myFuncObj = (obj: { height: number, width: number }) => {
  return {
    y: obj.height,
    x: obj.width,
  };
};
```

对于任何现有的 Bolt CEP 项目，请放心，遗留的 `evalES()` 函数将照常保留，如 `main.tsx` 中所示。

```js
evalES(`helloWorld("${csi.getApplicationID()}")`);
```

您还需要使用此函数直接调用全局范围内的 ExtendScript 函数，方法是将 `true` 传递给第二个参数：

```js
evalES(
  `alert("Hello from ExtendScript :: " + app.appName + " " + app.version)`,
  true
);
```

---

## 从 ExtendScript 调用 CEP JavaScript

对于某些情况，例如挂接到事件侦听器或在长函数期间发送更新，将事件从 ExtendScript 环境触发到 JavaScript 环境是有意义的。这可以通过 `listenTS()` 和 `dispatchTS()`来完成。

使用此方法可以考虑：

- 在 JS 端为 CSEvent 设置一个作用域监听器
- 在 ExtendScript 端设置 PlugPlug CSEvent 事件
- 确保事件的端到端类型安全

### 1. 在 shared/universals.ts 的 EventTS 中声明事件类型

```js
export type EventTS = {
  myCustomEvent: {
    oneValue: string,
    anotherValue: number,
  },
  // [... other events]
};
```

### 2. 在 CEP JavaScript 中监听

```js
import { listenTS } from "../lib/utils/bolt";

listenTS("myCustomEvent", (data) => {
  console.log("oneValue is", data.oneValue);
  console.log("anotherValue is", data.anotherValue);
});
```

### 3. Dispatch in ExtendScript

```js
import { dispatchTS } from "../utils/utils";

dispatchTS("myCustomEvent", { oneValue: "name", anotherValue: 20 });
```

或者，也可以从 CEP 端以相同的方式使用 `dispatchTS()` 来触发 CEP 面板内部或之间的事件，只需确保从 `js` 文件夹中的正确文件导入 dispatchTS() 函数即可。

```js
import { dispatchTS } from "../lib/utils/bolt";

dispatchTS("myCustomEvent", { oneValue: "name", anotherValue: 20 });
```

---

## GitHub Actions ZXP 版本

此存储库附带一个配置的 GitHub Action 工作流，用于构建 ZXP 并在每次添加 git 标签时添加到发行版中。

```
git tag 1.0.0
git push origin --tags
```

然后，您的新版本将在 GitHub Releases 下可用。


---

## 复制资源

如果您想复制资源而不受打包器的影响，则可以在cep.config.ts中添加可选的 `copyAssets:[]` 数组以包含文件或整个文件夹。

```js
  copyAssets: ["public", "custom/my.jsx"],
```

**示例:**

放置在 `src/public` 中的文件将被复制到 `dist/public`，并将配置设置为 `copyAssets: ["public"]`。

---

## ExtendScript 范围

此样板针对附加到所有面板的辅助对象 `$` 的单个 JSX 对象进行了调味，以防止全局命名空间中的污染。如果您希望包含自己的原始 JSX，请将其包含在 Copy Assets 对象（上图）中，并将可选的 scriptPath 对象添加到您的 cep.config.ts 文件中。

```js
  panels: [
    {
      name: "main",
      scriptPath: "custom/index.jsx",
      [...]
    },
    {
      name: "settings",
      scriptPath: "custom/settings.jsx",
      [...]
    },
  ],
  copyAssets: ["custom"],
```

---

## 故障排除模块

Node.js 内置模块可以从 `src/js/lib/node.ts` 文件导入。

```js
import { os, path, fs } from "../lib/node";
```

要使用第三方库，请首先尝试使用标准 import 语法。

```js
import { FaBolt } from "react-icons/fa";
```

如果 import 语法失败（通常使用Node.js运行时的模块），你可以使用Node.js `require()` 语法。

```js
const unzipper = require("unzipper");
```

构建系统将使用 `require()` 检测任何非内置 Node.js 模块并将它们复制到输出的 `node_modules` 文件夹，但如果缺少包，你可以将其显式添加到 `cep.config.ts` 文件中的 `installModules: []` 数组中。

```js
  installModules: ["unzipper"],
```

此外，如果它们是特定于 Node.js 的模块，最好将 requires 放在函数内部，以便它们仅在运行时需要，并且不会在浏览器中预览时破坏面板。

---

## 关于 路由 的说明

如果您想设置像 react-router 这样的路由系统，请注意您必须为 CEP 进行调整。例如，React Router 将路由器路径基于 `window.location.pathname` ，在浏览器中解析为页面：

`/main/index.html`

但在 CEP 上下文中解析为完整的系统路径：

`file:///C:/Users/Username/AppData/Roaming/Adobe/CEP/extensions/com.bolt.cep/main/index.html`

要解决这个问题，你需要调整每个上下文的路由器基本名称，这里有一种使用名为 `main` 的面板来实现这一点的方法：

```js
const posix = (str: string) => str.replace(/\\/g, "/");

const cepBasename = window.cep_node
  ? `${posix(window.cep_node.global.__dirname)}/`
  : "/main/";

ReactDOM.render(
  <React.StrictMode>
    <Router basename={cepBasename}>[...]</Router>
  </React.StrictMode>,
  document.getElementById("root")
);
```