Свойства времени разработки для пользовательских элементов управления (Windows Forms .NET)

В этой статье описано, как свойства обрабатываются для элементов управления в конструкторе визуальных элементов Windows Forms в Visual Studio.

Каждый элемент управления наследует множество свойств из базового класса System.Windows.Forms.Control, например:

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

При создании элемента управления можно определить новые свойства и управлять тем, как они отображаются в конструкторе.

Внимание

Документация по рабочему столу для .NET 7 и .NET 6 находится в стадии разработки.

Определение свойства

Любое общедоступное свойство с методом доступа, определенным элементом управления, автоматически отображается в окне свойств Visual Studio. Если свойство также определяет метод доступа к набору, свойство можно изменить в окне свойств. Однако свойства можно явно отображать или скрывать из окна свойств , применяя его BrowsableAttribute. Этот атрибут принимает один логический параметр, чтобы указать, отображается ли он. Дополнительные сведения об атрибутах см. в разделе "Атрибуты" (C#) или "Атрибуты" (Visual Basic).

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

<Browsable(False)>
Public Property IsSelected As Boolean

[ПРИМЕЧАНИЕ] Сложные свойства, которые не могут быть неявно преобразованы в строку и из нее, требуют преобразователя типов.

Сериализованные свойства

Свойства, заданные в элементе управления, сериализуются в файл кода конструктора. Это происходит, когда для свойства задано значение, отличное от его значения по умолчанию.

Когда конструктор обнаруживает изменение свойства, он вычисляет все свойства элемента управления и сериализирует любое свойство, значение которого не соответствует значению по умолчанию для свойства. Значение свойства сериализуется в файл кода конструктора. Значения по умолчанию помогают конструктору определить, какие значения свойств следует сериализовать.

Значения по умолчанию

Свойство считается значением по умолчанию, если оно применяет DefaultValueAttribute атрибут, либо класс свойства содержит свойства и ResetShouldSerialize методы. Дополнительные сведения об атрибутах см. в разделе "Атрибуты" (C#) или "Атрибуты" (Visual Basic).

Задав значение по умолчанию, включите следующее:

• Свойство предоставляет визуальное указание в окне свойств , если оно было изменено со значения по умолчанию.
• Пользователь может щелкнуть свойство правой кнопкой мыши и выбрать пункт Сбросить, чтобы восстановить значение свойства по умолчанию.
• Конструктор создает более эффективный код.

Если свойство использует простой тип, например примитивный тип, значение по умолчанию можно задать, применив его к свойству DefaultValueAttribute . Однако свойства с этим атрибутом не начинаются автоматически с присвоенного значения. Необходимо задать для резервного поля свойства одно и то же значение по умолчанию. Свойство можно задать в объявлении или конструкторе класса.

Если свойство является сложным типом или вы хотите управлять поведением сброса и сериализации конструктора, определите Reset<PropertyName> и ShouldSerialize<PropertyName> методы класса. Например, если элемент управления определяет Age свойство, методы именуются ResetAge и ShouldSerializeAge.

Внимание

Примените его к свойству DefaultValueAttribute или укажите оба ShouldSerialize<PropertyName>Reset<PropertyName> и методы. Не используйте оба.

Свойства можно "сбросить" в значения по умолчанию в окне "Свойства ", щелкнув правой кнопкой мыши имя свойства и выбрав "Сброс".

Доступность параметра контекстного меню "Свойства>" правой кнопкой мыши ">Сброс" включена, когда:

• Свойство имеет DefaultValueAttribute примененный атрибут, а значение свойства не соответствует значению атрибута.
• Класс свойства определяет Reset<PropertyName> метод без ShouldSerialize<PropertyName>метода.
• Класс свойства определяет Reset<PropertyName> метод и ShouldSerialize<PropertyName> возвращает значение true.

DefaultValueAttribute

Если значение свойства не соответствует указанному значению DefaultValueAttribute, свойство считается измененным и может быть сброшено через окно свойств .

Внимание

Этот атрибут не следует использовать для свойств, имеющих соответствующие методы и ShouldSerialize<PropertyName> соответствующие Reset<PropertyName> методы.

Следующий код объявляет два свойства, перечисление со значением по умолчанию и целым числом по умолчанию со значением North по умолчанию 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

Сброс и следует инициализация

Как и ранее упоминание, методы предоставляют возможность управлять не только поведением сброса свойства, Reset<PropertyName>ShouldSerialize<PropertyName> но и при определении того, изменяется ли значение и должно быть сериализовано в файл кода конструктора. Оба метода работают вместе, и вы не должны определять один без другого.

Внимание

Методы Reset<PropertyName> и методы не должны создаваться для свойства, имеющего объектDefaultValueAttribute.ShouldSerialize<PropertyName>

При Reset<PropertyName> определении окно свойств отображает параметр контекстного меню сброса для этого свойства. При выборе сбросаReset<PropertyName> вызывается метод. Параметр контекстного меню сброса включен или отключен тем, что возвращается методом ShouldSerialize<PropertyName> . При ShouldSerialize<PropertyName> возврате trueуказывает, что свойство изменилось со значения по умолчанию и должно быть сериализовано в файл программной части и включает параметр контекстного меню сброса. Когда false возвращается, параметр контекстного меню сброса отключен, а код позади удален код набора свойств.

Совет

Оба метода могут и должны быть определены с помощью частных область, чтобы они не составляют общедоступный API элемента управления.

Следующий фрагмент кода объявляет свойство с именем Direction. Поведение конструктора этого свойства управляется методами ResetDirection и 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

Преобразователи типов

Хотя преобразователи типов обычно преобразуют один тип в другой, они также предоставляют преобразование строк в значение для сетки свойств и других элементов управления времени разработки. Преобразование строк в значение позволяет представлять сложные свойства в этих элементах управления времени разработки.

Большинство встроенных типов данных (числа, перечисления и другие) имеют преобразователи типов по умолчанию, обеспечивающие преобразования строк в значение и выполняющие проверку проверка. Преобразователи типов по умолчанию находятся в System.ComponentModel пространстве имен и именуются после преобразования типа. Имена типов преобразователя используют следующий формат: {type name}Converter Например, StringConverter, TimeSpanConverter и Int32Converter.

Преобразователи типов широко используются во время разработки в окне "Свойства ". Преобразователь типов можно применять к свойству или типу с помощью преобразователя TypeConverterAttributeтипов.

Окно свойств использует преобразователи для отображения свойства в виде строкового значения при TypeConverterAttribute объявлении свойства. TypeConverterAttribute При объявлении типа окно свойств использует преобразователь для каждого свойства этого типа. Преобразователь типов также помогает сериализовать значение свойства в файле кода конструктора.

Редакторы типов

Окно свойств автоматически использует редактор типов для свойства, если тип свойства является встроенным или известным типом. Например, логическое значение редактируется как поле со списком со значениями True и False , а тип DateTime использует раскрывающийся список календаря.

Внимание

С платформа .NET Framework редакторы пользовательских типов изменились. Дополнительные сведения см. в разделе "Изменения конструктора с момента платформа .NET Framework (Windows Forms .NET)".