Właściwości możliwe do wiązania

Właściwości powiązania interfejsu użytkownika aplikacji wieloplatformowej platformy .NET (.NET MAUI) rozszerzają funkcjonalność właściwości środowiska uruchomieniowego języka wspólnego (CLR), tworząc kopię zapasową właściwości typu BindableProperty , a nie z polem. Właściwości możliwe do powiązania mają na celu zapewnienie systemu właściwości obsługującego powiązanie danych, style, szablony i wartości ustawione za pośrednictwem relacji nadrzędny-podrzędny. Ponadto powiązane właściwości mogą udostępniać wartości domyślne, walidację wartości właściwości i wywołania zwrotne monitorujące zmiany właściwości.

W aplikacjach MAUI platformy .NET właściwości powinny być implementowane jako właściwości możliwe do powiązania w celu obsługi co najmniej jednej z następujących funkcji:

• Działanie jako prawidłowa właściwość docelowa powiązania danych. Aby uzyskać więcej informacji na temat właściwości docelowych, zobacz Podstawowe powiązania.
• Ustawianie właściwości za pomocą stylu.
• Podanie domyślnej wartości właściwości innej niż domyślna dla typu właściwości.
• Weryfikowanie wartości właściwości.
• Monitorowanie zmian właściwości.

Przykłady właściwości możliwych do powiązania programu MAUI platformy .NET obejmują Label.Text, Button.BorderRadiusi StackLayout.Orientation. Każda właściwość powiązana ma odpowiednie public static readonly pole typu BindableProperty , które jest uwidocznione w tej samej klasie i jest identyfikatorem właściwości możliwej do powiązania. Na przykład odpowiedni identyfikator właściwości możliwej do powiązania dla Label.Text właściwości to Label.TextProperty.

Tworzenie właściwości możliwej do powiązania

Proces tworzenia właściwości możliwej do powiązania jest następujący:

1. BindableProperty Utwórz wystąpienie z jednym BindableProperty.Create z przeciążeń metody.
2. Zdefiniuj BindableProperty metody dostępu do właściwości dla wystąpienia.

Wszystkie BindableProperty wystąpienia muszą zostać utworzone w wątku interfejsu użytkownika. Oznacza to, że tylko kod uruchamiany w wątku interfejsu użytkownika może pobrać lub ustawić wartość właściwości możliwej do powiązania. Jednak BindableProperty dostęp do wystąpień można uzyskać z innych wątków, marshaling do wątku interfejsu użytkownika. Aby uzyskać więcej informacji, zobacz Uruchamianie kodu w wątku interfejsu użytkownika.

Tworzenie właściwości

Aby utworzyć BindableProperty wystąpienie, klasa zawierająca musi pochodzić z BindableObject klasy . BindableObject Jednak klasa jest wysoka w hierarchii klas, więc większość klas używanych do obsługi funkcji interfejsu użytkownika obsługuje właściwości możliwe do powiązania.

Właściwość, którą można powiązać, można utworzyć, deklarując public static readonly właściwość typu BindableProperty. Właściwość powiązana powinna być ustawiona na zwracaną wartość jednego z BindableProperty.Create przeciążeń metody. Deklaracja powinna znajdować się w treści klasy pochodnej BindableObject , ale poza definicjami składowymi.

W przypadku tworzenia BindablePropertyobiektu należy określić co najmniej identyfikator wraz z następującymi parametrami:

• Nazwa elementu BindableProperty.
• Typ właściwości.
• Typ obiektu będącego właścicielem.
• Wartość domyślna właściwości . Gwarantuje to, że właściwość zawsze zwraca określoną wartość domyślną, gdy jest ona niezastawiona i może być inna niż wartość domyślna typu właściwości. Wartość domyślna zostanie przywrócona, gdy ClearValue metoda zostanie wywołana we właściwości możliwej do powiązania.

Ważne

Konwencja nazewnictwa właściwości możliwych do powiązania polega na tym, że identyfikator właściwości możliwej do powiązania musi być zgodny z nazwą właściwości określoną w Create metodzie, z dołączonym do niego ciągiem "Property".

Poniższy kod przedstawia przykład właściwości możliwej do powiązania z identyfikatorem i wartościami dla czterech wymaganych parametrów:

public static readonly BindableProperty IsExpandedProperty =
  BindableProperty.Create ("IsExpanded", typeof(bool), typeof(Expander), false);

Spowoduje to utworzenie BindableProperty wystąpienia o nazwie IsExpandedProperty, typu bool. Właściwość jest własnością Expander klasy i ma wartość falsedomyślną .

Uwaga

Expander to kontrolka w zestawie narzędzi .NET MAUI Community Toolkit. Aby uzyskać więcej informacji, zobacz Expander.

Opcjonalnie podczas tworzenia BindableProperty wystąpienia można określić następujące parametry:

• Tryb powiązania. Służy do określania kierunku, w którym zmiany wartości właściwości będą propagowane. W domyślnym trybie powiązania zmiany będą propagowane ze źródła do miejsca docelowego. Aby uzyskać więcej informacji, zobacz Podstawowe powiązania.
• Delegat weryfikacji, który zostanie wywołany po ustawieniu wartości właściwości. Aby uzyskać więcej informacji, zobacz Sprawdzanie poprawności wywołań zwrotnych.
• Delegat zmiany właściwości, który zostanie wywołany po zmianie wartości właściwości. Aby uzyskać więcej informacji, zobacz Wykrywanie zmian właściwości.
• Delegat zmiany właściwości, który zostanie wywołany, gdy wartość właściwości zostanie zmieniona. Ten delegat ma ten sam podpis, co właściwość zmieniona delegata.
• Delegat wartości coerce, który zostanie wywołany po zmianie wartości właściwości. Aby uzyskać więcej informacji, zobacz Coerce value callbacks (Wywołania zwrotne wartości coerce).
• Element Func używany do inicjowania wartości właściwości domyślnej. Aby uzyskać więcej informacji, zobacz Create a default value with a Func (Tworzenie wartości domyślnej za pomocą narzędzia Func).

Tworzenie metod dostępu

Metody dostępu do właściwości są wymagane do używania składni właściwości w celu uzyskania dostępu do właściwości możliwej do powiązania. Akcesorium Get powinno zwrócić wartość zawartą w odpowiedniej właściwości możliwej do powiązania. Można to osiągnąć, wywołując metodę GetValue , przekazując identyfikator właściwości możliwej do powiązania, dla której ma zostać pobrana wartość, a następnie rzutując wynik na wymagany typ. Metodę Set dostępu należy ustawić wartość odpowiedniej właściwości możliwej do powiązania. Można to osiągnąć, wywołując metodę SetValue , przekazując identyfikator właściwości możliwej do powiązania, dla której należy ustawić wartość, oraz wartość do ustawienia.

Poniższy przykład kodu przedstawia metody dostępu dla właściwości możliwej IsExpanded do powiązania:

public bool IsExpanded
{
    get => (bool)GetValue(IsExpandedProperty);
    set => SetValue(IsExpandedProperty, value);
}

Korzystanie z właściwości możliwej do powiązania

Po utworzeniu właściwości możliwej do powiązania można jej użyć z kodu lub kodu XAML. W języku XAML jest to osiągane przez zadeklarowanie przestrzeni nazw z prefiksem z deklaracją przestrzeni nazw wskazującą nazwę przestrzeni nazw CLR i opcjonalnie nazwę zestawu. Aby uzyskać więcej informacji, zobacz Przestrzenie nazw XAML.

W poniższym przykładzie kodu pokazano przestrzeń nazw XAML dla typu niestandardowego zawierającego właściwość powiązaną, która jest zdefiniowana w tym samym zestawie co kod aplikacji odwołujący się do typu niestandardowego:

<ContentPage ... xmlns:local="clr-namespace:DataBindingDemos" ...>
  ...
</ContentPage>

Deklaracja przestrzeni nazw jest używana podczas ustawiania właściwości możliwej IsExpanded do powiązania, jak pokazano w poniższym przykładzie kodu XAML:

<Expander IsExpanded="true">
    ...
</Expander>

Równoważny kod języka C# jest pokazany w poniższym przykładzie kodu:

Expander expander = new Expander
{
    IsExpanded = true
};

Zaawansowane scenariusze

Podczas tworzenia BindableProperty wystąpienia istnieje wiele opcjonalnych parametrów, które można ustawić w celu włączenia zaawansowanych scenariuszy właściwości możliwych do powiązania. W tej sekcji omówiono te scenariusze.

Wykrywanie zmian właściwości

static Metodę wywołania zwrotnego zmiany właściwości można zarejestrować za pomocą właściwości możliwej do powiązania, określając propertyChanged parametr metody BindableProperty.Create . Określona metoda wywołania zwrotnego zostanie wywołana po zmianie wartości właściwości możliwej do powiązania.

W poniższym przykładzie kodu pokazano, jak IsExpanded właściwość z możliwością powiązania rejestruje OnIsExpandedChanged metodę jako metodę wywołania zwrotnego zmiany właściwości:

public static readonly BindableProperty IsExpandedProperty =
    BindableProperty.Create(nameof(IsExpanded), typeof(bool), typeof(Expander), false, propertyChanged: OnIsExpandedChanged);
...

static void OnIsExpandedChanged (BindableObject bindable, object oldValue, object newValue)
{
  // Property changed implementation goes here
}

W metodzie wywołania zwrotnego zmienionej właściwości parametr służy do oznaczania, BindableObject które wystąpienie klasy będącej właścicielem zgłosiło zmianę, a wartości dwóch object parametrów reprezentują stare i nowe wartości właściwości możliwe do powiązania.

Wywołania zwrotne weryfikacji

static Metodę wywołania zwrotnego weryfikacji można zarejestrować za pomocą właściwości możliwej do powiązania, określając validateValue parametr metody BindableProperty.Create . Określona metoda wywołania zwrotnego zostanie wywołana po ustawieniu wartości właściwości możliwej do powiązania.

W poniższym przykładzie kodu pokazano, jak Angle właściwość z możliwością powiązania rejestruje IsValidValue metodę jako metodę wywołania zwrotnego weryfikacji:

public static readonly BindableProperty AngleProperty =
    BindableProperty.Create("Angle", typeof(double), typeof(MainPage), 0.0, validateValue: IsValidValue);
...

static bool IsValidValue(BindableObject view, object value)
{
    double result;
    double.TryParse(value.ToString(), out result);
    return (result >= 0 && result <= 360);
}

Wywołania zwrotne weryfikacji są dostarczane z wartością i powinny zwracać true , jeśli wartość jest prawidłowa dla właściwości, w przeciwnym razie false. Wyjątek zostanie zgłoszony, jeśli wywołanie zwrotne weryfikacji zwróci falsewartość , którą należy obsłużyć. Typowym zastosowaniem metody wywołania zwrotnego walidacji jest ograniczenie wartości liczb całkowitych lub podwaja się po ustawieniu właściwości możliwej do powiązania. Na przykład metoda sprawdza, IsValidValue czy wartość właściwości mieści się double w zakresie od 0 do 360.

Wywołania zwrotne wartości coerce

Metodę static wywołania zwrotnego wartości coerce można zarejestrować za pomocą właściwości możliwej do powiązania, określając coerceValue parametr dla BindableProperty.Create metody . Określona metoda wywołania zwrotnego zostanie wywołana, gdy wartość właściwości możliwej do powiązania zostanie zmieniona, aby można było dostosować nową wartość przed jej zastosowaniem.

Ważne

Oprócz wyzwalania przez aparat właściwości, który można powiązać, można wywołać wywołania zwrotne coerce-value z kodu. Typ BindableObject ma metodę CoerceValue , którą można wywołać w celu wymuszenia ponownej oceny wartości argumentu BindableProperty , wywołując wywołanie zwrotne wartości coerce.

Wywołania zwrotne wartości coerce są używane do wymuszenia ponownej oceny właściwości możliwej do powiązania, gdy wartość właściwości ma ulec zmianie. Na przykład wywołanie zwrotne wartości coerce może służyć do zapewnienia, że wartość jednej właściwości możliwej do powiązania nie jest większa niż wartość innej właściwości możliwej do powiązania.

W poniższym przykładzie kodu pokazano, jak Angle właściwość z możliwością powiązania rejestruje CoerceAngle metodę jako metodę wywołania zwrotnego wartości coerce:

public static readonly BindableProperty AngleProperty =
    BindableProperty.Create("Angle", typeof(double), typeof(MainPage), 0.0, coerceValue: CoerceAngle);
public static readonly BindableProperty MaximumAngleProperty =
    BindableProperty.Create("MaximumAngle", typeof(double), typeof(MainPage), 360.0, propertyChanged: ForceCoerceValue);
...

static object CoerceAngle(BindableObject bindable, object value)
{
    MainPage page = bindable as MainPage;
    double input = (double)value;

    if (input > page.MaximumAngle)
    {
        input = page.MaximumAngle;
    }

    return input;
}

static void ForceCoerceValue(BindableObject bindable, object oldValue, object newValue)
{
    bindable.CoerceValue(AngleProperty);
}

Metoda CoerceAngle sprawdza wartość MaximumAngle właściwości, a jeśli Angle wartość właściwości jest większa niż, przekształca wartość na MaximumAngle wartość właściwości. Ponadto, gdy MaximumAngle właściwość zmienia wywołanie zwrotne wartości coerce jest wywoływane we Angle właściwości przez wywołanie CoerceValue metody .

Tworzenie wartości domyślnej za pomocą narzędzia Func

Element może Func służyć do inicjowania wartości domyślnej właściwości możliwej do powiązania, jak pokazano w poniższym przykładzie:

public static readonly BindableProperty DateProperty =
    BindableProperty.Create ("Date", typeof(DateTime), typeof(MyPage), default(DateTime), BindingMode.TwoWay, defaultValueCreator: bindable => DateTime.Today);

Parametr defaultValueCreator jest ustawiony na wartość Func , która zwraca wartość reprezentującą bieżącą DateTime datę.