display.loadRemoteImage()

类型 函数
库 display.*
返回值 无
版本 版本 2024.3703
关键字 网络、下载、图像下载、远程图像
另请参见 network.download()
network.request()

概述

这是一种类似于 network.download() 的便捷方法，用于返回包含图像的 display 对象，以及将图像保存到文件。

语法

display.loadRemoteImage( url, method, listener [, params], destFilename [, baseDir] [, x, y] )
url (必需)

字符串. 指向有效的远程 PNG 或 JPG 文件的 HTTP 请求 URL。

method (必需)

字符串. HTTP 方法；可接受的值为 "GET"（默认值）或 "POST"。

listener (必需)

侦听器. 在 HTTP 操作完成后调用的监听器函数。它传递了一个 event 对象，其中包含以下属性

  • event.response — 一个字符串，包含目标文件名。如果你正在为各种文件下载编写一个通用事件处理程序，这很有用。
  • event.target — 下载图像后创建的新显示对象。
  • event.isError — 布尔 值：网络错误时为 true；如果不是，则为 false。
params (可选)

表格. 有关更多信息，请参见 参数 部分。

destFilename (必需)

字符串. 将 HTTP 响应保存到的文件名。

baseDir (可选)

常量. 将文件保存到的文件夹路径。

x / y (可选)

数字. 成功下载并保存文件后，放置新创建的显示对象时使用的 **x** 和 **y** 坐标。

参数

params 表格是一个可选表格，用于指定要在请求中包含的自定义 HTTP 标头或正文。要指定自定义标头，请附加一个 headers 表格，该表格用字符串键指定标头值。要指定自定义正文消息，请附加一个 body 属性，该属性的字符串值为 HTTP 正文。

local params = {}
params.headers = {}  -- contains header values to send with your request
params.body = ""     -- specific body to send with your request
headers (可选)

表格. 一个表格，用字符串键指定标头值。

body (可选)

字符串. 包含与请求一起发送的 HTTP 正文。

陷阱

调用此函数不会返回任何内容。如果下载成功，侦听器回调将包含 display 对象 值 (event.target)。

图像指南

示例

标准
local function networkListener( event )
    if ( event.isError ) then
        print ( "Network error - download failed" )
    else
        event.target.alpha = 0
        transition.to( event.target, { alpha = 1.0 } )
    end

    print ( "event.response.fullPath: ", event.response.fullPath )
    print ( "event.response.filename: ", event.response.filename )
    print ( "event.response.baseDirectory: ", event.response.baseDirectory )
end
 
display.loadRemoteImage( "https://plugins.solar2d.com/images/logo-banner.png", "GET", networkListener, "logo-banner.png", system.TemporaryDirectory, 50, 50 )
在完成之前取消远程加载
--The 'display.loadRemoteImage()' API call is a convenience method around the 'network.request()' API.
--The code below is the implementation of 'display.loadRemoteImage()'. If you need to cancel your call,
--feel free to use the code below and modify it to your needs.

local function networkListener( event )
    if ( event.isError ) then
        print ( "Network error - download failed" )
    else
        event.target.alpha = 0
        transition.to( event.target, { alpha = 1.0 } )
    end

    print ( "event.response.fullPath: ", event.response.fullPath )
    print ( "event.response.filename: ", event.response.filename )
    print ( "event.response.baseDirectory: ", event.response.baseDirectory )
end

local function remoteImageListener( self, event )
    local listener = self.listener

    local target
    if ( not event.isError and event.phase == "ended" ) then
        target = display.newImage( self.filename, self.baseDir, self.x, self.y )
        event.target = target
    end
    listener( event )
end

-- display.loadRemoteImage( url, method, listener [, params], destFilename [, baseDir] [, x, y] )
display.loadRemoteImage = function( url, method, listener, ... )
    local arg = { ... }

    local params, destFilename, baseDir, x, y
    local nextArg = 1

    if ( "table" == type( arg[nextArg] ) ) then
        params = arg[nextArg]
        nextArg = nextArg + 1
    end

    if ( "string" == type( arg[nextArg] ) ) then
        destFilename = arg[nextArg]
        nextArg = nextArg + 1
    end

    if ( "userdata" == type( arg[nextArg] ) ) then
        baseDir = arg[nextArg]
        nextArg = nextArg + 1
    else
        baseDir = system.DocumentsDirectory
    end

    if ( "number" == type( arg[nextArg] ) and "number" == type( arg[nextArg + 1] ) ) then
        x = arg[nextArg]
        y = arg[nextArg + 1]
    end

    if ( destFilename ) then
        local options = {
            x=x, 
            y=y,
            filename=destFilename, 
            baseDir=baseDir,
            networkRequest=remoteImageListener, 
            listener=listener 
        }    

        if ( params ) then
            network.download( url, method, options, params, destFilename, baseDir )
        else
            network.download( url, method, options, destFilename, baseDir )
        end
    else
        print( "ERROR: no destination filename supplied to display.loadRemoteImage()" )
    end
end

display.loadRemoteImage( 
    "https://plugins.solar2d.com/images/logo-banner.png", "GET", networkListener, "logo-banner.png", system.TemporaryDirectory, display.contentCenterX, display.contentCenterY )