2015 年 12 月 18 日
教程：使用 iCloud 键值存储
今天，我们很高兴推出 iCloud 插件，该插件自 Daily Build 2015.2795 起可用。 此插件目前处于“beta”阶段，我们正在完成 文档 的润色并进行进一步的测试。
在本教程中，我们将探讨 键值存储 或 KVS （我们将在其他教程中讨论“iCloud 中的文档”和“CloudKit”）。
概述
KVS 允许您使用一组非常简单的 API 调用在 Apple 的 iCloud 中存储“键值”对。使用 KVS，您可以使用简单的 iCloud.set() 调用来存储字符串、数字和数据表。
在您深入了解之前，需要注意一些 KVS 限制
- 您最多可以使用 1 兆字节的存储空间。
- 您最多可以拥有 1024 个总键。
- 键的长度最多为 64 字节，并且包含 Unicode 字符。Unicode 字符比字母数字字符占用更多空间。您最多可以使用 63 个字母数字字符。
根据您的需求，您可以使用一个包含大量表格数据的键，也可以使用许多包含单独数据位的键。请记住，当您同步一个包含大量数据的键时，您将同时更改大量数据。还要记住，数据通常通过 WiFi 和蜂窝网络同步，因此同步包含大量数据的键可能很耗时，即使只有该数据的一小部分发生了更改。
配置您的应用程序
在您可以将支持 iCloud 的应用程序部署到商店之前，您的配置文件必须启用 iCloud。这在 Apple Developer 门户的 Member Center 中的 Certificates, Identifiers & Profiles 下完成。在那里，单击 Identifiers → App IDs。单击所需的应用程序（它不能使用通配符 App ID），然后向下滚动到 iCloud 行。在那里，选中该复选框以启用 iCloud。接下来，单击单选按钮以启用 CloudKit，然后单击 Edit 按钮。
在下一个屏幕上，选中您的应用程序的捆绑包 ID 的复选框
单击 Continue，然后单击 Done。此时，您需要重新生成您的配置文件（请参阅 此处 的 创建配置文件 部分）。
更新 build.settings
要包含 iCloud 插件，您必须将其添加到您的 build.settings 文件中
|
1 2 3 4 5 6 7 8 9 10 11 12 |
settings = { plugins = { ["plugin.iCloud"] = { publisherId = "com.coronalabs", supportedPlatforms = { iphone=true, osx=true, appletvos=true }, }, }, } |
此外，您必须编辑 iphone 和/或 tvos 的块
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
settings = { iphone = { iCloud = true, plist = { } }, -- 可选（仅用于 Apple TV 和 tvOS） tvos = { iCloud = true, }, } |
Corona Enterprise
对于企业内部版本，您必须包含 Corona_plugin_iCloud.framework，该框架位于 每日构建页面 的企业插件下载选项卡上。
此外，在项目的 Capabilities 屏幕上，有一些启用 iCloud 所需的 Xcode 设置。在这里，请确保已启用 iCloud 并选中了 键值存储。
将值保存到 iCloud
在您需要访问 iCloud 服务的任何场景或 Lua 文件中，您必须 require 该插件
|
1 2 |
local iCloud = require( "plugin.iCloud" ) |
然后，当您准备好保存一些数据时，只需使用键和值调用 iCloud.set()，例如
|
1 2 |
iCloud.set( "playMusic", "on" ) |
这将设置一个名为 playMusic 的键，其值为 "on"。
接受的值
KVS 允许您存储以下数据类型
- 数字
- 字符串
- 表格
虽然您无法以这种方式存储布尔值，但它们可以成为表格数据的一部分。或者，您可以简单地使用像 1 或 0 这样的数字来表示 true 或 false，或者只是存储字符串 "true" 或 "false"，但您需要在将它们用作 Lua 布尔值之前将它们转换回布尔值。
请注意，如果您选择存储表格，则它必须仅包含键值对。具有数字键（数组）的表格不能直接作为表格存储。换句话说，如果您尝试将其存储到 KVS，则以下数组会产生错误
|
1 2 |
local array = { true, 0, 10 } -- 这类似于 { 1=true, 2=0, 3=10 } iCloud.set( "myArray", array ) -- 此值不会被存储 |
如果您有要存储的数组，一种选择是在表格上使用 json.encode() 并将其保存为字符串数据，然后在字符串上使用 json.decode()，以便在从 iCloud 检索后将其转换回表格。
检索数据
要从 KVS 中获取数据，只需调用 iCloud.get() 方法
|
1 2 |
local musicOn = iCloud.get( "playMusic" ) |
如果找不到该值，则会返回 nil。就这么简单！
删除数据
如果您不再需要某些数据，您可以使用 iCloud.delete() 方法从 iCloud 中删除键来恢复使用的存储空间
|
1 2 |
iCloud.delete( "playMusic" ) |
同步数据
iCloud 的一个重要目的是允许用户在多个设备之间共享数据。换句话说，如果您在 iPad 上完成了一个游戏关卡，您应该可以在 iPhone 上继续玩下一个关卡。如果应用程序启动时从 KVS 加载了某些保存的设置（数据），则应用程序应该具有最新的数据——但是如果应用程序同时在两个设备上打开，并且数据发生了更改，那又该如何呢？
一种选择是通过 iCloud.setKVSListener() 启用一个监听器函数，当值发生更改时，该函数将执行，从而有效地使您的应用程序保持最新状态。请考虑以下代码块
|
1 2 3 4 5 6 7 8 |
local function on_iCloudUpdate( event ) if ( event.type == "initialSync" or event.type == "serverChange" ) then musicOn = iCloud.get( "playMusic" ) end end iCloud.setKVSListener( on_iCloudUpdate ) |
请参阅 iCloudKVSEvent 文档，了解作为 event 表一部分返回的各种值。
结论
本教程只是关于在 Apple iCloud 中存储和共享数据的第一个教程。要了解更多信息，请参阅 iCloud 文档。
Corona SDK 添加 Mac OS 支持；tvOS 测试版gamedev.fm | gamedev.fm
发布于 06:34，12 月 19 日[...] 要开始使用 iCloud 插件，请参阅文档和我们的第一个教程。 [...]
Sem
发布于 07:55，12 月 26 日这是否仅适用于 iOS 应用程序？
Rob Miracle
发布于 09:29，12 月 26 日目前适用于 iOS 和 tvOS。在某个时候，我们也会使其可用于 OS X 构建。工程部门正在研究 Android 的等效版本，然后我们将研究一个包装器来制作跨平台版本。
René
发布于 01:58，12 月 28 日非常酷。谢谢你，Rob。
限制：1 MB 存储空间，总共 1024 个键等，这些限制是针对每个应用程序的吗？
Rob Miracle
发布于 18:40，12 月 28 日是的，每个应用程序 1MB/1024 个键。多个应用程序可以共享单个存储空间。在这种情况下，共享的整个套件的配额为 1MB/1024 个键。
Jeremiah
发布于 09:04，12 月 30 日如果用户禁用 iCloud 会发生什么？这些方法会抛出错误，还是只是静默失败？例如，返回 null/不执行任何操作。
Rob Miracle
发布于 16:31，1 月 1 日如果它们失败并且您期望返回值，则它们应该返回 nil。如果是不期望返回值的操作，则不会返回任何内容。
Rob
Umut Demirel
发布于 05:42，3 月 31 日是否有任何方法可以从实际设备上的 iCloud 设置中清除数据？我在“设置”->“iCloud”->“存储”->“管理存储”部分找不到我的应用程序名称。iCloud.delete() 函数是清除它的唯一方法吗？
Vlad Shcherban
发布于 12:12，3 月 31 日“设置”->“iCloud”->“存储”->“管理存储”仅显示 iCloud 中的文档（可能是 CloudKit）。用户无法重置 iCloud KVS 存储，并且从应用程序内部删除它们是 Apple 生态系统中唯一的方法。
Tim
发布于 08:32，5 月 3 日使用 iCloud 和 KVS，一切似乎都很好。可以写入、同步、读取。但是，一旦我重新安装，一切都消失了。这只能意味着它根本没有写入 iCloud，只是一个本地保存文件。
非常简单的代码。
只需在开发者门户中设置配置。
然后按照教程使用插件
最后使用
iCloud.set( “value”, myValue)
和
iCloud.get( “value”)
有什么想法吗？
Tim
发布于 12:01，5 月 3 日简单的修复。即使您的应用程序在使用 KVS 时不会显示，也需要打开 iCloud。
http://stackoverflow.com/questions/30430380/detect-icloud-account-availibility-change-using-key-value-store-only
Cesar
发布于 12:20，7 月 3 日大家好。
首先，感谢这个出色的教程和你们的辛勤工作。
我开始使用 iCloud 是因为我的应用程序需要备份 mysql 数据库和一个 prefs.json 文件。我正在考虑将这两个文件压缩并上传到 iCloud 文档。但我无法做到这一点。我也不知道是否可以使用 KVS 来存储小于 1 MB 的文件（zip 文件格式）。我认为 json 可以将 zip 文件转换为纯文本文件，以便使用 KVS 设置值。我不知道是否需要使用文档。
我真的不知道该怎么做。
此外，CloudKit 似乎允许数据库在不同的用户之间共享数据，但是，如何将我的 sqlite 数据库上传到那里？我认为我必须将 sqlite 数据库完全转换为 CloudKit 版本。
亲爱的，您是否计划也发布文档和 CloudKit 教程？
关于是否可以使用 KVS 存储 zip 文件有什么想法吗？
非常感谢，
此致，
Rob Miracle
发布于 11:17，7 月 5 日该插件支持所有三个。本教程仅涵盖键值对。您可以查看文档：https://docs.solar2d.cn/plugin/iCloud/index.html