{StaticResource} 標記延伸{StaticResource} markup extension

透過評估對某個已定義資源的參考,以提供任一 XAML 屬性的值。Provides a value for any XAML attribute by evaluating a reference to an already defined resource. 資源是在 ResourceDictionary 中定義,而 StaticResource 用法會參考該資源在 ResourceDictionary 中的索引鍵。Resources are defined in a ResourceDictionary, and a StaticResource usage references the key of that resource in the ResourceDictionary.

XAML 屬性用法XAML attribute usage

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

XAML 值XAML values

詞彙Term 描述Description
索引鍵key 要求資源的金鑰。The key for the requested resource. 這個索引鍵最初是由 ResourceDictionary 所指派。This key is initially assigned by the ResourceDictionary. 資源索引鍵可以是定義在 XamlName 文法中的任何字串。A resource key can be any string defined in the XamlName Grammar.

備註Remarks

StaticResource 是一項技術,可以為 XAML 屬性取得定義在 XAML 資源字典中其他位置的值。StaticResource is a technique for obtaining values for a XAML attribute that are defined elsewhere in a XAML resource dictionary. 由於這些值是要供多個屬性值共用,或由於 XAML 資源字典被當作一項 XAML 封裝或分解技術來使用,因此這些值可能會放在資源字典中。Values might be placed in a resource dictionary because they are intended to be shared by multiple property values, or because a XAML resource dictionary is used as a XAML packaging or factoring technique. 其中一個 XAML 封裝技術範例就是控制項的佈景主題字典。An example of a XAML packaging technique is the theme dictionary for a control. 另一個範例是用於資源後援的合併資源字典。Another example is merged resource dictionaries used for resource fallback.

StaticResource 可採用一個引數,這個引數會指定所要求的資源的索引鍵。StaticResource takes one argument, which specifies the key for the requested resource. 資源索引鍵一律是 Windows 執行階段 XAML 中的一個字串。A resource key is always a string in Windows Runtime XAML. 如需如何在一開始指定資源索引鍵的詳細資訊,請參閱 x:Key 屬性For more info on how the resource key is initially specified, see x:Key attribute.

StaticResource 解析成資源字典中的項目時所依據的規則,並不屬於本主題說明的範圍。The rules by which a StaticResource resolves to an item in a resource dictionary are not described in this topic. 那些規則取決於參考和資源是否同時存在於範本中,以及是否使用合併的資源字典等等。That depends on whether the reference and the resource both exist in a template, whether merged resource dictionaries are used, and so on. 如需有關如何定義資源及正確使用 ResourceDictionary (包括範例程式碼) 的詳細資訊,請參閱 ResourceDictionary 與 XAML 資源參考For more info on how to define resources and properly use a ResourceDictionary, including sample code, see ResourceDictionary and XAML resource references.

重要   StaticResource不得嘗試對 XAML 檔案中進一步定義的資源進行向前參考。Important   A StaticResource must not attempt to make a forward reference to a resource that is defined lexically further within the XAML file. 不支援嘗試這樣的做法。Attempting to do so is not supported. 即使向前參考並未失敗,但是嘗試這樣做會導致效能降低。Even if the forward reference doesn't fail, trying to make one carries a performance penalty. 為獲得最佳結果,請調整您資源字典的組合以避免向前參考。For best results, adjust the composition of your resource dictionaries so that forward references are avoided.

嘗試將 StaticResource 指定給無法解析的索引鍵,會導致在執行階段擲回 XAML 剖析例外狀況。Attempting to specify a StaticResource to a key that cannot resolve throws a XAML parse exception at run time. 設計工具也可能發出警告或錯誤。Design tools may also offer warnings or errors.

在 Windows 執行階段 XAML 處理器實作中,沒有 StaticResource 功能的支援類別表示法。In the Windows Runtime XAML processor implementation, there is no backing class representation for StaticResource functionality. StaticResource 僅限在 XAML 中使用。StaticResource is exclusively for use in XAML. 在程式碼中最接近的相等做法是使用 ResourceDictionary 的集合 API,例如呼叫 ContainsTryGetValueThe closest equivalent in code is to use the collection API of a ResourceDictionary, for example calling Contains or TryGetValue.

{ThemeResource} 標記延伸是類似的標記延伸,會參考其他位置中的具名資源。{ThemeResource} markup extension is a similar markup extension that references named resources in another location. 差異在於 {ThemeResource} 標記延伸能夠根據作用中的系統佈景主題傳回不同的資源。The difference is that {ThemeResource} markup extension has the ability to return different resources depending on the system theme that's active. 如需詳細資訊,請參閱 {ThemeResource} 標記延伸For more info see {ThemeResource} markup extension.

StaticResource 是一個標記延伸。StaticResource is a markup extension. 如果必須將屬性 (Attribute) 值加上逸出符號,以免成為常值或處理常式名稱,而且這個動作必須更全面地實施 (而不是只對特定類型或屬性 (Property) 設定類型轉換子 (Type Converter)),則通常會實作標記延伸。Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. XAML 中的所有標記延伸 { } 都會在其屬性語法中使用 "" 和 "" 字元,這是 xaml 處理器辨識標記延伸必須處理屬性的慣例。All markup extensions in XAML use the "{" and "}" characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute.

{StaticResource} 用法範例An example {StaticResource} usage

這個 XAML 範例來自 XAML 資料繫結範例This example XAML is taken from the XAML data binding sample.

<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 中將它建立成資源。This particular example creates an object that's backed by a custom class, and creates it as a resource in a ResourceDictionary. 若要成為有效的資源,這個 local:S2Formatter 元素必須也具有一個 x:Key 屬性值。To be a valid resource, this local:S2Formatter element must also have an x:Key attribute value. 這個屬性的值會設為 "GradeConverter"。The value of the attribute is set to "GradeConverter".

然後,在 XAML 中稍微再進一步的地方會呼叫該資源,其中您會看到 {StaticResource GradeConverter}The resource is then requested just a bit further into the XAML, where you see {StaticResource GradeConverter}.

請注意 {StaticResource} 標記延伸用法如何設定另一個標記延伸 {Binding} 標記延伸的屬性,因此這裡使用了兩個巢狀標記延伸。Note how the {StaticResource} markup extension usage is setting a property of another markup extension {Binding} markup extension, so there's two nested markup extension usages here. 內部的項目會先進行評估,因此可以先取得資源並做為值。The inner one is evaluated first, so that the resource is obtained first and can be used as a value. {Binding} 標記延伸中也顯示了這個相同的範例。This same example is also shown in {Binding} markup extension.

{StaticResource} 標記延伸的設計階段工具支援Design-time tools support for the {StaticResource} markup extension

當您在 XAML 頁面中使用 {StaticResource} 標記延伸時,Microsoft Visual Studio 2013 可以在 Microsoft IntelliSense 下拉式清單中包含可能的索引鍵值。Microsoft Visual Studio 2013 can include possible key values in the Microsoft IntelliSense dropdowns when you use the {StaticResource} markup extension in a XAML page. 例如,一旦輸入 "{StaticResource" 之後,任何來自目前查閱範圍的資源索引鍵就會立即顯示於 IntelliSense 下拉式清單中。For example, as soon as you type "{StaticResource", any of the resource keys from the current lookup scope are displayed in the IntelliSense dropdowns. 除了您在頁面層級 (FrameworkElement.Resources) 和 app 層級 (Application.Resources) 上擁有的典型資源之外,您也會看到 XAML 佈景主題資源,以及專案正在使用之任何延伸的資源。In addition to the typical resources you'd have at page level (FrameworkElement.Resources) and app level (Application.Resources), you also see XAML theme resources, and resources from any extensions your project is using.

一旦資源索引鍵存在於任何 {StaticResource} 用法中,移至定義 (F12) 功能就可以立即解析該資源,並為您顯示其定義所在的目錄。Once a resource key exists as part of any {StaticResource} usage, the Go To Definition (F12) feature can resolve that resource and show you the dictionary where it's defined. 針對佈景主題資源,這會在設計階段移至 generic.xaml。For the theme resources, this goes to generic.xaml for design time.