Skip to content

Latest commit

 

History

History
377 lines (255 loc) · 10.1 KB

README.md

File metadata and controls

377 lines (255 loc) · 10.1 KB
Raw

Platform CocoaPods Compatible Carthage Compatible License

WXNavigationBar

WeChat NavigationBar

Features

  • Support transparent navigationbar
  • Support navigationbar background image
  • Support navigationbar large title mode
  • Support iOS 13 dark mode
  • Support fullscreen pop gesture
  • As Simple as using UINavigationBar

Requirements

  • iOS 9.0+
  • Xcode 11.0+
  • Swift 5.0+

Installation

CocoaPods

WXNavigationBar is available through CocoaPods. To install it, simply add the following line to your Podfile:

use_frameworks!

pod 'WXNavigationBar', '~> 2.3.6'

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate WXNavigationBar into your Xcode project using Carthage, specify it in your Cartfile:

github alexiscn/WXNavigationBar

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler. It is in early development, but WXNavigationBar does support its use on supported platforms.

Once you have your Swift package set up, adding WXNavigationBar as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
    .package(url: "https://github.com/alexiscn/WXNavigationBar.git", .upToNextMajor(from: "2.3.6"))
]

Design Principle

WXNavigation make the actual UINavigationBar transparent and add a view as a fake navigation bar to the view controller.

The actual navigation bar still handles the touch events, the fake navigation bar do the display staffs, eg: backgroundColor, backgroundImage.

So you use navigation bar as usual. when you want to handle the display things, you use WXNavigationBar

Getting Started

In your AppDelegate.swift

import WXNavigationBar

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // ...    
    WXNavigationBar.setup()
}

You can customize WXNavigationBar if needed. There are two ways to configure WXNavigationBar: via WXNavigationBar.NavBar or via UIViewController properties.

UINavigationController based configuration

Using WXNavigationBar.NavBar to configure WXNavigationBar will effect all viewcontrollers.

In your AppDelegate.swift

import WXNavigationBar

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // ...
    
    // Customize WXNavigationBar if needed (Optional)
    // WXNavigationBar.NavBar.backImage = UIImage(named: "xxx")
}

You can configure following options:

/// Back Image for Navigation Bar
public static var backImage: UIImage? = Utility.backImage

/// Use custom view to create back button.
/// Note: You do not need to add tap event to custom view. It's handled in WXNavigationBar.
public static var backButtonCustomView: UIView? = nil
        
/// Background Image for NavigationBar
public static var backgroundImage: UIImage? = nil

/// Background color for NavigationBar
public static var backgroundColor: UIColor = UIColor(white: 237.0/255, alpha: 1.0)

/// Tint Color for NavigationBar
public static var tintColor = UIColor(white: 24.0/255, alpha: 1.0)

/// Shadow Image for NavigationBar
public static var shadowImage: UIImage? = UIImage()

/// Enable fullscreen pop gesture
public static var fullscreenPopGestureEnabled = false

ViewController based configuration

You can also configure specific view controller by override properties that WXNavigationBar supported.

Background Color

You can configure background color of navigation bar.

/// Background color of fake NavigationBar
/// Default color is UIColor(white: 237.0/255, alpha: 1.0)
override var wx_navigationBarBackgroundColor: UIColor? {
    return .white
}

Background Image

You can confgiure navigation bar background using image.

override var wx_navigationBarBackgroundImage: UIImage? {
    return UIImage(named: "icons_navigation_bar")
}

System blur navigation bar

If you want to use system alike blured navigation bar:

override var wx_useSystemBlurNavBar: Bool {
    return true
}

NavigationBar bar tint color

By setting wx_barBarTintColor, you actually setting barTintColor of navigationController?.navigationBar

override var wx_barBarTintColor: UIColor? {
    return .red
}

NavigationBar tint color

By setting wx_baTintColor, you actually setting tintColor of navigationController?.navigationBar

override var wx_barTintColor: UIColor? {
    return .black
}

Shadow Image

You can specify navigation bar shadow image for specific view controller(eg: solid color line or gradient color line):

override var wx_shadowImage: UIImage? {
    return UIImage(named: "icons_navigation_bar_shadow_line")
}

Shadow Image Tint Color

You can create shadow image from color, this property will overwrite wx_shadowImage

override var wx_shadowImageTintColor: UIColor? {
    return .red
}

Back Button Image

You can specify navigation bar back image for specific view controller:

override var wx_backImage: UIImage? {
    return UIImage(named: "icons_view_controller_back_image")
}

Back Button Custom View

You can specify back button with custom view:

override var wx_backButtonCustomView: UIView? {
    let label = UILabel()
    label.text = "back"
    label.textAlignment = .center
    return label
}

Disable Interactive Pop Gesture

override var wx_disableInteractivePopGesture: Bool {
    return true
}

fullscreen interactive pop gesture

override var wx_fullScreenInteractivePopEnabled: Bool {
    return false
}

interactivePopMaxAllowedDistanceToLeftEdge

override wx_interactivePopMaxAllowedDistanceToLeftEdge: CGFloat {
    return view.bounds.width * 0.5
}

Advance usage

Here is some advance usage suggestions for WXNavigationBar.

Transparent Navigation Bar

There are several ways to make navigation bar transparent.

alpha
wx_navigationBar.alpha = 0
hidden
wx_navigationBar.isHidden = true
background color
override var wx_navigationBarBackgroundColor: UIColor? {
    return .clear
}

alpha and hidden make wx_navigationBar invisible, while backgroundColor just change the color of wx_navigationBar

Dynamic update navigation bar

You can dynamically update navigation bar, such as dynamically update while scrolling.

See MomentViewController for details.

wx_navigationBar

wx_navigationBar is a subclass of UIView, so you can do anything with wx_navigationBar that can be done with UIView.

Handle back button event

If you want to do something when user tap back button, you can override wx_backButtonClicked in your view controller. For example, you can present alert when user tap back button.

override func wx_backButtonClicked() {
    let alert = UIAlertController(title: "Are you sure to exit", message: nil, preferredStyle: .alert)
    alert.addAction(UIAlertAction(title: "OK", style: .default, handler: { [weak self] _ in
        self?.navigationController?.popViewController(animated: true)
    }))
    alert.addAction(UIAlertAction(title: "Cancel", style: .cancel, handler: { _ in
        
    }))
    present(alert, animated: true, completion: nil)
}

Notes

Child View Controller

wx_navigationBar can be overlaid when you dynamically add child view controller. So it's your responsibility to bring wx_navigationBar to front.

// addChild(controller) or addSubview

view.bringSubviewToFront(wx_navigationBar)

License

WXNavigationBar is MIT-licensed. LICENSE

中文文档

你可以参考中文文档