devxoul/URLNavigator
Fork: 297 Star: 3268 (更新于 2024-12-10 18:01:56)
license: MIT
Language: Swift .
⛵️ Elegant URL Routing for Swift
最后发布版本: 2.5.1 ( 2023-07-10 01:59:52)
URLNavigator
⛵️ URLNavigator provides an elegant way to navigate through view controllers by URLs. URL patterns can be mapped by using URLNavigator.register(_:_:)
function.
URLNavigator can be used for mapping URL patterns with 2 kind of types: URLNavigable
and URLOpenHandler
. URLNavigable
is a type which defines an custom initializer and URLOpenHandler
is a closure which can be executed. Both an initializer and a closure receive an URL and placeholder values.
Getting Started
1. Understanding URL Patterns
URL patterns can contain placeholders. Placeholders will be replaced with matching values from URLs. Use <
and >
to make placeholders. Placeholders can have types: string
(default), int
, float
, and path
.
For example, myapp://user/<int:id>
matches with:
-
myapp://user/123
-
myapp://user/87
But it doesn't match with:
-
myapp://user/devxoul
(expected int) -
myapp://user/123/posts
(different url structure) -
/user/devxoul
(missing scheme)
2. Mapping View Controllers and URL Open Handlers
URLNavigator allows to map view controllers and URL open handlers with URL patterns. Here's an example of mapping URL patterns with view controllers and a closure. Each closures has three parameters: url
, values
and context
.
-
url
is an URL that is passed frompush()
andpresent()
. -
values
is a dictionary that contains URL placeholder keys and values. -
context
is a dictionary which contains extra values passed frompush()
,present()
oropen()
.
let navigator = Navigator()
// register view controllers
navigator.register("myapp://user/<int:id>") { url, values, context in
guard let userID = values["id"] as? Int else { return nil }
return UserViewController(userID: userID)
}
navigator.register("myapp://post/<title>") { url, values, context in
return storyboard.instantiateViewController(withIdentifier: "PostViewController")
}
// register url open handlers
navigator.handle("myapp://alert") { url, values, context in
let title = url.queryParameters["title"]
let message = url.queryParameters["message"]
presentAlertController(title: title, message: message)
return true
}
3. Pushing, Presenting and Opening URLs
URLNavigator can push and present view controllers and execute closures with URLs.
Provide the from
parameter to push()
to specify the navigation controller which the new view controller will be pushed. Similarly, provide the from
parameter to present()
to specify the view controller which the new view controller will be presented. If the nil
is passed, which is a default value, current application's top most view controller will be used to push or present view controllers.
present()
takes an extra parameter: wrap
. If a UINavigationController
class is specified, the new view controller will be wrapped with the class. Default value is nil
.
Navigator.push("myapp://user/123")
Navigator.present("myapp://post/54321", wrap: UINavigationController.self)
Navigator.open("myapp://alert?title=Hello&message=World")
Installation
URLNavigator officially supports CocoaPods only.
Podfile
pod 'URLNavigator'
Example
You can find an example app here.
- Build and install the example app.
- Open Safari app
- Enter
navigator://user/devxoul
in the URL bar. - The example app will be launched.
Tips and Tricks
Where to initialize a Navigator instance
-
Define as a global constant:
let navigator = Navigator() class AppDelegate: UIResponder, UIApplicationDelegate { // ... }
-
Register to an IoC container:
container.register(NavigatorProtocol.self) { _ in Navigator() } // Swinject let navigator = container.resolve(NavigatorProtocol.self)!
-
Inject dependency from a composition root.
Where to Map URLs
I'd prefer using separated URL map file.
struct URLNavigationMap {
static func initialize(navigator: NavigatorProtocol) {
navigator.register("myapp://user/<int:id>") { ... }
navigator.register("myapp://post/<title>") { ... }
navigator.handle("myapp://alert") { ... }
}
}
Then call initialize()
at AppDelegate
's application:didFinishLaunchingWithOptions:
.
@UIApplicationMain
final class AppDelegate: UIResponder, UIApplicationDelegate {
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?
) -> Bool {
// Navigator
URLNavigationMap.initialize(navigator: navigator)
// Do something else...
}
}
Implementing AppDelegate Launch Option URL
It's available to open your app with URLs if custom schemes are registered. In order to navigate to view controllers with URLs, you'll have to implement application:didFinishLaunchingWithOptions:
method.
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?
) -> Bool {
// ...
if let url = launchOptions?[.url] as? URL {
if let opened = navigator.open(url)
if !opened {
navigator.present(url)
}
}
return true
}
Implementing AppDelegate Open URL Method
You'll might want to implement custom URL open handler. Here's an example of using URLNavigator with other URL open handlers.
func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
// If you're using Facebook SDK
let fb = FBSDKApplicationDelegate.sharedInstance()
if fb.application(application, open: url, sourceApplication: sourceApplication, annotation: annotation) {
return true
}
// URLNavigator Handler
if navigator.open(url) {
return true
}
// URLNavigator View Controller
if navigator.present(url, wrap: UINavigationController.self) != nil {
return true
}
return false
}
Passing Extra Values when Pushing, Presenting and Opening
let context: [AnyHashable: Any] = [
"fromViewController": self
]
Navigator.push("myapp://user/10", context: context)
Navigator.present("myapp://user/10", context: context)
Navigator.open("myapp://alert?title=Hi", context: context)
Defining custom URL Value Converters
You can define custom URL Value Converters for URL placeholders.
For example, the placeholder <region>
is only allowed for the strings ["us-west-1", "ap-northeast-2", "eu-west-3"]
. If it doesn't contain any of these, the URL pattern should not match.
Add a custom value converter to the [String: URLValueConverter]
dictionary on your instance of Navigator
.
navigator.matcher.valueConverters["region"] = { pathComponents, index in
let allowedRegions = ["us-west-1", "ap-northeast-2", "eu-west-3"]
if allowedRegions.contains(pathComponents[index]) {
return pathComponents[index]
} else {
return nil
}
}
With the code above, for example, myapp://region/<region:_>
matches with:
-
myapp://region/us-west-1
-
myapp://region/ap-northeast-2
-
myapp://region/eu-west-3
But it doesn't match with:
-
myapp://region/ca-central-1
For additional information, see the implementation of default URL Value Converters.
License
URLNavigator is under MIT license. See the LICENSE file for more info.
最近版本更新:(数据更新于 2024-10-08 14:35:47)
2023-07-10 01:59:52 2.5.1
2023-07-10 01:59:22 2.5.0
2022-06-19 16:39:59 2.4.1
2022-06-19 16:23:00 2.4.0
2019-11-06 23:16:05 2.3.0
2019-04-02 18:17:45 2.2.0
2018-09-26 19:21:31 2.1.0
2018-06-11 07:03:04 2.0.6
2018-04-27 16:33:35 2.0.5
2017-12-01 15:57:32 2.0.4
主题(topics):
deeplink, ios, routing, swift
devxoul/URLNavigator同语言 Swift最近更新仓库
2024-12-21 13:48:53 argmaxinc/WhisperKit
2024-12-19 06:06:30 stripe/stripe-ios
2024-12-16 23:43:56 wordpress-mobile/WordPress-iOS
2024-12-04 20:33:05 Artificial-Pancreas/iAPS
2024-12-03 10:12:09 utmapp/UTM
2024-11-25 23:11:48 Alamofire/Alamofire