display.capture()

Android

当应用暂停时，Android 操作系统会从内存中移除所有 OpenGL 纹理。当应用恢复时，Corona 必须重新加载所有图像，但捕捉图像不再存在于内存中。如果您需要在 Android 中恢复捕捉的图像，可以使用以下解决方案

• 通过 display.save() 函数将返回的捕捉图像保存到文件。请注意，您不能在 Android 的 "applicationSuspend" 和 "applicationExit" 事件 中使用 display.save() 函数，因为内存中没有要保存的 OpenGL 纹理。
• 使用捕捉对象的边界，通过 display.newImageRect() 显示保存到文件的图像。

此外，如果您在 saveToPhotoLibrary 选项 中设置值为 true，则必须在 build.settings 文件中设置以下权限

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

iOS

在 iOS 上，如果您在 saveToPhotoLibrary 选项 中设置值为 true，则必须在 build.settings 的 plist 表中包含以下键/描述。当系统提示用户允许访问时，相关的描述将作为警报的一部分显示。请注意，您可以根据自己的喜好自定义这些描述，甚至可以对其进行本地化（指南）。

settings =
{
    iphone =
    {
        plist =
        {
            NSPhotoLibraryUsageDescription = "This app would like to access the photo library.",
            NSPhotoLibraryAddUsageDescription = "This app would like to add the photo library.",
        },
    },
}

macOS

将屏幕捕捉图像另存为 JPEG 文件到当前用户的“图片”文件夹中。

请注意，如果您计划将应用程序提交到 Mac App Store，它将被**沙盒化**。这意味着必须请求在“图片”文件夹中读取/写入文件的特殊权限。为此，只需在settings → osxbuild.settings 表中添加 entitlements 条目，如下所示。有关更多详细信息，请参阅 Apple 的 文档。

settings = 
{
    osx = {
        entitlements = {
            ["com.apple.security.assets.pictures.read-write"] = true,
        },
    },
}

Windows

将屏幕捕捉图像另存为 PNG 文件到用户的我的图片目录下的以 Corona 应用命名的子目录中。对于 Corona 模拟器，此目录将是我的图片\Corona Simulator。对于Corona 构建的桌面应用，此目录将是我的图片\<AppName>.

启动时捕捉

如果您需要在应用程序启动时捕捉显示对象，例如在执行 main.lua 初始化应用程序时，则必须在 timer.performWithDelay() 调用中调用 display.capture()。建议延迟至少 100 毫秒。

local myObject1 = display.newRect( 50, 50, 100, 150 )

local function captureWithDelay()
    local capture = display.capture( myObject1 )
end

timer.performWithDelay( 100, captureWithDelay )

displayObject _^(必填)

显示对象. 引用要捕捉的显示对象/组的变量。

options _^(可选)

表. 捕捉选项的表 — 有关详细信息，请参阅下一节。

saveToPhotoLibrary _^(可选)

布尔值. 如果为 true，则将图像添加到设备的相册中（PNG 文件）。对于 Android 和 iOS 设备，这也需要满足 陷阱 中列出的要求。

captureOffscreenArea _^(可选)

布尔值. 如果为 true，则会捕捉整个对象/组，即使屏幕上不可见的部分也会被捕捉。如果省略，捕捉将被限制在屏幕边界内。出于旧版兼容性目的，可以使用已弃用的 isFullResolution 选项名称，其效果相同。

displayObject _^(必填)

显示对象. 引用要捕捉的显示对象/组的变量。

saveToPhotoLibrary _^(可选)

布尔值. 如果为 true，则将图像添加到设备的相册中（PNG 文件）。对于 Android 和 iOS 设备，这也需要满足 陷阱 中列出的要求。