Customize action sheets

2025-06-04 02:32

The super app can customize the appearance of action sheets within mini programs to ensure a consistent user interface. An action sheet appears when a mini program invokes the my.showActionSheet JSAPI, presenting users with a set of contextual actions related to a specific item or task. It supports the following elements on iOS:

A title (displays if provided by the mini program)
Multiple action options
Badges around action options (display if provided by the mini program)
A cancel button

Default user interface

By default, an action sheet appears as a bottom sheet. It displays the title at the top, followed by a list of action options, with optional red badges on their right sides, and then a cancel button at the bottom. The following figure shows an example of the default UI:

Before you begin

To customize the user interface for action sheets, ensure that the integrated iOS IAPMiniProgram SDK is version 2.67.0 or later. For more information, see SDK release notes.

Procedure

To customize action sheets, take the following two steps:

Step 1: Implement `GRVActionSheetDelegate`

Define a class that implements the GRVActionSheetDelegate protocol. Within the class, implement the showActionSheet method to customize an action sheet. Refer to the following code for a sample implementation. For more information about the protocol and its defined method, refer to GRVActionSheetDelegate.

copy
class DemoActionSheetImpl: NSObject, GRVActionSheetDelegate {
    func showActionSheet(with param: GRVActionSheetParam, finishHandler: @escaping (Int) -> Void, cancelHandler: @escaping () -> Void) {
        // Implement the logic to build a custom action sheet
    }
}

Step 2: Configure `actionSheetDelegate`

After initializing the SDK, create an instance of GRVExtensionDelegate and assign the implementation (for example, DemoActionSheetImpl in the sample) to the actionSheetDelegate property of the delegate's uiProvider. Refer to the following sample configuration code:

copy
let extensionDelegate = GRVExtensionDelegate()
extensionDelegate.uiProvider.actionSheetDelegate = DemoActionSheetImpl()

Protocol

GRVActionSheetDelegate

The GRVActionSheetDelegate protocol defines a method for the super app to customize an action sheet, which the SDK then calls to render the custom sheet. Refer to the following code for the protocol definition:

copy
@protocol GRVActionSheetDelegate <NSObject>

- (void)showActionSheetWithParam:(GRVActionSheetParam *)param
                   finishHandler:(void(^)(NSInteger selectedIndex))finishHandler
                   cancelHandler:(void(^)(void))cancelHandler;

@end

The following table lists the details of the defined method:

Method	Required	Description
showActionSheetWithParam:finishHandler:cancelHandler:	Yes	Called by the SDK to render a custom action sheet. For more information, refer to `showActionSheetWithParam:finishHandler:cancelHandler:`.

showActionSheetWithParam:finishHandler:cancelHandler:

The showActionSheetWithParam:finishHandler:cancelHandler: method has the following input parameters whose values are passed by the SDK:

Parameter	Data type	Required	Description
param	GRVActionSheetParam object	Yes	An object that contains the configuration for a custom action sheet.
finishHandler	Function	Yes	A callback that is triggered when the user completes a selection, returning the selected action. For more information about the return value, refer to `finishHandler`.
cancelHandler	Function	Yes	A callback that is triggered when the user dismisses the action sheet without a selection.

GRVActionSheetParam

The GRVActionSheetParam object is defined as follows:

copy
@class GRVActionSheetItem;
@interface GRVActionSheetParam : NSObject

@property (nonatomic, weak) UIViewController *currentViewController;
@property (nonatomic, copy, nullable) NSString *title;
@property (nonatomic, copy) NSArray<GRVActionSheetItem *> *items;
@property (nonatomic, copy, nullable) UIColor *itemColor;
@property (nonatomic, copy) NSString *cancelButtonText;
@property (nonatomic, assign) NSUInteger destructiveBtnIndex;

@end

typedef NS_ENUM(NSUInteger, GRVActionSheetBadgeType) {
    GRVActionSheetBadgeTypeNone,
    GRVActionSheetBadgeTypePoint,
    GRVActionSheetBadgeTypeNum,
    GRVActionSheetBadgeTypeText,
    GRVActionSheetBadgeTypeMore,
};

@interface GRVActionSheetItem : NSObject
@property (nonatomic, copy) NSString *itemText;
@property (nonatomic, assign) GRVActionSheetBadgeType badgeType;
@property (nonatomic, copy, nullable) NSString *badgeText;

@end

The following table lists the parameter details of this object:

Parameter	Data type	Required	Description
currentViewController	UIViewController	No	A weak reference to the view controller that displays and manages the action sheet. The SDK typically passes this controller, but it might become deallocated.
title	NSString	No	The title of the action sheet. Specified only if provided by the mini program.
items	NSArray<GRVActionSheetItem *>	Yes	A list of available actions on the action sheet.
itemColor	UIColor	No	The color of the action text in hexadecimal RGB or ARGB format (e.g., `#RRGGBB` or `#AARRGGBB`). Note: The super app must specify a default color to display the action text. It is recommended to use `#000000` (black) to align with the my.showActionSheet JSAPI specification.
cancelButtonText	NSString	Yes	The text displayed on the cancel button.
destructiveBtnIndex	NSUInteger	Yes	The index (starting from `0`) of the destructive action (e.g., delete) in the items array. This action needs a visual highlight. If the value is set to `-1`, no action is destructive. Note: For the destructive action style, it is recommended to highlight the action text in red to align with the my.showActionSheet JSAPI specification.

GRVActionSheetItem

Parameter	Data type	Required	Description
itemText	NSString	Yes	The text for the action.
badgeType	GRVActionSheetBadgeType	Yes	The type of badge displayed next to the action. Valid values are: `GRVActionSheetBadgeTypeNone`: No badge. `GRVActionSheetBadgeTypePoint`: A solid red point. `GRVActionSheetBadgeTypeNum`: A solid red point with a number. `GRVActionSheetBadgeTypeText`: A solid red point with text. `GRVActionSheetBadgeTypeMore`: A solid red point with an ellipsis (...), typically indicating that some additional options might follow. For visual illustrations of different badges, refer to the figure in Default user interface. Note: It is recommended to create badges based on the value description to align with the my.showActionSheet JSAPI specification.
badgeText	NSString	No	The text displayed within a badge. Specified only if badgeType is `GRVActionSheetBadgeTypeText` or `GRVActionSheetBadgeTypeNum`.

finishHandler

Parameter	Data type	Required	Description
selectedIndex	NSInteger	Yes	The index (starting from `0`) of the action selected the user in the items array.