Ações de aplicativo

Artigo
09/24/2024

Este artigo descreve como você pode usar a interface IAppActions do .NET MAUI (.NET Multi-platform App UI), que permite criar e responder a atalhos do aplicativo. Os atalhos do aplicativo são úteis para os usuários porque permitem que você, como desenvolvedor do aplicativo, apresente a eles maneiras extras de iniciar o aplicativo. Por exemplo, se você estivesse desenvolvendo um aplicativo de email e calendário, poderia apresentar duas ações de aplicativo diferentes, uma para abrir o aplicativo diretamente no dia atual do calendário e outra para abrir na pasta da caixa de entrada de email.

A implementação padrão da interface IAppActions está disponível por meio da propriedade AppActions.Current. A interface IAppActions e a classe AppActions estão contidas no namespace Microsoft.Maui.ApplicationModel.

Introdução

Para acessar a funcionalidade AppActions, a configuração específica da plataforma a seguir é necessária.

No arquivo Platforms/Android/MainActivity.cs, adicione as substituições OnResume e OnNewIntent à classe MainActivity e o seguinte atributo IntentFilter:

[Activity(Theme = "@style/Maui.SplashTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize | ConfigChanges.Density)]
[IntentFilter(new[] { Platform.Intent.ActionAppAction },
              Categories = new[] { global::Android.Content.Intent.CategoryDefault })]
public class MainActivity : MauiAppCompatActivity {

    protected override void OnResume()
    {
        base.OnResume();

        Platform.OnResume(this);
    }

    protected override void OnNewIntent(Android.Content.Intent intent)
    {
        base.OnNewIntent(intent);

        Platform.OnNewIntent(intent);
    }

}

Criar ações

As ações do aplicativo podem ser criadas a qualquer momento, mas geralmente são criadas quando um aplicativo é iniciado. Para configurar ações do aplicativo, invoque o método ConfigureEssentials(MauiAppBuilder, Action<IEssentialsBuilder>) no objeto MauiAppBuilder no arquivo MauiProgram.cs. Há dois métodos que você deve chamar no objeto IEssentialsBuilder para habilitar uma ação do aplicativo:

AddAppAction

Esse método cria uma ação. É necessária uma cadeia de caracteres id para identificar exclusivamente a ação e uma cadeia de caracteres title que é exibida para o usuário. Opcionalmente, você pode fornecer um subtitle e um icon.
OnAppAction

O delegado passado para esse método é chamado quando o usuário invoca uma ação do aplicativo, fornecida a instância da ação do aplicativo. Verifique a propriedade Id da ação para determinar qual ação do aplicativo foi iniciada pelo usuário.

O código a seguir demonstra como configurar as ações do aplicativo na inicialização do aplicativo:

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();

    builder
        .UseMauiApp<App>()
        .ConfigureFonts(fonts =>
        {
            fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
        })
        .ConfigureEssentials(essentials =>
        {
            essentials
                .AddAppAction("app_info", "App Info", icon: "app_info_action_icon")
                .AddAppAction("battery_info", "Battery Info")
                .OnAppAction(App.HandleAppActions);
        });

    return builder.Build();
}

Resposta a ações

Depois que as ações do aplicativo forem configuradas, o método OnAppAction será chamado para todas as ações do aplicativo invocadas pelo usuário. Use a propriedade Id para diferenciá-las. O código a seguir demonstra como tratar uma ação do aplicativo:

public static void HandleAppActions(AppAction appAction)
{
    App.Current.Dispatcher.Dispatch(async () =>
    {
        var page = appAction.Id switch
        {
            "battery_info" => new SensorsPage(),
            "app_info" => new AppModelPage(),
            _ => default(Page)
        };

        if (page != null)
        {
            // Assume an app with a single window.
            await Application.Current.Windows[0].Page.Navigation.PopToRootAsync();
            await Application.Current.Windows[0].Page.Navigation.PushAsync(page);
        }
    });
}

Verifique se as ações do aplicativo são aceitas

Ao criar uma ação de aplicativo, seja na sua inicialização ou enquanto ele está sendo usado, verifique se as ações de aplicativo são aceitas na propriedade AppActions.Current.IsSupported.

Criar uma ação de aplicativo fora do bootstrap de inicialização

Para criar ações de aplicativo, chame o método SetAsync:

if (AppActions.Current.IsSupported)
{
    await AppActions.Current.SetAsync(new[] { new AppAction("app_info", "App Info", icon: "app_info_action_icon"),
                                              new AppAction("battery_info", "Battery Info") });
}

Mais informações sobre ações do aplicativo

Se não houver suporte para ações de aplicativo na versão específica do sistema operacional, um FeatureNotSupportedException será gerado.

Use o construtor AppAction(String, String, String, String) para definir os seguintes aspectos de uma ação do aplicativo:

Id: um identificador exclusivo usado para responder ao toque de ação.
Title: o title visível a ser exibido.
Subtitle: se possível, um subtitle a ser exibida sob o title.
Icon: deve corresponder aos ícones no diretório de recursos correspondente em cada plataforma.

Ações do aplicativo na tela inicial.

Ações "Get"

Você pode obter a lista atual de ações do aplicativo chamando AppActions.Current.GetAsync.

Compartilhar via