Skip to main content

解析器

¥Resolver

在 PixiJS 中，资源管理以 UnresolvedAsset 和 ResolvedAsset 的概念为中心。该系统旨在支持多格式资源、条件加载以及基于平台功能（例如 WebP 支持、设备分辨率或性能限制）的运行时优化。

¥In PixiJS, asset management centers around the concept of UnresolvedAsset and ResolvedAsset. This system is designed to support multi-format assets, conditional loading, and runtime optimization based on platform capabilities (e.g., WebP support, device resolution, or performance constraints).

开发者无需指定固定的 URL，而是描述可以加载哪些资源 - PixiJS 会动态选择最佳选项。

¥Rather than specifying a fixed URL, developers describe what assets could be loaded — and PixiJS selects the best option dynamically.

解析器生命周期​

¥Resolver Lifecycle

分辨率过程包含四个关键步骤：

¥The resolution process involves four key steps:

  1. 未解析的资源创建：使用字符串或对象定义的资源在内部被规范化为 UnresolvedAsset 实例。这些包括别名、通配符路径、解析器提示和自定义数据等元数据。

    ¥UnresolvedAsset Creation Assets defined using a string or object are internally normalized into UnresolvedAsset instances. These include metadata such as aliases, wildcard paths, parser hints, and custom data.

  2. 源扩展 UnresolvedAsset 的 src 字段可以是字符串或字符串数​​组。PixiJS 会将任何通配符模式（例如 myAsset@{1,2}x.{png,webp}）扩展为具体的候选 URL 列表。

    ¥Source Expansion The src field of an UnresolvedAsset can be a string or array of strings. PixiJS expands any wildcard patterns (e.g. myAsset@{1,2}x.{png,webp}) into a list of concrete candidate URLs.

  3. 最佳匹配选择：PixiJS 会评估所有候选 URL，并使用平台感知启发式算法来选择最合适的源。因素包括支持的格式（例如 WebP 与 PNG）、设备像素比以及自定义配置（例如首选格式）。

    ¥Best-Match Selection PixiJS evaluates all candidate URLs and uses platform-aware heuristics to pick the most suitable source. Factors include supported formats (e.g. WebP vs PNG), device pixel ratio, and custom configuration such as preferred formats.

  4. ResolvedAsset 输出结果为 ResolvedAsset，包含特定 URL 和所有必需的元数据，可传递给相关解析器并加载到内存中。

    ¥ResolvedAsset Output The result is a ResolvedAsset containing a specific URL and all required metadata, ready to be passed to the relevant parser and loaded into memory.

使用未解析的资源​

¥Using Unresolved Assets

UnresolvedAsset 是 PixiJS 中用于定义资源的主要结构。它允许你指定源 URL、别名以及加载所需的任何其他数据。它们更复杂，但也更强大。

¥An UnresolvedAsset is the primary structure used to define assets in PixiJS. It allows you to specify the source URL(s), alias(es), and any additional data needed for loading. They are more complex, but are also more powerful.

字段类型描述
aliasstring | string[]用于稍后引用此资源的一个或多个别名。
srcstring | string[]一个或多个资源候选路径。支持通配符。
loadParser（可选）string一个用于处理资源（例如 'loadTextures'、'loadJson'）的专用解析器。
data（可选）any传递给加载器的额外数据。这会根据解析器类型而有所不同。

示例​

¥Examples

加载单个资源​

¥Loading a Single Asset

import { Assets } from 'pixi.js';

await Assets.load({
    alias: 'bunny',
    src: 'images/bunny.png',
});

使用显式解析器和加载器选项加载​

¥Loading with Explicit Parser and Loader Options

await Assets.load({
    alias: 'bunny',
    src: 'images/bunny.png',
    loadParser: 'loadTextures',
    data: {
        alphaMode: 'no-premultiply-alpha',
    },
});

使用通配符实现响应式和格式感知加载​

¥Using Wildcards for Responsive and Format-Aware Loading

await Assets.load({
    alias: 'bunny',
    src: 'images/bunny@{0.5,1,2}x.{png,webp}',
});

此模式内部扩展为：

¥This pattern expands internally to:

[
    'images/bunny@0.5x.png',
    'images/bunny@0.5x.webp',
    'images/bunny@1x.png',
    'images/bunny@1x.webp',
    'images/bunny@2x.png',
    'images/bunny@2x.webp',
];

PixiJS 将根据运行时功能选择最佳匹配（例如，如果支持，则选择 WebP；如果在高分辨率显示器上，则选择 2x）。

¥PixiJS will select the best match depending on runtime capabilities (e.g. chooses WebP if supported, 2x if on a high-res display).

¥Related Tools and Features

  • 资源包：如果你管理大型资源集，AssetPack 可以使用 glob 模式生成优化的清单，并自动输出 UnresolvedAsset 结构。

    ¥AssetPack: If you're managing large asset sets, AssetPack can generate optimized manifests using glob patterns and output UnresolvedAsset structures automatically.

  • 资源清单和资源包：使用 清单和包 预定义未解析的资源组，并通过 Assets.loadBundle 加载它们。

    ¥Asset Manifests & Bundles: Use manifests and bundles to predefine groups of unresolved assets and load them via Assets.loadBundle.