Customize the navigation bar in iOS

Basic concepts

Navigation bar elements

Navigation bar elements are located in three main areas. Customizing the navigation bar usually involves changing these areas:

1. back: The back button area. The mPaaS page base class creates this area. By default, it displays a back arrow and back text.

2. title/subTitle: The title bar area. It is hidden by default. To display it, you can call the system method to set the page title.

3. optionMenu: The page menu options area. It is hidden by default. To display it, you can call the system method to set the rightNavigationItem for the current page.

Navigation bar structure

• For applications created in the mPaaS framework, the default UI structure is window/navigationController > tabViewController > a viewController embedded in each tab. The root view controller of the main application window is a UINavigationController object. The root view controller of this UINavigationController is a UITabViewController.

• In this UI structure, the entire application has only one global navigationController. Therefore, all pages share the same navigation bar, which is an APNavigationBar instance by default.

  

• To ensure a consistent navigation bar style across all pages, every view controller (VC) in an mPaaS application must inherit from DTViewController. This applies to both native and H5 pages.

• The default theme for applications created in the mPaaS framework has a white background with black text and blue buttons:

  

Customize the application theme

Every application has its own theme. To change the default theme of an mPaaS application, follow these steps:

• To change the background color, back button area, or title area of the navigation bar, you can override the au_defaultTheme_extraInfo method of the AUThemeManager class and change the return values for the following keys.

  • Method

    @interface AUThemeManager(AUExtendinfo)
    /* The Alipay client has a default theme. A standalone app can modify this default value.
    * This method only needs to return the key-value pairs that are different from the default theme. Use the keys defined in AUTheme.h.
    */
    +(NSDictionary *)au_defaultTheme_extraInfo;
    
    @end
    /*
    *  For example
    *  +(NSDictionary*)au_defaultTheme_add_Info
    *  {
    *    NSMutableDictionary *dict = [INSMutableDictionary alloc] init];
    *    dictITITLEBAR_BACKGROUND_COLOR] = AU_COLOR_APP_GREEN; // Background color of AUTitleBar
    *    dit[TITLEBAR TITLE TEXTCOLOR1 = [UIColor redColor];   // Title color of AUTitleBar
    *    ...
    *    return dict;
    *  }
    */

  • Code example

    @implementation AUThemeManager (Portal)
    
    + (NSDictionary *)au_defaultTheme_extraInfo
    {
        NSMutableDictionary *dict = [[NSMutableDictionary alloc] init];
        dict[TITLEBAR_BACKGROUND_COLOR] = @"COLOR(#108EE9,1)"; // Navigation bar background color
        dict[TITLEBAR_LINE_COLOR] = @"COLOR(#108EE9,1)";       // Color of the line separator or edge at the bottom of the navigation bar
        dict[TITLEBAR_TITLE_TEXTCOLOR] = @"COLOR(#ffffff,1)";  // Navigation bar title color
        dict[TITLEBAR_TITLE_TEXTSIZE_BOLD] = @"FONT(18)";      // Navigation bar title size
        dict[TITLEBAR_TEXTCOLOR] = @"COLOR(#ffffff,1)";        // Navigation bar back button color
    
        return dict;
    }
    
    @end
    }

    Note

    The color value must be in the format COLOR(#108EE9,1). Otherwise, an error occurs.

• To change the back button image in the theme, you can override the au_default_backButtonImg method of the AUBarButtonItem class.

  • API method

    #import "AUUILoadDefine.h"// Automatically generated by the program
    #ifdef ANTUI_UI_TitleBar_AUBarButtonltem// Automatically generated by the program
    //
    // AUBarButtonltem+AUExtendInfo.h
    // AntUI
    //
    // Copyright © 2017 Alipay. All rights reserved.
    //
    #import "AUBarButtonltem.h"
    
    @interface AUBarButtonltem(AUExtendInfo)
    
    // The Alipay back button is a blue icon by default. Standalone apps can change the default back button icon.
    +(UIImage *)au_default_backButtonImg;
    
    @end

  • Code example

    @implementation AUBarButtonItem (CGBBarButtonItem)
    
    + (UIImage *)au_default_backButtonImg
    {
        // Customize the back button image
        return  APCommonUILoadImage(@"back_button_normal_white");
    
    }
    @end

• You can also change the style and text of the back button for all pages.

Customize the navigation bar for a specific page

In addition to customizing the theme, you can also customize the navigation bar for a specific page. For example, you can change the background color or the back button style. mPaaS provides different methods for these customizations, depending on when you apply the changes.

• Before the page loads: To change the navigation bar color from the default value, you can implement the methods defined in DTNavigationBarAppearanceProtocol within the page's view controller. This lets you change the color of a specific area.

  • Interface method

    @protocol DTNavigationBarAppearanceProtocol<NSObject>
    
    @optional
    
    /** Specifies whether this DTViewController should automatically hide the navigationBar. The default value is NO. To hide the NavigationBar for a specific ViewController, override this method and return YES.
    **/
    -(BOOL)autohideNavigationBar;
    
    /** After hiding the navigation bar for the current VC, to set a fully transparent navigation bar and set the back button text consistent with the framework logic for the current page, override this method and return an APCustomNavigationView instance.
    **/
    -(UIView *)customNavigationBar;
    
    /** If a viewcontroller's titlebar should be opaque with a specific color, override this method and return the desired color.
    * This is only for VCs that are pushed. VCs in a tabbar cannot change the translucency property of the navigationBar.
    */
    -(UIColor *)opaqueNavigationBarColor;
    
    /**
     *  If a viewcontroller needs to change the status bar style, override this method and return the desired style.
     */
    - (UIStatusBarStyle)customStatusBarStytle;
    
    /**
     *  If a viewcontroller needs to change the navigation bar title color, override this method and return the desired color.
     */
    - (UIColor *)customNavigationBarTitleColor;

  • Code example

    #pragma mark DTNavigationBarAppearanceProtocol: Change the navigation bar style when entering the page
    - (UIColor *)opaqueNavigationBarColor
    {
        // Set the navigation bar background color of the current page to red
        return [UIColor redColor];
    
    //    // Make the navigation bar of the current page transparent
    //    return [UIColor colorWithRGB:0xff0000 alpha:0];
    }
    
    - (BOOL)autohideNavigationBar
    {
        // Set whether to hide the navigation bar of the current page
        return NO;
    }
    
    - (UIStatusBarStyle)customStatusBarStytle
    {
        // Set the status bar style for the current page
        return UIStatusBarStyleDefault;
    }
    
    - (UIColor *)customNavigationBarBackButtonTitleColor
    {
        // Set the back button text color for the current page
        return [UIColor greenColor];
    }
    
    - (UIImage *)customNavigationBarBackButtonImage
    {
        // Set the back button image for the current page
        return APCommonUILoadImage(@"back_button_normal_white");
    }
    
    - (UIColor *)customNavigationBarTitleColor
    {
        // Set the title color for the current page
        return [UIColor greenColor];
    }

• After the page opens: To dynamically change the navigation bar style during user interaction, you can modify different areas. Examples include creating a gradient background color on scroll or changing the right menu buttons. The methods are grouped by the area they modify:

  • Background area: You can hide or show the navigation bar, make it transparent, change its background color, or change the status bar color.

    - (void)gotoHideNavigator
    {
        // Hide the navigation bar
        [self.navigationController.navigationBar setHidden:YES];
    }
    
    - (void)gotoShowNavigator
    {
        // Show the navigation bar
        [self.navigationController.navigationBar setHidden:NO];
    }
    
    - (void)gotoTransparency
    {
        // Make the navigation bar transparent
        [self.navigationController.navigationBar setNavigationBarTranslucentStyle];
    }
    
    - (void)gotoUpdateBackgroundColor
    {
        // Change the navigation bar background color
        [self.navigationController.navigationBar setNavigationBarStyleWithColor:[UIColor whiteColor] translucent:NO];
        [self.navigationController.navigationBar setNavigationBarBottomLineColor:[UIColor whiteColor]];
    }
    
    - (void)gotoUpdateStatusBarStyle
    {
        // Change the status bar color
        [[UIApplication sharedApplication] setStatusBarStyle:UIStatusBarStyleLightContent];
    }

  • Back button area: You can change the default back button's text color, change the default back button's arrow style, or completely reset the back button's style.

    - (void)gotoUpdateBackTitleColor
    {
        // Change the default back button text color
        NSArray *leftBarButtonItems = self.navigationItem.leftBarButtonItems;
        if ([leftBarButtonItems count] == 1) {
            if (leftBarButtonItems[0] && [leftBarButtonItems[0] isKindOfClass:[AUBarButtonItem class]]) {
                AUBarButtonItem *backItem = leftBarButtonItems[0];
                backItem.titleColor = [UIColor blackColor];
            }
        }
    }
    
    - (void)gotoUpdateBackImage
    {
        // Change the default back button arrow style
        NSArray *leftBarButtonItems = self.navigationItem.leftBarButtonItems;
        if ([leftBarButtonItems count] == 1) {
            if (leftBarButtonItems[0] && [leftBarButtonItems[0] isKindOfClass:[AUBarButtonItem class]]) {
                AUBarButtonItem *backItem = leftBarButtonItems[0];
                backItem.backButtonImage = APCommonUILoadImage(@"back_button_normal");
            }
        }
    }
    
    - (void)gotoUpdateBackItem
    {
        // Reset the back button style
        self.navigationItem.leftBarButtonItem = [AUBarButtonItem barButtonItemWithImageType:AUBarButtonImageTypeDelete target:self action:@selector(onClickBack)];
    }
    
    - (void)onClickBack
    {
        [self.navigationController popViewControllerAnimated:YES];
    }

  • Title area: You can change the default title color, set a main title and a subtitle, or display an image as the title.

    - (void)gotoUpdateTitleColor
    {
        // Change the title color
        [self.navigationController.navigationBar setNavigationBarTitleTextAttributesWithTextColor:[UIColor blackColor]];
    }
    
    - (void)gotoTwoTitle
    {
        // Change the title style: main title and subtitle
        self.navigationItem.titleView = [[AUDoubleTitleView alloc] initWithTitle:@"Main Title" detailTitle:@"Subtitle"];
    }
    
    - (void)gotoTitleImage
    {
        // Change the title style: image
        UIImageView *imageView = [[UIImageView alloc] initWithImage:APCommonUILoadImage(@"ilustration_ap_expection_alert")];
        imageView.frame = CGRectMake(0, 0, self.self.view.width-100, 64);
        self.navigationItem.titleView = imageView;
    }

  • Menu area: You can set one or more menu buttons on the right.

    - (void)gotoSetOptionMenu
    {
        // Set a single button on the right
        self.navigationItem.rightBarButtonItem = [AUBarButtonItem barButtonItemWithImageType:AUBarButtonImageTypeGroupChat target:self action:@selector(onClickRightItem)];
    }
    
    - (void)gotoSetTwoOptionMenu
    {
        // Set two buttons on the right
        AUBarButtonItem *item1 = [AUBarButtonItem barButtonItemWithImageType:AUBarButtonImageTypeGroupChat target:self action:@selector(onClickRightItem)];
        AUBarButtonItem *item2 = [AUBarButtonItem barButtonItemWithImageType:AUBarButtonImageTypeHelp target:self action:@selector(onClickRightItem)];
        self.navigationItem.rightBarButtonItems = @[item1, item2];
    }

• Immersive navigation bar: An immersive navigation bar is transparent when the page opens and becomes opaque when the user scrolls to a certain position. To create one, you can follow two main steps:

  • Make the navigation bar transparent when the page loads. To do this, you can override the following method in the page's view controller.

    - (UIColor *)opaqueNavigationBarColor
      {
          // Make the navigation bar of the current page transparent
          return [UIColor colorWithRGB:0xff0000 alpha:0];
      }

  • When the page scrolls to a specific position, you can change the style of the navigation bar's background, back button, title, and menu areas.

      - (void)gotoUpdateBackgroundColor
      {
          // Change the navigation bar background color
          [self.navigationController.navigationBar setNavigationBarStyleWithColor:[UIColor whiteColor] translucent:NO];
          [self.navigationController.navigationBar setNavigationBarBottomLineColor:[UIColor whiteColor]];
      }
    
      - (void)gotoUpdateBackTitleColor
      {
          // Change the default back button text color
          NSArray *leftBarButtonItems = self.navigationItem.leftBarButtonItems;
          if ([leftBarButtonItems count] == 1) {
              if (leftBarButtonItems[0] && [leftBarButtonItems[0] isKindOfClass:[AUBarButtonItem class]]) {
                  AUBarButtonItem *backItem = leftBarButtonItems[0];
                  backItem.titleColor = [UIColor blackColor];
              }
          }
      }
    
      - (void)gotoUpdateTitleColor
      {
          // Change the title color
          [self.navigationController.navigationBar setNavigationBarTitleTextAttributesWithTextColor:[UIColor blackColor]];
      }