# Setting the Mini-Program Top Navigation Bar

# 1. Effect Preview

# 2. Method for Replacing the Left Back Button

# 2.1 Scope of Application

This setting is implemented by the Host-App. Once set, all Mini-Programs, Mini-Games, and H5 applications within the Host-App will adopt this effect.

# 2.2 iOS Setup Method

Simply place a PNG image named fin_btn_navi_back in the project, ensuring the image is correctly accessible via the mainBundle.

# 2.3 Android Setup Method

When initializing the SDK, you can configure the image resource file for the back button. Example code is as follows:

FinAppConfig.UIConfig uiConfig = new FinAppConfig.UIConfig();
// Set the back button image resource file
uiConfig.setNavigateBarBackImageRes(backImageRes);
// Initialize the SDK
FinAppConfig finAppConfig = new FinAppConfig.Builder()
        .setUiConfig(uiConfig)
        // Other configurations omitted
        .build();
FinAppClient.INSTANCE.init(application, finAppConfig, callback);

Note

  • If using an image, it is recommended to use a PNG image with a [transparent background], with dimensions of 60x60.
  • The SDK will apply a black tint to the image, so the displayed back button color will be black during runtime.

# 2.4 Desktop Setup Method

When initializing the SDK, configure via the finclip_init_with_config / finclip_init_with_json functions:

  params = finclip_create_params();
  finclip_params_set("appkey", "XXXXXXXXXX");
  // ... Other required parameters
  finclip_params_set("title_bar.back.url.normal", "./res/miniapps_back_pressed.png");
  finclip_params_set("title_bar.back.url.hover", "./res/miniapps_back_normal.png");
  finclip_params_set("title_bar.back.url.pressed", "./res/miniapps_back_hover.png");
  finclip_init_with_config(appstore, params);

  // Or use a JSON string
  params = {
      "appkey": "XXXXXXXXXX",
      // ... Other required parameters
      "title_bar.back.url.normal": "./res/miniapps_back_pressed.png",
      "title_bar.back.url.hover": "./res/miniapps_back_normal.png",
      "title_bar.back.url.pressed": "./res/miniapps_back_hover.png"
    }
  finclip_init_with_json(appstore, params);

# 2.5 HarmonyOS Setup Method

When initializing the SDK, configure via UIConfig. For specific parameters, refer to INavBackConfig, as shown below:

const navBackConfig: IFinAppConfig.INavBackConfig = {
  darkImage: 'xxx', // Dark image, ResourceStr type
  lightImage: 'xxx' // Light image, ResourceStr type
}

const uiConfig: IFinAppConfig.IUIConfig = {
  navBackConfig,
}

const finAppConfig: IFinAppConfig.IFinAppConfig = {
  finStoreConfigs,
  uiConfig,
}

FinAppClient.init(finAppConfig,context,entryInfo,)

# 3. UI Customization Method for the Navigation Bar Home Button

# 3.1 Scope of Application

This setting is implemented by the Host-App. Once set, all Mini-Programs within the Host-App will adopt this effect.

Currently, the conditions for the home button to appear are (all must be met):

  1. The default navigation bar style (non-custom) is used.
  2. It is not the home page or a tabbar page (as defined in app.json).
  3. It is the bottom page in the page stack.

Mini-Programs can call hideHomeButton() in onShow to manually hide the home button.

# 3.2 iOS Setup Method

FATNavHomeConfig *navHomeConfig = [[FATNavHomeConfig alloc] init];
uiConfig.navHomeConfig = navHomeConfig;

Supported configuration properties are as follows:

@interface FATNavHomeConfig : NSObject

/**
 Width of the home button
 */
@property (nonatomic, assign) CGFloat width;

/**
 Height of the home button
 */
@property (nonatomic, assign) CGFloat height;

/**
 Left margin of the home button, default value is 10
 */
@property (nonatomic, assign) CGFloat leftMargin;

/**
 Corner radius of the home button, default value is 5
 */
@property (nonatomic, assign) CGFloat cornerRadius;

/**
 Border width of the home button, default value is 0.8
 */
@property (nonatomic, assign) CGFloat borderWidth;

/**
 Light image object for the home button. If not provided, the default icon will be used.
 (Dark Mode)
*/
@property (nonatomic, strong) UIImage *lightImage;

/**
 Dark image object for the home button. If not provided, the default icon will be used.
 (Light Mode)
*/
@property (nonatomic, strong) UIImage *darkImage;

/**
 Light border color for the home button
 (Dark Mode)
 */
@property (nonatomic, strong) UIColor *borderLightColor;

/**
 Dark border color for the home button
 (Light Mode)
 */
@property (nonatomic, strong) UIColor *borderDarkColor;

/**
 Light background color for the home button
 (Light Mode)
 */
@property (nonatomic, strong) UIColor *bgLightColor;

/**
 Dark background color for the home button
 (Dark Mode)
 */
@property (nonatomic, strong) UIColor *bgDarkColor;

@end

# 3.3 Android Setup Method

When initializing the SDK, configure via UIConfig, as shown below:

UIConfig.NavHomeConfig navHomeConfig = new UIConfig.NavHomeConfig();
uiConfig.setNavHomeConfig(navHomeConfig);

Supported configuration properties are as follows:

public static class NavHomeConfig {
    /**
     * Light icon for the navigation bar home button. If not provided, the default icon will be used.
     */
    public int lightImage = R.drawable.miniapps_home_light;
    /**
     * Dark icon for the navigation bar home button. If not provided, the default icon will be used.
     */
    public int darkImage = R.drawable.miniapps_home_dark;
    
    /**
     * Width of the home button, default is 44
     */
    public float width = 44;
    
    /**
     * Height of the home button, default is 32
     */
    public float height = 32;
    
    /**
     * Left margin of the home button, default is 7
     */
    public float leftMargin = 7;
    
    /**
     * Corner radius of the home button border, default is 5
     */
    public float cornerRadius = 5;
    
    /**
     * Border width of the home button, default is 1
     */
    public float borderWidth = 1;
    
    /**
     * Light border color for the home button, default is 0X80FFFFFF
     */
    public int borderLightColor = 0x80ffffff;
    
    /**
     * Dark border color for the home button, default is 0X26000000
     */
    public int borderDarkColor = 0x26000000;
    
    /**
     * Light background for the home button, default is 0x33000000
     */
    public int bgLightColor = 0x33000000;
    
    /**
     * Dark background for the home button, default is 0x33000000
     */
    public int bgDarkColor = 0x80ffffff;
}

# 3.4 HarmonyOS Setup Method

When initializing the SDK, configure via UIConfig. For specific parameters, refer to INavHomeConfig, as shown below:

const navHomeConfig: IFinAppConfig.INavHomeConfig = {
  darkImage: 'xxx', // Dark image, ResourceStr type
  lightImage: 'xxx' // Light image, ResourceStr type
}

const uiConfig: IFinAppConfig.IUIConfig = {
  navHomeConfig,
}

const finAppConfig: IFinAppConfig.IFinAppConfig = {
  finStoreConfigs,
  uiConfig,
}

FinAppClient.init(finAppConfig,context,entryInfo,)

# 4. Method for Replacing Title Style

# 4.1 Scope of Application

This setting is implemented by the Host-App. Once set, all Mini-Programs within the Host-App will adopt this effect.

This setting allows adjustment of the title font, font size, and position.

# 4.2 iOS Setup Method

When initializing the SDK, configure via UIConfig, as shown below:

// Navigation bar title text style
[FATClient sharedClient].uiConfig.navigationTitleTextAttributes[NSFontAttributeName] = [UIFont boldSystemFontOfSize:18.0f];

# 4.3 Android Setup Method

When initializing the SDK, configure via UIConfig, as shown below:

FinAppConfig.UIConfig uiConfig = new FinAppConfig.UIConfig();
// Navigation bar title text style
uiConfig.setNavigationBarTitleTextAppearance(R.style.TextAppearance_AppCompat);
// Gravity of the navigation bar title relative to the parent control
uiConfig.setNavigationBarTitleTextLayoutGravity(Gravity.CENTER);

# 4.4 Desktop Setup Method

When initializing the SDK, configure via the finclip_init_with_config / finclip_init_with_json functions:

  params = finclip_create_params();
  finclip_params_set("appkey", "XXXXXXXXXX");
  // ... Other required parameters
  finclip_params_set("title_bar.font.height", "Cascadia Mono,Cascadia Code PL,Monaco,Menlo,Courier New,monospace");
  finclip_params_set("title_bar.font.height", "22");
  finclip_params_set("title_bar.font.align", "center");
  finclip_init_with_config(appstore, params);

  // Or use a JSON string
  params = {
      "appkey": "XXXXXXXXXX",
      // ... Other required parameters
      "title_bar.font.families": "Cascadia Mono,Cascadia Code PL,Monaco,Menlo,Courier New,monospace",
      "title_bar.font.height": "22",
      "title_bar.font.align": "center",  // left/right/center
  }
  finclip_init_with_json(appstore, params);
  finclip_init_with_json(appstore, R"(//{
      "appkey": "XXXXXXXXXX",
      // ...

  }//)");

# 4.6 HarmonyOS Setup Method

When initializing the SDK, configure via UIConfig. For specific parameters, refer to INavTitleConfig, as shown below:

const navTitleConfig: IFinAppConfig.INavTitleConfig = {
  fontSize: 20, 
  fontWeight: 700,
  textAlign: 'left' 
}

const uiConfig: IFinAppConfig.IUIConfig = {
  navTitleConfig,
}

const finAppConfig: IFinAppConfig.IFinAppConfig = {
  finStoreConfigs,
  uiConfig,
}

FinAppClient.init(finAppConfig,context,entryInfo,)

# 5. Method for Removing the Background Animation When the Navigation Bar Back Button is Pressed

# 5.1 Scope of Application

This setting is implemented by the Host-App. Once set, all Mini-Programs within the Host-App will adopt this effect.

# 5.2 iOS Setup Method

When initializing the SDK, configure via UIConfig, as shown below:

None, this setting is not available on iOS.

# 5.3 Android Setup Method

When initializing the SDK, configure via UIConfig, as shown below:

FinAppConfig.UIConfig uiConfig = new FinAppConfig.UIConfig();
// Whether to clear the background of the navigation bar nav button
uiConfig.setClearNavigationBarNavButtonBackground(true);

# 6. Method for Hiding the Entire Mini-Program Navigation Bar

# 6.1 Scope of Application

This configuration is set by the Mini-Program itself. Each Mini-Program displays different effects based on its own configuration.

# 6.2 Setup Method

In the Mini-Program's app.json, modify the global window configuration.

{
  "window":{
    "navigationStyle": "hide"
  }
}

After setting, both the navigation bar and the top-right capsule will be hidden.

# 7. How to Display the Back Button on the Home Page When Using the Default Navigation Bar Style?

# 7.1 Scope of Application

This setting is implemented by the Host-App. Once set, all Mini-Programs within the Host-App will adopt this effect.

# 7.2 iOS Setup Method

When initializing the SDK, configure via UIConfig, as shown below:

None, this setting is not available on iOS.

# 7.3 Android Setup Method

When initializing the SDK, configure via UIConfig, as shown below:

FinAppConfig.UIConfig uiConfig = new FinAppConfig.UIConfig();
// Whether to always show the back button when using the default navigation bar
uiConfig.setAlwaysShowBackInDefaultNavigationBar(false);

# 7.4 HarmonyOS Setup Method

When initializing the SDK, configure via UIConfig, as shown below:

// Whether to always show the back button when using the default navigation bar
const uiConfig: IFinAppConfig.IUIConfig = {
  isAlwaysShowBackInDefaultNavigationBar: true,
}

# 8.1 Navigation Bar API

Name Function Description
ft.showNavigationBarLoading Display the navigation bar loading animation on the current page
ft.setNavigationBarTitle Dynamically set the title of the current page
ft.setNavigationBarColor Set the page navigation bar color
ft.hideNavigationBarLoading Hide the navigation bar loading animation on the current page

# 8.2 Global Configuration app.json

For details, see Global Configuration

Property Type Default Value Description
navigationBarBackgroundColor HexColor #000000 Navigation bar background color, e.g., #000000
navigationBarTextStyle String white Navigation bar title color, currently only supports black / white
navigationBarTitleText String Navigation bar title text content, should not be too long
navigationStyle String default Navigation bar style, only supports the following values: 1. default (default style), 2. custom (custom navigation bar, only the top-right button remains), 3.hide (hide navigation bar and top-right capsule)
navigationBarHideCloseButton Boolean false Hide the capsule close button
navigationBarHideMoreButton Boolean false Hide the capsule menu button

# 8.3 Page Configuration

For details, see Page Configuration

Property Type Default Value Description Minimum Version
navigationBarBackgroundColor HexColor #000000 Navigation bar background color, e.g., #000000
navigationBarTextStyle string white Navigation bar title color, only supports black / white
navigationBarTitleText string Navigation bar title text content
navigationStyle string default Navigation bar style, only supports the following values: 1. default (default style), 2. custom (custom navigation bar, only the top-right button remains), 3.hide (hide navigation bar and top-right capsule)
© FinClip with ❤ , Since 2017