密碼方塊

密碼方塊是一種文字輸入方塊，會基於隱私權而隱藏輸入的字元。 密碼方塊看起來就像文字輸入方塊，只不過它會將已輸入的文字轉譯成預留文字字元。 您可以設定預留文字字元。

根據預設，密碼方塊可讓使用者按住顯示按鈕來檢視密碼。 您可以停用顯示按鈕，或提供顯示密碼的替代機制，例如核取方塊。

這是正確的控制項嗎？

使用 PasswordBox 控制項，以收集密碼或其他私人資料，例如身分證字號。

如需如何選擇正確文字控制項的詳細資訊，請參閱文字控制項文章。

建議

• 如果密碼方塊的目的不清楚，請使用標籤或預留位置文字。 無論文字輸入方塊是否包含值，都會顯示標籤。 預留位置文字會顯示在文字輸入方塊內，只要輸入值就會消失。
• 為密碼方塊指定的寬度需適合可輸入的值範圍。 每個語言的單字長度都不相同，所以如果您希望您的應用程式能夠全球化，請考慮到當地語系化。
• 請勿密碼輸入方塊旁邊放置其他控制項。 密碼方塊提供密碼顯示按鈕，可讓使用者確認自己輸入的密碼，若再放置其他控制項，可能會讓使用者在嘗試與其他控制項互動時意外顯示密碼。 為了防止這種情況發生，請在密碼輸入方塊與其他控制項之間保留些許間隔，或將其他控制項放在下一行。
• 建議為帳戶的建立提供兩個密碼方塊：一個用於新密碼，一個用於確認新密碼。
• 登入時則只顯示單一密碼方塊。
• 如果將密碼方塊用於輸入 PIN，建議在輸入最後一個數字時提供立即回應，而不是使用確認按鈕。

範例

密碼方塊有數種狀態，以下這幾種值得留意。

待用密碼方塊可以顯示提示文字，讓使用者知道用途：

使用者在密碼方塊中輸入文字時，預設行為是顯示項目符號來隱藏輸入文字：

按下右側的 [顯示] 按鈕，即可查看輸入的密碼文字：

UWP 和 WinUI 2

重要

本文中的資訊和範例針對使用 Windows App SDK 和 WinUI 3 的應用程式進行了最佳化，但通常適用於使用 WinUI 2 的 UWP 應用程式。 如需平台特定資訊和範例，請參閱 UWP API 參考。

本節包含您在 UWP 或 WinUI 2 應用程式中使用控制項所需的資訊。

此控制項的 API 位在 Windows.UI.Xaml.Controls 命名空間中。

• UWP API：PasswordBox 類別、Password 屬性、PasswordChar 屬性、PasswordRevealMode 屬性、PasswordChanged 事件
• 開啟 WinUI 2 程式庫應用程式，並查看 PasswordBox 運作情形。 WinUI 2 程式庫應用程式包含大部分 WinUI 2 控制項、特性和功能的互動式範例。 從 Microsoft Store 取得應用程式，或在 Github 上取得原始程式碼。

建議使用最新的 WinUI 2 來取得所有控制項的最新樣式和範本。 WinUI 2.2 或更新版本包含此使用圓角之控制項的新範本。 如需詳細資訊，請參閱圓角半徑。

建立密碼方塊

• 重要 API：PasswordBox 類別、Password 屬性、PasswordChar 屬性、PasswordRevealMode 屬性、PasswordChanged 事件

開啟 WinUI 3 程式庫應用程式，並查看 PasswordBox 運作情形。

WinUI 3 資源庫應用程式包含大多數 WinUI 3 控制項和功能的互動式範例。 從 Microsoft Store 取得應用程式，或在 GitHub 上取得原始程式碼

使用 Password 屬性來取得或設定 PasswordBox 的內容。 您可以在 PasswordChanged 事件的處理常式中執行此動作，以便在使用者輸入密碼時執行驗證。 或者，您也可以使用其他事件，例如按鈕點擊，以便在使用者完成文字輸入之後執行驗證。

以下密碼方塊控制項的 XAML，呈現了 PasswordBox 的預設外觀。 當使用者輸入密碼時，您必須檢查密碼是否為常值「Password」。 如果是，您需要向使用者顯示訊息。

<StackPanel>  
  <PasswordBox x:Name="passwordBox" Width="200" MaxLength="16"
             PasswordChanged="passwordBox_PasswordChanged"/>

  <TextBlock x:Name="statusText" Margin="10" HorizontalAlignment="Center" />
</StackPanel>   

private void passwordBox_PasswordChanged(object sender, RoutedEventArgs e)
{
    if (passwordBox.Password == "Password")
    {
        statusText.Text = "'Password' is not allowed as a password.";
    }
    else
    {
        statusText.Text = string.Empty;
    }
}

以下是在執行此程式碼且使用者輸入「Password」後的結果。

密碼字元

您可以藉由設定 PasswordChar 屬性來變更用於遮蔽密碼的字元。 以下，預設項目符號以英磅符號取代。

<PasswordBox x:Name="passwordBox" Width="300" PasswordChar="#"/>

結果如下所示。

標頭和預留位置文字

您可以使用 Header 和 PlaceholderText 屬性來提供 PasswordBox 內容。 如果您有多個方塊，例如在表單上變更密碼，這種作法尤其實用。

<PasswordBox x:Name="passwordBox" Width="200" Header="Password" PlaceholderText="Enter your password"/>

最大長度

藉由設定 MaxLength 屬性，您可以指定使用者可輸入的字元數上限。 沒有屬性可指定最小長度，但您可以在應用程式的程式碼中檢查密碼長度，並執行任何其他驗證。

密碼顯示模式

PasswordBox 的內建按鈕會在使用者按下時顯示密碼文字。 以下是使用者執行動作的結果。 當使用者放開按鈕時，密碼會自動再次隱藏。

查看模式

根據預設，密碼顯示按鈕 (或「查看」按鈕) 會顯示。 使用者必須持續按住按鈕來檢視密碼，這樣是為了維護高層級的安全性。

PasswordRevealMode 屬性的值並不是唯一可決定使用者是否可看到密碼顯示按鈕的因素。 其他因素還包括控制項是否以最小寬度以上來顯示、PasswordBox 是否有焦點，以及文字輸入欄位是否包含至少一個字元。 只有在 PasswordBox 初次收到焦點且使用者輸入字元時，密碼顯示按鈕才會顯示。 如果 PasswordBox 失去焦點，然後重新取得焦點，密碼顯示按鈕並不會再次顯示，除非使用者將密碼清除並重新輸入字元。

隱藏和可見模式

其他 PasswordRevealMode 列舉值 Hidden 和 Visible 會隱藏密碼顯示按鈕，並讓您以程式設計方式管理密碼是否不可見。

若要一律隱藏密碼，請將 PasswordRevealMode 設為 Hidden。 除非需要一律隱藏密碼，否則您可以提供自訂 UI，讓使用者將 PasswordRevealMode 切換為 Hidden 或 Visible。 例如，您可以使用核取方塊來切換是否遮蔽密碼，如下列範例所示。 您也可以使用其他控制項，例如 ToggleButton，讓使用者切換模式。

此範例示範如何使用 CheckBox 讓使用者切換 PasswordBox 的顯示模式。

<StackPanel Width="200">
    <PasswordBox Name="passwordBox1"
                 PasswordRevealMode="Hidden"/>
    <CheckBox Name="revealModeCheckBox" Content="Show password"
              IsChecked="False"
              Checked="CheckBox_Changed" Unchecked="CheckBox_Changed"/>
</StackPanel>

private void CheckBox_Changed(object sender, RoutedEventArgs e)
{
    if (revealModeCheckBox.IsChecked == true)
    {
        passwordBox1.PasswordRevealMode = PasswordRevealMode.Visible;
    }
    else
    {
        passwordBox1.PasswordRevealMode = PasswordRevealMode.Hidden;
    }
}

此 PasswordBox 會顯示如下。

選擇文字控制項的正確鍵盤

為協助使用者使用觸控式鍵盤或螢幕輸入面板 (SIP) 輸入資料，您可以設定文字控制項的輸入範圍，使其符合使用者要輸入的資料類型。 PasswordBox 僅支援 Password 和 NumericPin 輸入範圍值。 任何其他值都將忽略。

如需詳細瞭解如何使用輸入範圍，請參閱使用輸入範圍來變更觸控式鍵盤。

取得範例程式碼

• WinUI 資源庫範例 - 以互動式格式查看所有 XAML 控制項。

相關文章

文字控制項

• 拼字檢查指導方針
• 新增搜尋
• 文字輸入的指導方針
• TextBox 類別 \(英文\)
• class
• String.Length 屬性 \(部分機器翻譯\)