今天要来自定义一个展示诗词的小组件
Widget，它显示的内容包括：诗词名字、作者、前两句（为什么只显示前两句呢，因为我找的免费API它只有给前两句😎）。切入正题，接下里开始实现，还不了解
Widget的同学可以先看看这里iOS14 Widget小组件开发实践1
1、新建一个Widget Extension，命名PoetryWidget。
2、获取网络数据请求处理
先看下免费的API接口：https://v1.alapi.cn/api/shici?type=shuqing的返回参数：
{
"code": 200,
"msg": "success",
"data": {
"content": "范增一去无谋主，韩信原来是逐臣。",
"origin": "乌江项王庙",
"author": "严遂成",
"category": "古诗文-抒情-爱国"
},
"author": {
"name": "Alone88",
"desc": "由Alone88提供的免费API 服务，官方文档：www.alapi.cn"
}
}
声明一个诗词需要的数据model：
struct Poetry {
let content: String // 内容
let origin: String // 名字
let author: String // 作者
}
既然是请求API接口，那就需要一个请求函数，并且回调请求参数，声明一个请求工具，实现数据请求以及json转model：
struct PoetryRequest {
static func request(completion: @escaping (Result<Poetry, Error>) -> Void) {
let url = URL(string: "https://v1.alapi.cn/api/shici?type=shuqing")!
let task = URLSession.shared.dataTask(with: url) { (data, response, error) in
guard error == nil else {
completion(.failure(error!))
return
}
let poetry = poetryFromJson(fromData: data!)
completion(.success(poetry))
}
task.resume()
}
static func poetryFromJson(fromData data: Data) -> Poetry {
let json = try! JSONSerialization.jsonObject(with: data, options: []) as! [String: Any]
//因为免费接口请求频率问题，如果太频繁了，请求可能失败，这里做下处理，放置crash
guard let data = json["data"] as? [String: Any] else {
return Poetry(content: "诗词加载失败，请稍微再试！", origin: "耐依福", author: "佚名")
}
let content = data["content"] as! String
let origin = data["origin"] as! String
let author = data["author"] as! String
return Poetry(content: content, origin: origin, author: author)
}
}
3、搭建展示界面
数据有了，就可以实现界面搭建了，这里必须用SwiftUI实现：
struct PoetryWidgetView: View {
let entry: PoetryEntry
var body: some View {
VStack(alignment: .leading, spacing: 4) {
Text(entry.poetry.origin)
.font(.system(size: 20))
.fontWeight(.bold)
Text(entry.poetry.author)
.font(.system(size: 16))
Text(entry.poetry.content)
.font(.system(size: 18))
}
.frame(minWidth: 0, maxWidth: .infinity, minHeight: 0, maxHeight: .infinity, alignment: .leading)
.padding()
.background(LinearGradient(gradient: Gradient(colors: [.init(red: 144 / 255.0, green: 252 / 255.0, blue: 231 / 255.0), .init(red: 50 / 204, green: 188 / 255.0, blue: 231 / 255.0)]), startPoint: .topLeading, endPoint: .bottomTrailing))
}
}
这里用了三个Text文本组件来展示三部分内容，很明显这里没有分别处理三种样式的UI，因此在编辑预览界面，三种样式的Widget能提供的内容是一样的，如果要实现三种样式各显示不同的内容，需要获取WidgetFamily的实例属性，实现不同的界面展示。
@Environment(\.widgetFamily) var family: WidgetFamily
来看看苹果官方文档的相关实现代码片段例子：
struct GameStatusView : View {
@Environment(\.widgetFamily) var family: WidgetFamily
var gameStatus: GameStatus
@ViewBuilder
var body: some View {
switch family {
case .systemSmall: GameTurnSummary(gameStatus)
case .systemMedium: GameStatusWithLastTurnResult(gameStatus)
case .systemLarge: GameStatusWithStatistics(gameStatus)
default: GameDetailsNotAvailable()
}
}
}
4、实现PoetryEntry
让结构体PoetryEntry遵守TimelineEntry协议：
struct PoetryEntry: TimelineEntry {
var date: Date
let poetry: Poetry // 可以理解为绑定了Poetry模型数据
}
5、实现PoetryProvider
让结构体PoetryProvider遵守TimelineProvider协议，同时实现：
struct PoetryProvider: TimelineProvider {
func placeholder(in context: Context) -> PoetryEntry { ...... }
func getSnapshot(in context: Context, completion: @escaping (PoetryEntry) -> Void) { ...... }
func getTimeline(in context: Context, completion: @escaping (Timeline<PoetryEntry>) -> Void) { ...... }
}
placeholder：实现默认视图
func placeholder(in context: Context) -> PoetryEntry {
let poetry = Poetry(content: "床前明月光，疑似地上霜", origin: "耐依福", author: "佚名")
return PoetryEntry(date: Date(), poetry: poetry)
}
getSnapshot：在组件的添加页面可以看到效果
func getSnapshot(in context: Context, completion: @escaping (PoetryEntry) -> Void) {
let poetry = Poetry(content: "床前明月光，疑似地上霜", origin: "月光光", author: "佚名")
let entry = PoetryEntry(date: Date(), poetry: poetry)
completion(entry)
}
getTimeline：在这个方法内可以进行网络请求，拿到的数据保存在对应的entry中，调用completion之后会到刷新小组件
这里有坑高能！！！
这里关于刷新策略，根据官方文档来看，Timeline的刷新策略是会延迟的，并不一定根据你设定的时间来。同时官方规定每个配置的窗口小部件每天都接收有限数量的刷新，具体的详情说明请看官方解释：TimelineProvider
func getTimeline(in context: Context, completion: @escaping (Timeline<PoetryEntry>) -> Void) {
let currentDate = Date()
// 下一次更新间隔以分钟为单位，间隔5分钟请求一次新的数据
let updateDate = Calendar.current.date(byAdding: .minute, value: 5, to: currentDate)
PoetryRequest.request { result in
let poetry: Poetry
if case .success(let response) = result {
poetry = response
} else {
poetry = Poetry(content: "诗词加载失败，请稍微再试！", origin: "耐依福", author: "佚名")
}
let entry = PoetryEntry(date: currentDate, poetry: poetry)
let timeline = Timeline(entries: [entry], policy: .after(updateDate!))
completion(timeline)
}
}
实现PoetryWidget
@main：代表着Widget的主入口，系统从这里加载
kind：是Widget的唯一标识
StaticConfiguration：初始化配置代码
configurationDisplayName：添加编辑界面展示的标题
description：添加编辑界面展示的描述内容
supportedFamilies这里可以限制要提供三个样式中的哪几个
@main
struct PoetryWidget: Widget {
var body: some WidgetConfiguration {
StaticConfiguration(kind: "PoetryWidget", provider: PoetryProvider()) { entry in
PoetryWidgetView(entry: entry)
}
.configurationDisplayName("每日一湿")
.description("默读并背诵全文")
}
}
到这里一个完整的Widget小组件的实现就完成了，然后就让代码跑起来，看看效果。
参考资料
creating-a-widget-extension
TimelineProvider
https://swiftrocks.com
