diff --git a/docs/guides/styles-and-resources/troubleshooting.md b/docs/guides/styles-and-resources/troubleshooting.md index 2e72df7a1..5b37ba557 100644 --- a/docs/guides/styles-and-resources/troubleshooting.md +++ b/docs/guides/styles-and-resources/troubleshooting.md @@ -24,16 +24,16 @@ Check whether you have used a child selector where there are no children to matc Styles are applied in order of declaration. If there are multiple style files included that target the same control property, the last style included will override the previous ones. For example: -```xml +```xml title="Style1.axaml" ``` -```xml +```xml title="Style2.axaml" ``` @@ -58,7 +58,14 @@ A local value defined directly on a control often has higher priority than any s You can see the full list of value priorities in the `BindingPriority` enum, where lower enum values have the higher priority. -
BindingPriority ValueComment
Animation-1The highest priority - even overrides a local value
LocalValue0A local value is set on the property of the control.
StyleTrigger1This is triggered when a pseudo class becomes active.
TemplatedParent2
Style3
Unset2147483647
+| BindingPriority | Value | Comment | +|-----------------|------------|------------------------------------------------------| +| `Animation` | -1 | The highest priority - even overrides a local value | +| `LocalValue` | 0 | A local value is set on the property of the control. | +| `StyleTrigger` | 1 | This is triggered when a style becomes active. | +| `Template` | 2 | | +| `Style` | 3 | | +| `Unset` | 2147483647 | | :::warning The exception is that `Animation` values have the highest priority and can even override local values. @@ -104,7 +111,7 @@ The following code example of styles that can be expected to work on top of defa You might expect the `Button` to be red by default and blue when pointer is over it. In fact, only setter of first style will be applied, and second one will be ignored. -The reason is hidden in the Button's template. You can find the default templates in the Avalonia source code (old [Default](https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Themes.Default/Button.xaml) theme and new [Fluent](https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Themes.Fluent/Controls/Button.xaml) theme), but for convenience here we have simplified one from the Fluent theme: +The reason is hidden in the Button's template. You can find the default templates in the Avalonia source code ([Simple](https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Themes.Simple/Controls/Button.xaml) theme and [Fluent](https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Themes.Fluent/Controls/Button.xaml) theme), but for convenience here we have simplified one from the Fluent theme: ```xml ``` -```xml +```xml title="Style2.axaml" ``` @@ -58,7 +58,14 @@ A local value defined directly on a control often has higher priority than any s You can see the full list of value priorities in the `BindingPriority` enum, where lower enum values have the higher priority. -
BindingPriority ValueComment
Animation-1The highest priority - even overrides a local value
LocalValue0A local value is set on the property of the control.
StyleTrigger1This is triggered when a pseudo class becomes active.
TemplatedParent2
Style3
Unset2147483647
+| BindingPriority | Value | Comment | +|-----------------|------------|------------------------------------------------------| +| `Animation` | -1 | The highest priority - even overrides a local value | +| `LocalValue` | 0 | A local value is set on the property of the control. | +| `StyleTrigger` | 1 | This is triggered when a style becomes active. | +| `Template` | 2 | | +| `Style` | 3 | | +| `Unset` | 2147483647 | | :::warning The exception is that `Animation` values have the highest priority and can even override local values. @@ -104,7 +111,7 @@ The following code example of styles that can be expected to work on top of defa You might expect the `Button` to be red by default and blue when pointer is over it. In fact, only setter of first style will be applied, and second one will be ignored. -The reason is hidden in the Button's template. You can find the default templates in the Avalonia source code (old [Default](https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Themes.Default/Button.xaml) theme and new [Fluent](https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Themes.Fluent/Controls/Button.xaml) theme), but for convenience here we have simplified one from the Fluent theme: +The reason is hidden in the Button's template. You can find the default templates in the Avalonia source code ([Simple](https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Themes.Simple/Controls/Button.xaml) theme and [Fluent](https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Themes.Fluent/Controls/Button.xaml) theme), but for convenience here we have simplified one from the Fluent theme: ```xml ``` -```xml +```xml title="Style2.axaml" ``` @@ -42,11 +42,11 @@ _Avalonia UI_ 的选择器，就像 CSS 选择器一样，当没有匹配的控 ``` -在这个例子中，首先应用了来自文件 **Styles1.axaml** 的样式，所以文件 **Styles2.axaml** 中的样式设置会覆盖之前的样式。最终的 TextBlock 将具有 FontSize="16" 和 Foreground="Green"。在样式文件内部也会发生相同的优先级排序。 +在此例中，**Style1.axaml** 的样式会先应用，**Style2.axaml** 的样式会覆盖前者。最终 TextBlock 生效的是 FontSize="16" 和 Foreground="Blue"。在样式文件内部也是同样的优先级规则。 -## 本地设置的属性具有优先级 +## 本地设置的属性值优先级更高 -直接在控件上定义的本地值通常比任何样式值具有更高的优先级。因此，在这个例子中，文本块的前景色将是红色的： +直接在控件上设置的本地值通常优先于样式值。例如，以下代码中 TextBlock 的前景色为红色： ```xml ``` -您可能期望 `Button` 在默认情况下是红色的，当鼠标指针悬停在上面时是蓝色的。实际上，只有第一个样式的 setter 将被应用，第二个将被忽略。 +您可能认为 Button 的背景色默认是红色，悬停时是蓝色。实际上，只有第一个样式的 setter 会生效，第二个会被忽略。 -原因在于 Button 的模板中。您可以在 Avalonia 源代码中找到默认模板（旧版 [Default](https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Themes.Default/Button.xaml) 主题和新版 [Fluent](https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Themes.Fluent/Controls/Button.xaml) 主题），但为了方便起见，我们在此处简化了来自 Fluent 主题的模板： +原因藏在 Button 的模板中。您可以在 Avalonia 源代码中找到默认模板（[Simple](https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Themes.Simple/Controls/Button.xaml) 主题和（[Fluent](https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Themes.Fluent/Controls/Button.xaml) 主题）。但是为了便利，这里提供了一个简化的 Fluent 主题示例： ```xml ``` -实际背景是由 `ContentPresenter` 渲染的，在默认情况下它与按钮的 `Background` 属性绑定。然而，在 pointerover 状态下，选择器直接将背景应用于 `ContentPresenter (Button:pointerover /template/ ContentPresenter#PART_ContentPresenter)`。这就是为什么在前一个代码示例中我们的 setter 被忽略的原因。修正后的代码应该直接针对 content presenter： +实际的背景是由 ContentPresenter 渲染的，默认情况下它绑定到 Button 的 Background 属性。然而在 pointerover 状态时，选择器会直接将背景应用到 ContentPresenter（即 Button:pointerover /template/ ContentPresenter#PART_ContentPresenter）。这就是为什么前面示例中的 setter 被忽略了。正确的做法是直接针对 ContentPresenter 设置样式。 ```xml - + ``` :::info -您可以在默认主题（包括旧版 Default 和新版 Fluent）中看到所有控件的这种行为，不仅限于 Button。而且不仅限于 Background，还包括其他依赖于状态的属性。 +你可以在所有控件的默认主题（包括 Simple 和 Fluent）中看到这种写法，不仅仅是 Button，也不仅限于 Background 属性，其他依赖状态的属性同样如此。 ::: :::info -为什么默认样式直接更改 `ContentPresenter` 的 `Background` 属性而不是更改 `Button.Background` 属性？ +为什么默认样式会直接修改 ContentPresenter 的 `Background` 属性，而不是修改 `Button.Background` 属性？ -这是因为如果用户在按钮上设置了本地值，它将覆盖所有样式，并使按钮始终具有相同的颜色。有关更多详情，请参见 [撤销的 PR](https://github.com/AvaloniaUI/Avalonia/pull/2662#issuecomment-515764732). +这是因为如果用户在按钮上设置了本地值，这个本地值会覆盖所有样式，使按钮始终显示为同一种颜色。更多详情请浏览这个[回退的 PR](https://github.com/AvaloniaUI/Avalonia/pull/2662#issuecomment-515764732)。 ::: -### 当样式不再应用时，特定属性的先前值不会恢复 +### 样式失效时属性值不会恢复 -在 Avalonia 中，我们有多种类型的属性，其中之一是直接属性（Direct Property），它根本不支持样式。这些属性以简化的方式工作，以实现较低的开销和更高的性能，并且不存储多个依赖于优先级的值。而是只保存最新的值，无法恢复之前的值。您可以在 [此处](../custom-controls/defining-properties) 找到有关属性的更多详情。 +Avalonia 有多种属性类型，其中 DirectProperty（直接属性）不支持样式。此类属性为了提升性能，仅保存最新值，不会根据优先级存储多个值，因此无法恢复之前的值。更多属性详情见[此处](../custom-controls/defining-properties)。 -典型的例子是 [CommandProperty](https://api-docs.avaloniaui.net/docs/P_Avalonia_Controls_Button_Command)。它被定义为直接属性，因此它永远不会正常工作。将来，尝试为直接属性设置样式将导致编译时错误，详见 [#6837](https://github.com/AvaloniaUI/Avalonia/issues/6837)。 +典型例子如 [CommandProperty](https://api-docs.avaloniaui.net/docs/P_Avalonia_Controls_Button_Command)，它是直接属性，无法通过样式正常工作。在未来，为直接属性设置样式会导致编译错误，详见 [#6837](https://github.com/AvaloniaUI/Avalonia/issues/6837)。