使用筆刷繪製背景、前景和外框

使用 Brush 物件繪製 XAML 圖形、文字和控件的內部和外框，使其顯示在您的應用程式 UI 中。

WinUI 3 Gallery 應用程式包含大部分 WinUI 3 控制項、特性和功能的互動式範例。 從 Microsoft Store 取得應用程式，或在 GitHub 上取得原始程式碼

筆刷簡介

若要繪製應用程式畫布上顯示之 Control 的 Shape、文字或部分，請將 Shape 的 Fill 属性或 Background 和 Foreground 属性設定為 Brush 值。

不同類型的筆刷如下：

• 壓克力刷
• SolidColorBrush
• LinearGradientBrush
• RadialGradientBrush
• ImageBrush
• XamlCompositionBrushBase

純色筆刷

SolidColorBrush 能夠用單一 Color來塗畫區域，例如紅色或藍色。 這是最基本的筆刷。 在 XAML 中，有三種方式可以定義 SolidColorBrush ，以及其指定的色彩：預先定義的色彩名稱、十六進位色彩值或屬性元素語法。

預先定義的色彩名稱

您可以使用預先定義的色彩名稱，例如 Yellow 或 Magenta。 有 256 種已命名的可用色彩。 XAML 剖析器會將色彩名稱轉換成具有正確色彩通道的 色彩結構。 256 個具名色彩是以級聯樣式表、層級 3 （CSS3） 規格中的 X11 色彩名稱為基礎，因此如果您先前有 Web 開發或設計的經驗，您可能已經熟悉此具名色彩清單。

以下範例將 填滿屬性 的 矩形 設定為預定義的顏色 紅色。

<Rectangle Width="100" Height="100" Fill="Red" />

實色畫刷套用至矩形

如果您使用程式代碼而非 XAML 來定義 SolidColorBrush ，則每個具名色彩都可作為 Colors 類別的靜態屬性值。 例如，若要宣告 SolidColorBrushColor 值來表示指定色彩“Orchid”，請將 Color 值設定為靜態值 Colors.Orchid。

十六進位色彩值

您可以使用十六進位格式字串，為 SolidColorBrush宣告具有 8 位元 Alpha 通道的精確 24 位元色彩值。 範圍 0 到 F 中的兩個字元會定義每個元件值，而十六進位字串的元件值順序為：Alpha 色板（不透明度）、紅色通道、綠色色板和藍色色板 （ARGB）。 例如，十六進位值 「#FFFF0000」 定義完全不透明的紅色 （alpha=“FF”， red=“FF”， green=“00”， 和 blue=“00” ）。

這個 XAML 範例會將 Rectangle 的 Fill 屬性設定為十六進位值 "#FFFF0000"，並且使用命名色彩 Colors.Red得到相同的結果。

<StackPanel>
  <Rectangle Width="100" Height="100" Fill="#FFFF0000" />
</StackPanel>

屬性元素語法

您可以使用屬性元素語法來定義 SolidColorBrush。 此語法比先前的方法更詳細，但您可以在元素上指定其他屬性值，例如 Opacity。 如需 XAML 語法的詳細資訊，包括屬性元素語法，請參閱 XAML 概觀 和 XAML 語法指南。

在先前的範例中，筆刷的建立是透過 XAML 語言的刻意速記，隱含且自動地進行的，有助於讓 UI 定義在最常見的情況下保持簡單。 下一個範例會建立 Rectangle，並明確建立 SolidColorBrush 做為 Rectangle.Fill 屬性的元素值。 SolidColorBrush 的 Color 會設定為 Blue，而 Opacity 會設定為 0.5。

<Rectangle Width="200" Height="150">
    <Rectangle.Fill>
        <SolidColorBrush Color="Blue" Opacity="0.5" />
    </Rectangle.Fill>
</Rectangle>

線性漸層筆刷

LinearGradientBrush 用於繪製漸層區域，漸層是沿著一條線定義的。 這條線稱為 漸層軸。 您可以使用 GradientStop 物件，在漸層軸上指定漸層色彩及其位置。 根據預設，漸層軸從左上角延伸到筆刷塗畫區域的右下角，因此產生對角線的陰影效果。

GradientStop 是漸層筆刷的基本建置組塊。 漸層停駐點會指定筆刷 色彩 在漸層軸上 位移 時，筆刷套用至要繪製的區域。

漸層停駐點的 Color 屬性會指定漸層停駐點的色彩。 您可以使用預先定義的色彩名稱或指定十六進位 ARGB 值來設定色彩。

GradientStop 的 Offset 屬性指定每個 GradientStop 在漸層軸上的位置。 Offset 是範圍從 0 到 1 的 雙。 Offset 0 會將 GradientStop 置於漸層軸的開頭，也就是說，靠近它的 StartPoint。 Offset 1 會將 GradientStop 放在 EndPoint。 至少，一個實用的 LinearGradientBrush 應該有兩個 GradientStop 值，其中每個 GradientStop 都應該指定不同的 Color，而且在 0 到 1 之間有不同的 Offset。

此範例建立具有四種色彩的線性漸層，並用它來繪製 Rectangle。

<!-- This rectangle is painted with a diagonal linear gradient. -->
<Rectangle Width="200" Height="100">
    <Rectangle.Fill>
        <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
            <GradientStop Color="Yellow" Offset="0.0" x:Name="GradientStop1"/>
            <GradientStop Color="Red" Offset="0.25" x:Name="GradientStop2"/>
            <GradientStop Color="Blue" Offset="0.75" x:Name="GradientStop3"/>
            <GradientStop Color="LimeGreen" Offset="1.0" x:Name="GradientStop4"/>
        </LinearGradientBrush>
    </Rectangle.Fill>
</Rectangle>

漸層停駐點之間的每個點色彩會以線性方式插補為兩個周框漸層停駐點所指定之色彩的組合。 下圖醒目提示上一個範例中的漸層停駐點。 圓形會標示漸層停駐點的位置，虛線會顯示漸層軸。

由兩個邊界漸層停駐點指定的色彩組合

您可以藉由將 StartPoint 和 EndPoint 屬性設定為與 (0,0) 和開始預設值 (1,1) 不同的值，來變更漸層停駐點位置的線條。 藉由變更 StartPoint 和 EndPoint 座標值，您可以建立水準或垂直漸層、反轉漸層方向，或壓縮漸層散佈以套用至小於完整繪製區域的範圍。 若要壓縮漸層，您可以將 StartPoint 和/或 EndPoint 的值設定為介於值 0 和 1 之間的值。 例如，如果您想要一個水平漸層，其中筆刷的左半全部是漸淡，而右半則保持純色直至最後的 GradientStop 色彩，則需要指定 StartPoint 為 (0,0)，以及 EndPoint 為 (0.5,0)。

徑向漸層筆刷

RadialGradientBrush 是在由 Center、RadiusX和 RadiusY 屬性所定義的橢圓形內繪製。 漸層的色彩從橢圓形中央開始，並結束於半徑。

放射漸層的顏色由加入至 GradientStops 集合屬性的顏色停駐點所定義。 每個漸層停駐點都會指定沿著漸層的色彩和位移。

漸層原點預設為置中，而且可以使用 GradientOrigin 屬性 位移。

MappingMode 會定義 Center、RadiusX、RadiusY 和 GradientOrigin 是否代表相對或絕對座標。

當 MappingMode 設定為 RelativeToBoundingBox時，會將三個屬性的 X 和 Y 值視為相對於元素界限，其中 (0,0) 代表左上角 (1,1) ，並代表 Center、 RadiusX 和 RadiusY 屬性之元素界限的右下角，並 (0,0) 代表 GradientOrigin 屬性的中心。

當 MappingMode 設定為 Absolute時，會將三個屬性的 X 和 Y 值視為元素界限內的絕對座標。

此範例建立具有四種色彩的線性漸層，並用它來繪製 Rectangle。

<!-- This rectangle is painted with a radial gradient. -->
<Rectangle Width="200" Height="200">
    <Rectangle.Fill>
        <media:RadialGradientBrush>
            <GradientStop Color="Blue" Offset="0.0" />
            <GradientStop Color="Yellow" Offset="0.2" />
            <GradientStop Color="LimeGreen" Offset="0.4" />
            <GradientStop Color="LightBlue" Offset="0.6" />
            <GradientStop Color="Blue" Offset="0.8" />
            <GradientStop Color="LightGray" Offset="1" />
        </media:RadialGradientBrush>
    </Rectangle.Fill>
</Rectangle>

漸層停駐點之間每個點的色彩會星形插補為兩個周框漸層停駐點所指定之色彩的組合。 下圖醒目提示上一個範例中的漸層停駐點。

漸層停駐點

影像筆刷

ImageBrush 使用影像繪製區域，而要繪製的影像則來自圖像檔來源。 您將 ImageSource 屬性設為要載入的影像路徑。 圖片來源通常來自於您的應用程式資源中的 Content 項目。

根據預設，ImageBrush 會延展影像以完全覆蓋繪製區域，如果繪製區域與影像的外觀比例不同，可能會導致影像變形。 您可以透過將 Stretch 屬性的預設值從 Fill 改為 None、Uniform 或 UniformToFill 來變更此行為。

下一個範例會建立 ImageBrush ，並將 ImageSource 設定為名為 licorice.jpg的映射，您必須在應用程式中將其納入為資源。 ImageBrush 然後繪製由 橢圓形 圖形定義的區域。

<Ellipse Height="200" Width="300">
   <Ellipse.Fill>
     <ImageBrush ImageSource="licorice.jpg" />
   </Ellipse.Fill>
</Ellipse>

轉譯的 ImageBrush

ImageBrush 和 Image 都會依統一資源識別碼 （URI） 參考影像來源檔案，其中該影像來源檔案會使用數種可能的影像格式。 這些影像來源檔案會指定為URI。 如需指定影像來源、可用影像格式，以及將它們封裝在應用程式中的詳細資訊，請參閱 Image 和 ImageBrush。

筆刷和文字

您也可以使用筆刷將轉譯特性套用至文字元素。 例如，TextBlock 的 Foreground 屬性會採用 Brush。 您可以將這裡所述的任何筆刷套用至文字。 不過，請注意使用筆刷套用到文字上，因為如果您使用會與背景融合的筆刷，可能會導致文字與背景混淆而無法閱讀。 在大部分情況下，請使用 SolidColorBrush 進行文字元素的可讀性，除非您希望文字元素大部分是裝飾性的。

即使您使用純色，請確定您選擇的文字色彩與文字版面配置容器的背景色彩具有足夠的對比。 文字前景與文字容器背景之間的對比程度是無障礙考量的一部分。

XamlCompositionBrushBase

XamlCompositionBrushBase 是用來建立使用 CompositionBrush 繪製 XAML UI 元素之自定義筆刷的基類。

這使得 Windows.UI.Xaml 和 Windows.UI.Composition 層之間可以進行「下層」的互相運作，如 視覺層概覽中所述，。

要建立一個自訂筆刷，請建立一個新的類別，該類別繼承自 XamlCompositionBrushBase 並實作所需的方法。

例如，可以用 CompositionEffectBrush將 效果應用於 XAML UIElements，例如 GaussianBlurEffect 或 SceneLightingEffect，當以 XamlLight照明時，以控制其 XAML UIElement 的反射屬性。

如需程式代碼範例，請參閱 XamlCompositionBrushBase。

筆刷作為 XAML 資源

您可以將任何筆刷宣告為在 XAML 資源字典中的具有鍵的 XAML 資源。 這可讓您輕鬆地複製並套用相同的筆刷值至 UI 中的多個元素。 然後，筆刷值會共用並套用到在 XAML 中以 {StaticResource} 形式參考筆刷資源的任何情況。 這包括您有參考共用筆刷的 XAML 控制項範本，而控件範本本身是索引鍵 XAML 資源的情況。

程序代碼中的筆刷

使用 XAML 指定筆刷比使用程式代碼來定義筆刷更常見。 這是因為筆刷通常定義為 XAML 資源，而且因為筆刷值通常是設計工具的輸出，或是做為 XAML UI 定義的一部分。 不過，針對您可能想要使用程式代碼定義筆刷的偶爾情況，所有 Brush 類型都可供程式代碼具現化使用。

若要在程式代碼中建立 SolidColorBrush ，請使用採用 Color 參數的建構函式。 傳遞一個值，這個值是 Colors 類別的靜態屬性，如下所示：

SolidColorBrush blueBrush = new SolidColorBrush(Colors.Blue);

Microsoft::UI::Xaml::Media::SolidColorBrush blueBrush{ Microsoft::UI::Colors::Blue() };

針對 ImageBrush，請使用預設建構函式，然後先呼叫其他 API，再嘗試將該筆刷用於 UI 屬性。

當您使用程式代碼定義 ImageBrush 時，ImageSource 需要 BitmapImage （非 URI）。 如果您的來源是數據流，請使用 SetSourceAsync 方法來初始化值。 如果您的來源是 URI，其中包含在您的應用程式中使用 ms-appx ms-appx 或 ms-resource 方案的內容，請使用接受 URI 的 BitmapImage 建構子。 如果在擷取或譯碼影像來源時發生計時問題，您可能需要在影像來源可用之前顯示替代內容，同時可以考慮處理 ImageOpened 事件。

如需程式碼範例，請參閱 ImageBrush 和 XamlCompositionBrushBase。

UWP 和 WinUI 2

筆刷 API 存在於 Windows.UI.Xaml.Controls 和 Windows.UI.Xaml.Controls 命名空間中。

我們建議使用最新的 WinUI 2 來取得所有控制項的最新樣式、範本和功能。

WebViewBrush （僅限 UWP）

WebViewBrush 是一種特殊的筆刷類型，可存取在 WebView 控件中通常檢視的內容。 WebViewBrush 在具有轉譯介面 Brush-type 屬性的另一個專案上，WebViewBrush，而不是轉譯矩形 WebView 中的內容。 WebViewBrush 不適用於每個筆刷案例，但對於轉換 WebView很有用。 如需詳細資訊，請參閱 WebViewBrush。

如果您在程式碼中建立 WebViewBrush ，請使用預設建構函式，然後先呼叫其他 API，再嘗試將該筆刷用於 UI 屬性。 如果您最近重設了 SourceName 屬性，或 WebView 的內容也使用程式碼變更，您可能需要呼叫 Redraw。

如需程式碼範例，請參閱 WebViewBrush。