Xamarin.Essentials: Uprawnienia

Artykuł
09/21/2022
Czas czytania: 5 min

Klasa Permissions umożliwia sprawdzanie i żądanie uprawnień środowiska uruchomieniowego.

Rozpoczęcie pracy

Aby rozpocząć korzystanie z tego interfejsu API, przeczytaj przewodnik Xamarin.Essentialswprowadzający, aby upewnić się, że biblioteka jest poprawnie zainstalowana i skonfigurowana w projektach.

Ten interfejs API używa uprawnień środowiska uruchomieniowego w systemie Android. Upewnij się, że Xamarin.Essentials obsługa uprawnień jest w pełni zainicjowana, a obsługa uprawnień jest skonfigurowana w aplikacji.

W projekcie MainLauncher systemu Android lub dowolnym Activity , który jest uruchamiany Xamarin.Essentials , musi zostać zainicjowany w metodzie OnCreate :

protected override void OnCreate(Bundle savedInstanceState) 
{
    //...
    base.OnCreate(savedInstanceState);
    Xamarin.Essentials.Platform.Init(this, savedInstanceState); // add this line to your code, it may also be called: bundle
    //...
}

Aby obsłużyć uprawnienia środowiska uruchomieniowego w systemie Android, Xamarin.Essentials należy otrzymać dowolny OnRequestPermissionsResult. Dodaj następujący kod do wszystkich Activity klas:

public override void OnRequestPermissionsResult(int requestCode, string[] permissions, Android.Content.PM.Permission[] grantResults)
{
    Xamarin.Essentials.Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults);

    base.OnRequestPermissionsResult(requestCode, permissions, grantResults);
}

Korzystanie z uprawnień

Dodaj odwołanie do Xamarin.Essentials elementu w klasie:

using Xamarin.Essentials;

Sprawdzanie uprawnień

Aby sprawdzić bieżący stan uprawnienia, użyj CheckStatusAsync metody wraz z określonym uprawnieniem, aby uzyskać stan.

var status = await Permissions.CheckStatusAsync<Permissions.LocationWhenInUse>();

Element PermissionException jest zgłaszany, jeśli wymagane uprawnienie nie jest zadeklarowane.

Przed żądaniem najlepiej sprawdzić stan uprawnienia. Każdy system operacyjny zwraca inny stan domyślny, jeśli użytkownik nigdy nie został wyświetlony monit. System iOS zwraca wartość Unknown, a inne zwracają wartość Denied. Jeśli stan ma wartość Granted , nie ma potrzeby nawiązywania innych wywołań. W systemie iOS, jeśli stan ma być Denied wyświetlany, użytkownik powinien monitować użytkownika o zmianę uprawnień w ustawieniach i w systemie Android, aby wykryć ShouldShowRationale , czy użytkownik już odmówiono uprawnień w przeszłości.

Żądanie uprawnień

Aby zażądać uprawnień od użytkowników, użyj RequestAsync metody wraz z określonymi uprawnieniami do żądania. Jeśli użytkownik udzielił wcześniej uprawnień i nie odwołał go, ta metoda zwróci Granted natychmiast i nie wyświetli okna dialogowego.

var status = await Permissions.RequestAsync<Permissions.LocationWhenInUse>();

Element PermissionException jest zgłaszany, jeśli wymagane uprawnienie nie jest zadeklarowane.

Należy pamiętać, że na niektórych platformach żądanie uprawnień można aktywować tylko raz. Dalsze monity muszą być obsługiwane przez dewelopera, aby sprawdzić, czy uprawnienie jest w Denied stanie i poprosić użytkownika o ręczne włączenie.

Stan uprawnień

W przypadku użycia elementu CheckStatusAsync lub RequestAsyncPermissionStatus elementu zostanie zwrócony element , którego można użyć do określenia następnych kroków:

Nieznane — uprawnienie jest w nieznanym stanie
Odmowa — użytkownik odmówił żądania uprawnień
Wyłączone — funkcja jest wyłączona na urządzeniu
Przyznane — użytkownikowi udzielono uprawnień lub jest udzielany automatycznie
Ograniczone — w stanie ograniczonym

Wyjaśnienie, dlaczego wymagane jest uprawnienie

Najlepszym rozwiązaniem jest wyjaśnienie, dlaczego aplikacja potrzebuje określonego uprawnienia. W systemie iOS należy określić ciąg wyświetlany użytkownikowi. System Android nie ma tej możliwości, a także domyślnie określa stan uprawnień Wyłączone. Ogranicza to możliwość sprawdzenia, czy użytkownik nie zezwolił na uprawnienie, czy też po raz pierwszy wyświetli monit o podanie uprawnień. Metody ShouldShowRationale można użyć do określenia, czy powinien być wyświetlany edukacyjny interfejs użytkownika. Jeśli metoda zwróci true tę wartość, ponieważ użytkownik odmówiono lub wyłączył uprawnienie w przeszłości. Inne platformy zawsze będą zwracane false podczas wywoływania tej metody.

Dostępne uprawnienia

Xamarin.Essentials podejmuje próbę abstrakcji jak największej liczby uprawnień. Jednak każdy system operacyjny ma inny zestaw uprawnień środowiska uruchomieniowego. Ponadto istnieją różnice podczas udostępniania pojedynczego interfejsu API dla niektórych uprawnień. Oto przewodnik po aktualnie dostępnych uprawnieniach:

Przewodnik po ikonach:

— Obsługiwane
— Nieobsługiwane/wymagane

Uprawnienie	Android	iOS	Platforma UWP	watchOS	tvOS	Tizen
Element CalendarRead
CalendarWrite
Aparat fotograficzny
KontaktyPrzeczytaj
KontaktyWrite
Latarka
LocationWhenInUse
LokalizacjeAlways
Multimedia
Mikrofon
Telefon
Zdjęcia
Przypomnienia
Czujniki
Sms
Mowa
StorageRead
StorageWrite

Jeśli uprawnienie jest oznaczone jako not supported zawsze będzie zwracane Granted po zaznaczeniu lub zażądaniu.

Ogólne użycie

Poniższy kod przedstawia ogólny wzorzec użycia umożliwiający określenie, czy udzielono mu uprawnień i zażądanie go, jeśli nie. Ten kod używa funkcji dostępnych w Xamarin.Essentials wersji 1.6.0 lub nowszej.

public async Task<PermissionStatus> CheckAndRequestLocationPermission()
{
    var status = await Permissions.CheckStatusAsync<Permissions.LocationWhenInUse>();
    
    if (status == PermissionStatus.Granted)
        return status;        
    
    if (status == PermissionStatus.Denied && DeviceInfo.Platform == DevicePlatform.iOS)
    {
        // Prompt the user to turn on in settings
        // On iOS once a permission has been denied it may not be requested again from the application
        return status;
    }
    
    if (Permissions.ShouldShowRationale<Permissions.LocationWhenInUse>())
    {
        // Prompt the user with additional information as to why the permission is needed
    }   

    status = await Permissions.RequestAsync<Permissions.LocationWhenInUse>();

    return status;
}

Każdy typ uprawnień może mieć utworzone wystąpienie, które można wywołać bezpośrednio za pomocą metod.

public async Task GetLocationAsync()
{
    var status = await CheckAndRequestPermissionAsync(new Permissions.LocationWhenInUse());
    if (status != PermissionStatus.Granted)
    {
        // Notify user permission was denied
        return;
    }

    var location = await Geolocation.GetLocationAsync();
}

public async Task<PermissionStatus> CheckAndRequestPermissionAsync<T>(T permission)
            where T : BasePermission
{
    var status = await permission.CheckStatusAsync();
    if (status != PermissionStatus.Granted)
    {
        status = await permission.RequestAsync();
    }

    return status;
}

Rozszerzanie uprawnień

Interfejs API uprawnień został utworzony w taki sposób, aby był elastyczny i rozszerzalny dla aplikacji, które wymagają dodatkowej weryfikacji lub uprawnień, które nie są uwzględnione w Xamarin.Essentialsprogramie . Utwórz nową klasę, która dziedziczy z BasePermission i implementuje wymagane metody abstrakcyjne.

public class MyPermission : BasePermission
{
    // This method checks if current status of the permission
    public override Task<PermissionStatus> CheckStatusAsync()
    {
        throw new System.NotImplementedException();
    }

    // This method is optional and a PermissionException is often thrown if a permission is not declared
    public override void EnsureDeclared()
    {
        throw new System.NotImplementedException();
    }

    // Requests the user to accept or deny a permission
    public override Task<PermissionStatus> RequestAsync()
    {
        throw new System.NotImplementedException();
    }
}

Podczas implementowania uprawnienia na określonej platformie klasę BasePlatformPermission można dziedziczyć. Zapewnia to dodatkowe metody pomocnika platformy do automatycznego sprawdzania deklaracji. Może to pomóc podczas tworzenia uprawnień niestandardowych, które grupują. Na przykład możesz zażądać dostępu zarówno do odczytu, jak i zapisu do magazynu w systemie Android przy użyciu następującego uprawnienia niestandardowego.

public class ReadWriteStoragePermission : Xamarin.Essentials.Permissions.BasePlatformPermission
{
    public override (string androidPermission, bool isRuntime)[] RequiredPermissions => new List<(string androidPermission, bool isRuntime)>
    {
        (Android.Manifest.Permission.ReadExternalStorage, true),
        (Android.Manifest.Permission.WriteExternalStorage, true)
    }.ToArray();
}

Następnie możesz wywołać nowe uprawnienie z projektu systemu Android.

await Permissions.RequestAsync<ReadWriteStoragePermission>();

Jeśli chcesz wywołać ten interfejs API z udostępnionego kodu, możesz utworzyć interfejs i użyć usługi zależności , aby zarejestrować i uzyskać implementację.

public interface IReadWritePermission
{        
    Task<PermissionStatus> CheckStatusAsync();
    Task<PermissionStatus> RequestAsync();
}

Następnie zaimplementuj interfejs w projekcie platformy:

public class ReadWriteStoragePermission : Xamarin.Essentials.Permissions.BasePlatformPermission, IReadWritePermission
{
    public override (string androidPermission, bool isRuntime)[] RequiredPermissions => new List<(string androidPermission, bool isRuntime)>
    {
        (Android.Manifest.Permission.ReadExternalStorage, true),
        (Android.Manifest.Permission.WriteExternalStorage, true)
    }.ToArray();
}

Następnie możesz zarejestrować konkretną implementację:

DependencyService.Register<IReadWritePermission, ReadWriteStoragePermission>();

Następnie z udostępnionego projektu możesz rozwiązać ten problem i użyć go:

var readWritePermission = DependencyService.Get<IReadWritePermission>();
var status = await readWritePermission.CheckStatusAsync();
if (status != PermissionStatus.Granted)
{
    status = await readWritePermission.RequestAsync();
}

Specyfika implementacji platformy

Uprawnienia muszą mieć zgodne atrybuty ustawione w pliku manifestu systemu Android. Domyślnie stan uprawnień to Odmowa.

Przeczytaj więcej na temat dokumentacji dotyczącej uprawnień na platformie Xamarin.Android .

Uprawnienia muszą mieć pasujący ciąg w Info.plist pliku. Po zażądaniu uprawnienia i odmowie wyskakującego okienka nie będzie już wyświetlane, jeśli zażądasz uprawnienia po raz drugi. Użytkownik musi monitować użytkownika o ręczne dostosowanie ustawienia na ekranie ustawień aplikacji w systemie iOS. Stan uprawnień jest domyślnie ustawiony na Nieznany.

Przeczytaj więcej na temat dokumentacji funkcji zabezpieczeń i prywatności systemu iOS .

interfejs API

Znajdź więcej filmów na platformie Xamarin w witrynach Channel 9 i YouTube.

Xamarin.Essentials: Uprawnienia

Rozpoczęcie pracy

Korzystanie z uprawnień

Sprawdzanie uprawnień

Żądanie uprawnień

Stan uprawnień

Wyjaśnienie, dlaczego wymagane jest uprawnienie

Dostępne uprawnienia

Ogólne użycie

Rozszerzanie uprawnień

Specyfika implementacji platformy

interfejs API

Dodatkowe zasoby

Dodatkowe zasoby

Xamarin.Essentials: Uprawnienia

Rozpoczęcie pracy

Korzystanie z uprawnień

Sprawdzanie uprawnień

Żądanie uprawnień

Stan uprawnień

Wyjaśnienie, dlaczego wymagane jest uprawnienie

Dostępne uprawnienia

Ogólne użycie

Rozszerzanie uprawnień

Specyfika implementacji platformy

interfejs API

Powiązane wideo

Dodatkowe zasoby

Dodatkowe zasoby