687 lines
17 KiB
Markdown
687 lines
17 KiB
Markdown
# 模块08：新建文件夹功能
|
||
|
||
---
|
||
|
||
## 🎨 UI设计系统概览
|
||
|
||
> **完整设计系统文档请参考：** `UI设计系统.md`
|
||
|
||
### 核心设计原则
|
||
- **现代简约**：界面清晰，层次分明
|
||
- **专业高效**：减少操作步骤，提升工作效率
|
||
- **一致性**：统一的视觉语言和交互模式
|
||
- **可访问性**：符合WCAG 2.1 AA标准
|
||
|
||
### 关键设计令牌
|
||
|
||
**颜色系统：**
|
||
- 主色：`#0d6efd`（操作按钮、选中状态）
|
||
- 成功：`#198754`（连接成功状态）
|
||
- 危险：`#dc3545`（删除操作、错误提示）
|
||
- 深灰：`#212529`（导航栏背景）
|
||
- 浅灰：`#e9ecef`（工具栏背景）
|
||
|
||
**字体系统：**
|
||
- 字体族：系统字体栈（-apple-system, Segoe UI, Roboto等）
|
||
- 正文：14px，行高1.5
|
||
- 标题：20-32px，行高1.2-1.4
|
||
- 小号文字：12px（文件大小、日期等）
|
||
|
||
**间距系统：**
|
||
- 基础单位：8px
|
||
- 标准间距：16px（1rem）
|
||
- 组件内边距：8px-16px
|
||
|
||
**组件规范：**
|
||
- 导航栏：高度48px，深色背景
|
||
- 工具栏：浅灰背景，按钮间距8px
|
||
- 文件项：最小高度44px，悬停效果150ms
|
||
- 按钮：圆角4px，过渡150ms
|
||
|
||
**交互规范：**
|
||
- 悬停效果：150ms过渡
|
||
- 触摸目标：最小44x44px
|
||
- 键盘导航：Tab、Enter、Delete、F2、F5、Esc
|
||
- 焦点状态：2px蓝色轮廓
|
||
|
||
**响应式断点：**
|
||
- 移动端：< 768px（双面板垂直排列）
|
||
- 平板：768px - 1024px
|
||
- 桌面：> 1024px（标准布局）
|
||
|
||
---
|
||
|
||
## 8.1 功能概述
|
||
实现在本地文件系统和SFTP服务器上创建新文件夹的功能。
|
||
|
||
## 8.2 后端设计
|
||
|
||
### 8.2.1 LocalFileService创建目录方法
|
||
|
||
```java
|
||
// 创建目录
|
||
public boolean createDirectory(String path) throws Exception {
|
||
File directory = new File(path);
|
||
|
||
if (directory.exists()) {
|
||
throw new Exception("目录已存在: " + path);
|
||
}
|
||
|
||
// 验证目录名
|
||
String dirName = directory.getName();
|
||
if (!isValidDirectoryName(dirName)) {
|
||
throw new Exception("目录名包含非法字符: " + dirName);
|
||
}
|
||
|
||
// 检查父目录是否存在
|
||
File parentDir = directory.getParentFile();
|
||
if (parentDir != null && !parentDir.exists()) {
|
||
// 父目录不存在，询问是否创建多级目录
|
||
throw new Exception("父目录不存在: " + parentDir.getPath());
|
||
}
|
||
|
||
boolean result = directory.mkdirs();
|
||
if (!result) {
|
||
throw new Exception("创建目录失败");
|
||
}
|
||
|
||
return true;
|
||
}
|
||
|
||
// 创建多级目录
|
||
public boolean createDirectories(String path) throws Exception {
|
||
File directory = new File(path);
|
||
|
||
if (directory.exists()) {
|
||
throw new Exception("目录已存在: " + path);
|
||
}
|
||
|
||
// 验证路径中的每个目录名
|
||
String[] parts = path.split("[/\\\\]");
|
||
for (String part : parts) {
|
||
if (!isValidDirectoryName(part)) {
|
||
throw new Exception("路径包含非法字符: " + part);
|
||
}
|
||
}
|
||
|
||
boolean result = directory.mkdirs();
|
||
if (!result) {
|
||
throw new Exception("创建目录失败");
|
||
}
|
||
|
||
return true;
|
||
}
|
||
|
||
// 验证目录名是否有效
|
||
private boolean isValidDirectoryName(String dirName) {
|
||
if (dirName == null || dirName.isEmpty()) {
|
||
return false;
|
||
}
|
||
|
||
// Windows非法字符
|
||
String illegalChars = "\\/:*?\"<>|";
|
||
for (char c : illegalChars.toCharArray()) {
|
||
if (dirName.indexOf(c) != -1) {
|
||
return false;
|
||
}
|
||
}
|
||
|
||
// 检查长度限制
|
||
if (dirName.length() > 255) {
|
||
return false;
|
||
}
|
||
|
||
// 检查保留名称（Windows）
|
||
String upperName = dirName.toUpperCase();
|
||
String[] reservedNames = {"CON", "PRN", "AUX", "NUL"};
|
||
for (String reserved : reservedNames) {
|
||
if (upperName.equals(reserved)) {
|
||
return false;
|
||
}
|
||
}
|
||
|
||
return true;
|
||
}
|
||
```
|
||
|
||
### 8.2.2 SftpService创建目录方法
|
||
|
||
```java
|
||
// 创建目录
|
||
public boolean createDirectory(String sessionId, String path) throws Exception {
|
||
ChannelSftp channel = sessionManager.getSession(sessionId);
|
||
if (channel == null) {
|
||
throw new Exception("会话不存在或已断开");
|
||
}
|
||
|
||
try {
|
||
// 检查目录是否已存在
|
||
try {
|
||
channel.stat(path);
|
||
throw new Exception("目录已存在: " + path);
|
||
} catch (SftpException e) {
|
||
if (e.id != ChannelSftp.SSH_FX_NO_SUCH_FILE) {
|
||
throw e;
|
||
}
|
||
}
|
||
|
||
// 创建目录
|
||
channel.mkdir(path);
|
||
return true;
|
||
} catch (SftpException e) {
|
||
throw new Exception("创建目录失败: " + e.getMessage(), e);
|
||
}
|
||
}
|
||
|
||
// 创建多级目录
|
||
public boolean createDirectories(String sessionId, String path) throws Exception {
|
||
ChannelSftp channel = sessionManager.getSession(sessionId);
|
||
if (channel == null) {
|
||
throw new Exception("会话不存在或已断开");
|
||
}
|
||
|
||
try {
|
||
// 检查目录是否已存在
|
||
try {
|
||
channel.stat(path);
|
||
throw new Exception("目录已存在: " + path);
|
||
} catch (SftpException e) {
|
||
if (e.id != ChannelSftp.SSH_FX_NO_SUCH_FILE) {
|
||
throw e;
|
||
}
|
||
}
|
||
|
||
// 递归创建多级目录
|
||
createDirectoriesRecursive(channel, path);
|
||
return true;
|
||
} catch (SftpException e) {
|
||
throw new Exception("创建目录失败: " + e.getMessage(), e);
|
||
}
|
||
}
|
||
|
||
// 递归创建多级目录
|
||
private void createDirectoriesRecursive(ChannelSftp channel, String path) throws SftpException {
|
||
// 如果是根目录，直接返回
|
||
if (path.equals("/") || path.isEmpty()) {
|
||
return;
|
||
}
|
||
|
||
// 检查父目录是否存在
|
||
String parentPath = getParentPath(path);
|
||
if (!parentPath.equals(path)) {
|
||
try {
|
||
channel.stat(parentPath);
|
||
} catch (SftpException e) {
|
||
if (e.id == ChannelSftp.SSH_FX_NO_SUCH_FILE) {
|
||
// 父目录不存在，递归创建
|
||
createDirectoriesRecursive(channel, parentPath);
|
||
} else {
|
||
throw e;
|
||
}
|
||
}
|
||
}
|
||
|
||
// 创建当前目录
|
||
channel.mkdir(path);
|
||
}
|
||
|
||
// 获取父路径
|
||
private String getParentPath(String path) {
|
||
if (path.endsWith("/")) {
|
||
path = path.substring(0, path.length() - 1);
|
||
}
|
||
int index = path.lastIndexOf("/");
|
||
if (index == -1) {
|
||
return "/";
|
||
}
|
||
if (index == 0) {
|
||
return "/";
|
||
}
|
||
return path.substring(0, index);
|
||
}
|
||
```
|
||
|
||
### 8.2.3 FileController创建目录接口
|
||
|
||
```java
|
||
// 创建目录
|
||
@PostMapping("/mkdir")
|
||
public ApiResponse<Void> createDirectory(@RequestBody Map<String, String> request) {
|
||
try {
|
||
String sessionId = request.get("sessionId");
|
||
String path = request.get("path");
|
||
|
||
if (path == null || path.isEmpty()) {
|
||
return ApiResponse.error("路径不能为空");
|
||
}
|
||
|
||
boolean result;
|
||
if ("local".equals(sessionId)) {
|
||
result = localFileService.createDirectory(path);
|
||
} else {
|
||
result = sftpService.createDirectory(sessionId, path);
|
||
}
|
||
|
||
if (result) {
|
||
return ApiResponse.success("创建成功", null);
|
||
} else {
|
||
return ApiResponse.error("创建失败");
|
||
}
|
||
} catch (Exception e) {
|
||
return ApiResponse.error("创建失败: " + e.getMessage());
|
||
}
|
||
}
|
||
|
||
// 创建多级目录
|
||
@PostMapping("/mkdir-p")
|
||
public ApiResponse<Void> createDirectories(@RequestBody Map<String, String> request) {
|
||
try {
|
||
String sessionId = request.get("sessionId");
|
||
String path = request.get("path");
|
||
|
||
if (path == null || path.isEmpty()) {
|
||
return ApiResponse.error("路径不能为空");
|
||
}
|
||
|
||
boolean result;
|
||
if ("local".equals(sessionId)) {
|
||
result = localFileService.createDirectories(path);
|
||
} else {
|
||
result = sftpService.createDirectories(sessionId, path);
|
||
}
|
||
|
||
if (result) {
|
||
return ApiResponse.success("创建成功", null);
|
||
} else {
|
||
return ApiResponse.error("创建失败");
|
||
}
|
||
} catch (Exception e) {
|
||
return ApiResponse.error("创建失败: " + e.getMessage());
|
||
}
|
||
}
|
||
```
|
||
|
||
## 8.3 前端设计
|
||
|
||
### 8.3.1 新建文件夹交互
|
||
|
||
```javascript
|
||
// 显示新建文件夹对话框
|
||
function showMkdirDialog(panelId) {
|
||
const sessionId = panelState[panelId].sessionId;
|
||
const currentPath = panelState[panelId].currentPath;
|
||
|
||
const folderName = prompt('请输入文件夹名称:', '新建文件夹');
|
||
if (folderName && folderName.trim() !== '') {
|
||
createDirectory(sessionId, currentPath, folderName);
|
||
}
|
||
}
|
||
|
||
// 创建目录
|
||
function createDirectory(sessionId, parentPath, folderName) {
|
||
// 验证文件夹名称
|
||
if (!validateDirectoryName(folderName)) {
|
||
return;
|
||
}
|
||
|
||
// 构建完整路径
|
||
let fullPath;
|
||
if ("local".equals(sessionId)) {
|
||
fullPath = parentPath + File.separator + folderName;
|
||
} else {
|
||
fullPath = parentPath.endsWith('/') ?
|
||
parentPath + folderName :
|
||
parentPath + '/' + folderName;
|
||
}
|
||
|
||
$.ajax({
|
||
url: '/api/files/mkdir',
|
||
method: 'POST',
|
||
contentType: 'application/json',
|
||
data: JSON.stringify({
|
||
sessionId: sessionId,
|
||
path: fullPath
|
||
}),
|
||
success: function(response) {
|
||
if (response.success) {
|
||
alert('文件夹创建成功');
|
||
refreshCurrentPanel();
|
||
} else {
|
||
alert('创建失败: ' + response.message);
|
||
}
|
||
},
|
||
error: handleError
|
||
});
|
||
}
|
||
|
||
// 验证目录名
|
||
function validateDirectoryName(dirName) {
|
||
if (!dirName || dirName.trim() === '') {
|
||
alert('文件夹名称不能为空');
|
||
return false;
|
||
}
|
||
|
||
// Windows非法字符
|
||
const illegalChars = /\\\/:\*\?"<>\|/;
|
||
if (illegalChars.test(dirName)) {
|
||
alert('文件夹名称包含非法字符');
|
||
return false;
|
||
}
|
||
|
||
// 长度限制
|
||
if (dirName.length > 255) {
|
||
alert('文件夹名称过长（最大255字符）');
|
||
return false;
|
||
}
|
||
|
||
return true;
|
||
}
|
||
|
||
// 刷新当前面板
|
||
function refreshCurrentPanel() {
|
||
const activePanelId = getActivePanelId();
|
||
loadFiles(activePanelId);
|
||
}
|
||
```
|
||
|
||
### 8.3.2 新建文件夹按钮
|
||
|
||
```html
|
||
<div class="toolbar">
|
||
<button onclick="showMkdirDialog('left')">新建文件夹</button>
|
||
</div>
|
||
```
|
||
|
||
### 8.3.3 右键菜单新建文件夹
|
||
|
||
```javascript
|
||
// 在右键菜单中添加新建文件夹选项
|
||
function showContextMenu(event, panelId) {
|
||
event.preventDefault();
|
||
|
||
const menu = $('<div class="context-menu">');
|
||
menu.css({
|
||
position: 'absolute',
|
||
left: event.pageX + 'px',
|
||
top: event.pageY + 'px'
|
||
});
|
||
|
||
menu.append('<div class="menu-item" onclick="showMkdirDialog(\'' +
|
||
panelId + '\')">新建文件夹</div>');
|
||
|
||
$('body').append(menu);
|
||
|
||
$(document).one('click', function() {
|
||
menu.remove();
|
||
});
|
||
}
|
||
```
|
||
|
||
### 8.3.4 快捷键支持
|
||
|
||
```javascript
|
||
// 监听键盘事件
|
||
$(document).on('keydown', function(e) {
|
||
// Ctrl+Shift+N: 新建文件夹
|
||
if (e.ctrlKey && e.shiftKey && e.key === 'N') {
|
||
const activePanelId = getActivePanelId();
|
||
showMkdirDialog(activePanelId);
|
||
e.preventDefault();
|
||
}
|
||
});
|
||
```
|
||
|
||
### 8.3.5 在线输入（高级功能）
|
||
|
||
```javascript
|
||
// 在文件列表中直接输入新文件夹名称
|
||
function showInlineMkdir(panelId) {
|
||
const fileList = $(`#${panelId}-file-list`);
|
||
|
||
// 创建新建文件夹项
|
||
const newItem = $(`
|
||
<div class="file-item new-folder">
|
||
<span class="file-icon">📁</span>
|
||
<span class="file-name">
|
||
<input type="text" class="new-folder-input" placeholder="输入文件夹名称">
|
||
</span>
|
||
</div>
|
||
`);
|
||
|
||
// 插入到列表顶部
|
||
fileList.prepend(newItem);
|
||
|
||
// 聚焦输入框
|
||
const input = newItem.find('.new-folder-input');
|
||
input.focus();
|
||
|
||
// 失去焦点时创建
|
||
input.on('blur', function() {
|
||
const folderName = input.val().trim();
|
||
if (folderName) {
|
||
createDirectory(panelState[panelId].sessionId,
|
||
panelState[panelId].currentPath,
|
||
folderName);
|
||
}
|
||
newItem.remove();
|
||
});
|
||
|
||
// 按Enter创建
|
||
input.on('keypress', function(e) {
|
||
if (e.which === 13) {
|
||
input.blur();
|
||
}
|
||
});
|
||
|
||
// 按Esc取消
|
||
input.on('keydown', function(e) {
|
||
if (e.which === 27) {
|
||
newItem.remove();
|
||
}
|
||
});
|
||
}
|
||
```
|
||
|
||
## 8.4 输入验证
|
||
|
||
### 8.4.1 前端验证
|
||
|
||
```javascript
|
||
// 验证目录名
|
||
function validateDirectoryName(dirName) {
|
||
// 基本验证
|
||
if (!dirName || dirName.trim() === '') {
|
||
alert('文件夹名称不能为空');
|
||
return false;
|
||
}
|
||
|
||
// 去除首尾空格
|
||
dirName = dirName.trim();
|
||
|
||
// Windows非法字符
|
||
const illegalChars = /\\\/:\*\?"<>\|/;
|
||
if (illegalChars.test(dirName)) {
|
||
alert('文件夹名称包含非法字符: \\ / : * ? " < > |');
|
||
return false;
|
||
}
|
||
|
||
// 不能以点开头或结尾（Linux/Mac隐藏目录）
|
||
if (dirName.startsWith('.') || dirName.endsWith('.')) {
|
||
alert('文件夹名称不能以点开头或结尾');
|
||
return false;
|
||
}
|
||
|
||
// 长度限制
|
||
if (dirName.length > 255) {
|
||
alert('文件夹名称过长（最大255字符）');
|
||
return false;
|
||
}
|
||
|
||
// Windows保留名称
|
||
const upperName = dirName.toUpperCase();
|
||
const reservedNames = ['CON', 'PRN', 'AUX', 'NUL',
|
||
'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
|
||
'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9'];
|
||
if (reservedNames.includes(upperName)) {
|
||
alert('文件夹名称是系统保留名称');
|
||
return false;
|
||
}
|
||
|
||
return true;
|
||
}
|
||
```
|
||
|
||
### 8.4.2 后端验证
|
||
|
||
```java
|
||
// 验证目录名（后端）
|
||
private boolean isValidDirectoryName(String dirName) {
|
||
if (dirName == null || dirName.isEmpty()) {
|
||
return false;
|
||
}
|
||
|
||
// 去除首尾空格
|
||
dirName = dirName.trim();
|
||
|
||
// Windows非法字符
|
||
String illegalChars = "\\/:*?\"<>|";
|
||
for (char c : illegalChars.toCharArray()) {
|
||
if (dirName.indexOf(c) != -1) {
|
||
return false;
|
||
}
|
||
}
|
||
|
||
// 不能以点开头或结尾
|
||
if (dirName.startsWith(".") || dirName.endsWith(".")) {
|
||
return false;
|
||
}
|
||
|
||
// 长度限制
|
||
if (dirName.length() > 255) {
|
||
return false;
|
||
}
|
||
|
||
// Windows保留名称
|
||
String upperName = dirName.toUpperCase();
|
||
String[] reservedNames = {"CON", "PRN", "AUX", "NUL",
|
||
"COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9",
|
||
"LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9"};
|
||
for (String reserved : reservedNames) {
|
||
if (upperName.equals(reserved)) {
|
||
return false;
|
||
}
|
||
}
|
||
|
||
return true;
|
||
}
|
||
```
|
||
|
||
### 8.4.3 路径处理
|
||
|
||
```javascript
|
||
// 拼接路径
|
||
function joinPath(parentPath, childName) {
|
||
// 移除子名称的首尾空格
|
||
childName = childName.trim();
|
||
|
||
// 判断是否为本地路径
|
||
const isLocal = parentPath.includes('\\') ||
|
||
parentPath.includes('C:') ||
|
||
parentPath.includes('D:');
|
||
|
||
if (isLocal) {
|
||
// Windows路径
|
||
if (parentPath.endsWith('\\') || parentPath.endsWith('/')) {
|
||
return parentPath + childName;
|
||
} else {
|
||
return parentPath + '\\' + childName;
|
||
}
|
||
} else {
|
||
// Linux/SFTP路径
|
||
if (parentPath.endsWith('/')) {
|
||
return parentPath + childName;
|
||
} else {
|
||
return parentPath + '/' + childName;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 实施步骤
|
||
|
||
1. **更新LocalFileService**：添加创建目录方法
|
||
|
||
2. **更新SftpService**：添加创建目录方法
|
||
|
||
3. **更新FileController**：添加创建目录接口
|
||
|
||
4. **添加前端创建目录功能**
|
||
|
||
5. **编译测试**
|
||
```
|
||
mvn clean compile
|
||
```
|
||
|
||
6. **启动服务**
|
||
```
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
## 测试验证
|
||
|
||
### 1. 创建单级目录
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/sftp-manager/api/files/mkdir \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"sessionId": "local",
|
||
"path": "C:/test/newfolder"
|
||
}'
|
||
```
|
||
|
||
### 2. 创建多级目录
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/sftp-manager/api/files/mkdir-p \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"sessionId": "local",
|
||
"path": "C:/test/level1/level2/level3"
|
||
}'
|
||
```
|
||
|
||
### 3. 在SFTP上创建目录
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/sftp-manager/api/files/mkdir \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"sessionId": "sftp-uuid",
|
||
"path": "/home/user/newfolder"
|
||
}'
|
||
```
|
||
|
||
### 4. 测试非法目录名
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/sftp-manager/api/files/mkdir \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"sessionId": "local",
|
||
"path": "C:/test/folder<name"
|
||
}'
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **目录名验证**：严格验证目录名，防止非法字符
|
||
2. **路径拼接**：正确处理不同操作系统的路径分隔符
|
||
3. **权限检查**：确保有权限在指定位置创建目录
|
||
4. **同名检查**：创建前检查目录是否已存在
|
||
5. **父目录存在性**：单级创建时检查父目录是否存在
|
||
|
||
## 下一步
|
||
|
||
完成模块08后，继续模块09：双面板UI界面设计
|