XCEngine/docs/api/XCEngine/Components/MeshRendererComponent/GetMaterialHandle.md

# MeshRendererComponent::GetMaterialHandle

获取指定槽位的材质句柄。

```cpp
const Resources::ResourceHandle<Resources::Material>& GetMaterialHandle(size_t index) const;
```

## 参数

- `index` - 材质槽索引。

## 返回值

- 若索引有效则返回对应句柄引用。
- 否则返回一个静态空句柄引用。

## 行为说明

和 [GetMaterial](GetMaterial.md) 一样，当前实现会在返回前先执行：

1. `EnsureDeferredAsyncMaterialLoadStarted(index)`
2. `ResolvePendingMaterials()`

因此它也可能在首次访问时启动一次异步加载，而不是单纯返回缓存引用。

## 注意事项

- 越界时返回的是共享的静态空句柄，而不是临时对象。
- 即使索引有效，返回的句柄也可能仍为空，因为异步结果尚未完成或加载失败。
- 如果调用方只想读取路径 / `AssetRef` 元数据，应优先使用 [GetMaterialPath](GetMaterialPath.md) 或 [GetMaterialAssetRefs](GetMaterialAssetRefs.md)。

## 相关文档

- [返回类型总览](MeshRendererComponent.md)
- [GetMaterial](GetMaterial.md)
- [GetMaterialAssetRefs](GetMaterialAssetRefs.md)