Format a Property Value 设置属性值的格式

In this lesson, you will learn how to set a display format and an edit mask to a business class property. For this purpose, the Task.StartDate, Task.DueDate, Task.PercentCompleted and PhoneNumber.Number properties' display format will be customized using the Model Editor.

在本课中，您将学习如何为 Business 类属性设置显示格式和编辑掩码。为此，将使用模型编辑器自定义 Task.Startdate、Task.Date、Task.完成百分比和电话号码属性的显示格式。

Note 注意

Before proceeding, take a moment to review the following lessons:

• Inherit from the Business Class Library Class (XPO/EF)
• Place an Action in a Different Location

注意

在继续之前，请花点时间复习以下课程：

从商务舱库类 （XPO/EF） 继承

将操作放置在其他位置

Apply an Edit Mask and a Display Format to a DateTime Property Value

将编辑蒙版和显示格式应用于日期时间属性值

• Invoke the Model Editor for the MySolution.Module project. Navigate to the BOModel | DevExpress.Persistent.BaseImpl(DevExpress.Persistent.BaseImpl.EF) | Task | OwnMembers node and select the DueDate child node. To the right, you will see properties that represent the DueDate property's settings.

• Find the DisplayFormat property located under the Format category. Its default value is "{0:d}". This mask corresponds to the short date pattern (e.g., "3/21/2014"). To use the long date pattern (e.g., "Friday, March 21, 2014"), set the DisplayFormat property to "{0:D}". However, the long date pattern is inconvenient when typing the date manually. So, set the EditMask property value to "d". This mask will be used when the DueDate property editor is focused.

• 调用 MySolution.模块项目的模型编辑器。导航到 BOModel |开发快递.持久.BaseImpl（开发快车.持久.BaseImpl.EF） |任务 |拥有成员节点并选择"到期日"子节点。在右侧，您将看到表示"过期日期"属性设置的属性。

查找位于"格式"类别下的"显示格式"属性。其默认值为 "{0：d}"。"。此掩码对应于短日期模式（例如，"3/21/2014"）。要使用长日期模式（例如，"2014 年 3 月 21 日星期五"），将 DisplayFormat 属性设置为"{0：D}"。"但是，在手动键入日期时，长日期模式不方便。因此，将"编辑掩码"属性值设置为"d"。"。当对焦点的"过期"属性编辑器进行聚焦时，将使用此掩码。

Note 注意

You can set the DisplayFormat property to "D" instead of "{0:D}". These values set the same formatting in a WinForms application. However, note that the "D" value is not valid in an ASP.NET application. Use the "{0:<Format_Specifiers>}" syntax instead.

您可以将 DisplayFormat 属性设置为"D"，而不是"{0：D}"。这些值在 WinForms 应用程序中设置相同的格式。但是，请注意，"D"值在ASP.NET应用程序中无效。请改用"{0：<Format_Specifiers>}"语法。

Select the StartDate child node. Set the DisplayFormat property to "{0:D}" and the EditMask to "d".

选择"开始日期"子节点。将"显示格式"属性设置为"{0：D}"，将"编辑蒙版"设置为"d"。"

• Run the WinForms application. Invoke a detail form for the DemoTask class. You will see that the formatting of the StartDate and DueDate properties depends on the focus. When the Property Editor is focused, the EditMask is applied, and the property value is formatted according to the short date pattern (the "d" edit mask). When the Property Editor is not focused, the DisplayFormat is applied, and the property value is formatted according to the long date pattern (the "D" format specifier).

• 运行 WinForms 应用程序。调用演示任务类的详细信息窗体。您将看到"开始日期"和"到期日期"属性的格式取决于焦点。聚焦属性编辑器时，将应用"编辑蒙版"，并根据短日期模式（"d"编辑蒙版）设置属性值的格式。当属性编辑器未聚焦时，将应用 DisplayFormat，并根据长日期模式（"D"格式指定符）设置属性值的格式。

  

• Run the ASP.NET application. Invoke a detail form for the DemoTask class. You will see that the DisplayFormat is applied, and the StartDate and DueDate property values are formatted according to the long date pattern (the "D" format specifier).

• 运行ASP.NET应用程序。调用演示任务类的详细信息窗体。您将看到"显示格式"已应用，并且"开始日期"和"到期日期"属性值根据长日期模式（"D"格式指定符）进行格式化。

• Click the Edit button to display the DemoTask object in Edit mode. You will see that the EditMask is applied, and the StartDate and DueDate property values are formatted according to the short date pattern (the "d" edit mask).

• 单击"编辑"按钮以"编辑"模式显示"演示任务"对象。您将看到应用了"编辑蒙版"，并且"开始日期"和"到期日期"属性值根据短日期模式（"d"编辑蒙版）进行格式化。

Note 注意

Refer to the Mask Type: Date-time, Format Specifiers and Composite Formatting topics for details about formatting with masks in WinForms, and the Mask Types topic for formatting in ASP.NET. Note the differences in the use of angle brackets.
有关使用 WinForms 中的蒙版进行格式设置的详细信息，请参阅"蒙版类型：日期时间、格式说明符和复合格式设置"主题，以及有关ASP.NET格式设置的"蒙版类型"主题。请注意尖括号使用的差异。

Apply the Display Format to an Integer Property Value

将显示格式应用于整数属性值

• Invoke the Model Editor for the MySolution.Module project. Navigate to the BOModel | DevExpress.Persistent.BaseImpl | Task | OwnMembers node and select the PercentCompleted child node. To the right, you will see properties that represent the PercentCompleted property settings.

• Set the DisplayFormat property to "{0:N0}%".

• 调用 MySolution.模块项目的模型编辑器。导航到 BOModel |开发快车.持久.基础任务 |拥有成员节点并选择完成百分比子节点。在右侧，您将看到表示"完成百分比"属性设置的属性。

• 将"显示格式"属性设置为 {0：N0}%"。"。

• Run the application. Invoke a detail form for the DemoTask class. You will see that the ercentCompleted property value is displayed with the '%' sign appended.

In a WinForms application:

• 运行应用程序。调用演示任务类的详细信息窗体。您将看到"完成百分比"属性值显示并附加了"%"符号。
  在 WinForms 应用程序中：

• In an ASP.NET application:

• 在ASP.NET应用程序中：

• Since the EditMask was not specified, the '%' sign is not appended when the editor is focused in a WinForms application. In an ASP.NET application, the '%' sign is not appended when the Detail View is in Edit mode.

• 由于未指定编辑掩码，因此当编辑器在 WinForms 应用程序中集中时，不会附加"%"符号。在ASP.NET应用程序中，当"详细信息视图处于编辑"模式时，不会附加"%"符号。

Apply the Edit Mask to a String Property Value

将编辑蒙版应用于字符串属性值

• Invoke the Model Editor for the MySolution.Module project. Navigate to the BOModel | DevExpress.Persistent.BaseImpl | PhoneNumber | OwnMembers node and select the Number child node. To the right, you will see properties that represent the Number property's settings.

• Set the EditMask property to "[phone]".

• 调用 MySolution.模块项目的模型编辑器。导航到 BOModel |开发快车.持久.基础电话号码 |拥有成员节点并选择"数字子节点"。在右侧，您将看到表示 Number 属性设置的属性。
• 将 EditMask 属性设置为"[phone]"。。

Note 注意

• The EditMaskType property is set to Simple by default. However, you can use the simplified regular expression mask by setting this property to RegEx. In this instance, an appropriate regular expression for a phone number is "((\d\d\d))\d\d\d-\d\d-\d\d". However, note that the RegEx edit mask type is currently supported in WinForms applications only.
• 默认情况下，"编辑掩码类型"属性设置为"简单"。但是，您可以通过将此属性设置为 RegEx 来使用简化的正则表达式掩码。In this instance, an appropriate regular expression for a phone number is "((ddd))ddd-dd-dd".但是，请注意，RegEx 编辑掩码类型目前仅在 WinForms 应用程序中受支持。
• When the EditMask property is focused, the ellipsis button () is displayed to the right of the property value. You can click this button to invoke the Mask editor dialog, which helps you create and test a mask.
• 聚焦"编辑蒙版"属性时，省略号按钮（椭圆按钮）将显示在属性值的右侧。可以单击此按钮来调用"掩码编辑器"对话框，这有助于创建和测试蒙版。

• Run the WinForms or ASP.NET application. Invoke a detail form for the Contact class. Add a PhoneNumber object to it using the New Action that accompanies the PhoneNumbers collection. In the PhoneNumber Detail View, you will see that the Number property supports the specified mask.

• 运行 WinForms 或ASP.NET应用程序。调用联系人类的详细信息表单。使用"电话号码"集合附带的"新操作"向其添加"电话名"对象。在"电话号码详细信息"视图中，您将看到"号码"属性支持指定的掩码。

• The PhoneNumber Property Editor allows you to input digits at the positions specified by the '0' metacharacters. The '(', ')' and '-' characters cannot be removed, and their positions are fixed. As a result, end-users will not be allowed to type an incorrectly formatted phone number.
• "电话数字"属性编辑器允许您在"0"元字符指定的位置输入数字。无法删除"（'、'）"和"-"字符，并且它们的位置是固定的。因此，最终用户将不允许键入格式不正确的电话号码。
• The '(', ')' and '-' characters are saved within the property value, so you do not need to specify the DisplayFormat to display the parentheses and hyphen when the Property Editor is not focused, or the property value is not editable.

• 属性值中保存了"（''、'）"和"-"字符，因此，当属性编辑器未聚焦或属性值不可编辑时，无需指定 DisplayFormat 来显示括号和连字符。

Refer to the Mask Type: Simple topic for details.
有关详细信息，请参阅掩码类型：简单主题。

Note 注意

The EditMask only prompts a user. It cannot prohibit saving the incorrect value (e.g., when a user does not fill all the required digits in a phone number). Use the Validation Module to configure strict rules.

A custom formatting example is provided in the PropertyEditors | Custom Formatting Properties section of the FeatureCenter demo. By default, the FeatureCenter application is installed in %PUBLIC%\Documents\DevExpress Demos 19.2\Components\eXpressApp Framework\FeatureCenter.
编辑掩码仅提示用户。它不能禁止保存不正确的值（例如，当用户未填写电话号码中的所有所需数字时）。使用验证模块配置严格的规则。
属性编辑器中提供了自定义格式设置示例 |功能中心演示的自定义格式化属性部分。默认情况下，功能中心应用程序安装在 %PUBLIC%_文档_DevExpress 演示 19.2_组件_eXpressApp 框架_功能中心中。

Tip 提示

You can specify default formatting for all properties of a given type. In a platform-specific project, use IModelRegisteredPropertyEditor.DefaultDisplayFormat and IModelRegisteredPropertyEditor.DefaultEditMask properties of a ViewItems | PropertyEditors | RegisteredPropertyEditor node.

您可以为给定类型的所有属性指定默认格式。在特定于平台的项目中，使用 IModel 注册属性编辑器。默认显示格式和 IModel 注册属性编辑器。默认编辑蒙版视图项的属性 |属性编辑器 |已注册属性编辑器节点。