Przeczytaj w języku angielskim

Udostępnij za pośrednictwem


Xamarin.Essentials:Uprawnienia

Klasa Permissions zapewnia możliwość sprawdzania i żądania uprawnień środowiska uruchomieniowego.

Rozpocznij

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

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

W projekcie MainLauncher systemu Android lub dowolnym Activity uruchomionym Xamarin.Essentials projekcie musi zostać zainicjowana w metodzie OnCreate :

C#
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 musi otrzymać dowolny OnRequestPermissionsResult. Dodaj następujący kod do wszystkich Activity klas:

C#
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 klasy:

C#
using Xamarin.Essentials;

Sprawdzanie uprawnień

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

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

Wartość jest PermissionException zgłaszana, jeśli wymagane uprawnienie nie jest zadeklarowane.

Przed zażądaniem tego uprawnienia najlepiej sprawdzić stan uprawnień. 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 to Granted , nie ma potrzeby nawiązywania innych wywołań. Jeśli w systemie iOS jest Denied wyświetlany stan, użytkownik powinien monitować użytkownika o zmianę uprawnień w ustawieniach i w systemie Android, aby wykryć ShouldShowRationale , czy użytkownik już zaprzeczył uprawnienia w przeszłości.

Żądanie uprawnień

Aby zażądać uprawnień od użytkowników, użyj RequestAsync metody wraz z określonym uprawnieniem 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.

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

Wartość jest PermissionException zgłaszana, 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 go.

Stan uprawnień

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

  • Nieznany — uprawnienie jest w nieznanym stanie
  • Odmowa — użytkownik odmówił żądania uprawnień
  • Wyłączone — funkcja jest wyłączona na urządzeniu
  • Przyznane — użytkownik przyznał uprawnienie lub jest automatycznie udzielany
  • 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 powoduje wyłączenie stanu uprawnień. Ogranicza to możliwość sprawdzenia, czy użytkownik nie zezwolił na uprawnienie, czy też po raz pierwszy monitował użytkownika. Metody ShouldShowRationale można użyć do określenia, czy powinien być wyświetlany edukacyjny interfejs użytkownika. Jeśli metoda zwróci true to, ponieważ użytkownik odmówił 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 próbuje wyodrębnić jak najwięcej uprawnień, jak to możliwe. Jednak każdy system operacyjny ma inny zestaw uprawnień środowiska uruchomieniowego. Ponadto istnieją różnice w przypadku udostępniania pojedynczego interfejsu API dla niektórych uprawnień. Oto przewodnik po aktualnie dostępnych uprawnieniach:

Przewodnik po ikonach:

  • Pełna obsługa -Obsługiwane
  • Nieobsługiwany — Nieobsługiwane/wymagane
Uprawnienie Android iOS Platforma UWP watchOS tvOS Tizen
Element CalendarRead Obsługiwany system Android Obsługiwane systemy iOS Platforma UWP nie jest obsługiwana Obsługiwane przez system watchOS System tvOS nie jest obsługiwany Tizen nie jest obsługiwany
CalendarWrite Obsługiwany system Android Obsługiwane systemy iOS Platforma UWP nie jest obsługiwana Obsługiwane przez system watchOS System tvOS nie jest obsługiwany Tizen nie jest obsługiwany
Kamera Obsługiwany system Android Obsługiwane systemy iOS Platforma UWP nie jest obsługiwana system watchOS nie jest obsługiwany System tvOS nie jest obsługiwany Tizen obsługiwane
KontaktyPrzeczytane Obsługiwany system Android Obsługiwane systemy iOS Obsługiwana platforma UWP system watchOS nie jest obsługiwany System tvOS nie jest obsługiwany Tizen nie jest obsługiwany
KontaktyWrite Obsługiwany system Android Obsługiwane systemy iOS Obsługiwana platforma UWP system watchOS nie jest obsługiwany System tvOS nie jest obsługiwany Tizen nie jest obsługiwany
Latarka Obsługiwany system Android System iOS nie jest obsługiwany Platforma UWP nie jest obsługiwana system watchOS nie jest obsługiwany System tvOS nie jest obsługiwany Tizen obsługiwane
LocationWhenInUse Obsługiwany system Android Obsługiwane systemy iOS Obsługiwana platforma UWP Obsługiwane przez system watchOS Obsługa systemu tvOS Tizen obsługiwane
LocationAlways Obsługiwany system Android Obsługiwane systemy iOS Obsługiwana platforma UWP Obsługiwane przez system watchOS System tvOS nie jest obsługiwany Tizen obsługiwane
Multimedia System Android nie jest obsługiwany Obsługiwane systemy iOS Platforma UWP nie jest obsługiwana system watchOS nie jest obsługiwany System tvOS nie jest obsługiwany Tizen nie jest obsługiwany
Mikrofon Obsługiwany system Android Obsługiwane systemy iOS Obsługiwana platforma UWP system watchOS nie jest obsługiwany System tvOS nie jest obsługiwany Tizen obsługiwane
Phone Obsługiwany system Android Obsługiwane systemy iOS Platforma UWP nie jest obsługiwana system watchOS nie jest obsługiwany System tvOS nie jest obsługiwany Tizen nie jest obsługiwany
Photos System Android nie jest obsługiwany Obsługiwane systemy iOS Platforma UWP nie jest obsługiwana system watchOS nie jest obsługiwany Obsługa systemu tvOS Tizen nie jest obsługiwany
Przypomnienia System Android nie jest obsługiwany Obsługiwane systemy iOS Platforma UWP nie jest obsługiwana Obsługiwane przez system watchOS System tvOS nie jest obsługiwany Tizen nie jest obsługiwany
Czujniki Obsługiwany system Android Obsługiwane systemy iOS Obsługiwana platforma UWP Obsługiwane przez system watchOS System tvOS nie jest obsługiwany Tizen nie jest obsługiwany
SMS Obsługiwany system Android Obsługiwane systemy iOS Platforma UWP nie jest obsługiwana system watchOS nie jest obsługiwany System tvOS nie jest obsługiwany Tizen nie jest obsługiwany
Mowa Obsługiwany system Android Obsługiwane systemy iOS Platforma UWP nie jest obsługiwana system watchOS nie jest obsługiwany System tvOS nie jest obsługiwany Tizen nie jest obsługiwany
StorageRead Obsługiwany system Android System iOS nie jest obsługiwany Platforma UWP nie jest obsługiwana system watchOS nie jest obsługiwany System tvOS nie jest obsługiwany Tizen nie jest obsługiwany
StorageWrite Obsługiwany system Android System iOS nie jest obsługiwany Platforma UWP nie jest obsługiwana system watchOS nie jest obsługiwany System tvOS nie jest obsługiwany Tizen nie jest obsługiwany

Jeśli uprawnienie jest oznaczone jako nieobsługiwane 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.

C#
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.

C#
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 tak, 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.

C#
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 BasePlatformPermission klasę 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.

C#
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.

C#
await Permissions.RequestAsync<ReadWriteStoragePermission>();

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

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

Następnie zaimplementuj interfejs w projekcie platformy:

C#
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żna zarejestrować określoną implementację:

C#
DependencyService.Register<IReadWritePermission, ReadWriteStoragePermission>();

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

C#
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. Stan uprawnień jest domyślnie blokowany.

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

interfejs API

Więcej filmów na platformie Xamarin można znaleźć w witrynach Channel 9 i YouTube.