可选参数

文:Santy-Wang,Xunyi

为了增加灵活性和可扩展性,Asset Manager 中大部分的加载接口包括 assetManager.loadAnyassetManager.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.loadresources.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 可以看做是使用可选参数扩展的第一个实例。

条与 "" 相匹配的结果

    没有与 "" 匹配的结果