onDemandResources.request()

类型 函数
返回值 无
修订版 版本 2024.3703
关键字 按需资源，onDemandResources，请求
另请参阅 onDemandResources.setEventListener()
onDemandResources.*

概述

这是插件的核心函数。调用它会启动请求，以访问按需在“build.settings”中配置的资源。

重要

  • 在尝试使用资源之前，这些资源必须可用。该函数可以同时检查资源的可用性或下载它们。如果所需的资源不可用，则应请求下载它们，并在尝试使用它们之前，等待成功的回调响应。

  • 在成功请求和下载资源后，可以安全地访问它们，直到应用程序终止为止。

  • 即使你可以使用按需资源，就好像它们存在于应用软件包中一样，但实际上它们并不存在。使用 system.pathForFile() 检索实际路径，或者使用便捷函数 onDemandResources.path()。例如，当按需资源为文本文件时，这可能是必要的(不是图像)和 io.open() 需要打开该文件并读取其内容 (指南)。

注意

请记住按需资源请求被设计为在后台运行，因此你可以在应用程序流程中的逻辑时间点请求多个资源。例如，如果玩家正在进行游戏教程，你可以在使用该游戏教程之前一段时间请求进一步说明所需的资源，而不是在打算使用它们之前就直接请求。

语法

onDemandResources.request( tag [, download] [, listener] )
标签(必需)

字符串. 要请求的标签按需资源。

下载(可选)

布尔值. 指示如果资源不在本地可用，是否应该开始下载该资源。默认值为 true。如果你只想检查关联的资源是否在本地可用，请传递 false，这样此函数将几乎立即调用按需资源 事件。

侦听器(可选)

侦听器. 当资源可以访问时或发生错误时，将接收按需资源 事件 的侦听器函数。此侦听器只会接收与该请求特别关联的事件，如果你希望设置一个更广泛的侦听器函数来处理常规按需资源调用，请使用 onDemandResources.setEventListener()。

范例

检查资源
local odr = require( "plugin.onDemandResources" )

-- On-demand resources listener function
local function odrListener( event )
    if ( event .isError ) then
        -- Resources are not downloaded; see next example for download usage
    end
end

-- Check image resources for second level
odr.request( "imgL2", false, odrListener )  -- Pass 'false' as second argument to check (not download)
下载资源
local odr = require( "plugin.onDemandResources" )

-- On-demand resources listener function
local function odrListener( event )

    if not ( event.isError ) then
        print( "Resources for tag '" .. event.tag .. "' downloaded" )
    else
        print( "ERROR: errorCode = " .. tostring(event.errorCode) )
    end
end

-- Request image resources for first level
odr.request( "imgL1", true, odrListener )
进程指示器
local odr = require( "plugin.onDemandResources" )
local composer = require( "composer" )
local widget = require( "widget" )

local levelTag = "assetsL1"
local levelScene = "level1"

-- This function will indicate progress via a widget and go to scene when done
local function downloadResources( tag )

    -- Create progress bar
    local progressBar = widget.newProgressView( { x=160, y=240, width=120, isAnimated=false } )
    progressBar:setProgress( 0 )

    -- Runtime listener to update progress bar
    local function updateProgress()
        progressBar:setProgress( odr.progress(tag) )
    end
    Runtime:addEventListener( "enterFrame", updateProgress )

    -- Now, download resources with "urgent" priority
    odr.request( tag, true,
        function( event )
            -- Remove progress bar
            Runtime:removeEventListener( "enterFrame", updateProgress )
            progressBar:removeSelf()
            progressBar = nil
            -- Proceed to level scene
            if not ( event.isError ) then
                composer.gotoScene( levelScene )
            end
        end )
    odr.setDownloadPriority( tag, "urgent" )
end

-- First, simply check if resources are already downloaded
odr.request( levelTag, false,
    function( event )
        if not ( event.isError ) then
            -- Resources already downloaded; proceed to level scene
            composer.gotoScene( levelScene )
        else
            -- Resources must be downloaded; call download function above
            downloadResources( levelTag )
        end
    end )