Maui-AppActions.Icons.Maui

[删除(380066935@qq.com或微信通知)]

AppActions.Icons.Maui

A .NET MAUI library that provides some default icons for AppActions without having to create your own.

adenearnshaw/AppActions.Icons.Maui: A .NET MAUI library that provides some default icons for AppActions without having to create your own. (github.com)

Features

Based on iOS' Home Screen Quick Action Icons, this library provides similar icons for both Android & Windows, but styled towards the platforms default design style. Also supports the use of SFSymbols as Icons on iOS.

Hero image of icons

  • Out-of-the-box icons available for Android, iOS & Windows
  • Use SF Symbols on iOS
  • Customise Android icons with brand colors
  • Builds on top of the Maui Essentials api
  • Specify different image names per platform

Getting Started

  1. Add the AppActions.Icons.Maui nuget package to your MAUI project.

  2. Setup you app actions as per the Maui Documentation

  3. In your MauiProgram.CreateMauiApp(), add UseAppActionIcons() to your Essentials configuration builder.

    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureEssentials(essentials =>
            {
                essentials
                    .UseAppActionIcons() // Add this line
                    .AddAppAction("home_sc", "Home", icon: AppActionIcon.Home)
                    .OnAppAction(App.HandleAppActions);
            });
    
        return builder.Build();
    }
  4. Now set the AppAction's icon property using one of the provided AppActionIcon options.

Using SF Symbols

Declare an SF Symbol for iOS and use your own custom icon on other platforms

  1. Replace the icon property value with SystemSymbol() passing in the SF Symbol name.

    .AddAppAction("record_sc", "Record", icon: new SystemSymbol("mic.circle.fill"))

    On non-iOS platforms the periods (.) in the name are replaced with underscores (_). So mic.circle.fill will need a custom Android/Windows image called mic_circle_fill.

  2. Add your icon for other platforms into the Resources\Images folder.

Using SF Symbols with AppActionIcon fallback

Declare an SF Symbol for iOS and use one of the other provided icons for other platforms

  1. Use the PlatformString() to set specific icons for each platform within SystemSymbol

    .AddAppAction("pause_sc", "Pause", icon: new SystemSymbol(new PlatformString(AppActionIcon.Prohibit, ios: "pause.circle.fill")))

    This will use the default Pause icon on Window & Android. On iOS, this will use the SF Symbol of a filled circle with an pause icon in it.

Using a different icon per platform

The PlatformString can be used independently of SystemSymbol to be able to declare custom icons for each platform

  1. Use the PlatformString() to set specific icons for each platform

    .AddAppAction("stop_sc", "Stop", icon: new PlatformString("quicklaunch_stop", android: "ic_app_action_stop", ios: "quickaction_stop"))

Customise the icon colors on Android

Each Android icon uses a VectorDrawable and as such, the colors of the icon and the circle's background are variables that can be overriden.

  1. In your app's Platforms\Android\Resources\values\colors.xml file, add additional properties for appActionBackground and appActionForeground.

    <?xml version="1.0" encoding="utf-8"?>
    <resources>
        ...
    
        <color name="appActionBackground">#E6DFFC</color>
        <color name="appActionForeground">#512BD4</color>
    </resources>

    When set the icons will change from the default gray color to those of your choosing.

    Example of custom icon color

Creating a custom icon

Each platform has different specifications for the icons needed for shortcuts.

Android

Android Icon Dimensions
Width48px
Height48px

Along with PNGs and JPGs, Android also supports VectorDrawables. A sample icon can be found here

iOS

iOS Icon Dimensions
Width35px
Height35px

Images should be added to the AssetCatalog with the Render As: option set to Template Image

ImageSet with Render Mode set to Template Image

Windows

Windows Icon Dimensions
Width44px
Height44px

Troubleshooting

Opening links in the same Android instance each time

If the app is backgrounded and a shortcut is tapped, your app may relaunch and re-initialized the App from scratch, wiping any existing navigation backstack. This is caused by the MainActivity recreating itself when coming in via the IntentFilter. To re-launch the app in the same instance that was backgrounded add the following property to the Activity attribute in your MainActivity

LaunchMode = LaunchMode.SingleTask