Options
All
  • Public
  • Public/Protected
  • All
Menu

Class CCLoader

资源加载管理器,引擎会自动创建一个单例对象 {{loader}}。

Hierarchy

Index

Constructors

constructor

Properties

_assetTables

_assetTables: any

Private _autoReleaseSetting

_autoReleaseSetting: any

_cache

_cache: any = createMap(true)

Protected _pipes

_pipes: Array<IPipe>

Private _releasedAssetChecker_DEBUG

_releasedAssetChecker_DEBUG: any

assetLoader

assetLoader: AssetLoader

loader 中的资源加载器,默认情况下是最先加载的。
用于标识资源的类型,并确定如何加载此资源。

downloader

downloader: Downloader

loader 中的资源下载程序,默认情况下是第二个加载的。
它用于下载带有多个处理程序的文件:纯文本,图像,脚本,音频,字体,uuid。
您可以使用 addDownloadHandlers 来添加自己的下载函数

getXMLHttpRequest

getXMLHttpRequest: Function

获取一个新的 XMLHttpRequest 的实例。

loader

loader: Loader

loader 中的资源下载程序,默认情况下是第三个加载的。
它用于解析下载的内容及多个处理程序的文件:纯文本,图像,脚本,音频,字体,uuid。
您可以使用 addLoadHandlers 来添加自己的下载函数

md5Pipe

md5Pipe: null

loader 中的 md5 加载管道,如果项目没有使用 md5 构建,则此项可能不存在。
用于修改带有 md5 后缀的真实可下载的 URL 。

onProgress

onProgress: Function | null

Loader 默认的进度回调函数,如果在调用 {{load}} 函数时没有指定进度回调函数的话,会调用默认进度回调函数。

Static ItemState

ItemState: any = ItemState

LoadingItems 队列中的加载项状态,状态的值可能是 {{ItemState.WORKING}} | {{ItemState.COMPLETE}} | {{ItemState.ERROR}}

Methods

getReferenceKey

  • getReferenceKey(assetOrUrlOrUuid: any): any
  • 在 laoder 中找到资源的引用 id ,参数可以是资源对象、资源的 uuid 或者是资源的 url

    Parameters

    • assetOrUrlOrUuid: any

    Returns any

getResUuid

  • getResUuid(url: string, type?: Function, mount?: any, quiet?: any): string

Private loadResUuids

  • loadResUuids(uuids: any, progressCallback: any, completeCallback: any, urls?: any): void

Private parseLoadResArgs

  • parseLoadResArgs(type: any, onProgress: any, onComplete: any): { onComplete: any; onProgress: any; type: any }
  • Parameters

    • type: any
    • onProgress: any
    • onComplete: any

    Returns { onComplete: any; onProgress: any; type: any }

    • onComplete: any
    • onProgress: any
    • type: any

Private urlNotFound

  • urlNotFound(url: any, type: any, completeCallback: any): void

addDownloadHandlers

  • addDownloadHandlers(extMap: Map<string, Function>): void
  • 为下载程序添加自定义支持的类型处理程序或修改现有的类型处理程序。

    example
     loader.addDownloadHandlers({
         // This will match all url with `.scene` extension or all url with `scene` type
         'scene' : function (url, callback) {}
     });

    Parameters

    • extMap: Map<string, Function>

      Handlers for corresponding type in a map

    Returns void

addLoadHandlers

  • addLoadHandlers(extMap: Map<string, Function>): void
  • 为加载程序添加自定义支持的类型处理程序或修改现有的类型处理程序。

    example
     loader.addLoadHandlers({
         // This will match all url with `.scene` extension or all url with `scene` type
         'scene' : function (url, callback) {}
     });

    Parameters

    • extMap: Map<string, Function>

      Handlers for corresponding type in a map

    Returns void

appendPipe

  • appendPipe(pipe: IPipe): void
  • 添加一个新的 pipe 到 pipeline 尾部。
    该 pipe 必须包含一个字符串类型 ‘id’ 和 ‘handle’ 函数,该 id 在 pipeline 必须是唯一标识。

    Parameters

    • pipe: IPipe

      The pipe to be appended

    Returns void

clear

  • clear(): void

copyItemStates

  • 从一个源 item 向所有目标 item 复制它的 pipe 状态,用于避免重复通过部分 pipe。
    当一个源 item 生成了一系列新的 items 时很有用,
    你希望让这些新的依赖项进入 pipeline,但是又不希望它们通过源 item 已经经过的 pipe,
    但是你可能希望他们源 item 已经通过并跳过所有 pipes,
    这个时候就可以使用这个 API。

    Parameters

    • srcItem: IItem

      The source item

    • dstItems: IItem | Array<IItem>

      A single destination item or an array of destination items

    Returns void

flowIn

  • flowIn(items: Array<IItem>): void
  • 让新的 item 流入 pipeline 中。
    这里的每个 item 可以是一个简单字符串类型的 url 或者是一个对象, 如果它是一个对象的话,他必须要包含 ‘id’ 属性。
    你也可以指定它的 ‘type’ 属性类型,默认情况下,该类型是 ‘url’ 的后缀名。
    也通过添加一个 包含 ‘skips’ 属性的 item 对象,你就可以跳过 skips 中包含的 pipe。
    该对象可以包含任何附加属性。

    example
     pipeline.flowIn([
         'res/Background.png',
         {
             id: 'res/scene.json',
             type: 'scene',
             name: 'scene',
             skips: ['Downloader']
         }
     ]);

    Parameters

    • items: Array<IItem>

      The {{IItem}} to be appended to the current pipeline

    Returns void

flowInDeps

  • flowInDeps(owner: any, urlList: any, callback: any): IItem[]

flowOut

  • flowOut(item: IItem): void

getDependsRecursively

  • getDependsRecursively(owner: Asset | RawAsset | string): Array<string>
  • 获取一个指定资源的所有依赖资源,包含它自身,并保存在数组中返回。
    owner 参数接收以下几种类型:1. 资源 asset 对象;2. 资源目录下的 url;3. 资源的 uuid。
    返回的数组将仅保存依赖资源的 uuid,获取这些 uuid 后,你可以从 loader 释放这些资源;通过 getRes 获取某个资源或者进行其他你需要的操作。
    想要释放一个资源及其依赖资源,可以参考 release
    下面是一些示例代码:

    example
    import { loader, Texture2D } from 'cc';
    // Release all dependencies of a loaded prefab
    let deps = loader.getDependsRecursively(prefab);
    loader.release(deps);
    // Retrieve all dependent textures
    let deps = loader.getDependsRecursively('prefabs/sample');
    let textures = [];
    for (let i = 0; i < deps.length; ++i) {
        let item = loader.getRes(deps[i]);
        if (item instanceof Texture2D) {
            textures.push(item);
        }
    }

    Parameters

    • owner: Asset | RawAsset | string

      The asset itself or the asset url or the asset uuid

    Returns Array<string>

getItem

  • getItem(id: string): IItem | null

getRes

  • getRes<T>(url: string, type?: Function): T | null
  • 根据 ID 获取资源数据。
    当使用 loadloadRes 来加载资源时,
    URL 将是资源的唯一标识。
    在完成加载之后,你可以通过将 URL 传递给此 API 来获取它们。

    Type parameters

    • T

    Parameters

    • url: string

      The asset url, it should be related path without extension to the resources folder.

    • Optional type: Function

      If type is provided, the asset for correspond type will be returned

    Returns T | null

getResCount

  • getResCount(): Number

init

  • init(director: any): void

insertPipe

  • insertPipe(pipe: IPipe, index: number): void
  • 在给定的索引位置插入一个新的 pipe。
    一个 pipe 必须包含一个字符串类型的 ‘id’ 和 ‘handle’ 函数,该 id 在 pipeline 必须是唯一标识。

    Parameters

    • pipe: IPipe

      The pipe to be inserted

    • index: number

      The index to insert

    Returns void

insertPipeAfter

  • insertPipeAfter(refPipe: IPipe, newPipe: IPipe): void

isAutoRelease

  • isAutoRelease(assetOrUrl: Asset | string): Boolean
  • 返回指定的资源是否有被设置为自动释放,不论场景的“Auto Release Assets”如何设置。

    参考:{{setAutoRelease}},{{setAutoReleaseRecursively}}

    Parameters

    • assetOrUrl: Asset | string

      asset object or the raw asset's url

    Returns Boolean

load

  • load(resources: string | string[] | Object, progressCallback?: Function | null, completeCallback?: Function | null): void
  • 使用进度回调和完整回调加载资源。
    进度回调与 Pipeline 的 LoadingItems.onProgress 相同
    完整的回调与 Pipeline 的 LoadingItems.onComplete 几乎相同
    唯一的区别是当用户将单个 URL 作为资源传递时,完整的回调将其结果直接设置为第二个参数。

    example
    import { loader, log, Texture2D } from 'cc';
    loader.load('a.png', function (err, tex) {
        log('Result should be a texture: ' + (tex instanceof Texture2D));
    });
    loader.load('http://example.com/a.png', function (err, tex) {
        log('Should load a texture from external url: ' + (tex instanceof Texture2D));
    });
    loader.load({url: 'http://example.com/getImageREST?file=a.png', type: 'png'}, function (err, tex) {
        log('Should load a texture from RESTful API by specify the type: ' + (tex instanceof Texture2D));
    });
    loader.load(['a.png', 'b.json'], function (errors, results) {
        if (errors) {
            for (let i = 0; i < errors.length; i++) {
                log('Error url [' + errors[i] + ']: ' + results.getError(errors[i]));
            }
        }
        let aTex = results.getContent('a.png');
        let bJsonObj = results.getContent('b.json');
    });

    Parameters

    • resources: string | string[] | Object

      Url list or load request list

    • Optional progressCallback: Function | null

      Progression callback

    • Optional completeCallback: Function | null

      Completion callback

    Returns void

loadRes

  • loadRes<T>(url: string, type: Constructor<T>, mount: string, progressCallback: LoadProgressCallback, completeCallback: LoadCompleteCallback<T>): any
  • loadRes<T>(url: string, type: Constructor<T>, progressCallback: LoadProgressCallback, completeCallback: LoadCompleteCallback<T>): any
  • loadRes<T>(url: string, type: Constructor<T>, completeCallback: LoadCompleteCallback<T>): any
  • 从项目的 “assets” 文件夹下的 “resources” 文件夹中加载资源

    注意:Creator 中的所有资源 URL 都使用正斜杠,使用反斜杠的 URL 将不起作用。

    example
    import { loader, error, log, Prefab, SpriteFrame } from 'cc';
    // load the prefab (project/assets/resources/misc/character/cocos) from resources folder
    loader.loadRes('misc/character/cocos', function (err, prefab) {
        if (err) {
            error(err.message || err);
            return;
        }
        log('Result should be a prefab: ' + (prefab instanceof Prefab));
    });
    // load the sprite frame of (project/assets/resources/imgs/cocos.png) from resources folder
    loader.loadRes('imgs/cocos', SpriteFrame, function (err, spriteFrame) {
        if (err) {
            error(err.message || err);
            return;
        }
        log('Result should be a sprite frame: ' + (spriteFrame instanceof SpriteFrame));
    });

    Type parameters

    • T

    Parameters

    • url: string

      The url of the asset to be loaded, this url should be related path without file extension to the resources folder.

    • type: Constructor<T>

      If type is provided, only asset for correspond type will be loaded

    • mount: string
    • progressCallback: LoadProgressCallback

      Progression callback

    • completeCallback: LoadCompleteCallback<T>

      Completion callback

    Returns any

  • example
    import { loader, error, log, Prefab, SpriteFrame } from 'cc';
    // load the prefab (project/assets/resources/misc/character/cocos) from resources folder
    loader.loadRes('misc/character/cocos', function (err, prefab) {
        if (err) {
            error(err.message || err);
            return;
        }
        log('Result should be a prefab: ' + (prefab instanceof Prefab));
    });
    // load the sprite frame of (project/assets/resources/imgs/cocos.png) from resources folder
    loader.loadRes('imgs/cocos', SpriteFrame, function (err, spriteFrame) {
        if (err) {
            error(err.message || err);
            return;
        }
        log('Result should be a sprite frame: ' + (spriteFrame instanceof SpriteFrame));
    });

    Type parameters

    • T

    Parameters

    • url: string
    • type: Constructor<T>
    • progressCallback: LoadProgressCallback
    • completeCallback: LoadCompleteCallback<T>

    Returns any

  • example
    import { loader, error, log, Prefab, SpriteFrame } from 'cc';
    // load the prefab (project/assets/resources/misc/character/cocos) from resources folder
    loader.loadRes('misc/character/cocos', function (err, prefab) {
        if (err) {
            error(err.message || err);
            return;
        }
        log('Result should be a prefab: ' + (prefab instanceof Prefab));
    });
    // load the sprite frame of (project/assets/resources/imgs/cocos.png) from resources folder
    loader.loadRes('imgs/cocos', SpriteFrame, function (err, spriteFrame) {
        if (err) {
            error(err.message || err);
            return;
        }
        log('Result should be a sprite frame: ' + (spriteFrame instanceof SpriteFrame));
    });

    Type parameters

    • T

    Parameters

    • url: string
    • type: Constructor<T>
    • completeCallback: LoadCompleteCallback<T>

    Returns any

loadResArray

  • loadResArray(urls: string[], type?: Function, mount?: any, progressCallback?: Function, completeCallback?: Function): void
  • 此方法除了接受 URL 数组参数外,与 loadRes 方法相同。

    example
    import { loader, error, SpriteFrame } from 'cc';
    // load the SpriteFrames from resources folder
    let spriteFrames;
    let urls = ['misc/characters/character_01', 'misc/weapons/weapons_01'];
    loader.loadResArray(urls, SpriteFrame, function (err, assets) {
        if (err) {
            error(err);
            return;
        }
        spriteFrames = assets;
        // ...
    });

    Parameters

    • urls: string[]
    • Optional type: Function

      If type is provided, only assets for correspond type will be loaded

    • Optional mount: any
    • Optional progressCallback: Function

      Progression callback

    • Optional completeCallback: Function

      Completion callback

    Returns void

loadResDir

  • loadResDir(url: string, type?: Function, mount?: any, progressCallback?: Function, completeCallback?: Function): void
  • 将所有资产加载到项目 “assets / resources” 文件夹中
    注意:Creator 中的所有资源 URL 都使用正斜杠,使用反斜杠的 URL 将不起作用。

    example
    import { loader, error, Texture2D } from 'cc';
    // load the texture (resources/imgs/cocos.png) and the corresponding sprite frame
    loader.loadResDir('imgs/cocos', function (err, assets) {
        if (err) {
            error(err);
            return;
        }
        let texture = assets[0];
        let spriteFrame = assets[1];
    });
    // load all textures in "resources/imgs/"
    loader.loadResDir('imgs', Texture2D, function (err, textures) {
        let texture1 = textures[0];
        let texture2 = textures[1];
    });
    // load all JSONs in "resources/data/"
    loader.loadResDir('data', function (err, objects, urls) {
        let data = objects[0];
        let url = urls[0];
    });

    Parameters

    • url: string

      The url of the directory to be loaded, this url should be related path to the resources folder.

    • Optional type: Function

      If type is provided, only assets for correspond type will be loaded

    • Optional mount: any
    • Optional progressCallback: Function

      Progression callback

    • Optional completeCallback: Function

      Completion callback

    Returns void

release

  • release(asset: Asset | RawAsset | string | Array<Asset | RawAsset | string>): void
  • 通过 id(通常是资源 url)来释放一个资源或者一个资源数组。
    这个方法不仅会从 loader 中删除资源的缓存引用,还会清理它的资源内容。
    比如说,当你释放一个 texture 资源,这个 texture 和它的 gl 贴图数据都会被释放。
    在复杂项目中,我们建议你结合 getDependsRecursively 来使用,便于在设备内存告急的情况下更快地释放不再需要的资源的内存。
    注意,这个函数可能会导致资源贴图或资源所依赖的贴图不可用,如果场景中存在节点仍然依赖同样的贴图,它们可能会变黑并报 GL 错误。
    如果你只想删除一个资源的缓存引用,请使用 Pipeline.removeItem

    example
    // Release a texture which is no longer need
    loader.release(texture);
    // Release all dependencies of a loaded prefab
    let deps = loader.getDependsRecursively('prefabs/sample');
    loader.release(deps);
    // If there is no instance of this prefab in the scene, the prefab and its dependencies like textures, sprite frames, etc, will be freed up.
    // If you have some other nodes share a texture in this prefab, you can skip it in two ways:
    // 1. Forbid auto release a texture before release
    loader.setAutoRelease(texture2d, false);
    // 2. Remove it from the dependencies array
    let deps = loader.getDependsRecursively('prefabs/sample');
    let index = deps.indexOf(texture2d._uuid);
    if (index !== -1)
        deps.splice(index, 1);
    loader.release(deps);

    Parameters

    • asset: Asset | RawAsset | string | Array<Asset | RawAsset | string>

      Asset or assets to be released

    Returns void

releaseAll

  • releaseAll(): void

releaseAsset

  • releaseAsset(asset: Asset): void

releaseRes

  • releaseRes(url: string, type?: Function, mount?: any): void
  • 释放通过 {{loadRes}} 加载的资源。详细信息请参考 {{release}}

    Parameters

    • url: string

      The asset url, it should be related path without extension to the resources folder.

    • Optional type: Function

      If type is provided, the asset for correspond type will be returned

    • Optional mount: any

    Returns void

releaseResDir

  • releaseResDir(url: string, type?: Function, mount?: any): void
  • 释放通过 {{loadResDir}} 加载的资源。详细信息请参考 {{release}}

    Parameters

    • url: string

      The url of the directory to release, it should be related path to the resources folder.

    • Optional type: Function

      If type is provided, the asset for correspond type will be returned

    • Optional mount: any

    Returns void

removeItem

  • removeItem(key: any): boolean

setAutoRelease

  • setAutoRelease(assetOrUrlOrUuid: Asset | string, autoRelease: Boolean): void
  • 设置当场景切换时是否自动释放资源。
    默认情况下,当加载新场景时,旧场景的资源根据旧场景是否勾选“Auto Release Assets”,将会被释放或者保留。
    而使用 loader.loadResloader.loadResDir 动态加载的资源,则不受场景设置的影响,默认不自动释放。
    使用这个 API 可以在单个资源上改变这个默认行为,强制在切换场景时保留或者释放指定资源。

    参考:{{setAutoReleaseRecursively}},{{isAutoRelease}}

    example
    // auto release the texture event if "Auto Release Assets" disabled in current scene
    loader.setAutoRelease(texture2d, true);
    // don't release the texture even if "Auto Release Assets" enabled in current scene
    loader.setAutoRelease(texture2d, false);
    // first parameter can be url
    loader.setAutoRelease(audioUrl, false);

    Parameters

    • assetOrUrlOrUuid: Asset | string

      The asset or its url or its uuid

    • autoRelease: Boolean

      Whether to release automatically during scene switch

    Returns void

setAutoReleaseRecursively

  • setAutoReleaseRecursively(assetOrUrlOrUuid: Asset | string, autoRelease: Boolean): void
  • 设置当场景切换时是否自动释放资源及资源引用的其它资源。
    默认情况下,当加载新场景时,旧场景的资源根据旧场景是否勾选“Auto Release Assets”,将会被释放或者保留。
    而使用 loader.loadResloader.loadResDir 动态加载的资源,则不受场景设置的影响,默认不自动释放。
    使用这个 API 可以在指定资源及资源递归引用到的所有资源上改变这个默认行为,强制在切换场景时保留或者释放指定资源。

    参考:{{setAutoRelease}},{{isAutoRelease}}

    example
    // auto release the SpriteFrame and its Texture event if "Auto Release Assets" disabled in current scene
    loader.setAutoReleaseRecursively(spriteFrame, true);
    // don't release the SpriteFrame and its Texture even if "Auto Release Assets" enabled in current scene
    loader.setAutoReleaseRecursively(spriteFrame, false);
    // don't release the Prefab and all the referenced assets
    loader.setAutoReleaseRecursively(prefab, false);

    Parameters

    • assetOrUrlOrUuid: Asset | string

      The asset or its url or its uuid

    • autoRelease: Boolean

      Whether to release automatically during scene switch

    Returns void

Generated using TypeDoc