Eagle2Ae 文档中心

Appearance

Eagle 插件组件详细说明 ​

概述 ​

Eagle2Ae Eagle插件是一个后台服务插件，负责监控Eagle中的文件选择并与After Effects扩展进行通信。本文档详细说明插件的各个UI组件、功能按钮和面板的作用。

插件架构 ​

服务模式 ​

  • 后台服务模式: 插件启动时自动运行后台服务，无需用户干预
  • UI管理模式: 提供可视化管理界面，用户可以监控和控制服务状态
  • 混合模式: 同时支持后台服务和UI管理，提供最佳用户体验

主界面组件 ​

1. 标题栏区域 ​

主标题 ​

  • 组件: <h2>Eagle2Ae - 后台服务管理</h2>
  • 功能: 显示插件名称和当前模式
  • 样式: 蓝色下划线，突出显示

设置按钮 ​

  • 组件: #title-settings-button
  • 图标: ⚙ (齿轮图标)
  • 功能: 打开插件设置对话框
  • 交互: 点击触发 showSettings() 函数
  • 样式: 悬停时背景变色，提供视觉反馈

2. 服务状态面板 ​

状态容器 ​

  • 组件: .status-section
  • 布局: 深色背景，圆角边框
  • 内容: 包含三个状态项

AE连接端口 ​

  • 组件: #ae-port
  • 功能: 显示当前WebSocket服务器监听端口
  • 数据源:
    • 优先从 eagle2ae.config.wsPort 获取
    • 备选从本地存储设置获取
    • 默认显示 "8080"
  • 更新频率: 每秒更新一次

连接状态 ​

  • 组件: #connection-status
  • 状态类型:
    • connected: 绿色背景，显示"已连接"
    • disconnected: 红色背景，显示"未连接"
    • error: 红色背景，显示错误信息
  • 判断逻辑:
    javascript
    if (eagle2ae && eagle2ae.httpServer && eagle2ae.httpServer.listening) {
    // 显示已连接
} else if (eagle2ae && eagle2ae.aeStatus && eagle2ae.aeStatus.connected) {
    // 显示已连接
} else {
    // 显示未连接
}

运行时间 ​

  • 组件: #uptime
  • 功能: 显示插件运行时长
  • 格式: HH:MM:SS
  • 计算方式: Date.now() - startTime
  • 更新频率: 每秒更新

3. 文件选择面板 ​

文件计数器 ​

  • 组件: #files-count
  • 功能: 显示当前选中文件数量
  • 状态:
    • 有文件时: "已选择 X 个文件"
    • 无文件时: "未选择文件"

文件列表 ​

  • 组件: #files-list
  • 功能: 显示选中文件的详细信息
  • 交互: 点击列表触发 handleFileListClick() → handleManualExport()
  • 限制: 最多显示10个文件，超出部分显示省略信息

文件项组件 ​

  • 结构:
    html
    <div class="file-item">
    <span class="file-name">文件名</span>
    <span class="file-type">扩展名</span>
</div>
  • 样式: 深色背景，蓝色左边框，文件类型标签

空状态提示 ​

  • 组件: .no-files
  • 内容: "请在Eagle中选择要导出的文件"
  • 显示条件: 当没有选中文件时

4. 操作日志面板 ​

日志容器 ​

  • 组件: #log-output
  • 功能: 显示插件运行日志和操作记录
  • 样式: 黑色背景，等宽字体，滚动条
  • 高度: 动态计算，最小200px，最大400px

日志条目 ​

  • 结构:
    html
    <div class="log-entry log-{type}">
    <span class="log-time">[时间戳]</span>
    消息内容
    <span class="duplicate-count">(×重复次数)</span>
</div>
  • 日志类型:
    • log-info: 白色文字，一般信息
    • log-warning: 黄色文字，警告信息
    • log-error: 红色文字，错误信息

日志去重机制 ​

  • 功能: 5秒内相同消息自动合并
  • 显示: 重复消息显示计数 (×N)
  • 限制: 最多保留50条日志

自动滚动 ​

  • 功能: 新日志自动滚动到底部
  • 实现: logOutput.scrollTop = logOutput.scrollHeight

设置对话框组件 ​

1. 对话框容器 ​

  • 组件: #settings-overlay
  • 功能: 模态对话框遮罩层
  • 交互: 点击遮罩关闭对话框

2. 设置项 ​

操作通知开关 ​

  • 组件: #show-notifications
  • 类型: 复选框
  • 功能: 控制是否显示操作通知
  • 默认: 已选中

服务器端口设置 ​

  • 组件: #server-port
  • 类型: 数字输入框
  • 范围: 1024-65535
  • 默认: 8080
  • 功能: 设置WebSocket服务器监听端口

剪切板检查间隔 ​

  • 组件: #clipboard-interval
  • 类型: 数字输入框
  • 范围: 500-10000毫秒
  • 默认: 1000毫秒
  • 功能: 设置剪切板监控频率

3. 操作按钮 ​

保存设置按钮 ​

  • 组件: #save-settings
  • 功能: 保存设置到本地存储
  • 交互: 调用 saveSettings() 函数
  • 效果: 更新插件配置，重启相关服务

取消按钮 ​

  • 组件: #cancel-settings
  • 功能: 关闭设置对话框，不保存更改
  • 交互: 调用 hideSettings() 函数

核心功能组件 ​

1. UI更新管理器 ​

定时更新 ​

  • 函数: startUIUpdates()
  • 频率: 每秒更新一次
  • 功能: 协调所有UI组件的数据更新

更新流程 ​

javascript
async function updateUI() {
    await updateSelectedFiles();    // 更新文件列表
    updateServiceStatus();          // 更新服务状态
    updateUptime();                 // 更新运行时间
}

2. 文件选择监控 ​

Eagle API集成 ​

  • API: eagle.item.getSelected()
  • 功能: 获取Eagle中当前选中的文件
  • 错误处理: 检测Eagle API可用性

文件信息提取 ​

  • 属性:
    • item.name: 文件名
    • item.ext: 文件扩展名
    • item.path: 文件路径
  • 显示优化: 长文件名自动截断

3. 手动导出功能 ​

触发方式 ​

  • 点击文件列表: 直接触发导出
  • 函数: handleManualExport()

导出流程 ​

javascript
1. 检查Eagle API可用性
2. 获取选中文件列表
3. 验证文件数量
4. 调用eagle2ae.handleSelectedFiles()
5. 记录操作日志

4. 设置管理 ​

本地存储 ​

  • 键名: eagle2ae-settings
  • 格式: JSON字符串
  • 内容: 所有用户设置项

设置同步 ​

  • 加载: 页面初始化时从本地存储读取
  • 保存: 用户点击保存时写入本地存储
  • 应用: 实时更新插件配置

状态管理 ​

1. 全局状态 ​

  • 变量: eagle2ae (全局实例)
  • 作用: 连接UI和后台服务
  • 检查: typeof eagle2ae !== 'undefined'

2. UI状态 ​

  • 启动时间: startTime = Date.now()
  • 更新定时器: uiUpdateInterval
  • 日志缓存: lastLogMessage, duplicateCount

3. 服务状态 ​

  • HTTP服务器: eagle2ae.httpServer.listening
  • AE连接: eagle2ae.aeStatus.connected
  • 配置信息: eagle2ae.config

错误处理 ​

1. API错误 ​

  • Eagle API不可用: 显示警告日志
  • 文件获取失败: 记录错误信息
  • 导出失败: 显示用户友好的错误提示

2. UI错误 ​

  • 设置加载失败: 使用默认值
  • 设置保存失败: 显示错误日志
  • DOM操作失败: 静默处理，记录调试信息

3. 网络错误 ​

  • 服务器连接失败: 更新连接状态
  • 端口占用: 尝试其他端口
  • 通信超时: 自动重试机制

性能优化 ​

1. 更新频率控制 ​

  • UI更新: 1秒间隔，避免过度刷新
  • 文件检查: 仅在有变化时更新DOM
  • 日志去重: 减少重复日志的DOM操作

2. 内存管理 ​

  • 日志限制: 最多保留50条
  • 定时器清理: 页面卸载时清理定时器
  • 事件监听: 避免重复绑定事件

3. 用户体验 ​

  • 即时反馈: 按钮悬停效果
  • 状态指示: 清晰的连接状态显示
  • 操作确认: 设置保存后的确认提示

扩展性设计 ​

1. 组件化结构 ​

  • 独立功能: 每个面板功能相对独立
  • 事件驱动: 基于事件的组件通信
  • 配置化: 通过设置控制组件行为

2. API兼容性 ​

  • Eagle API: 检测API可用性，优雅降级
  • 浏览器环境: 支持在浏览器中预览
  • 版本兼容: 向后兼容旧版本设置

3. 主题支持 ​

  • CSS变量: 使用CSS变量定义颜色
  • 深色主题: 默认深色主题适配Eagle
  • 自定义样式: 支持用户自定义样式

相关文档 ​

Released under the MIT License.

Copyright © 2025 Eagle2Ae