Skip to main content

资源

🌐 Assets

PixiJS 拥有 Assets 单例，它用于简化资源加载。它是现代的、基于 Promise 的、支持缓存并且高度可扩展——使其成为所有 PixiJS 资源管理的一站式解决方案！

🌐 PixiJS has the Assets singleton which is used to streamline resource loading. It’s modern, Promise-based, cache-aware, and highly extensible—making it the one stop shop for all PixiJS resource management!

import { Assets } from 'pixi.js';

await Assets.init({ ... });

const texture = await Assets.load('path/to/hero.png');

主要功能​

🌐 Key Capabilities

  • 通过 Promises 或 async/await 异步加载资源。
  • 缓存可以防止重复的网络请求。
  • 内置支持常见的媒体格式（图片、视频、字体）。
  • 自定义解析器 和 解析器 以提高灵活性。
  • 后台加载、基于清单的包，以及智能回退。

支持的文件类型​

🌐 Supported File Types

类型扩展名加载器
纹理.png, .jpg, .gif, .webp, .avif, .svgloadTextures, loadSvg
视频纹理.mp4, .m4v, .webm, .ogg, .ogv, .h264, .avi, .movloadVideoTextures
精灵图集.jsonspritesheetAsset
位图字体.fnt, .xml, .txtloadBitmapFont
网络字体.ttf, .otf, .woff, .woff2loadWebFont
JSON.jsonloadJson
文本.txtloadTxt
压缩纹理.basis, .dds, .ktx, .ktx2loadBasis, loadDDS, loadKTX

需要更多？添加自定义解析器！

入门​

🌐 Getting started

加载资源​

🌐 Loading Assets

使用 PixiJS 加载资源就像调用 Assets.load() 并传入资源的 URL 一样简单。该函数返回一个 Promise，它会解析为已加载的资源——无论是纹理、字体、JSON 还是其他支持的格式。

🌐 Loading an asset with PixiJS is as simple as calling Assets.load() and passing in the asset’s URL. This function returns a Promise that resolves to the loaded resource—whether that’s a texture, font, JSON, or another supported format.

你可以提供绝对 URL（例如来自 CDN）：

🌐 You can provide either an absolute URL (e.g. from a CDN):

const texture = await Assets.load('https://example.com/assets/hero.png');

或者在你的项目中的相对路径：

🌐 Or a relative path within your project:

const texture = await Assets.load('assets/hero.png');

PixiJS 通常 会根据其 文件扩展名 自动决定如何加载资源，并缓存结果以避免重复下载。

🌐 PixiJS will typically automatically determine how to load the asset based on its file extension and will cache the result to avoid redundant downloads.

import { Application, Assets, Texture } from 'pixi.js';

const app = new Application();
// Application must be initialized before loading assets
await app.init({ backgroundColor: 0x1099bb });

// Load a single asset
const bunnyTexture = await Assets.load<Texture>('path/to/bunny.png');
const sprite = new Sprite(bunnyTexture);

// Load multiple assets at once
const textures = await Assets.load<Texture>(['path/to/bunny.png', 'path/to/cat.png']);
const bunnySprite = new Sprite(textures['path/to/bunny.png']);
const catSprite = new Sprite(textures['path/to/cat.png']);

重复加载是安全的​

🌐 Repeated Loads Are Safe

Assets 按 URL 或别名缓存。对相同资源的请求会返回相同的纹理。

const p1 = await Assets.load('bunny.png');
const p2 = await Assets.load('bunny.png');
console.log(p1 === p2); // true

资源别名​

🌐 Asset Aliases

你也可以使用别名来引用资源，而不是使用它们的完整 URL。这提供了一种更方便的管理资源的方式，尤其是在你拥有长或复杂的 URL 时。

🌐 You can also use aliases to refer to assets instead of their full URLs. This provides a more convenient way to manage assets, especially when you have long or complex URLs.

await Assets.load<Texture>({ alias: 'bunny', src: 'path/to/bunny.png' });
const bunnyTexture = Assets.get('bunny');

所有资源 API 都支持别名，包括 Assets.load()、Assets.get() 和 Assets.unload()。

🌐 All Asset APIs support aliases, including Assets.load(), Assets.get(), and Assets.unload().

有更复杂的定义资源的方法，你可以在 Resolver 部分阅读相关内容。

🌐 There is more complex ways of defining assets and you can read about them in the Resolver section.

检索已加载的资源​

🌐 Retrieving Loaded Assets

你也可以使用 Assets.get() 检索已经加载的资源：

🌐 You can also retrieve assets that have already been loaded using Assets.get():

await Assets.load<Texture>('path/to/bunny.png');
const bunnyTexture = Assets.get('path/to/bunny.png');
const sprite = new Sprite(bunnyTexture);

当你在代码的其他位置预加载了资源，并希望稍后访问它们而不必从初始加载传递引用时，这很有用。

🌐 This is useful for when you have preloaded your assets elsewhere in your code and want to access them later without having to pass round references from the initial load.

卸载资源​

🌐 Unloading Assets

要卸载一个资源，你可以使用 Assets.unload()。这将从缓存中移除该资源并释放内存。请注意，如果在卸载后尝试访问该资源，你需要重新加载它。

🌐 To unload an asset, you can use Assets.unload(). This will remove the asset from the cache and free up memory. Note that if you try to access the asset after unloading it, you will need to load it again.

await Assets.load<Texture>('path/to/bunny.png');
const bunnyTexture = Assets.get('path/to/bunny.png');
const sprite = new Sprite(bunnyTexture);
// Unload the asset
await Assets.unload('path/to/bunny.png');

自定义资源加载​

🌐 Customizing Asset Loading

你可以通过向 Assets.init() 方法提供选项来自定义资源加载过程。这允许你设置资源加载的偏好，指定资源的基础路径等。

🌐 You can customize the asset loading process by providing options to the Assets.init() method. This allows you to set preferences for how assets are loaded, specify a base path for assets, and more.

import { Assets } from 'pixi.js';

await Assets.init({...});
选项类型描述
basePathstring应用于所有相对资源路径的前缀（例如用于 CDN）。
defaultSearchParamsstring追加到所有加载资源的默认 URL 参数字符串
skipDetectionsboolean跳过资源的环境检测解析器。
manifestManifest命名资源包及其内容的描述符。
preferencesAssetPreferences指定每个加载器的偏好设置
bundleIdentifierBundleIdentifierOptions高级 - 覆盖 bundlesIds 的生成方式。

高级用法​

🌐 Advanced Usage

Assets API 提供了多种高级功能，可以帮助你更有效地管理资源。 你可以在文档的其余部分中阅读有关这些功能的更多信息：

🌐 There are several advanced features available in the Assets API that can help you manage your assets more effectively. You can read more about these features in the rest of the documentation:

API 参考​

🌐 API Reference