Contract zh CN

命名与约定

返回目录

适用于:   v1.1.12 或更新的版本

本篇文档假定你已清楚如何使用WPF资源字典。资源字典可以被添加在 App.xaml 中来获得全局效果，或是放置在控件的 Resources 属性中来影响该控件及其所有子控件的效果。
有关如何使用资源字典（ResourceDictionary），或如何使用合并资源字典（MergedResourceDictionaries），请使用这些关键字查阅WPF教程。
本文档中提及的 Xxx 均表示可能出现的前缀或后缀英文单词，而非实际的属性名称。

---

命名

原生控件的辅助类

所有 Panuon.WPF.UI 提供支持的WPF原生控件都通过 Helper辅助类 来调整样式。
例如， Button 按钮 的辅助类为 ButtonHelper ， TextBox 输入框 的辅助类为 TextBoxHelper 。
在Visual Studio编辑器的 Button 按钮 控件上，输入以下代码中的最后一个小数点后，弹出的智能感知中就会展示出所有支持的属性。

xmlns:pu="https://opensource.panuon.com/wpf-ui"
...

<Button pu:ButtonHelper.

利用Visual Studio的智能感知功能，可以帮助你更好地熟悉控件库的使用。

特殊的通用辅助类

GlobalSettings 辅助类可以全局设置所有控件渐变动画的时长、禁用时的透明度、字体、图标字体等属性。
WindowXCaption 辅助类可以且仅可以用于调整 WindowX 窗体X 控件的标题栏区域。
WindowXModalDialog 辅助类可以且仅可以用于调整 WindowX 窗体X 控件的模态按钮栏区域。
IconHelper 辅助类可以用于调整任何带有 Icon 属性的控件（例如 Button 按钮 、 DateTimePicker 等）的图标样式。
ShadowHelper 辅助类可以用于调整任何带有 ShadowColor 或 XxxShadowColor 属性（例如 HoverShadowColor 和 CheckedShadowColor 等）的控件（例如 Button 按钮 、 DateTimePicker 等）的阴影效果。
DropDownHelper 辅助类可以用于调整任何带有 PopupX 弹出框的控件（例如 ComboBox 、 Menu 、 ContextMenu 、 DateTimePicker 、 DropDown 等，详见控件文档）的弹出框样式。

属性

无论是原生控件还是Panuon.WPF.UI中提供的自定义控件，所有属性均采用相似的命名方式。

常规

定义悬浮效果的属性名称通常为HoverXxx，而定义选中效果的属性名称为SelectedXxx或CheckedXxx，等。
对于复杂控件，例如 DataGrid ，属性还会增加前缀。例如，修改标头样式的属性名称为 ColumnHeaderXxx，修改单元格样式的属性名称为CellXxx，修改行样式的属性名称为RowXxx，等。

派生自ItemsControl的控件

对于派生自ItemsControl的原生控件（例如 ComboBox 、ListBox 、 TabControl 等），其控件和子项控件的属性会分别使用 XxxHelper 和 XxxItemHelper 做区分。例如， ComboBox 控件的样式需要使用 ComboBoxHelper 辅助类调整，而 ComboBoxItem 控件的属性则通过 ComboBoxItemHelper 辅助类来调整。

此外，对于派生自ItemsControl的所有控件（包括原生控件以及自定义控件 CalendarX ， Pagination 等），所有以 Items 为前缀的属性都具有统一设置其所有子项控件中对应属性的效果。
这是一个示例：

xmlns:pu="https://opensource.panuon.com/wpf-ui"
···

<ComboBox pu:ComboBoxHelper.ItemsHoverBackground="Red">
    <ComboBoxItem Content="Item 1" />
    <ComboBoxItem Content="Item 2" />
    <ComboBoxItem Content="Item 3"
                  pu:ComboBoxItemHelper.HoverBackground="Blue" />
</ComboBox>

当鼠标悬浮在第1、2个 ComboBoxItem 上时，它的背景色会变成红色；当鼠标悬浮在第3个子项上时， ComboBoxItem 的背景色会变成蓝色。

---

样式

以下内容仅针对WPF中的原生控件，对于 Panuon.WPF.UI 中提供的自定义控件，无需引用任何资源字典即可使用。
Panuon.WPF.UI 提供了三种不同的方式来适配你的项目。通过后两种方式（尤其是最后一种方式），你可以在使用 Panuon.WPF.UI 的同时还能使用其他的控件库，让你的项目效果变得更加丰富。

1. 让Panuon.WPF.UI对所有原生控件都生效

使用以下资源字典：

<ResourceDictionary Source="pack://application:,,,/Panuon.WPF.UI;component/Control.xaml" />

2. 让Panuon.WPF.UI只对某一种控件生效

使用控件文档中提供的概述 -> 全局资源字典。全局资源字典通常为以下格式（以控件文档中提供的为准）：

<ResourceDictionary Source="pack://application:,,,/Panuon.WPF.UI;component/Styles/$TypeName$.xaml" />  

上述代码中的 $TypeName$ 应被替换为对应的原生控件名称，例如 Button 按钮 、 TextBox 输入框 等。例如：

<ResourceDictionary Source="pack://application:,,,/Panuon.WPF.UI;component/Styles/Button.xaml" />  

3. 让Panuon.WPF.UI只对某一个控件生效

Step 1 添加资源字典

使用控件文档中提供的概述 -> 独立资源字典。独立资源字典通常为以下格式（以控件文档中提供的为准）：

<ResourceDictionary Source="pack://application:,,,/Panuon.WPF.UI;component/Styles/$TypeName$Style.xaml" />  

上述代码中的 $TypeName$ 应当被替换为对应的原生控件名称，例如 Button 按钮 、 TextBox 输入框 等。例如：

<ResourceDictionary Source="pack://application:,,,/Panuon.WPF.UI;component/Styles/ButtonStyle.xaml" />  

Step 2 继承样式或直接使用

使用控件文档中提供的概述 -> 独立资源样式键。独立资源样式键通常为以下格式（以控件文档中提供的为准）：
pu:StyleKeys.$TypeName$Style
上述格式中的 $TypeName$ 应当被替换为对应的原生控件名称，例如 Button 按钮 、 TextBox 输入框 等。
这是一个代码示例：

xmlns:pu="https://opensource.panuon.com/wpf-ui"
···
<!--也可以在App.xaml中引用该资源字典，这样就不需要在每个控件中都写一遍-->
<Window.Resources>
    <ResourceDictionary Source="pack://application:,,,/Panuon.WPF.UI;component/Styles/ButtonStyle.xaml" /> 
</Window.Resources>

···

<Style x:Key="MyButtonStyle"
       BasedOn="{StaticResource {x:Static pu:StyleKeys.ButtonStyleKey}}">
</Style>
···

<!--这两个控件的效果是完全相同的，但第一种方式允许你在Panuon.WPF.UI的基础上进行二次封装。-->
<Button Style="{StaticResource MyButtonStyle}" />
<Button Style="{StaticResource {x:Static pu:StyleKeys.ButtonStyleKey}}" />

对于 ComboBox 、 ListBox 、Menu 等派生自 ItemsControl 的控件，如果希望修改其子项的样式并保留 Panuon.WPF.UI 提供的效果，可以使用如下代码：

<ListBox.ItemContainerStyle>
    <Style TargetType="ListBoxItem"
           BasedOn="{StaticResource {x:Static pu:StyleKeys.ListBoxItemStyleKey}}">
    </Style>
</ListBox.ItemContainerStyle>

---

组件资源键

如果 Panuon.WPF.UI 在控件内使用了其他控件（例如 WindowX 窗体X 标题栏中的最小化按钮 Button 按钮 控件），并且你需要重新定义该控件的样式，就需要通过继承资源键的方式来继承原有样式的属性值，并在此基础上进行修改。
通常情况下，组件资源键的样式中只包含与显示效果有关的属性。这意味着，继承组件资源键的样式并不是必须的；但如果不从该资源键上继承样式，你可能需要通过添加更多的新属性来保证显示效果。

资源键格式

资源键的格式通常为（以控件文档中提供的为准）：
$PropertyName$Key
上述格式中的 $PropertyName$ 应当被替换为属性的名称。
这是一个代码示例：

<pu:WindowXCaption.MinimizeButtonStyle>
    <Style TargetType="Button"
           BasedOn="{StaticResource {x:Static pu:WindowXCaption.MinimizeButtonStyleKey}}">
    </Style>
</pu:WindowXCaption.MinimizeButtonStyle>

上述示例演示了继承WindowX最小化按钮样式的方法。其中，资源键的名称 = 属性名称 + Key 后缀。在Panuon.WPF.UI中，所有的资源键命名都遵循这种格式。

注意：这些内部控件的样式不依赖任何资源字典。在不引用任何资源字典的情况下，就能继承资源键中的样式。