141 lines
3.6 KiB
Markdown
141 lines
3.6 KiB
Markdown
# PathHelper 使用指南
|
||
|
||
## 文件位置
|
||
|
||
`src/Utils/PathHelper.cs`
|
||
|
||
## 用途
|
||
|
||
提供文件路径相关的通用方法，包括插件目录管理、文件名处理、截图生成等。
|
||
|
||
## 核心方法
|
||
|
||
### 目录操作
|
||
|
||
```csharp
|
||
// 获取插件目录路径
|
||
string pluginDir = PathHelper.GetPluginDirectory();
|
||
// 返回: C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin
|
||
|
||
// 获取截图目录路径
|
||
string screenshotDir = PathHelper.GetScreenshotDirectory();
|
||
|
||
// 获取报告目录路径
|
||
string reportDir = PathHelper.GetReportDirectory();
|
||
|
||
// 确保目录存在（不存在则创建）
|
||
PathHelper.EnsureDirectoryExists("C:\\MyFolder\\SubFolder");
|
||
```
|
||
|
||
### 文件名处理
|
||
|
||
```csharp
|
||
// 清理文件名中的非法字符
|
||
string safeName = PathHelper.SanitizeFileName("文件<名称>:非法*字符?");
|
||
// 返回: "文件名称非法字符"
|
||
|
||
// 生成带时间戳的文件名
|
||
string fileName = PathHelper.GenerateTimestampedFileName("screenshot", "png");
|
||
// 返回: "screenshot_20240225_143052.png"
|
||
```
|
||
|
||
### 路径计算
|
||
|
||
```csharp
|
||
// 计算从HTML文件到目标文件的相对路径
|
||
string relativePath = PathHelper.GetRelativePath(
|
||
@"C:\reports\index.html",
|
||
@"C:\images\photo.png"
|
||
);
|
||
// 返回: "../images/photo.png"
|
||
```
|
||
|
||
### 图像格式转换
|
||
|
||
```csharp
|
||
// ImageFormat 转文件扩展名
|
||
string ext = PathHelper.ImageFormatToExtension(ImageFormat.Jpeg); // "jpg"
|
||
string ext = PathHelper.ImageFormatToExtension(ImageFormat.Png); // "png"
|
||
|
||
// 文件扩展名转 ImageFormat
|
||
ImageFormat format = PathHelper.ExtensionToImageFormat(".jpg"); // Jpeg
|
||
ImageFormat format = PathHelper.ExtensionToImageFormat(".png"); // Png
|
||
```
|
||
|
||
### 截图生成
|
||
|
||
```csharp
|
||
// 生成场景截图到默认目录
|
||
string path = PathHelper.GenerateSceneScreenshot(
|
||
sceneName: "collision_view",
|
||
width: 1920,
|
||
height: 1080,
|
||
format: ImageFormat.Png,
|
||
prefix: "collision"
|
||
);
|
||
// 返回: 截图文件完整路径
|
||
|
||
// 生成场景截图到指定目录
|
||
string path = PathHelper.GenerateSceneScreenshotToDirectory(
|
||
outputDirectory: @"C:\MyScreenshots",
|
||
sceneName: "path_view",
|
||
width: 1920,
|
||
height: 1080,
|
||
format: ImageFormat.Jpeg,
|
||
prefix: "path"
|
||
);
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 示例1：生成带时间戳的报告文件
|
||
|
||
```csharp
|
||
// 生成报告文件名
|
||
string reportDir = PathHelper.GetReportDirectory();
|
||
PathHelper.EnsureDirectoryExists(reportDir);
|
||
|
||
string safeRouteName = PathHelper.SanitizeFileName(route.Name);
|
||
string reportFile = PathHelper.GenerateTimestampedFileName(
|
||
$"collision_report_{safeRouteName}",
|
||
"html"
|
||
);
|
||
string fullPath = Path.Combine(reportDir, reportFile);
|
||
|
||
// 保存报告...
|
||
```
|
||
|
||
### 示例2：批量处理文件名
|
||
|
||
```csharp
|
||
// 清理多个文件名
|
||
var fileNames = new[] { "文件:1", "名称*2", "测试?3" };
|
||
var safeNames = fileNames.Select(f => PathHelper.SanitizeFileName(f));
|
||
// 结果: "文件1", "名称2", "测试3"
|
||
```
|
||
|
||
### 示例3：生成碰撞报告截图
|
||
|
||
```csharp
|
||
// 在显示碰撞结果后生成截图
|
||
string screenshotPath = PathHelper.GenerateSceneScreenshot(
|
||
sceneName: $"collision_{collisionId}",
|
||
width: 1920,
|
||
height: 1080,
|
||
format: ImageFormat.Png,
|
||
prefix: "collision"
|
||
);
|
||
|
||
if (!string.IsNullOrEmpty(screenshotPath))
|
||
{
|
||
LogManager.Info($"截图已保存: {screenshotPath}");
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **目录自动创建**：`GenerateSceneScreenshot` 会自动创建必要的目录
|
||
2. **非法字符处理**：`SanitizeFileName` 会移除所有 Windows 文件系统不支持的字符
|
||
3. **时间戳格式**：使用 `yyyyMMdd_HHmmss` 格式，确保文件名唯一且可排序
|
||
4. **相对路径**：`GetRelativePath` 返回的路径使用正斜杠（/），适合在 HTML 中使用
|