PermissionsSwiftUI: 一个处理权限的SwiftUI包
PermissionsSwiftUI
在SwiftUI中显示和处理权限。它在很大程度上受到 SPPermissions 的启发。
用户界面高度可定制,并采用 Apple 风格。如果您喜欢这个项目,请 点亮星标 ★
。
PermissionsSwiftUI 在 ☀️亮色模式和 🌑 暗色模式下同样精美。
🧭 导航
🖥️ 安装
要求
- iOS 11 (SwiftUI 需要 iOS 13.0) 或 iPadOS 13
- Xcode 12 和 Swift 5.3
- tvOS 支持即将推出
- 暂不支持 MacOS 和 WatchOS
安装
Swift Package Manager(推荐)
您可以通过 SPM 将 PermissionsSwiftUI 安装到您的 Xcode 项目中。 要了解更多关于 SPM 的信息,请点击这里
- 在 Xcode 12 中,打开您的项目并导航至 文件 → Swift 包 → 添加包依赖...
对于 Xcode 13,导航至 文件 → 添加包
- 粘贴仓库 URL(
https://github.com/jevonmao/PermissionsSwiftUI
)并点击 下一步。 - 对于 版本,确认选择 直到下一个主要版本。
- 点击 下一步,并仅选择所需的权限,否则 Apple 会拒绝您的应用
(您无需添加 CorePermissionsSwiftUI 或 PermissionsSwiftUI)
- 点击 完成
- 一切就绪,感谢您使用 PermissionsSwiftUI!
Cocoapods(已弃用)
您也可以通过 Cocoapods 安装 PermissionsSwiftUI。在您的 podfile 中添加 pod 'PermissionsSwiftUI'
:
platform :ios, '14.0'
target 'test abstract' do
use_frameworks!
pod 'PermissionsSwiftUI'
end
🚀 快速开始
在开始之前,请为这个仓库
点亮星标 ★
。您的星标是我熬夜维护这个开源项目的最大动力。
⚠️ v1.4.0 迁移指南
v1.4
已经发布!如果您遇到任何问题,请查看迁移指南,该指南旨在帮助开发者解决任何废弃和API更新的问题。
模态样式
要使用PermissionsSwiftUI,只需在任何视图上添加JMModal
修饰符:
.JMModal(showModal: $showModal, for: [.locationAlways, .photo, .microphone])
传入一个Binding<Bool>
来显示模态视图,并添加你想要显示的权限。例如:
struct ContentView: View {
@State var showModal = false
var body: some View {
Button(action: {
showModal=true
}, label: {
Text("向用户请求权限")
})
.JMModal(showModal: $showModal, for: [.locationAlways, .photo, .microphone])
}
}
警告样式
警告样式同样美观,使用更加灵活。当你需要请求少于3个权限时,建议使用此样式。 要显示权限弹出警告,请使用:
.JMAlert(showModal: $showModal, for: [.locationAlways, .photo])
与之前的JMPermissions
类似,你需要传入一个Binding<Bool>
来显示视图,并添加你想要显示的权限。
要快速了解PermissionsSwiftUI的所有自定义选项和配置,请查看速查表!
🛠️ 使用方法
自定义权限文本
要自定义权限文本,请使用setPermissionComponent()
修饰符
例如,你可以更改标题、描述和图标:
.setPermissionComponent(for: .camera,
image: AnyView(Image(systemName: "camera.fill")),
title: "摄像机",
description: "应用需要录制视频")
结果如下:
或者只更改标题或描述中的一项:
setPermissionComponent(for: .tracking, title: "跟踪器")
setPermissionComponent(for: .tracking, description: "跟踪描述")
注意:
- 未提供的参数将显示默认文本
- 在
JMPermissions
修饰符之后,将setPermissionComponent
修饰符添加到根级视图上
image
参数接受AnyView,因此可以随意使用SF Symbols或自定义资源:
.setPermissionComponent(for: .camera,
image: AnyView(Image("你的酷炫图片"))
甚至完整的SwiftUI视图也可以使用😱:
.setPermissionComponent(for: .camera,
image: AnyView(你的酷炫视图())
你可以使用单行代码为所有支持的权限自定义文本和图标。
自定义标题文本
要自定义标题,请使用changeHeaderTo
修饰符:
.JMPermissions(showModal: $showModal, for: [.camera, .location, .calendar])
.changeHeaderTo("应用权限")
要自定义标题描述,请使用changeHeaderDescriptionTo
修饰符:
.JMPermissions(showModal: $showModal, for: [.camera, .location, .photo])
.changeHeaderDescriptionTo("Instagram需要某些权限才能使所有功能正常工作。")
要自定义底部描述,请使用changeBottomDescriptionTo
修饰符:
.JMPermissions(showModal: $showModal, for: [.camera, .location, .photo])
.changeBottomDescriptionTo("如果未允许,你需要在设置中启用权限")
onAppear
和onDisappear
覆盖
当PermissionsSwiftUI视图出现和消失时执行代码或执行某些更新操作可能非常有用。 你可以通过以下方式在PermissionsSwiftUI视图出现或消失时执行操作:
.JMPermissions(showModal: $showModal, for: [.locationAlways, .photo, .microphone], onAppear: {}, onDisappear: {})
每次PermissionsSwiftUI视图出现和消失时,都将执行onAppear
和onDisappear
闭包参数。
JMAlert
修饰符也提供相同的视图修饰符闭包用于状态更改:
.JMAlert(showModal: $showModal,
for: [.locationAlways, .photo],
onAppear: {print("出现")},
onDisappear: {print("消失")})
自动检查授权
PermissionsSwiftUI默认会自动检查授权状态。它只会显示当前状态为notDetermined
的权限。(iOS系统阻止开发者请求被拒绝的权限。已允许的权限也会被PermissionsSwiftUI忽略)。如果所有权限都已允许或拒绝,PermissionsSwiftUI将不会显示模态或警告。
要设置自动检查授权,请使用autoCheckAuthorization
参数:
.JMModal(showModal: $showModal, for: [.camera], autoCheckAuthorization: false)
JMAlert也适用相同方法
.JMAlert(showModal: $showModal, for: [.camera], autoCheckAuthorization: false)
自动关闭
PermissionsSwiftUI默认不会有任何自动关闭行为。你可以覆盖此行为,使其在用户允许最后一个权限项后自动关闭模态或警告。(所有权限必须被允许,如果有任何权限被拒绝,它将不会自动关闭)。
.JMModal(... autoDismiss: Bool) -> some View
传入true
或false
来选择是否自动关闭视图。
自定义颜色
使用PermissionSwiftUI的功能,开发人员和设计师可以以令人难以置信的灵活性自定义所有UI颜色。您可以使用自定义颜色完全配置所有状态下的所有颜色。
要轻松更改强调色:
.setAccentColor(to: Color(.sRGB, red: 56/255, green: 173/255,
blue: 169/255, opacity: 1))
要更改主要(默认苹果蓝)和第三(默认苹果红)颜色:
.setAccentColor(toPrimary: Color(.sRGB, red: 56/255, green: 173/255,
blue: 169/255, opacity: 1),
toTertiary: Color(.systemPink))
⚠️
.setAccentColor()
和.setAllowButtonColor()
不应同时使用。
要充分自定义所有状态下的所有按钮颜色,您需要传入 AllButtonColors
结构:
.setAllowButtonColor(to: .init(buttonIdle: ButtonColor(foregroundColor: Color,
backgroundColor: Color),
buttonAllowed: ButtonColor(foregroundColor: Color,
backgroundColor: Color),
buttonDenied: ButtonColor(foregroundColor: Color,
backgroundColor: Color)))
有关上述方法的更多信息,请参考官方文档。
限制关闭
默认情况下,PermissionsSwiftUI会阻止用户在与所有权限交互之前关闭模态框和警告。这意味着如果用户没有明确拒绝或允许每个显示的权限,他们将无法关闭PermissionsSwiftUI视图。这种限制关闭行为可以通过 var restrictModalDismissal: Bool
或 var restrictAlertDismissal: Bool
属性来覆盖。
要禁用默认的限制关闭行为:
.JMModal(showModal: $show, for permissions: [.camera], restrictDismissal: false)
您也可以使用模型进行配置:
let model: PermissionStore = {
var model = PermissionStore()
model.permissions = [.camera]
model.restrictModalDismissal = false
model.restrictAlertDismissal = false
return model
}
......
.JMModal(showModal: $showModal, forModel: model)
配置健康权限
与其他权限不同,健康权限的配置略有不同。因为苹果要求开发人员明确设置读取和写入类型,PermissionsSwiftUI极大地简化了这个过程。
HKAccess
在初始化健康权限的枚举关联值时,需要使用HKAccess结构。它封装了健康权限的读取和写入类型权限。
设置读取和写入健康类型(这里以activeEnergyBurned
为例):
let healthTypes = Set([HKSampleType.quantityType(forIdentifier: .activeEnergyBurned)!])
.JMModal(showModal: $show, for: [.health(categories: .init(readAndWrite: healthTypes))])
//JMAlert样式的语法完全相同
.JMAlert(showModal: $show, for: [.health(categories: .init(readAndWrite: healthTypes))])
单独设置读取或写入:
let readTypes = Set([HKSampleType.quantityType(forIdentifier: .activeEnergyBurned)!])
let writeTypes = Set([HKSampleType.quantityType(forIdentifier: .appleStandTime)!])
.JMModal(showModal: $showModal, for: [.health(categories: .init(read: readTypes, write: writeTypes))])
您也可以只设置读取或写入类型:
let readTypes = Set([HKSampleType.quantityType(forIdentifier: .activeEnergyBurned)!])
.JMModal(showModal: $showModal, for: [.health(categories: .init(read: readTypes))])
📖 速查表
修饰符
自定义整体强调色:
setAccentColor(to:)
setAccentColor(toPrimary:toTertiary:)
自定义标题:
changeHeaderTo(_:)
自定义顶部描述:
changeHeaderDescriptionTo(_:)
自定义底部描述:
changeBottomDescriptionTo(_:)
自定义每个权限的显示文本和图像:
setPermissionComponent(for:image:title:description:)
setPermissionComponent(for:title:)
setPermissionComponent(for:description:)
自定义允许
按钮的颜色:
setAllowButtonColor(to:)
最后一个权限后自动关闭
autoDismiss: Bool
JMModal
和 JMAlert
的参数
在显示模态框或警告之前检查授权
autoCheckAuthorization: Bool
防止在所有权限交互之前关闭
restrictDismissal: Bool
在视图出现之前执行某些操作
onAppear: () -> Void
在视图消失之前执行某些操作
onDisappear: (() -> Void
🧰 支持的权限
以下是PermissionsSwiftUI支持的所有权限列表。是的,甚至包括iOS 14的最新跟踪
权限,让您保持领先。PermissionsSwiftUI中的所有权限都有默认的名称、描述和令人惊叹的苹果原生SF Symbols图标。
对FaceID权限的支持正在进行中,即将推出!如果您没有找到需要的权限,请开一个issue。更好的是,自己构建并开一个pull request,您可以按照这个步骤指南添加新权限。
💪 贡献
这里欢迎程序员和非程序员的贡献。无论您的技能水平如何,您肯定可以为PermissionSwiftUI的开源社区做出贡献。在开始之前,请阅读contributing.md,如果您想贡献一种新的iOS权限类型,请务必阅读这个逐步指南。 **如果您遇到任何问题、有任何顾虑或意见,请不要犹豫,随时告诉我。您可以开启讨论、提出问题或给我发邮件。**作为一名开发者,我理解当您对代码库中的某些内容不理解时的感受。我尽力做好注释和文档,但如果您遇到任何问题,我将很乐意尽我所能提供帮助。
附加信息
致谢
SPPermissions 在很大程度上是对 @verabeis 创建的著名 Swift 库 SPPermissions 的 SwiftUI 重制版。SPPermissions 最初创建于2017年,如今在 GitHub 上已获得超过4000颗星。PermissionsSwiftUI 旨在提供一个同样优美且强大的 SwiftUI 库。如果您给我的项目 PermissionsSwiftUI 加星 ★
,请务必查看原始项目 SPPermissions,我在其中借鉴了 UI 设计、部分 README.md 页面内容,以及在开发过程中的重要源代码参考。
许可证
PermissionsSwiftUI 由 Jingwen (Jevon) Mao 创建,并根据 MIT 许可证 授权。