CLAUDE.md

本文档为 Claude Code (claude.ai/code) 提供仓库开发指南。

项目速览

R2 Web — 纯客户端 Cloudflare R2 存储桶文件管理器，零构建、零框架、零后端。

核心特性 文件上传、目录浏览、文件预览、文件操作、图片压缩、PWA、多语言（zh/zh_TW/en/ja）、浅色/深色主题、多选批量操作。

快速启动

npx serve src
# 或
python3 -m http.server 5500 --directory src

代码地图

快速定位表

任务	文件
修改文件名模板逻辑	`src/js/utils.js` — `applyFilenameTemplate`
修改图片压缩逻辑	`src/js/upload-manager.js` — `compressFile`
添加 i18n 文案	`src/js/i18n.js` — `const I18N`
修改按钮样式	`src/css/components.css` — `.btn`
添加设计 Token	`src/css/tokens.css`
修改 R2 API 操作	`src/js/r2-client.js`
修改文件浏览逻辑	`src/js/file-explorer.js`
修改上传管理逻辑	`src/js/upload-manager.js`
多选批量操作逻辑	`src/js/file-explorer.js` — `toggleSelect` / `selectAll` / `clearSelection`

工具函数列表

以下函数定义在 src/js/utils.js，供各模块导入：

t(key, vars) — i18n 翻译（来自 src/js/i18n.js）
applyFilenameTemplate(tpl, file) — 文件名模板处理，占位符：[name]、[ext]、[hash:N]、[date:FORMAT]、[timestamp]、[uuid]、/
compressFile(file, config, onStatus) — 图片压缩（定义在 upload-manager.js）
- PNG 特殊处理：直接优化缓冲区，不重新编码
- 自适应逻辑：压缩后更大则使用原文件

项目结构

r2-web/
├── readme.md          — 项目说明、使用指南
├── package.json       — 依赖声明（仅用于类型提示）
├── jsconfig.json      — JSDoc 类型检查配置
└── src/               — 源码目录（即部署目录）
     ├── index.html    — 应用外壳、import map、对话框模板
     ├── main.js       — 入口（仅 new App()）
     ├── manifest.json — PWA 配置
     ├── style.css     — 样式主入口（仅导入 css 子目录）
     ├── js/           — 业务逻辑模块
     │    ├── app.js              — 主协调器
     │    ├── config-manager.js   — 配置持久化、Base64 分享
     │    ├── r2-client.js        — S3 API 客户端
     │    ├── ui-manager.js       — 主题、Toast、对话框、Tooltip
     │    ├── file-explorer.js    — 目录导航、排序、分页、缩略图
     │    ├── upload-manager.js   — 上传、文件名模板、图片压缩
     │    ├── file-preview.js     — 图片/视频/音频/文本预览
     │    ├── file-operations.js  — 重命名、复制、移动、删除
     │    ├── i18n.js             — 多语言（zh/zh_TW/en/ja）
     │    ├── constants.js        — 常量
     │    └── utils.js            — 工具函数
     └── css/          — 样式模块（CSS Layers）
          ├── reset.css       — CSS Reset
          ├── tokens.css      — 设计 Token（定义所有变量）
          ├── base.css        — 全局基础样式
          ├── layout.css      — 布局容器
          ├── components.css  — 通用 UI 组件
          ├── utilities.css   — 工具类
          └── animations.css  — 动画与过渡

架构速查

JavaScript 类架构

每个类独立为一个模块，位于 src/js/：

类	文件	职责
`ConfigManager`	`config-manager.js`	localStorage 持久化、Base64 配置分享
`R2Client`	`r2-client.js`	S3 API 客户端（基于 `aws4fetch` 签名）
`UIManager`	`ui-manager.js`	主题、Toast、对话框、上下文菜单、Tooltip
`FileExplorer`	`file-explorer.js`	目录导航、排序、分页、懒加载缩略图、列表缓存
`UploadManager`	`upload-manager.js`	拖拽/粘贴上传、文件名模板、图片压缩
`FilePreview`	`file-preview.js`	图片/视频/音频/文本预览
`FileOperations`	`file-operations.js`	重命名、复制、移动、删除（递归删除目录）
`App`	`app.js`	主协调器、i18n 处理

i18n 速查

多语言机制

I18N 对象 src/js/i18n.js（zh / zh_TW / en / ja 四语言）
翻译函数 t(key, vars) 支持变量替换
支持语言 zh（中文）、zh_TW（繁体）、en（英语）、ja（日语）
语言切换 App.updateLanguage() 自动更新所有文案

添加新文案

在 src/js/i18n.js 的 I18N 对象添加 zh / zh_TW / en / ja 键值
代码中使用 t('key') 或 t('key', { var: 'value' })
HTML 元素使用 data-tooltip-key="key" 支持动态更新

示例

// 1. 在 I18N 对象添加
const I18N = {
  zh: {
    deleteConfirm: '确定删除 {name} 吗？',
    deleteSuccess: '删除成功',
  },
  en: {
    deleteConfirm: 'Delete {name}?',
    deleteSuccess: 'Deleted successfully',
  },
  ja: {
    deleteConfirm: '{name} を削除しますか？',
    deleteSuccess: '削除しました',
  },
}

// 2. 代码中使用
const message = t('deleteConfirm', { name: fileName })
uiManager.toast(t('deleteSuccess'), 'success')

// 3. Tooltip 使用
button.dataset.tooltipKey = 'deleteConfirm'
button.dataset.tooltip = t('deleteConfirm')

6.2 KiB Raw Permalink Blame History Unescape Escape