Vlastnosti s podporou vazeb

Rozhraní .NET Multi-Platform App UI (.NET MAUI) svázatelné vlastnosti rozšiřují funkce vlastností CLR (Common Language Runtime) tak, že místo pole zálohují vlastnost s BindableProperty typem. Účelem vazebných vlastností je poskytnout systém vlastností, který podporuje datové vazby, styly, šablony a hodnoty nastavené prostřednictvím relací nadřazený-podřízený. Kromě toho můžou vlastnosti s možností vazby poskytovat výchozí hodnoty, ověřování hodnot vlastností a zpětná volání, která monitorují změny vlastností.

V aplikacích .NET MAUI by se vlastnosti měly implementovat jako vlastnosti s možností vazby, aby podporovaly jednu nebo více následujících funkcí:

• Funguje jako platná cílová vlastnost datové vazby. Další informace o cílovýchvlastnostech
• Nastavení vlastnosti stylem
• Zadejte výchozí hodnotu vlastnosti, která se liší od výchozího typu vlastnosti.
• Ověření hodnoty vlastnosti.
• Monitorování změn vlastností

Příklady vazebních vlastností .NET MAUI zahrnují Label.Text, Button.BorderRadiusa StackLayout.Orientation. Každá vlastnost bindable má odpovídající public static readonly pole typu BindableProperty , které je vystaveno ve stejné třídě a je identifikátor vlastnosti bindable. Například odpovídající identifikátor vlastnosti s možností vázání pro Label.Text vlastnost je Label.TextProperty.

Vytvoření vlastnosti s možností vytvoření vazby

Proces vytvoření vlastnosti bindable je následující:

1. Vytvořte BindableProperty instanci s jedním z BindableProperty.Create přetížení metody.
2. Definujte přístupové objekty vlastností pro BindableProperty instanci.

Všechny BindableProperty instance musí být vytvořeny ve vlákně uživatelského rozhraní. To znamená, že pouze kód, který běží na vlákně uživatelského rozhraní, může získat nebo nastavit hodnotu bindable vlastnosti. BindableProperty K instancím je však možné přistupovat z jiných vláken zařazováním do vlákna uživatelského rozhraní. Další informace naleznete v tématu Spuštění kódu ve vlákně uživatelského rozhraní.

Vytvoření vlastnosti

Chcete-li vytvořit BindableProperty instanci, musí obsahující třída odvodit z BindableObject třídy. Třída BindableObject je však v hierarchii tříd vysoká, takže většina tříd používaných pro funkce uživatelského rozhraní podporuje vazbové vlastnosti.

Vlastnost s možností vazby lze vytvořit deklarací public static readonly vlastnosti typu BindableProperty. Vlastnost bindable by měla být nastavena na vrácenou hodnotu jednoho z BindableProperty.Create přetížení metody. Deklarace by měla být v těle BindableObject odvozené třídy, ale mimo definice členů.

Při vytváření BindablePropertyidentifikátoru musí být minimálně zadán identifikátor spolu s následujícími parametry:

• Název procesu BindableProperty.
• Typ proměnné
• Typ vlastnícího objektu.
• Výchozí hodnota vlastnosti. Tím se zajistí, že vlastnost vždy vrátí určitou výchozí hodnotu, když je nenasazená, a může se lišit od výchozí hodnoty pro typ vlastnosti. Výchozí hodnota bude obnovena při ClearValue zavolání metody v bindable vlastnost.

Důležité

Konvence vytváření názvů pro vlastnosti bindable je, že identifikátor vlastnosti bindable se musí shodovat s názvem vlastnosti zadaný v Create metodě, s "Property" připojena k němu.

Následující kód ukazuje příklad bindable vlastnosti s identifikátorem a hodnotami pro čtyři požadované parametry:

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

Tím se BindableProperty vytvoří instance s názvem IsExpandedProperty, typu bool. Vlastnost je vlastněna Expander třídou a má výchozí hodnotu false.

Poznámka:

Expander je ovládací prvek v sadě .NET MAUI Community Toolkit. Další informace naleznete v tématu Expander.

Volitelně můžete při vytváření BindableProperty instance zadat následující parametry:

• Režim vazby. Slouží k určení směru, ve kterém se změny hodnoty vlastnosti rozšíří. Ve výchozím režimu vazby se změny rozšíří ze zdroje do cíle. Další informace naleznete v tématu Základní vazby.
• Delegát ověření, který bude vyvolán při nastavení hodnoty vlastnosti. Další informace naleznete v tématu Zpětná volání ověřování.
• Změna delegáta vlastnosti, která bude vyvolána při změně hodnoty vlastnosti. Další informace naleznete v tématu Detekce změn vlastností.
• Změna vlastnosti delegáta, která bude vyvolána při změně hodnoty vlastnosti. Tento delegát má stejný podpis jako vlastnost, která změnila delegáta.
• Delegát hodnoty převodu, který bude vyvolán při změně hodnoty vlastnosti. Další informace naleznete v tématu Zpětná volání hodnoty v coerce.
• Slouží Func k inicializaci výchozí hodnoty vlastnosti. Další informace naleznete v tématu Vytvoření výchozí hodnoty pomocí func.

Vytváření přístupových objektů

Přístup k vlastnosti s možností vázání vyžaduje přístup k syntaxi vlastností. Přistupovací Get objekt by měl vrátit hodnotu obsaženou v odpovídající svázatelné vlastnosti. Toho lze dosáhnout voláním GetValue metody, předáním identifikátoru vlastnosti bindable, na kterém získat hodnotu, a následným přetypováním výsledku na požadovaný typ. Přistupovací Set objekt by měl nastavit hodnotu odpovídající vlastnosti s možností vazby. Toho lze dosáhnout voláním SetValue metody, předáním identifikátoru vlastnosti bindable, na kterém chcete nastavit hodnotu, a hodnotu, která se má nastavit.

Následující příklad kódu ukazuje přístupové objekty pro IsExpanded bindable vlastnost:

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

Využití vlastnosti s možností vytvoření vazby

Jakmile je vytvořena vlastnost bindable, může být využita z XAML nebo kódu. V JAZYCE XAML toho dosáhnete deklarováním oboru názvů s předponou, deklarací oboru názvů označující název oboru názvů CLR a volitelně název sestavení. Další informace naleznete v tématu Obory názvů XAML.

Následující příklad kódu ukazuje obor názvů XAML pro vlastní typ, který obsahuje bindable vlastnost, která je definována ve stejném sestavení jako kód aplikace odkazující na vlastní typ:

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

Deklarace oboru názvů se používá při nastavování IsExpanded vlastnosti bindable, jak je znázorněno v následujícím příkladu kódu XAML:

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

Ekvivalentní kód jazyka C# je znázorněn v následujícím příkladu kódu:

Expander expander = new Expander
{
    IsExpanded = true
};

Pokročilé scénáře

Při vytváření BindableProperty instance existuje několik volitelných parametrů, které je možné nastavit tak, aby umožňovaly pokročilé scénáře vlastností s možností vázání. Tato část popisuje tyto scénáře.

Detekce změn vlastností

static Metodu zpětného volání změněnou vlastností lze zaregistrovat pomocí bindable vlastnosti zadáním propertyChanged parametru pro metoduBindableProperty.Create. Zadaná metoda zpětného volání bude vyvolána při změně hodnoty bindable vlastnost.

Následující příklad kódu ukazuje, jak IsExpanded bindable vlastnost registruje metodu OnIsExpandedChanged jako metodu zpětného volání změněné vlastností:

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
}

V metodě zpětného volání změněné vlastností BindableObject se parametr používá k označení, která instance vlastnící třídy oznámila změnu a hodnoty těchto dvou object parametrů představují staré a nové hodnoty bindable vlastnosti.

Zpětná volání ověřování

static Ověřovací metodu zpětného volání lze zaregistrovat pomocí vlastnosti bindable zadáním validateValue parametru pro metoduBindableProperty.Create. Zadaná metoda zpětného volání bude vyvolána při nastavení hodnoty bindable vlastnost.

Následující příklad kódu ukazuje, jak Angle bindable vlastnost registruje metodu IsValidValue jako ověřovací metodu zpětného volání:

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);
}

Ověřovací zpětná volání jsou poskytována s hodnotou a měla by se vrátit true , pokud je hodnota platná pro vlastnost, jinak false. Výjimka se vyvolá, pokud se vrátí falsezpětná vazba pro ověření , kterou byste měli zpracovat. Typické použití metody zpětného volání ověřování omezuje hodnoty celých čísel nebo zdvojnásobí při nastavení bindable vlastnost. Metoda například zkontroluje IsValidValue , že hodnota vlastnosti je double v rozsahu 0 až 360.

Zpětná volání hodnoty vyučovacími funkcemi

Metodu static zpětného volání hodnoty coerce lze zaregistrovat pomocí bindable vlastnosti zadáním coerceValue parametru pro metodu BindableProperty.Create . Zadaná metoda zpětného volání bude vyvolána, když hodnota bindable vlastnost se chystá změnit, takže můžete upravit novou hodnotu před jeho použití.

Důležité

Kromě toho, že je aktivovaný modulem vlastností bindable, můžete vyvolat zpětné volání hodnoty spolu s hodnotou z kódu. Typ BindableObject má metodu CoerceValue , která může být volána k vynucení opětovného hodnocení hodnoty argumentu BindableProperty vyvoláním zpětného volání hodnoty coerce.

Zpětné volání hodnoty coerce se používají k vynucení opětovného hodnocení bindable vlastnosti, když se hodnota vlastnosti chystá změnit. Zpětné volání hodnoty převodu hodnoty lze například použít k zajištění, že hodnota jedné bindable vlastnosti není větší než hodnota jiné bindable vlastnosti.

Následující příklad kódu ukazuje, jak Angle bindable vlastnost registruje metodu CoerceAngle jako metodu zpětného volání hodnoty 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 zkontroluje hodnotu MaximumAngle vlastnosti a pokud Angle je hodnota vlastnosti větší, převede hodnotu na MaximumAngle hodnotu vlastnosti. Kromě toho, když MaximumAngle vlastnost změní zpětné volání hodnoty coerce je vyvolána na Angle vlastnosti voláním CoerceValue metody.

Vytvoření výchozí hodnoty pomocí funcu

Lze Func použít k inicializaci výchozí hodnoty bindable vlastnosti, jak je znázorněno v následujícím příkladu:

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

Parametr defaultValueCreator je nastaven na Func hodnotu, která vrací DateTime hodnotu, která představuje dnešní datum.