contentful.swift - 用于 Contentful 的 Swift 内容交付库
Swift 库，用于 Contentful 的 内容交付 API 和 内容预览 API。它帮助您轻松访问以 Swift 应用存储在 Contentful 中的内容。
什么是Contentful？
Contentful 为数字团队提供内容基础设施，以支撑网站、应用程序和设备。与CMS不同，Contentful是为了与现代软件栈集成而构建的。它为结构化内容提供了一个中央枢纽，强大的管理和交付API，以及一个可定制的Web应用程序，使开发者和内容创作者能够更快地发布他们的产品。
目录
核心特性
- 通过内容交付API和内容预览API实现内容检索。
- 链接解析
- 丰富的查询语法，确保类型安全的查询
- 同步
- 本地化支持
- 与最新Swift开发栈保持一致：Swift 4.x | Xcode 10.x
- 支持环境（v2.0.0+）
- 实验性：要在iOS应用中渲染富文本，请查看GitHub上的rich-text-renderer.swift。
入门指南
要开始使用Contentful Swift库，您不仅需要安装它，还需要获取凭证，以便访问Contentful中的内容。
安装
CocoaPods 安装
platform :ios, '9.0'
use_frameworks!
pod 'Contentful'您可以根据需求指定Contentful的特定版本。有关Podfile中依赖关系版本控制操作的更多信息，请参阅CocoaPods的Podfile指南。
pod 'Contentful', '~> 5.0.0'Carthage 安装
您也可以使用Carthage进行集成，请将以下内容添加到您的 Cartfile 中
github "contentful/contentful.swift" ~> 5.0.0
Swift 包管理器 [swift-tools-version 5.0]
将以下行添加到您的依赖数组中
.package(url: "https://github.com/contentful/contentful.swift", .upToNextMajor(from: "5.0.0"))您的第一个请求
以下代码片段是您可以使用此库从Contentful获取内容的最基本示例
import Contentful
let client = Client(spaceId: "cfexampleapi",
environmentId: "master", // Defaults to "master" if omitted.
accessToken: "b4c0n73n7fu1")
client.fetch(Entry.self, id: "nyancat") { (result: Result<Entry, Error>) in
switch result {
case .success(let entry):
print(entry)
case .failure(let error):
print("Error \(error)!")
}
}访问预览API
要访问Content Preview API，使用您的预览访问令牌，并将客户端配置设置为预览，如下所示。
let client = Client(spaceId: "cfexampleapi",
accessToken: "e5e8d4c5c122cf28fc1af3ff77d28bef78a3952957f15067bbc29f2f0dde0b50",
host: Host.preview) // Defaults to Host.delivery if omitted.授权
通过
通过EntryDecodable将Contentful条目映射到Swift类
EntryDecodable协议允许您定义内容类型与要序列化的条目映射到Swift类之间的映射。当使用方法时：
let query = QueryOn<Cat>.where(field: .color, .equals("gray"))
client.fetchArray(of: Cat.self, matching: query) { (result: Result<ArrayResponse<Cat>>) in
guard let cats = result.value?.items else { return }
print(cats)
}异步返回的结果将是 ArrayResponse 类型的实例，其中泛型类型参数与您在 fetch 方法中传递的类型相同。如果您使用的是一个不限制响应只包含单个内容类型的 Query，则需要使用返回 MixedArrayResponse 而不是 ArrayResponse 的方法。EntryDecodable 协议扩展了 Swift 4 Foundation 标准库中的 Decodable 协议。该库提供了辅助方法来解析 EntryDecodable 之间的关系，以及从每个资源的 JSON 字段容器中获取值。
在上面的示例中，Cat 是一个遵循 EntryDecodable 和 FieldKeysQueryable 的自定义类型。为了使库能够正确创建您在接收 JSON 时发送的模型类型，您必须将这些类型传递给您的 Client 实例。
let contentTypeClasses: [EntryDecodable.Type] = [
Cat.self
Dog.self,
Human.self
]
let client = Client(spaceId: spaceId,
accessToken: deliveryAPIAccessToken,
contentTypeClasses: contentTypeClasses)Cat 模型类的源代码如下；请注意，库为 Swift 4 的 Decoder 类型添加了辅助方法来简化对 Contentful 返回的 JSON 的解析。您还需要将这些类型传递给您的 Client 实例，以便使用接受 EntryDecodable 类型引用的获取方法。
final class Cat: EntryDecodable, FieldKeysQueryable {
static let contentTypeId: String = "cat"
// FlatResource members.
let id: String
let localeCode: String?
let updatedAt: Date?
let createdAt: Date?
let color: String?
let name: String?
let lives: Int?
let likes: [String]?
// Metadata object if available
let metadata: Metadata?
// Relationship fields.
var bestFriend: Cat?
public required init(from decoder: Decoder) throws {
let sys = try decoder.sys()
id = sys.id
localeCode = sys.locale
updatedAt = sys.updatedAt
createdAt = sys.createdAt
let fields = try decoder.contentfulFieldsContainer(keyedBy: Cat.FieldKeys.self)
self.metadata = try decoder.metadata()
self.name = try fields.decodeIfPresent(String.self, forKey: .name)
self.color = try fields.decodeIfPresent(String.self, forKey: .color)
self.likes = try fields.decodeIfPresent(Array<String>.self, forKey: .likes)
self.lives = try fields.decodeIfPresent(Int.self, forKey: .lives)
try fields.resolveLink(forKey: .bestFriend, decoder: decoder) { [weak self] linkedCat in
self?.bestFriend = linkedCat as? Cat
}
}
enum FieldKeys: String, CodingKey {
case bestFriend
case name, color, likes, lives
}
}如果您想简化 EntryDecodable 的实现，请声明遵循 Resource，并向类中添加 let sys: Sys 属性并将通过初始化期间使用 sys = try decoder.sys() 来赋值。然后，id、localeCode、updatedAt 和 createdAt 都通过 sys 属性提供，无需作为类成员声明。但是，请注意，这种实现方式可能使与本地数据库框架（如 Realm 和 CoreData）的集成更加麻烦。
可选的，解码器有一个辅助函数用于解码元数据。
此外，该库要求表示条目或资产的类型的实例必须是 class 实例，而不是 struct — 这是因为库确保内存中的对象图是完整的，并且没有任何重复项。
文档与引用
参考文档
该库对所有公开变量、类型和函数有 100% 的文档覆盖率。您可以在 网络 上查看这些文档，或在 Xcode 中浏览它们。有关关于内容分发 API 的更多信息，请参阅 内容分发 API 参考文档。
教程与其他资源
- 这个库是我们Contentful Delivery REST API的包装器。一些更具体的细节，如搜索参数和分页，最好在REST API参考中解释，你也可以更好地理解底层请求的细节。
- 查看Contentful for Swift页面，获取教程、示例应用程序以及其他关于使用Swift与Contentful的信息。
Swift 交互式编码
如果你想要在Swift交互式编码环境（playground）中尝试该API的交互式演示，请按照以下步骤操作
git clone --recursive https://github.com/contentful/contentful.swift.git
cd contentful.swift
make open然后构建“Contentful_macOS”方案，打开playground文件，开始吧！注意：请确保在Xcode右侧的实用工具菜单中切换了“渲染文档”按钮，并且打开了控制台以查看对print的调用输出。
示例应用程序
请访问Github上的Swift iOS应用程序，按照README上的说明获取空间副本，以查看在Contentful中更改内容如何影响应用程序的展示。
迁移
我们在Migrations.md文件中收集了与从旧版本库迁移相关的所有信息。
Swift 版本控制
建议使用Swift 5.0，因为库的老旧版本不会进行回滚修复。如果必须使用较旧版本的Swift，请查看下面的兼容标签。
| Swift版本 | 兼容Contentful标签 |
|---|---|
| Swift 5.0 | [ ≥ 5.0.0 ] |
| Swift 4.2 | [ ≥ 4.0.0 ] |
| Swift 4.1 | [2.0.0 - 3.1.2] |
| Swift 4.0 | [0.10.0 - 1.0.1] |
| Swift 3.x | [0.3.0 - 0.9.3] |
| Swift 2.3 | 0.2.3 |
| Swift 2.2 | 0.2.1 |
联系我们
您对如何使用此库有疑问吗？
- 请联系我们的社区论坛：
- 加入我们的社区Slack频道：
您发现了错误或想要提出功能建议？
- 在此GitHub上提交问题：
。确保在分享前从代码中删除任何凭证。
您需要分享机密信息或有问题？
- 在我们的Contentful客户支持处提交支持票据：
参与其中
我们感谢对我们的存储库的任何帮助。有关如何贡献的更多详细信息，请参阅我们的Contributing.md文档。
许可证
本存储库遵循MIT许可证。
行为准则
我们希望为所有参与者提供一个安全、包容、友好和不受骚扰的空间和体验，无论其性别身份和表达、性取向、残疾、身体状况、社会经济地位、体型、种族、国籍、经验水平、年龄、宗教（或无宗教）或其他身份标记。