XCEngine/docs/api/resources/filearchive/filearchive.md

# FileArchive

**命名空间**: `XCEngine::Resources`

**类型**: `class` (extends IArchive)

**描述**: 文件归档封装类，用于读取归档包（如 .pak、.zip）中的资源文件。

## 概述

`FileArchive` 实现了 `IArchive` 接口，提供从单个归档包文件中读取资源的功能。它维护已打开归档的路径和有效性状态。

## 头文件

```cpp
#include <XCEngine/Resources/FileArchive.h>
```

## 继承关系

```
IArchive
└── FileArchive
```

## 公共方法

### 构造与析构

| 方法 | 描述 |
|------|------|
| `FileArchive()` | 默认构造 |
| `~FileArchive()` | 析构函数，关闭归档 |

### IArchive 接口实现

| 方法 | 描述 |
|------|------|
| `bool Open(const Containers::String& path) override` | 打开归档文件 |
| `void Close() override` | 关闭归档文件 |
| `bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const override` | 从归档中读取文件数据 |
| `size_t GetSize(const Containers::String& fileName) const override` | 获取归档内文件大小 |
| `bool Exists(const Containers::String& fileName) const override` | 检查文件是否存在于归档中 |
| `void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const override` | 枚举归档内匹配的文件（当前为 stub） |
| `bool IsValid() const override` | 检查归档是否有效 |

## 实现说明

**注意**: `Enumerate()` 当前为 stub，仅清空输出数组。

### 访问器

| 方法 | 描述 |
|------|------|
| `const Containers::String& GetPath() const` | 获取归档文件路径 |

## 使用示例

```cpp
FileArchive archive;
if (archive.Open("data/resources.pak")) {
    // 检查文件是否存在
    if (archive.Exists("textures/player.png")) {
        // 获取文件大小
        size_t size = archive.GetSize("textures/player.png");
        
        // 读取文件内容
        Containers::Array<Core::uint8> buffer(size);
        archive.Read("textures/player.png", buffer.Data(), size, 0);
    }
    
    // 枚举文件
    Containers::Array<Containers::String> files;
    archive.Enumerate("textures/*.png", files);
    
    archive.Close();
}
```

## 相关文档

- [IArchive](../filesystem/filesystem.md) - 归档接口
- [ResourceFileSystem](../filesystem/filesystem.md) - 资源文件系统
- [Resources 总览](../resources.md) - 返回模块总览