條件式 XAML

條件式 XAML 提供直接在 XAML 標記中使用 ApiInformation.IsApiContractPresent 方法的方法。 你可以根據作業系統層級 API 合約的存在設定屬性，而不必在背後寫程式碼。 條件語句在執行時被評估——若條件性 XAML 標籤的元素評值為 true ，則解析，否則忽略。

條件式 XAML 需要 Windows 10 版本 1809（版本 17763）或更新版本，這是 Windows 應用程式 SDK 應用程式的最低作業系統版本。

先決條件

Important

條件式 XAML 使用ApiInformation方法，檢查作業系統是否存在 Windows 執行階段 （Windows.*） API 契約與型別。 這些檢查不適用於 WinUI 3 （Microsoft.UI.Xaml.*） 控制項，因為 WinUI 3 是透過 Windows 應用程式 SDK 隨應用程式出貨，而非作業系統——無論裝置運行哪個 Windows 10/11 版本，應用程式所使用的每個 WinUI 3 控制項在執行時都會存在。 #if預處理器指令在這裡也沒什麼幫助：它們是在編譯時根據目標框架評估，而不是執行時根據實際安裝的作業系統或 Windows 應用程式 SDK 版本來評估。 若要根據應用程式目前執行所依據的 Windows 應用程式 SDK 版本來決定是否啟用某項功能，請在建置時檢查 SDK 版本，或在 API 呼叫外層使用 try/catch。 詳情請參見 版本自適應程式碼 。

關於 API 合約的背景資訊 ApiInformation ，請參見 版本自適應應用程式。

條件命名空間

要在 XAML 中使用條件方法，請在頁面頂端宣告一個條件式 XAML 命名空間 ：

xmlns:myNamespace="schema?conditionalMethod(parameter)"

分隔符前 ? 的內容是命名空間或結構。 ? 後面的內容是條件式方法，用來決定命名空間會評估為 true 或 false。

在大多數情況下，該結構是預設的 XAML 命名空間：

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

條件式 XAML 支援以下條件式方法：

方法 反向
IsApiContractPresent(ContractName, VersionNumber) IsApiContractNotPresent(ContractName, VersionNumber)
IsTypePresent(ControlType) IsTypeNotPresent(ControlType)
IsPropertyPresent(ControlType, PropertyName) IsPropertyNotPresent(ControlType, PropertyName)

Note

使用 IsApiContractPresent 並 IsApiContractNotPresent 獲得最佳的設計時體驗。 其他條件句在 Visual Studio 設計體驗中並不完全支援。

有條件地設定屬性

這個範例只有在應用程式於 Windows 10 版本 1903（2019 年 5 月更新，組建 18362）或更新版本上執行時，才會在 TextBlock 中顯示文字——這項合約檢查之所以有意義，是因為它比 Windows 應用程式 SDK 的最低支援版本 1809 更新。

首先，定義一個條件命名空間：

xmlns:contract8Present="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractPresent(Windows.Foundation.UniversalApiContract,8)"

接著在條件命名空間前綴該屬性：

<TextBlock contract8Present:Text="Hello, Conditional XAML"/>

以下是完整的標記：

<Page
    x:Class="ConditionalTest.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:contract8Present="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractPresent(Windows.Foundation.UniversalApiContract,8)">

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <TextBlock contract8Present:Text="Hello, Conditional XAML"/>
    </Grid>
</Page>

等效的檢查代碼如下：

TextBlock textBlock = new TextBlock();

if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
{
    textBlock.Text = "Hello, Conditional XAML";
}

Note

雖然 IsApiContractPresent 的合約名稱參數接受字串，但在 XAML 命名空間宣告中，不需要將它加上引號。

由於 Windows 應用程式 SDK 支援的最低作業系統版本是 1809（UniversalApiContract版本 7），因此在 Windows 應用程式 SDK 應用程式中，檢查合約版本是否為 7 或更低版本，結果一律會評估為 true，不會提供任何有用的資訊。 只檢查 合約 版本是否超過 7。

使用if/else條件

要根據 API 合約設定不同值，請定義正負條件命名空間：

xmlns:contract8NotPresent="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractNotPresent(Windows.Foundation.UniversalApiContract,8)"
xmlns:contract8Present="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractPresent(Windows.Foundation.UniversalApiContract,8)"

然後設定屬性兩次，每次都用不同的條件前綴。 執行時僅套用其中一種：

<TextBlock contract8NotPresent:Text="Hello, World"
           contract8Present:Text="Hello, May 2019 Update or later"/>

有條件地建立控制項

Note

根據作業系統 API 合約條件實例化 元素 ，而非條件設定 屬性 ，是 UWP 特有的模式。 這不適用於 WinUI 3 的控制項。

在 UWP 中，這個模式讓你在作業系統上沒有新控制項時，可以回退到舊 Windows.UI.Xaml.Controls 的控制項。 在 Windows 應用程式 SDK 應用程式中，WinUI 3 的控制項Microsoft.UI.Xaml.Controls.*（）是透過 Windows 應用程式 SDK 隨應用程式一同發佈，而不是透過作業系統。 你的應用程式所依賴的每一個控制——包括 ColorPicker ——都保證在執行時就存在，因此在實例化前不需要檢查作業系統版本。

如果你需要根據應用程式目標的 Windows 應用程式 SDK 版本來限制 WinUI 3 控制項或 API 的使用，請在建置時進行檢查（方法是將目標設為最低支援的 Windows 應用程式 SDK 套件版本），或將執行階段呼叫包在 try/catch 中，而不要使用條件式 XAML。

相關內容

  • Last updated on