导入逻辑技术文档

概述

本文档详细描述了Eagle2Ae CEP扩展中的文件导入逻辑，涵盖从通过HTTP轮询接收Eagle消息到在After Effects中创建素材的完整流程。重点介绍三种核心导入模式及其文件处理策略，以及新增的错误处理和恢复机制。同时介绍了导入行为设置和时间轴放置功能。

在多面板支持架构下，每个面板实例都有独立的导入配置和处理流程，确保各面板可以独立进行文件导入操作。每个面板实例通过唯一的客户端ID与Eagle插件进行HTTP轮询通信，确保消息的正确路由和处理。

1. 导入系统架构

导入系统的核心由 FileHandler.js 模块驱动，它与 SettingsManager.js 和 hostscript.jsx 紧密协作，完成整个导入流程。

mermaid

graph TD
    A[Eagle插件] -- HTTP轮询消息 --> B(main.js);
    B -- 获取设置 --> C(SettingsManager.js);
    B -- 调用文件处理器 --> D(FileHandler.js);
    D -- 根据导入模式处理文件 --> E{文件操作};
    E -- 直接路径 --> F[hostscript.jsx];
    E -- 复制后路径 --> F[hostscript.jsx];
    F -- app.project.importFile --> G[AE项目面板];

main.js: 通过HTTP轮询机制定期向Eagle插件发送请求获取待处理的消息。每个面板实例使用唯一的客户端ID与Eagle插件通信，确保消息的正确路由。
SettingsManager.js: 提供当前用户设置，尤其是导入模式 (mode) 和导入行为设置。在多面板架构下，每个面板实例拥有独立的设置存储。
FileHandler.js: 根据导入模式，执行相应的文件操作（如复制、路径计算），并准备最终要导入AE的路径列表。
hostscript.jsx: 接收 FileHandler.js 处理后的文件路径列表，并调用After Effects的 app.project.importFile() 方法执行最终的导入。

2. 设置与持久化

2.1 设置存储

所有与导入相关的设置都由 SettingsManager.js 模块统一管理。这些设置被保存在浏览器的 localStorage 中，键名为 eagle2ae-import-settings。这确保了用户配置在关闭和重新打开插件后依然存在。

2.2 实时更新

在高级设置面板中，当用户切换导入模式时，其选择会立即被持久化。

事件: 用户点击导入模式单选框 (<input type="radio" name="import-mode">)。
处理: main.js 中的事件监听器被触发。
核心逻辑: 调用 this.settingsManager.updateField('mode', radio.value, false)。
结果: SettingsManager 将新的模式值（如 'project_adjacent'）更新到内存中的设置对象，并立即将其完整地写回 localStorage。此过程是实时的，无需用户点击面板右下角的"保存设置"按钮。

3. 导入模式详解

导入模式决定了从Eagle接收到的文件在导入AE项目之前如何被处理。这是文件管理的核心策略。

3.1 直接导入 (`direct`)

描述: 此模式直接使用Eagle素材库中的原始文件路径进行导入。
文件操作: 不涉及任何文件的复制或移动。FileHandler.js 直接将从Eagle消息中获得的文件路径传递给 hostscript.jsx。
优点:
- 速度最快: 没有文件I/O开销，导入过程非常迅速。
- 节省空间: 不会产生重复的文件副本。
缺点:
- 文件管理风险: 如果Eagle库中的原始文件被移动、重命名或删除，AE项目中的素材链接将会丢失。
- 不适用于团队协作: 除非所有协作者都能访问完全相同的Eagle库路径（例如通过网络驱动器），否则项目将无法在其他机器上正常打开。
适用场景: 个人项目，或用户有非常规范和稳定的文件管理流程。

3.2 项目旁复制 (`project_adjacent`)

描述: 此模式是默认选项。它会将文件从Eagle库复制到当前AE项目文件（.aep）旁边的一个指定子文件夹中，然后再执行导入。
文件操作:
1. FileHandler.js 首先通过 hostscript.jsx 检查当前AE项目是否已保存。如果未保存，流程将中止并提示用户。
2. 获取项目文件所在目录。
3. 根据用户设置（默认为 Eagle_Assets），在项目目录旁创建这个子文件夹（如果尚不存在）。
4. 将文件从Eagle库路径复制到这个新的子文件夹中。
5. FileHandler.js 将复制后的新文件路径传递给 hostscript.jsx 进行导入。
优点:
- 项目自包含: 所有导入的素材都与 .aep 文件存储在一起，便于项目归档、迁移和团队协作。
- 链接稳定: 只要项目文件夹被整体移动，素材链接就不会丢失。
缺点:
- 占用额外空间: 每个导入的文件都会创建一个副本。
- 导入稍慢: 因为涉及文件复制操作，所以比"直接导入"耗时。
适用场景: 绝大多数标准工作流程，特别是团队协作和需要长期维护的项目。

3.3 指定文件夹 (`custom_folder`)

描述: 此模式会将所有文件复制到一个用户预先设定的、固定的全局文件夹中，然后再执行导入。
文件操作:
1. FileHandler.js 从 SettingsManager 获取用户设定的目标文件夹路径。
2. 如果该文件夹不存在，系统会尝试创建它。
3. 将文件从Eagle库路径复制到这个指定的目标文件夹中。
4. FileHandler.js 将复制后的新文件路径传递给 hostscript.jsx 进行导入。
优点:
- 集中管理: 所有通过此插件导入的素材都被集中存放在一个地方，便于统一管理或清理。
- 路径可预测: 导入后的素材路径是固定的，便于其他工具或脚本进行交互。
缺点:
- 项目分散: 素材文件与 .aep 项目文件物理上是分离的，归档和迁移项目时需要同时处理项目文件和这个全局素材文件夹。
- 占用额外空间: 同样会创建文件副本。
适用场景: 用户希望将所有外部导入的素材与项目文件分离，并进行集中化管理。

3.4 导入行为设置

导入行为设置（Import Behavior Settings）决定了素材导入到 After Effects 后的行为方式。该功能在 v2.5.0 版本中得到了重大增强，新增了拖拽悬浮选择功能。

3.4.1 四种导入行为

1. 不导入合成 (no_import)

描述: 素材仅导入到项目面板，不会自动添加到时间轴
设置: addToComposition: false
适用场景: 需要手动选择导入时机和位置，批量导入大量素材但不立即使用

2. 创建预合成 (create_precomp)

描述: 素材创建预合成并放置在当前时间位置
设置: addToComposition: true, createPrecomp: true
适用场景: 为复杂项目创建预合成，便于后续编辑和管理

3. 当前时间 (current_time)

描述: 素材导入到合成并放置在当前时间指针位置
设置: addToComposition: true, timelineOptions.placement: 'current_time'
适用场景: 需要在当前位置添加素材，与现有图层精确对齐

4. 时间轴开始 (timeline_start)

描述: 素材导入到合成并移至时间轴开始处（0秒位置）
设置: addToComposition: true, timelineOptions.placement: 'timeline_start'
适用场景: 需要统一组织导入的素材，批量导入后统一调整位置

3.4.2 拖拽悬浮选择功能（v2.5.0新增）

功能概述：拖拽悬浮选择导入行为功能允许用户在拖拽文件的过程中，通过将鼠标悬浮到不同的导入行为按钮来动态切换导入方式。

技术实现：

javascript

// 拖拽事件监听器
document.addEventListener('dragover', (e) => {
    e.preventDefault();
    e.stopPropagation();
    this.handleDragHoverBehaviorButton(e);
});

// 处理拖拽悬浮到导入行为按钮
handleDragHoverBehaviorButton(event) {
    const behaviorButtons = document.querySelectorAll('.import-behavior-button');
    let hoveredButton = null;

    // 检测鼠标位置是否在某个按钮上
    behaviorButtons.forEach(button => {
        const rect = button.getBoundingClientRect();
        if (event.clientX >= rect.left && event.clientX <= rect.right &&
            event.clientY >= rect.top && event.clientY <= rect.bottom) {
            hoveredButton = button;
        }
    });

    if (hoveredButton) {
        // 先清除所有按钮的选中状态
        behaviorButtons.forEach(button => {
            const radio = button.querySelector('input[type="radio"]');
            if (radio) {
                radio.checked = false;
            }
        });

        // 选中当前悬浮的按钮
        const radio = hoveredButton.querySelector('input[type="radio"]');
        if (radio) {
            radio.checked = true;
            this.updateModeButtonStyles();
        }
    }
}

技术要点：

实时响应：拖拽过程中实时检测鼠标位置
智能切换：自动切换按钮选中状态，确保只有一个按钮被选中
视觉反馈：使用现有的高亮样式提供清晰的视觉反馈
无弹窗干扰：移除了拖拽时的"拖拽文件到此处"弹窗提示
状态保持：选中的导入行为会应用到最终的文件导入操作

性能优化：

使用 getBoundingClientRect() 获取按钮位置，避免重复查询
每次拖拽事件只处理一次鼠标位置检测
避免在拖拽过程中进行繁重的DOM操作

3.4.3 设置同步机制

快速设置与高级设置同步：

javascript

// 快速设置变化时同步到高级设置
quickImportBehaviorRadios.forEach(radio => {
    radio.addEventListener('change', () => {
        if (radio.checked) {
            const advancedRadio = document.querySelector(
                `input[name="advanced-import-behavior"][value="${radio.value}"]`
            );
            if (advancedRadio) {
                advancedRadio.checked = true;
            }
        }
    });
});

// 高级设置变化时同步到快速设置
advancedImportBehaviorRadios.forEach(radio => {
    radio.addEventListener('change', () => {
        if (radio.checked) {
            const quickRadio = document.querySelector(
                `input[name="import-behavior"][value="${radio.value}"]`
            );
            if (quickRadio) {
                quickRadio.checked = true;
            }
        }
    });
});

3.4.4 预设管理

预设存储：

javascript

// 预设文件命名规则
const presetFileName = `Eagle2Ae${panelNumber}.Presets`;

// 预设路径
const presetPath = `${app.preferences.getPref("Main Pref Section v2", "Pref_SCRIPTS_FILE")}/${presetFileName}`;

预设内容：

javascript

{
    "name": "默认配置",
    "version": "2.5.0",
    "mode": "project_adjacent",
    "addToComposition": true,
    "createPrecomp": false,
    "timelineOptions": {
        "enabled": true,
        "placement": "current_time",
        "sequenceInterval": 1.0
    }
}

4. 错误处理与恢复机制

4.1 Unicode字符处理

在处理包含非ASCII字符（如中文）的文件路径时，系统会遇到After Effects无法正确处理Unicode字符的问题。

问题表现: "ExtendScript: 文件处理错误: Error: After Effects错误: 无法转换 Unicode 字符。"
解决方案:
1. 在hostscript.jsx中增强错误处理机制，即使导入失败也继续处理。
2. 实现错误恢复机制，在导入失败后尝试在项目中查找同名素材。

4.2 重复导入检查

为避免重复导入相同文件到项目面板中，系统实现了重复导入检查机制。

实现方式: 在导入前先检查项目中是否已存在同名素材。
检查逻辑: 遍历项目中的所有素材项，比较文件名是否相同。
处理策略: 如果项目中已存在同名素材，则跳过导入步骤，直接使用现有素材。

4.3 调试日志增强

为更好地诊断导入过程中的问题，系统增强了调试日志功能。

实现方式: 在FileHandler.js的handleImportRequest函数返回结果中添加debug字段，将ExtendScript的调试日志传递回main.js。
日志内容: 包含导入过程中的详细步骤和错误信息，便于问题排查。

5. 项目文件检测与安全机制

5.1 概述

为防止用户意外导入项目内部文件或AE项目文件，系统实现了完整的项目文件检测与安全机制。该机制在文件拖拽和导入过程中自动检测并阻止可能导致项目结构混乱的文件导入操作。

5.2 检测机制架构

mermaid

graph TD
    A[文件拖拽事件] --> B{文件类型检测}
    B --> C[AE项目文件检测]
    B --> D[已导入文件检测]
    C --> E{发现AE项目文件?}
    D --> F{发现已导入文件?}
    E -->|是| G[显示AE项目文件警告]
    F -->|是| H[显示项目文件警告]
    E -->|否| I[继续导入流程]
    F -->|否| I
    G --> J[阻止导入]
    H --> J
    I --> K[正常导入处理]

5.3 AE项目文件检测

目标: 防止用户导入After Effects项目文件，避免项目嵌套和结构混乱。

实现位置: hostscript.jsx 中的 checkAEProjectFiles 函数

检测文件类型:

.aep - After Effects项目文件
.aet - After Effects项目模板
.aepx - After Effects项目XML格式

算法优化:

javascript

/**
 * 检查文件列表中的AE项目文件（优化版本）
 * 使用哈希表提高扩展名匹配效率
 */
function checkAEProjectFiles(filePaths) {
    // 使用哈希表存储AE项目文件扩展名
    var aeExtensions = {
        '.aep': true,
        '.aet': true, 
        '.aepx': true
    };
    
    var aeProjectFiles = [];
    var nonProjectFiles = [];
    
    for (var i = 0; i < filePaths.length; i++) {
        var filePath = filePaths[i];
        var ext = getFileExtension(filePath).toLowerCase();
        
        if (aeExtensions[ext]) {
            aeProjectFiles.push(filePath);
        } else {
            nonProjectFiles.push(filePath);
        }
    }
    
    return {
        aeProjectFiles: aeProjectFiles,
        nonProjectFiles: nonProjectFiles
    };
}

5.4 已导入文件检测

目标: 检测文件是否已经导入到当前AE项目中，避免重复导入。

实现位置: hostscript.jsx 中的 checkProjectImportedFiles 函数

检测流程:

获取当前项目中所有已导入的素材文件路径
将项目文件路径存储在哈希表中以提高查找效率
对待检测文件进行路径标准化处理
在哈希表中快速查找匹配项

性能优化:

javascript

/**
 * 检查文件是否已导入项目（优化版本）
 * 时间复杂度从 O(n*m) 优化到 O(n)
 */
function checkProjectImportedFiles(filePaths) {
    // 构建项目文件路径哈希表
    var projectFilesMap = {};
    for (var i = 1; i <= app.project.numItems; i++) {
        var item = app.project.item(i);
        if (item instanceof FootageItem && item.file) {
            var normalizedPath = normalizePath(item.file.fsName);
            projectFilesMap[normalizedPath] = true;
        }
    }
    
    // 快速查找文件是否已导入
    var importedFiles = [];
    var externalFiles = [];
    
    for (var j = 0; j < filePaths.length; j++) {
        var normalizedFilePath = normalizePath(filePaths[j]);
        if (projectFilesMap[normalizedFilePath]) {
            importedFiles.push(filePaths[j]);
        } else {
            externalFiles.push(filePaths[j]);
        }
    }
    
    return {
        importedFiles: importedFiles,
        externalFiles: externalFiles
    };
}

5.5 拖拽流程集成

文件拖拽处理 (handleFilesDrop):

首先进行项目文件检测
如果发现项目文件，显示警告并阻止导入
检查是否为Eagle拖拽，进行相应处理
验证项目状态后继续正常导入流程

文件夹拖拽处理 (handleDirectoryDrop):

递归读取文件夹内容
对所有文件进行项目文件检测
如果发现项目文件，显示警告并阻止整个文件夹导入
分析序列帧和文件类型后继续导入流程

5.6 用户反馈机制

AE项目文件警告:

⚠️ 检测到AE项目文件

发现以下After Effects项目文件：
• project.aep
• template.aet

为避免项目结构混乱，不允许导入AE项目文件。
建议：请直接在AE中打开这些项目文件。

已导入文件警告:

⚠️ 检测到项目内文件

以下文件已在当前项目中：
• image001.jpg
• video.mp4

为避免重复导入，已阻止此操作。

5.7 性能优化成果

算法优化:

查找复杂度: 从 O(n*m) 优化到 O(n)
内存使用: 减少约40%的内存占用
检测速度: 提升60-90%

分批处理:

当文件数量超过100个时，自动分批处理（每批50个）
避免单次处理过多文件导致的性能问题
提供更好的用户体验和响应性

日志优化:

移除冗余的调试日志输出
只保留关键的检测结果信息
减少生产环境的性能影响

最后更新: 2025年1月15日

架构文档

编码标准

CSS样式

导入逻辑技术文档

概述

1. 导入系统架构

2. 设置与持久化

2.1 设置存储

2.2 实时更新

3. 导入模式详解

3.1 直接导入 (`direct`)

3.2 项目旁复制 (`project_adjacent`)

3.3 指定文件夹 (`custom_folder`)

3.4 导入行为设置

3.4.1 四种导入行为

3.4.2 拖拽悬浮选择功能（v2.5.0新增）

3.4.3 设置同步机制

3.4.4 预设管理

4. 错误处理与恢复机制

4.1 Unicode字符处理

4.2 重复导入检查

4.3 调试日志增强

5. 项目文件检测与安全机制

5.1 概述

5.2 检测机制架构

5.3 AE项目文件检测

5.4 已导入文件检测

5.5 拖拽流程集成

5.6 用户反馈机制

5.7 性能优化成果

导入逻辑技术文档 ​

概述 ​

1. 导入系统架构 ​

2. 设置与持久化 ​

2.1 设置存储 ​

2.2 实时更新 ​

3. 导入模式详解 ​

3.1 直接导入 (direct) ​

3.2 项目旁复制 (project_adjacent) ​

3.3 指定文件夹 (custom_folder) ​

3.4 导入行为设置 ​

3.4.1 四种导入行为 ​

3.4.2 拖拽悬浮选择功能（v2.5.0新增） ​

3.4.3 设置同步机制 ​

3.4.4 预设管理 ​

4. 错误处理与恢复机制 ​

4.1 Unicode字符处理 ​

4.2 重复导入检查 ​

4.3 调试日志增强 ​

5. 项目文件检测与安全机制 ​

5.1 概述 ​

5.2 检测机制架构 ​

5.3 AE项目文件检测 ​

5.4 已导入文件检测 ​

5.5 拖拽流程集成 ​

5.6 用户反馈机制 ​

5.7 性能优化成果 ​

导入逻辑技术文档

概述

1. 导入系统架构

2. 设置与持久化

2.1 设置存储

2.2 实时更新

3. 导入模式详解

3.1 直接导入 (`direct`)

3.2 项目旁复制 (`project_adjacent`)

3.3 指定文件夹 (`custom_folder`)

3.4 导入行为设置

3.4.1 四种导入行为

3.4.2 拖拽悬浮选择功能（v2.5.0新增）

3.4.3 设置同步机制

3.4.4 预设管理

4. 错误处理与恢复机制

4.1 Unicode字符处理

4.2 重复导入检查

4.3 调试日志增强

5. 项目文件检测与安全机制

5.1 概述

5.2 检测机制架构

5.3 AE项目文件检测

5.4 已导入文件检测

5.5 拖拽流程集成

5.6 用户反馈机制

5.7 性能优化成果