Alipay International Mini Program Development PlatformAlipay International Mini Program Development PlatformDOCS

GRVNavigationBackHomeButtonItemProtocol

IAPMiniProgram SDK provides the ability to customize the style of the Back to the homepage button in the title bar of the mini program, so that the Super App can use its own text or image to customize and render this button of the mini programs accordingly.

Follow this topic to realize this customization ability by implementing the specific interface of IAPMiniProgram SDK.

Procedures

Step 1. Implement the GRVNavigationBackHomeButtonItemProtocol protocol

Implement the GRVNavigationBackHomeButtonItemProtocol protocol and write code in the required methods according to your business logic.

Code sample as follows:

copy
class BackHomeButtonCustomization: NSObject, GRVNavigationBackHomeButtonItemProtocol {
    func itemContentType() -> GRVNavigationItemContentType {
        // return the customization type (icon/text)
    }

    func image() -> UIImage? {
        // if itemContentType is image，return the image
    }

    func text() -> String? {
        // if itemContentType is text，return the text
    }
}

Step 2. Configure the GRVNavigationBackHomeButtonItemProtocol protocol

Refer to the following sample code. Configure the GRVExtensionDelegate interface to register the GRVNavigationBackHomeButtonItemProtocol after initializing the SDK.

copy
let extensionDelegate = GRVExtensionDelegate()
extensionDelegate.uiProvider.backHomeButtonItemSetting = BackHomeButtonCustomization()

Then you can view the following screenshots for user experience.

Protocols

GRVNavigationBackHomeButtonItemProtocol protocol

The definition of the GRVNavigationBackHomeButtonItemProtocol interface is shown in the following codes:

copy
/**
* A protocol to customize the behavior and appearance of a back-to-home button in a navigation bar.
*
* This protocol allows developers to dynamically define the content type (text or image) of the back-home button
* and provide the corresponding display content.
**/
@protocol GRVNavigationBackHomeButtonItemProtocol <NSObject>

/// Returns the content type of the backHome button (text or image).
///
/// - Returns: `GRVNavigationItemContentText` or `GRVNavigationItemContentImage`.
/// - Discussion:
///   This method must be implemented. Based on the returned value, the framework will decide to call `text` or `image`
///   to fetch the display content. If the returned value does not align with the actual implementation of `text`/`image`,
///   it may lead to runtime errors.
- (GRVNavigationItemContentType)itemContentType;

@optional

/// Returns the text content of the button (valid only when `itemContentType` is `GRVNavigationItemContentText`).
///
/// - Returns: The text to display, which can be `nil` (but non-nil is recommended).
/// - Discussion:
///   - Must return a non-nil value when `itemContentType == GRVNavigationItemContentText`.
///   - This method should not be called if `itemContentType` is `GRVNavigationItemContentImage`.
///   - Returns `nil` by default, but ensure logical consistency in your implementation.
- (NSString * _Nullable)text;

/// Returns the image content of the button (valid only when `itemContentType` is `GRVNavigationItemContentImage`).
///
/// - Returns: The image to display, which can be `nil` (but non-nil is recommended).
/// - Discussion:
///   - Must return a non-nil value when `itemContentType == GRVNavigationItemContentImage`.
///   - This method should not be called if `itemContentType` is `GRVNavigationItemContentText`.
///   - Returns `nil` by default, but ensure logical consistency in your implementation.
- (UIImage * _Nullable)image;

@end

Methods

Based on the definition, this protocol provides the following methods:

Method

Description

itemContentType

This method returns the customized style of the Back to the homepage button. The following types of style (return value) are supported:

  • GRVNavigationItemContentText: the customized text is displayed for the button.
  • GRVNavigationItemContentImage: the customized image is displayed for the button.

Note: If other value is returned, this customization ability does not take effect.

text

This method is called when the return value of the itemContentType method is GRVNavigationItemContentText.

image

This method is called when the return value of the itemContentType method is GRVNavigationItemContentImage.

itemContentType method

The return value of this method is GRVNavigationItemContentType , which supports the following choices:

  • GRVNavigationItemContentText: indicates the customized text.
  • GRVNavigationItemContentImage: indicates the customized image.
copy
/// Defines the content type of a navigation item.
typedef NS_ENUM(NSUInteger, GRVNavigationItemContentType) {
    /// The item content is plain text.
    GRVNavigationItemContentText,

    /// The item content is an image.
    GRVNavigationItemContentImage
};

Appendices

UI illustration

Condition

Screenshot

Default UI

default.jpg

When the button style is a customized image.

icon.jpg

When the back button style is a customized text, e.g. "Home"

text.jpg