XCEngine/docs/api/resources/resource-loader/resource-loader.md

# IResourceLoader

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

**类型**: `class` (抽象基类)

**描述**: 资源加载器抽象接口，定义了资源加载的标准协议。每个资源类型需要提供对应的加载器实现。

## 概述

`IResourceLoader` 是资源加载系统的核心抽象接口。它定义了同步和异步加载资源的方法，以及资源类型的查询。`ResourceManager` 通过注册加载器来支持不同类型资源的加载。

## LoadResult 结构体

加载操作的返回值结构体。

```cpp
struct LoadResult {
    IResource* resource = nullptr;
    bool success = false;
    Containers::String errorMessage;
    LoadResult() = default;
    explicit LoadResult(IResource* res) : resource(res), success(res != nullptr) {}
    explicit LoadResult(const Containers::String& error) : success(false), errorMessage(error) {}
    explicit LoadResult(bool inSuccess, const Containers::String& error = "")
        : success(inSuccess), errorMessage(error) {}
    operator bool() const { return success && resource != nullptr; }
};
```

## 公共方法

### 资源信息

| 方法 | 描述 |
|------|------|
| [`GetResourceType`](getresourcetype.md) | 获取此加载器支持的资源类型 |
| [`GetSupportedExtensions`](getsupportedextensions.md) | 获取支持的文件扩展名列表 |
| [`CanLoad`](canload.md) | 检查此加载器是否能加载指定路径 |
| [`GetDefaultSettings`](getdefaultsettings.md) | 获取默认导入设置 |

### 同步加载

| 方法 | 描述 |
|------|------|
| [`Load`](load.md) | 同步加载资源 |

### 异步加载

| 方法 | 描述 |
|------|------|
| [`LoadAsync`](loadasync.md) | 异步加载资源（带默认实现，子类可重写） |

### 辅助方法（受保护）

| 方法 | 描述 |
|------|------|
| `static Containers::Array<Core::uint8> ReadFileData(const Containers::String& path)` | 读取文件数据 |
| `static Containers::String GetExtension(const Containers::String& path)` | 获取文件扩展名 |

## 实现说明

**注意**: 各资源加载器的 `GetDefaultSettings()` 当前返回 `nullptr`，未返回实际的默认设置对象。

## 宏

### REGISTER_RESOURCE_LOADER

自动注册加载器到 ResourceManager 的宏。

```cpp
REGISTER_RESOURCE_LOADER(TextureLoader)
```

## 使用示例

```cpp
class TextureLoader : public IResourceLoader {
public:
    ResourceType GetResourceType() const override {
        return ResourceType::Texture;
    }
    
    Containers::Array<Containers::String> GetSupportedExtensions() const override {
        return {".png", ".jpg", ".jpeg", ".bmp", ".tga"};
    }
    
    bool CanLoad(const Containers::String& path) const override {
        Containers::String ext = GetExtension(path);
        return ext == ".png" || ext == ".jpg" || ext == ".bmp";
    }
    
    ImportSettings* GetDefaultSettings() const override {
        return new TextureImportSettings();
    }
    
    LoadResult Load(const Containers::String& path,
                    const ImportSettings* settings = nullptr) override {
        LoadResult result;
        auto data = ReadFileData(path);
        if (data.Empty()) {
            return LoadResult("Failed to read file: " + path);
        }
        result.resource = new Texture();
        result.success = true;
        return result;
    }
};

// 注册加载器
ResourceManager::Get().RegisterLoader(new TextureLoader());
```

## 相关文档

- [ResourceManager](../resource-manager/resource-manager.md) - 资源管理器
- [AsyncLoader](../asyncloader/asyncloader.md) - 异步加载器
- [ImportSettings](../importsettings/importsettings.md) - 导入设置
- [Resources 总览](../resources.md) - 返回模块总览