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
:
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:
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:
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>();
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.
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:
- -Obsługiwane
- — Nieobsługiwane/wymagane
Uprawnienie | Android | iOS | Platforma UWP | watchOS | tvOS | Tizen |
---|---|---|---|---|---|---|
Element CalendarRead | ||||||
CalendarWrite | ||||||
Kamera | ||||||
KontaktyPrzeczytane | ||||||
KontaktyWrite | ||||||
Latarka | ||||||
LocationWhenInUse | ||||||
LocationAlways | ||||||
Multimedia | ||||||
Mikrofon | ||||||
Phone | ||||||
Photos | ||||||
Przypomnienia | ||||||
Czujniki | ||||||
SMS | ||||||
Mowa | ||||||
StorageRead | ||||||
StorageWrite |
Jeśli uprawnienie jest oznaczone jako 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 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.
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.
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 kodu udostępnionego, możesz utworzyć interfejs i użyć usługi zależności, aby zarejestrować i pobrać 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żna zarejestrować określoną 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. Stan uprawnień jest domyślnie blokowany.
Przeczytaj więcej na temat dokumentacji dotyczącej uprawnień na platformie Xamarin.Android .
interfejs API
Powiązany film wideo
Więcej filmów na platformie Xamarin można znaleźć w witrynach Channel 9 i YouTube.