Właściwości czasu projektowania dla kontrolek niestandardowych (Windows Forms .NET)

W tym artykule pokazano, jak właściwości są obsługiwane dla kontrolek w programie Windows Forms Visual Projektant w programie Visual Studio.

Każda kontrolka dziedziczy wiele właściwości z klasy System.Windows.Forms.Controlbazowej, takich jak:

• Enabled
• Font
• ForeColor
• Focused
• Visible
• Width

Podczas tworzenia kontrolki można zdefiniować nowe właściwości i kontrolować sposób ich wyświetlania w projektancie.

Ważne

Dokumentacja przewodnika dla komputerów dla platform .NET 7 i .NET 6 jest w budowie.

Definiowanie właściwości

Każda właściwość publiczna z akcesorem get zdefiniowanym przez kontrolkę jest automatycznie widoczna w oknie Właściwości programu Visual Studio. Jeśli właściwość definiuje również metodę dostępu zestawu , właściwość można zmienić w oknie Właściwości . Właściwości można jednak jawnie wyświetlać lub ukrywać w oknie Właściwości , stosując BrowsableAttributeelement . Ten atrybut przyjmuje pojedynczy parametr logiczny, aby wskazać, czy jest wyświetlany. Aby uzyskać więcej informacji na temat atrybutów, zobacz Atrybuty (C#) lub Omówienie atrybutów (Visual Basic).

[Browsable(false)]
public bool IsSelected { get; set; }

<Browsable(False)>
Public Property IsSelected As Boolean

[UWAGA] Złożone właściwości, które nie mogą być niejawnie konwertowane na i z ciągu wymagają konwertera typów.

Właściwości serializowane

Właściwości ustawione na kontrolce są serializowane w pliku za pomocą kodu projektanta. Dzieje się tak, gdy wartość właściwości jest ustawiona na inną niż jej wartość domyślna.

Gdy projektant wykryje zmianę właściwości, ocenia wszystkie właściwości kontrolki i serializuje dowolną właściwość, której wartość nie jest zgodna z wartością domyślną właściwości. Wartość właściwości jest serializowana w pliku code-behid projektanta. Wartości domyślne ułatwiają projektantowi określenie, które wartości właściwości powinny być serializowane.

Wartości domyślne

Właściwość jest uważana za wartość domyślną, gdy stosuje DefaultValueAttribute atrybut lub klasa właściwości zawiera właściwości specyficzne Reset i ShouldSerialize metody. Aby uzyskać więcej informacji na temat atrybutów, zobacz Atrybuty (C#) lub Omówienie atrybutów (Visual Basic).

Ustawiając wartość domyślną, należy włączyć następujące elementy:

• Właściwość udostępnia wizualne wskazanie w oknie Właściwości, jeśli została zmodyfikowana z jego wartości domyślnej.
• Użytkownik może kliknąć prawym przyciskiem myszy właściwość i wybrać polecenie Resetuj , aby przywrócić właściwość do jej wartości domyślnej.
• Projektant generuje bardziej wydajny kod.

Jeśli właściwość używa prostego typu, takiego jak typ pierwotny, można ustawić wartość domyślną, stosując DefaultValueAttribute właściwość do właściwości . Jednak właściwości z tym atrybutem nie zaczynają się automatycznie od tej przypisanej wartości. Należy ustawić pole tworzenia kopii zapasowej właściwości na tę samą wartość domyślną. Właściwość można ustawić na deklaracji lub w konstruktorze klasy.

Jeśli właściwość jest typem złożonym lub chcesz kontrolować zachowanie resetowania i serializacji projektanta, zdefiniuj Reset<PropertyName> metody i ShouldSerialize<PropertyName> w klasie . Jeśli na przykład kontrolka definiuje Age właściwość, metody są nazwane ResetAge i ShouldSerializeAge.

Ważne

Zastosuj element DefaultValueAttribute do właściwości lub podaj metody i Reset<PropertyName>ShouldSerialize<PropertyName> . Nie używaj obu tych elementów.

Właściwości mogą być "resetowane" do ich wartości domyślnych w oknie Właściwości, klikając prawym przyciskiem myszy nazwę właściwości i wybierając polecenie Resetuj.

Dostępność opcji menu kontekstowego Resetuj > prawym przyciskiem myszy>właściwości jest włączona, gdy:

• Właściwość ma DefaultValueAttribute zastosowany atrybut, a wartość właściwości nie jest zgodna z wartością atrybutu.
• Klasa właściwości definiuje metodę Reset<PropertyName> bez ShouldSerialize<PropertyName>klasy .
• Klasa właściwości definiuje metodę Reset<PropertyName> i ShouldSerialize<PropertyName> zwraca wartość true.

Defaultvalueattribute

Jeśli wartość właściwości nie jest zgodna z wartością podaną przez DefaultValueAttributeusługę , właściwość jest uważana za zmienioną i może zostać zresetowana za pośrednictwem okna Właściwości .

Ważne

Ten atrybut nie powinien być używany we właściwościach, które mają odpowiednie Reset<PropertyName> metody i ShouldSerialize<PropertyName> .

Poniższy kod deklaruje dwie właściwości, wyliczenie z wartością North domyślną i liczbą całkowitą z wartością domyślną 10.

[DefaultValue(typeof(Directions), "North")]
public Directions PointerDirection { get; set; } = Directions.North;

[DefaultValue(10)]
public int DistanceInFeet { get; set; } = 10;

<DefaultValue(GetType(Directions), "North")>
Public Property PointerDirection As Directions = Directions.North

<DefaultValue(10)>
Public Property DistanceInFeet As Integer = 10

Resetuj i ShouldSerialize

Jak wspomniano wcześniej, metody i ShouldSerialize<PropertyName> zapewniają możliwość kierowania nie tylko zachowaniem resetowania właściwości, ale także w określaniu, Reset<PropertyName> czy wartość została zmieniona i powinna być serializowana w pliku za pomocą kodu projektanta. Obie metody współpracują ze sobą i nie należy definiować jednej bez drugiej.

Ważne

Metody Reset<PropertyName> i ShouldSerialize<PropertyName> nie powinny być tworzone dla właściwości, która ma właściwość DefaultValueAttribute.

Po Reset<PropertyName> zdefiniowaniu w oknie Właściwości zostanie wyświetlona opcja menu kontekstowego Resetuj dla tej właściwości. Po wybraniu opcji Resetuj wywoływana Reset<PropertyName> jest metoda . Opcja Resetuj menu kontekstowego jest włączona lub wyłączona przez funkcję zwracaną przez metodę ShouldSerialize<PropertyName> . Gdy ShouldSerialize<PropertyName> funkcja zwraca truewartość , wskazuje, że właściwość zmieniła się z wartości domyślnej i powinna zostać serializowana w pliku za pomocą kodu i włącza opcję menu kontekstowego Resetuj . Po false powrocie opcja menu kontekstowego Resetuj jest wyłączona, a kod-behind ma usunięty kod zestawu właściwości.

Napiwek

Obie metody mogą i powinny być zdefiniowane z zakresem prywatnym, aby nie tworzą publicznego interfejsu API kontrolki.

Poniższy fragment kodu deklaruje właściwość o nazwie Direction. Zachowanie projektanta tej właściwości jest kontrolowane przez ResetDirection metody i ShouldSerializeDirection .

public Directions Direction { get; set; } = Directions.None;

private void ResetDirection() =>
    Direction = Directions.None;

private bool ShouldSerializeDirection() =>
    Direction != Directions.None;

Public Property Direction As Directions = Directions.None

Private Sub ResetDirection()
    Direction = Directions.None
End Sub

Private Function ShouldSerializeDirection() As Boolean
    Return Direction <> Directions.None
End Function

Konwertery typów

Konwertery typów zwykle konwertują jeden typ na inny, ale zapewniają również konwersję ciąg-wartość dla siatki właściwości i innych kontrolek czasu projektowania. Konwersja ciąg-wartość umożliwia reprezentowanie złożonych właściwości w tych kontrolkach czasu projektowania.

Większość wbudowanych typów danych (liczb, wyliczenia i innych) ma domyślne konwertery typów, które zapewniają konwersje ciąg-wartość i przeprowadzają kontrole poprawności. Konwertery typów domyślnych znajdują się w System.ComponentModel przestrzeni nazw i są nazwane po przekonwertowaniu typu. Nazwy typów konwertera używają następującego formatu: {type name}Converter. Na przykład , StringConverterTimeSpanConverteri Int32Converter.

Konwertery typów są szeroko używane w czasie projektowania w oknie Właściwości . Konwerter typów można zastosować do właściwości lub typu przy użyciu klasy TypeConverterAttribute.

Okno Właściwości używa konwerterów do wyświetlania właściwości jako wartości ciągu, gdy TypeConverterAttribute właściwość jest zadeklarowana we właściwości. TypeConverterAttribute Gdy właściwość jest zadeklarowana w typie, okno Właściwości używa konwertera dla każdej właściwości tego typu. Konwerter typów pomaga również serializować wartość właściwości w pliku za pomocą kodu projektanta.

Edytory typów

Okno Właściwości automatycznie używa edytora typów dla właściwości, gdy typ właściwości jest wbudowanym lub znanym typem. Na przykład wartość logiczna jest edytowana jako pole kombi z wartościami True i False , a DateTime typ używa listy rozwijanej kalendarza.

Ważne

Edytory typów niestandardowych zmieniły się od platformy .NET Framework. Aby uzyskać więcej informacji, zobacz Projektant zmienia się od .NET Framework (Windows Forms .NET).