network.download()

类型 函数
库 network.*
返回值 用户数据
修订 版本 2024.3703
关键词 异步, http, https, get, post, 下载
另请参阅 network.request()
network.cancel()
network.upload()
networkRequest
display.loadRemoteImage()

概述

此 API 是一个便捷方法，与异步 network.request() 非常相似，不同之处在于它始终尝试将响应下载到您指定的本地文件。实际上，此方法只是调用 network.request()，将目标 `filename` 和 `baseDirectory` 参数放入 `params.response` 中，并指定 `"download"` 进度通知。

您还可以使用 display.loadRemoteImage() 在单个 API 调用中下载并显示远程图像。

此函数返回一个句柄，可以将其传递给 network.cancel() 以取消请求。

注意事项

您不能在 `applicationSuspend` 或 `applicationExit` 事件 期间执行网络下载。当您的应用程序挂起时，不会触发任何回调。您可以通过在挂起时将您希望发出的请求保存到文件来解决此问题。然后，在 `applicationResume` 事件 上，检查是否有保存的待处理下载，如果有，则执行它。

网络请求在失败时不会引发运行时错误，因此无需将它们包装在 Lua `pcall()` 语句中（错误会在发送到网络侦听器的事件中报告）。

Android

在 Android 上，您必须将 `INTERNET` 权限添加到 `build.settings` 文件中。

settings =
{
   android =
   {
      usesPermissions =
      {
         "android.permission.INTERNET",
      },
   },
}

语法

network.download( url, method, listener [, params], filename [, baseDirectory] )
url （必填）

字符串。 HTTP 请求 URL。这必须符合 URL 的常用规则（如果您想在 URL 中使用非 ASCII 字符，请参见下面的示例）。

method （必填）

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

listener （必填）

侦听器。 在 HTTP 操作的各个阶段调用的侦听器函数。这将传递一个 networkRequest 事件。

当 `progress` 为 `true` 时，此 API 提供 `“download”` 进度，这意味着侦听器将接收 `“began”`、`“progress”` 和 `“ended”` 阶段的事件。如果未启用 `progress` 参数，则仅使用 `“ended”` 阶段事件调用侦听器。

params （可选）

表。 指定 HTTP 请求或响应处理选项的表，包括自定义请求标头或正文。支持以下键

  • `headers` — 使用字符串键指定请求标头值的表。
  • `body` — 包含请求正文的字符串（如果有）。
  • `timeout` — 超时时间（以秒为单位）。默认为 30 秒。
  • `bodyType` — 指示字符串请求正文是 `“text”` 还是 `“binary”` 的字符串。默认为 `“text”`。
  • `progress` — 设置为 `true` 将启用进度事件。默认为 `nil`，表示只需要 `“ended”` 阶段事件。
filename （必填）

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

baseDirectory （可选）

常量。 将保存文件的目录。如果未提供，则默认为 system.DocumentsDirectory。不能设置为 system.ResourceDirectory，因为该目录是只读的。

示例

下载并显示远程图像
local function networkListener( event )
    if ( event.isError ) then
        print( "Network error - download failed: ", event.response )
    elseif ( event.phase == "began" ) then
        print( "Progress Phase: began" )
    elseif ( event.phase == "ended" ) then
        print( "Displaying response image file" )
        myImage = display.newImage( event.response.filename, event.response.baseDirectory, 60, 40 )
        myImage.alpha = 0
        transition.to( myImage, { alpha=1.0 } )
    end
end

local params = {}
params.progress = true

network.download(
    "http://docs.solar2d.cn/images/simulator/image-mask-base2.png",
    "GET",
    networkListener,
    params,
    "maskCopy.png",
    system.TemporaryDirectory
)
在 URL 中使用非 ASCII 字符
--If you want to include non-ASCII characters in the URL, you must "urlencode" (https://en.wikipedia.org/wiki/Percent-encoding) them.
--Note that your browser does this behind the scenes.

local json = require "json"

function urlencode( str )
    if ( str ) then
        str = string.gsub( str, "\n", "\r\n" )
        str = string.gsub( str, "([^%w ])",
              function ( c ) return string.format ( "%%%02X", string.byte( c ) ) end )
        str = string.gsub( str, " ", "+" )
    end
    return str
end

function myNetworkListener( event )
    print( "myNetworkListener: "..json.encode( event, { indent=true } ) )
end

addedText = "これはテストです"
local paramFormat = "&parm3=".. urlencode( addedText )
local request = "http://127.0.0.1/~tester/response.php?info=11&parm1=1&parm2=2".. paramFormat

network.download( request, "GET", myNetworkListener, "result.txt", system.DocumentsDirectory )