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 :

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 RequestAsyncPermissionStatus 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:

  • Full Support -Obsługiwane
  • Not Supported — Nieobsługiwane/wymagane
Uprawnienie Android iOS Platforma UWP watchOS tvOS Tizen
Element CalendarRead Android supported iOS supported UWP not supported watchOS supported tvOS not supported Tizen not supported
CalendarWrite Android supported iOS supported UWP not supported watchOS supported tvOS not supported Tizen not supported
Kamera Android supported iOS supported UWP not supported watchOS not supported tvOS not supported Tizen supported
KontaktyPrzeczytane Android supported iOS supported UWP supported watchOS not supported tvOS not supported Tizen not supported
KontaktyWrite Android supported iOS supported UWP supported watchOS not supported tvOS not supported Tizen not supported
Latarka Android supported iOS not supported UWP not supported watchOS not supported tvOS not supported Tizen supported
LocationWhenInUse Android supported iOS supported UWP supported watchOS supported tvOS supported Tizen supported
LocationAlways Android supported iOS supported UWP supported watchOS supported tvOS not supported Tizen supported
Multimedia Android not supported iOS supported UWP not supported watchOS not supported tvOS not supported Tizen not supported
Mikrofon Android supported iOS supported UWP supported watchOS not supported tvOS not supported Tizen supported
Phone Android supported iOS supported UWP not supported watchOS not supported tvOS not supported Tizen not supported
Photos Android not supported iOS supported UWP not supported watchOS not supported tvOS supported Tizen not supported
Przypomnienia Android not supported iOS supported UWP not supported watchOS supported tvOS not supported Tizen not supported
Czujniki Android supported iOS supported UWP supported watchOS supported tvOS not supported Tizen not supported
Sms Android supported iOS supported UWP not supported watchOS not supported tvOS not supported Tizen not supported
Mowa Android supported iOS supported UWP not supported watchOS not supported tvOS not supported Tizen not supported
StorageRead Android supported iOS not supported UWP not supported watchOS not supported tvOS not supported Tizen not supported
StorageWrite Android supported iOS not supported UWP not supported watchOS not supported tvOS not supported Tizen not supported

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 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

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