学习017-01 Declare Conditional Appearance Rules in Code（在代码中声明条件显示规则）

Declare Conditional Appearance Rules in Code（在代码中声明条件显示规则）

The Conditional Appearance module allows you to change the appearance and visibility of different UI elements, as well as make them disabled/enabled. These elements include properties in List Views, built-in Property Editors and Static Text in Detail Views. In addition, you can make Actions visible/invisible or enabled/disabled. The required appearance can be applied under the specified conditions. To apply a particular appearance to the target UI element, define a rule in code or in the Application Model. In this topic, you will learn how to define an appearance rule in code. To learn the general information on the Conditional Appearance module and appearance rules, refer to the Conditional Appearance Module Overview topic. To learn how to define appearance rules in the Application Model, refer to the Declare Conditional Appearance Rules in the Application Model topic.
条件外观模块允许您更改不同用户界面元素的外观和可见性，以及使其禁用/启用。这些元素包括列表视图中的属性、内置属性编辑器和详细视图中的静态文本。此外，您可以使操作可见/不可见或启用/禁用。所需的外观可以在指定条件下应用。要将特定外观应用于目标用户界面元素，请在代码中或应用程序模型中定义规则。在本主题中，您将了解如何在代码中定义外观规则。要了解有关条件外观模块和外观规则的常规信息，请参阅“条件外观模块概述”主题。要了解如何在应用程序模型中定义外观规则，请参阅“在应用程序模型中声明条件外观规则”主题。

Prerequisites（先决条件）

Make sure that the following conditions are met:
确保满足以下条件：

1.Your project contains the DevExpress.ExpressApp.ConditionalAppearance NuGet package.
您的项目包含 DevExpress.ExpressApp.ConditionalAppearance NuGet 包。

2.The MySolution.Blazor.Server\\Startup.cs or MySolution.Win\\Startup.cs files contain the following line:
MySolution.Blazor.Server\\Startup.cs 或 MySolution.Win\\Startup.cs 文件包含以下行：

C#
builder.Modules
// …
.AddConditionalAppearance()
// …

For more information on how to add the Conditional Appearance Module, see: Conditional Appearance (Manage UI State).
有关如何添加条件外观模块的更多信息，请参阅：条件外观（管理用户界面状态）。

General Information（一般信息）

To define an appearance rule in code, use the AppearanceAttribute. This attribute is declared in the DevExpress.ExpressApp.ConditionalAppearance namespace of the DevExpress.ExpressApp.ConditionalAppearance.v24.1.dll assembly. So to use the attribute, you will need to add the corresponding using directive.
要在代码中定义外观规则，请使用AppearanceAttribute。此特性在DevExpress.ExpressApp.ConditionalAppearance.v24.1.dll程序集的DevExpress.ExpressApp.ConditionalAppearance命名空间中声明。因此，要使用该特性，您需要添加相应的using 指令。

When applying the Appearance attribute, set the rule’s Id using the AppearanceAttribute.Id parameter. The remaining rule properties are specified using the attribute’s named parameters.
应用外观属性时，使用AppearanceAttribute.Id参数设置规则的Id。其余规则属性使用该属性的命名参数指定。

• AppearanceAttribute.AppearanceItemType
• AppearanceAttribute.TargetItems
• AppearanceAttribute.Context
• AppearanceAttribute.Criteria
• AppearanceAttribute.BackColor
• AppearanceAttribute.FontColor
• AppearanceAttribute.FontStyle
• AppearanceAttribute.Enabled
• AppearanceAttribute.Visibility
• AppearanceAttribute.Method
• AppearanceAttribute.Priority

When using the Appearance attribute, first specify which UI elements you are going to affect via the appearance rule: apply the Appearance attribute to either a business class or a business class property, and set its AppearanceItemType and TargetItems parameters. The following table illustrates several use cases.
在使用“外观”属性时，首先要通过外观规则指定要影响哪些用户界面元素：将“外观”属性应用于业务类或业务类属性，并设置其AppearanceItemType和TargetItems参数。下表说明了几种用例。

Then, specify the rule’s activity scope. For this purpose, use the following Appearance attribute parameters:
然后，指定规则的活动范围。为此，请使用以下外观属性参数：

• AppearanceAttribute.Context – specify in which Views to activate the rule;（指定在哪些视图中激活该规则；）
• AppearanceAttribute.Criteria – specify which criteria must be satisfied by the target object;（指定目标对象必须满足哪些标准；）
• AppearanceAttribute.Method – specify the method that returns true for the rule’s activation (you can apply the Appearance attribute to this method and miss the Method parameter in the attribute’s definition);（指定一个方法，当规则激活时该方法返回true（你可以将Appearance属性应用于此方法，并且在属性定义中省略Method参数）；）
• AppearanceAttribute.Priority – specify the current rule’s volume when several rules affect the same UI element.（当多个规则影响同一个用户界面元素时，指定当前规则的作用范围。）

For details on these attribute parameters refer to their description in the Reference help section.
有关这些属性参数的详细信息，请参阅参考帮助部分中的描述。

The last step in the appearance rule definition is specifying required appearance customizations. For this purpose, use the following attribute parameters.
外观规则定义的最后一步是指定所需的外观自定义。为此，请使用以下属性参数。

• AppearanceAttribute.BackColor
• AppearanceAttribute.FontColor
• AppearanceAttribute.FontStyle
• AppearanceAttribute.Enabled
• AppearanceAttribute.Visibility

Rules declared via the Appearance attribute are reflected in the Application Model. They are collected in the corresponding Application | BOModel | |AppearanceRules node. For details on this node, refer to the Declare Conditional Appearance Rules in the Application Model topic.
通过“外观”属性声明的规则会反映在应用程序模型中。它们收集在相应的“应用程序”|“业务对象模型”|“<类>”|“外观规则”节点中。有关此节点的详细信息，请参阅“在应用程序模型中声明条件外观规则”主题。

Examples（示例）

According to the rule demonstrated in the example below, the Product objects whose Price is more than 50 will be displayed in Red background using Maroon font color in List Views.
根据以下示例所示的规则，在列表视图中，价格超过50的产品对象将以栗色字体显示在红色背景上。

C# (EF Core)
using DevExpress.ExpressApp.ConditionalAppearance;
//…
[Appearance("RedPriceObject", AppearanceItemType = "ViewItem", TargetItems = "*",
Criteria = "Price>50", Context = "ListView", BackColor = "Red",
FontColor = "Maroon", Priority = 2)]
public class Product : BaseObject {
public virtual string Name { get; set; }
public virtual decimal Price { get; set; }
public virtual ProductStatus Status { get; set; }
public virtual Category Category { get; set; }
}

// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.

C# (XPO)
using DevExpress.ExpressApp.ConditionalAppearance;
//…
[Appearance("RedPriceObject", AppearanceItemType = "ViewItem", TargetItems = "*",
Criteria = "Price>50", Context = "ListView", BackColor = "Red",
FontColor = "Maroon", Priority = 2)]
public class Product : BaseObject {
public Product(Session session) : base(session) { }
public string Name {
//…
}
public decimal Price {
//…
}
public ProductStatus Status {
//…
}
public Category Category {
//…
}
}

According to the rule demonstrated in the example below, the Category property in List Views will be displayed in Blue font color when its value is “Seafood”.
根据以下示例中展示的规则，当列表视图中的“类别”属性值为“海鲜”时，其字体颜色将显示为蓝色。

C# (EF Core)
using DevExpress.ExpressApp.ConditionalAppearance;
//…
[Appearance("CategoryColoredInListView", AppearanceItemType = "ViewItem", TargetItems = "Category",
Criteria = "Category = 'Seafood'", Context = "ListView", FontColor = "Blue", Priority = 1)]
public class Product : BaseObject {
public virtual Category Category { get; set; }
}

[DefaultProperty(nameof(Name))]
public class Category : BaseObject {
public virtual string Name { get; set; }
}

// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.

C# (XPO)
using DevExpress.ExpressApp.ConditionalAppearance;
//…
[Appearance("CategoryColoredInListView", AppearanceItemType = "ViewItem", TargetItems = "Category",
Criteria = "Category = 'Seafood'", Context = "ListView", FontColor = "Blue", Priority = 1)]
public class Product : BaseObject {
public Product(Session session) : base(session) { }
public Category Category {
//…
}
}
[DefaultProperty(nameof(Name))]
public class Category : BaseObject {
public Category(Session session) : base(session) {}
public string Name {
//…
}
}

According to the rule demonstrated in the example below, the Category layout item’s caption in Product Detail Views is displayed in blue when the product’s category is “Seafood”.
根据以下示例中展示的规则，当产品类别为“海鲜”时，产品详情视图中类别布局项的标题将显示为蓝色。

C# (EF Core)
using DevExpress.ExpressApp.ConditionalAppearance;
//…
public class Product : BaseObject {
[Appearance("CategoryColoredInDetailView", AppearanceItemType = "LayoutItem",
TargetItems = "Category", Criteria = "Category = 'Seafood'", Context = "DetailView",
FontColor = "Blue")]
public virtual Category Category { get; set; }
}

[DefaultProperty(nameof(Name))]
public class Category : BaseObject {
public virtual string Name { get; set; }
}

// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.

C# (XPO)
using DevExpress.ExpressApp.ConditionalAppearance;
//…
public class Product : BaseObject {
public Product(Session session) : base(session) { }
[Appearance("CategoryColoredInDetailView", AppearanceItemType = "LayoutItem",
TargetItems = "Category", Criteria = "Category = 'Seafood'", Context = "DetailView",
FontColor = "Blue")]
public Category Category {
//…
}
}
[DefaultProperty(nameof(Name))]
public class Category : BaseObject {
public Category(Session session) : base(session) {}
public string Name {
//…
}
}

According to the rule demonstrated in the example below, the “ProductParameters” layout group caption in the Product Detail View will be displayed in Blue font color when the Category property is set to “Seafood”.
根据以下示例所示规则，当“类别”属性设置为“海鲜”时，产品详细信息视图中的“产品参数”布局组标题将以蓝色字体显示。

C# (EF Core)
using DevExpress.ExpressApp.ConditionalAppearance;
//…
[Appearance("LayoutGroupColoredInDetailView", AppearanceItemType = "LayoutItem",
TargetItems = "ProductParametersLayoutGroup", Criteria = "Category = 'Seafood'",
Context = "Product_DetailView", FontColor = "Blue")]
public class Product : BaseObject {
public virtual string Name { get; set; }
public virtual decimal Price { get; set; }
public virtual ProductStatus Status { get; set; }
public virtual Category Category { get; set; }
}

[DefaultProperty(nameof(Name))]
public class Category : BaseObject {
public virtual string Name { get; set; }
}

// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.

C# (XPO)
using DevExpress.ExpressApp.ConditionalAppearance;
//…
[Appearance("LayoutGroupColoredInDetailView", AppearanceItemType = "LayoutItem",
TargetItems = "ProductParametersLayoutGroup", Criteria = "Category = 'Seafood'",
Context = "Product_DetailView", FontColor = "Blue")]
public class Product : BaseObject {
public Product(Session session) : base(session) { }
public string Name {
//…
}
public decimal Price {
//…
}
public ProductStatus Status {
//…
}
public Category Category {
//…
}
}
[DefaultProperty(nameof(Name))]
public class Category : BaseObject {
public Category(Session session) : base(session) {}
public string Name {
//…
}
}

According to the rule demonstrated in the example below, a Product’s Deactivate Action will be disabled when the Status property is set to “Inactive” in all Product Views. Note that the Action ID specified in this rule contains the class name (“Product.Deactivate”), because the Deactivate Action is declared using the ActionAttribute. If an Action is declared in a Controller, specify its ID without the class name, e.g., “Delete” or “Unlink”.
根据以下示例所示规则，当所有产品视图中的“状态”属性设置为“已停用”时，产品的“停用”操作将被禁用。请注意，此规则中指定的操作ID包含类名（“Product.Deactivate”），因为“停用”操作是使用ActionAttribute声明的。如果某个操作在控制器中声明，则指定其ID时无需包含类名，例如“删除”或“取消链接”。

C# (EF Core)
using DevExpress.ExpressApp.ConditionalAppearance;
//…
[Appearance("ActionState", AppearanceItemType = "Action",
TargetItems = "Product.Deactivate",
Criteria = "Status = 'Inactive'", Context = "Any", Enabled = false)]
public class Product : BaseObject {
public virtual ProductStatus Status { get; set; }
[Action(PredefinedCategory.RecordEdit, Caption = "Deactivate Product…", AutoCommit = true,
TargetObjectsCriteria = "Status = 'Active'",
SelectionDependencyType = MethodActionSelectionDependencyType.RequireSingleObject)]
public void Deactivate() {
Status = ProductStatus.Inactive;
}
}

// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.

C# (XPO)
using DevExpress.ExpressApp.ConditionalAppearance;
//…
[Appearance("ActionState", AppearanceItemType = "Action",
TargetItems = "Product.Deactivate",
Criteria = "Status = 'Inactive'", Context = "Any", Enabled = false)]
public class Product : BaseObject {
public Product(Session session) : base(session) { }
public ProductStatus Status {
//…
}
[Action(PredefinedCategory.RecordEdit, Caption = "Deactivate Product…", AutoCommit = true,
TargetObjectsCriteria = "Status = 'Active'",
SelectionDependencyType = MethodActionSelectionDependencyType.RequireSingleObject)]
public void Deactivate() {
Status = ProductStatus.Inactive;
}
}

According to the rule demonstrated in the example below, the Product objects in List Views will be displayed in Green background using Black font color when the RuleMethod returns true.
根据以下示例中展示的规则，当RuleMethod返回true时，列表视图中的产品对象将以黑色字体、绿色背景显示。

C# (EF Core)
using DevExpress.ExpressApp.ConditionalAppearance;
//…
public class Product : BaseObject {
public virtual decimal Price { get; set; }
public virtual ProductStatus Status { get; set; }
[Appearance("RuleMethod", AppearanceItemType = "ViewItem", TargetItems = "*", Context = "ListView",
BackColor = "Green", FontColor = "Black")]
public bool RuleMethod() {
if (Price < 10 && Status == ProductStatus.Active) {
return true;
}
else {
return false;
}
}
}

// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.

C# (XPO)
using DevExpress.ExpressApp.ConditionalAppearance;
//…
public class Product : BaseObject {
public Product(Session session) : base(session) { }
public decimal Price {
//…
}
public ProductStatus Status {
//…
}
[Appearance("RuleMethod", AppearanceItemType = "ViewItem", TargetItems = "*", Context = "ListView",
BackColor = "Green", FontColor = "Black")]
public bool RuleMethod() {
if (Price < 10 && Status == ProductStatus.Active) {
return true;
}
else {
return false;
}
}
}

There are more examples demonstrated in the FeatureCenter demo installed with XAF. This demo is located in the %PUBLIC%\\Documents\\DevExpress Demos 24.1\\Components\\XAF\\FeatureCenter.NETFramework.XPO folder by default.
在与XAF一起安装的功能中心演示中展示了更多示例。默认情况下，此演示位于 %PUBLIC%\\Documents\\DevExpress Demos 24.1\\Components\\XAF\\FeatureCenter.NETFramework.XPO文件夹中。