{StaticResource} 标记扩展

2025-09-11

通过评估对已定义资源的引用，为任何 XAML 属性提供值。资源在 ResourceDictionary 中定义， StaticResource 用法引用 ResourceDictionary 中该资源的键。

XAML 属性用法

<object property="{StaticResource key}" .../>

XAML 值

术语	Description
关键值	所请求资源的密钥。此密钥最初由 ResourceDictionary 分配。资源键可以是 XamlName 语法中定义的任何字符串。

注解

StaticResource 是一种用于获取 XAML 属性的值的技术，该属性在 XAML 资源字典中的其他位置定义。值可能放置在资源字典中，因为它们旨在由多个属性值共享，或者因为 XAML 资源字典用作 XAML 打包或分解技术。 XAML 打包技术的示例是控件的主题字典。另一个示例是用于资源回退的合并资源字典。

StaticResource 采用一个参数，该参数指定所请求资源的密钥。资源键始终是 Windows 运行时 XAML 中的字符串。有关如何最初指定资源密钥的详细信息，请参阅 x：Key 属性。

本主题未说明 StaticResource 如何在资源字典中解析为项目的规则。这取决于引用和资源是否都存在于模板中、是否使用合并资源字典等。有关如何定义资源并正确使用 ResourceDictionary（包括示例代码）的详细信息，请参阅 ResourceDictionary 和 XAML 资源引用。

重要StaticResource 不得尝试对 XAML 文件中进一步定义的资源进行前向引用。不支持尝试这样做。尽管前向引用不会失败，但尝试创建它会导致性能损失。为获得最佳结果，请调整资源字典的构成，以避免转发引用。

尝试将 StaticResource 指定给无法解析的键时，会在运行时抛出 XAML 解析异常。设计工具也可能提供警告或错误。

在 Windows 运行时 XAML 处理器实现中，StaticResource 功能没有后备类表示。 StaticResource 专门用于 XAML。代码中最接近的等效项是使用 ResourceDictionary 的集合 API，例如调用 Contains 或 TryGetValue。

{ThemeResource} 标记扩展是引用其他位置中命名资源的类似标记扩展。区别在于，{ThemeResource} 标记扩展能够返回不同的资源，具体取决于处于活动状态的系统主题。有关详细信息，请参阅 {ThemeResource} 标记扩展。

StaticResource 是标记扩展。当需要转义属性值，使其不只是字面量值或处理程序名称时，会通常实现标记扩展，因为这种需求不仅仅限于将类型转换器应用于某些类型或属性，而是更为广泛。 XAML 中的所有标记扩展在其属性语法中使用“{”和“}”字符，这是 XAML 处理器识别标记扩展必须处理该属性的约定。

示例 {StaticResource} 用法

此示例 XAML 取自 XAML 数据绑定示例。

<StackPanel Margin="5">
    <!-- Add converter as a resource to reference it from a Binding. --> 
    <StackPanel.Resources>
        <local:S2Formatter x:Key="GradeConverter"/>
    </StackPanel.Resources>
    <TextBlock Style="{StaticResource BasicTextStyle}" Text="Percent grade:" Margin="5" />
    <Slider x:Name="sliderValueConverter" Minimum="1" Maximum="100" Value="70" Margin="5"/>
    <TextBlock Style="{StaticResource BasicTextStyle}" Text="Letter grade:" Margin="5"/>
    <TextBox x:Name="tbValueConverterDataBound"
      Text="{Binding ElementName=sliderValueConverter, Path=Value, Mode=OneWay,  
        Converter={StaticResource GradeConverter}}" Margin="5" Width="150"/> 
</StackPanel>

此特定示例创建由自定义类支持的对象，并将其创建为 ResourceDictionary 中的资源。若要成为有效的资源，此 local:S2Formatter 元素还必须具有 x：Key 属性值。特性的值设置为“GradeConverter”。

然后，在XAML中稍微再往前一点的地方请求该资源，在那里可以看到{StaticResource GradeConverter}。

请注意 {StaticResource} 标记扩展用法如何设置另一个标记扩展 {Binding} 标记扩展的属性，因此此处有两个嵌套标记扩展用法。首先计算内部的资源，以便先获取它，并将其用作一个值。 {Binding} 标记扩展中也显示了同一示例。