可选参数

文：Santy-Wang，Xunyi

为了增加灵活性和可扩展性，Asset Manager 中大部分的加载接口包括 assetManager.loadAny 和 assetManager.preloadAny 都提供了 options 参数。options 除了可以配置 Creator 的内置参数，还可以自定义任意参数用于扩展引擎功能。如果开发者不需要配置引擎内置参数或者扩展引擎功能，可以无视它，直接使用更简单的 API 接口，比如 resources.load。

目前 options 中引擎已使用的参数包括：

uuid, url, path, dir, scene, type, priority, preset, audioLoadMode, ext, bundle, onFileProgress, maxConcurrency, maxRequestsPerFrame, maxRetryCount, version, xhrResponseType, xhrWithCredentials, xhrMimeType, xhrTimeout, xhrHeader, reloadAsset, cacheAsset, cacheEnabled

注意：请 不要 使用以上字段作为自定义参数的名称，避免与引擎功能发生冲突。

控制底层加载管线

可选参数是上层业务逻辑与底层加载管线之间的沟通工具。上层业务逻辑提供参数，用于控制下载器、解析器以及加载管线。

控制下载器和解析器

可选参数 priority, maxConcurrency, maxRequestsPerFrame, maxRetryCount 分别用于控制下载器对于下载请求的优先级排序、下载并发数限制、每帧能发起的请求数限制、最大重试次数。

assetManager.loadAny({'path': 'image/background'}, {priority: 2, maxRetryCount: 10}, callback);

控制下载器和解析器的处理方法

下载器/解析器中的文本文件和二进制文件等资源的处理方法，可接受可选参数 xhrResponseType, xhrWithCredentials, xhrMimeType, xhrTimeout, xhrHeader, onFileProgress 用于设置 XHR 的返回类型、头部以及下载进度回调等参数。

// 获取 XHR 的下载进度回调
assetManager.loadAny({
    'path': 'image/background'
},
{
    onFileProgress: function (loaded, total) {
        console.log(loaded/total);
    }
}, callback);

而可选参数 audioLoadMode 则用于控制音频文件的处理方法是否使用 WebAudio 来加载音频。

// 使用 WebAudio 远程加载音频
assetManager.loadRemote('http://example.com/background.mp3', {audioLoadMode: AudioClip.LoadMode.WEB_AUDIO}, callback);

注意：想要获取资源的加载进度必须在服务器端做好相关配置。

更多关于处理方法的介绍请参考 下载与解析。

控制加载流程

可选参数 reload, cacheAsset, cacheEnabled 用于控制加载管线是否复用缓存中的资源、是否缓存资源、以及是否缓存文件。

assetManager.loadRemote(url, {reload: true, cacheAsset: false, cacheEnabled: true}, (err, asset) => {});

而可选参数 uuid, url, path, dir, scene, type, ext, bundle 等，则是用于搜索资源。

assetManager.loadAny({'path': 'images/background', type: SpriteFrame, bundle: 'resources'}, callback);

assetManager.loadAny({'dir': 'images', type: SpriteFrame, bundle: 'resources'}, callback);

这种方式完全等价于直接使用 resources.load 和 resources.loadDir。

扩展引擎

开发者可以通过在 管线 和 自定义处理方法 中使用可选参数来扩展引擎的加载功能。

// 扩展管线
assetManager.pipeline.insert(function (task, done) {
    const input = task.input;
    for (let i = 0; i < input.length; i++) {
        if (input[i].options.myParam === 'important') {
            console.log(input[i].url);
        }
    }
    task.output = task.input;
    done();
}, 1);

assetManager.loadAny({'path': 'images/background'}, {'myParam': 'important'}, callback);

// 注册处理方法
assetManager.downloader.register('.myformat', function (url, options, callback) {
    // 下载对应资源
    const img = new Image();
    if (options.isCrossOrigin) {
        img.crossOrigin = 'anonymous';
    }

    img.onload = function () {
        callback(null, img);
    };

    img.onerror = function () {
        callback(new Error('download failed'), null);
    };

    img.src = url;

});

assetManager.parser.register('.myformat', function (file, options, callback) {
    // 解析下载完成的文件
    callback(null, file);
});

assetManager.loadAny({'url': 'http://example.com/myAsset.myformat'}, {isCrossOrigin: true}, callback);

通过可选参数，再结合管线和自定义处理方法，引擎可以获得极大的扩展度。Asset Bundle 可以看做是使用可选参数扩展的第一个实例。