common-components-skill

FileTerm 通用组件技能指南

概述

本指南详细介绍 FileTerm 项目中的通用组件架构、CSS 主题系统，以及独立窗口在亮暗主题下的落地方式。

---

一、通用组件架构

1.1 组件目录结构

renderer/
├── components/           # 核心通用组件
│   └── TerminalView.tsx  # 终端视图组件
└── features/
    └── common/           # 通用功能组件
        ├── AppIcon.tsx           # 图标组件
        ├── ContextMenu.tsx       # 右键菜单组件
        └── horizontal-scroll.ts  # 水平滚动工具函数

1.2 核心组件说明

TerminalView（终端组件）

文件路径：apps/desktop/src/renderer/components/TerminalView.tsx

功能特性：

• 基于 @xterm/xterm 构建的终端视图
• 支持主题颜色定制（通过 CSS 变量）
• 快捷键支持：复制(⌘C/Ctrl+Shift+C)、粘贴(⌘V/Ctrl+Shift+V)、查找(⌘F/Ctrl+F)
• 右键上下文菜单集成
• 自动适配容器尺寸
• 国际化文本支持

关键依赖：

import { Terminal } from '@xterm/xterm'
import { FitAddon } from '@xterm/addon-fit'
import { ContextMenu } from '../features/common/ContextMenu'

AppIcon（图标组件）

文件路径：apps/desktop/src/renderer/features/common/AppIcon.tsx

支持的图标类型：

图标名	用途
grid	网格视图
menu	菜单按钮
server	服务器连接
connections	连接管理
folder	文件夹
file	文件
history	历史记录
refresh	刷新
upload	上传
download	下载
flash	快速操作

使用方式：

<AppIcon name="folder" size={16} />

特性：

• 统一 SVG 图标系统
• 可自定义尺寸（默认 14px）
• 颜色继承父元素 currentColor

ContextMenu（右键菜单组件）

文件路径：apps/desktop/src/renderer/features/common/ContextMenu.tsx

功能特性：

• 点击外部区域自动关闭
• Esc 键关闭
• 位置自动调整（避免超出视口）
• 支持禁用状态和危险操作样式

接口定义：

type ContextMenuEntry = {
  label?: string
  shortcut?: string
  disabled?: boolean
  danger?: boolean
  action?(): void
  separator?: boolean
}

使用方式：

<ContextMenu
  items={[
    { label: '复制', shortcut: '⌘C', action: handleCopy },
    { separator: true },
    { label: '删除', danger: true, action: handleDelete }
  ]}
  onClose={closeMenu}
  position={{ x: 100, y: 100 }}
/>

handleHorizontalWheelScroll（水平滚动工具）