密码框Password box

密码框是指出于隐私目的隐藏所键入的字符的文本输入框。A password box is a text input box that conceals the characters typed into it for the purpose of privacy. 密码框的外观类似文本框,区别在于它在已输入文本的位置呈现占位符。A password box looks like a text box, except that it renders placeholder characters in place of the text that has been entered. 可配置占位符。You can configure the placeholder character.

默认情况下,密码框向用户提供了查看其密码的方法,即按下显示按钮。By default, the password box provides a way for the user to view their password by holding down a reveal button. 你可以禁用显示按钮,或提供显示密码的替代机制,如复选框。You can disable the reveal button, or provide an alternate mechanism to reveal the password, such as a check box.

获取 Windows UI 库Get the Windows UI Library

WinUI 徽标

Windows UI 库 2.2 或更高版本包含此控件的使用圆角的新模板。Windows UI Library 2.2 or later includes a new template for this control that uses rounded corners. 有关详细信息,请参阅圆角半径For more info, see Corner radius. WinUI 是一种 NuGet 包,其中包含用于 Windows 应用的新控件和 UI 功能。WinUI is a NuGet package that contains new controls and UI features for Windows apps. 有关详细信息(包括安装说明),请参阅 Windows UI 库For more info, including installation instructions, see Windows UI Library.

平台 APIPasswordBox 类Password 属性PasswordChar 属性PasswordRevealMode 属性PasswordChanged 事件Platform APIs: PasswordBox class, Password property, PasswordChar property, PasswordRevealMode property, PasswordChanged event

这是正确的控件吗?Is this the right control?

使用 PasswordBox 控件收集密码或其他隐私数据,如身份证号。Use a PasswordBox control to collect a password or other private data, such as a Social Security number.

有关选择正确的文本控件的详细信息,请参阅文本控件文章。For more info about choosing the right text control, see the Text controls article.

示例Examples

XAML 控件库XAML Controls Gallery
XAML controls gallery

如果已安装 XAML 控件库应用,请单击此处打开此应用,了解 PasswordBox 的实际应用If you have the XAML Controls Gallery app installed, click here to open the app and see the PasswordBox in action.

密码框具有多种状态,包括以下明显的状态。The password box has several states, including these notable ones.

处于闲置状态的密码框可以显示提示文本,以使用户知道它的用途:A password box at rest can show hint text so that the user knows its purpose:

带有提示文本的处于闲置状态的密码框

当用户在密码框中键入时,默认行为是显示隐藏正在输入的文本的项目符号:When the user types in a password box, the default behavior is to show bullets that hide the text being entered:

正在键入文本的密码框焦点状态

按右侧的“显示”按钮可粗略地看到正在输入的密码:Pressing the "reveal" button on the right gives a peek at the password text being entered:

显示文本的密码框

创建密码框Create a password box

使用 Password 属性获取或设置 PasswordBox 的内容。Use the Password property to get or set the contents of the PasswordBox. 你可以在 PasswordChanged 事件的处理程序中执行此操作,以便在用户输入密码时执行验证。You can do this in the handler for the PasswordChanged event to perform validation while the user enters the password. 或者,你可以使用其他事件(如按钮 Click),以在用户完成文本输入后执行验证。Or, you can use another event, like a button Click, to perform validation after the user completes the text entry.

下面是密码框控件的 XAML,演示了 PasswordBox 的默认外观。Here's the XAML for a password box control that demonstrates the default look of the PasswordBox. 当用户输入密码时,通过检查以判断它是否为文本值“Password”。When the user enters a password, you check to see if it's the literal value, "Password". 如果是,则向用户显示一条消息。If it is, you display a message to the user.

<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”时的结果。Here's the result when this code runs and the user enters "Password".

带有验证消息的密码框

密码字符Password character

通过设置 PasswordChar 属性,你可以更改用于屏蔽密码的字符。You can change the character used to mask the password by setting the PasswordChar property. 此处使用星号替换默认项目符号。Here, the default bullet is replaced with an asterisk.

<PasswordBox x:Name="passwordBox" Width="200" PasswordChar="*"/>

结果如下所示。The result looks like this.

带有自定义字符的密码框

标头和占位符文本Headers and placeholder text

你可以使用 HeaderPlaceholderText 属性为 PasswordBox 提供上下文。You can use the Header and PlaceholderText properties to provide context for the PasswordBox. 这在你拥有多个框时(例如在更改密码的窗体上)非常有用。This is especially useful when you have multiple boxes, such as on a form to change a password.

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

带有提示文本的处于闲置状态的密码框

最大长度。Maximum length

通过设置 MaxLength 属性,指定用户可输入的最大字符数。Specify the maximum number of characters that the user can enter by setting the MaxLength property. 不存在指定最小长度的属性,但你可以在应用代码中检查密码长度并执行任何其他验证。There is no property to specify a minimum length, but you can check the password length, and perform any other validation, in your app code.

密码显示模式Password reveal mode

PasswordBox 具有内置按钮,用户按下该按钮可显示密码文本。The PasswordBox has a built-in button that the user can press to display the password text. 下面是用户操作的结果。Here's the result of the user's action. 当用户释放该按钮时,密码会自动重新隐藏。When the user releases it, the password is automatically hidden again.

显示文本的密码框

速览模式Peek mode

默认情况下,会显示密码显示按钮(或“速览”按钮)。By default, the password reveal button (or "peek" button) is shown. 用户必须持续按住按钮来查看密码,以便保持较高级别的安全性。The user must continuously press the button to view the password, so that a high level of security is maintained.

PasswordRevealMode 属性值不是确定用户能否看到密码显示按钮的唯一因素。The value of the PasswordRevealMode property is not the only factor that determines whether a password reveal button is visible to the user. 其他因素包括控件所示宽度是否大于最小值、PasswordBox 是否具有焦点以及文本输入字段是否至少包含一个字符。Other factors include whether the control is displayed above a minimum width, whether the PasswordBox has focus, and whether the text entry field contains at least one character. 密码显示按钮仅在 PasswordBox 首次接收焦点并且在用户输入一个字符后显示。The password reveal button is shown only when the PasswordBox receives focus for the first time and a character is entered. 如果 PasswordBox 失去焦点后又重新获得焦点,除非已清除密码并从头开始输入字符,否则显示按钮将不会再次显示。If the PasswordBox loses focus and then regains focus, the reveal button is not shown again unless the password is cleared and character entry starts over.

注意  在 Windows 10 之前,密码显示按钮在默认情况下不显示。Caution  Prior to Windows 10, the password reveal button was not shown by default. 如果应用安全要求始终掩盖密码,请确保将 PasswordRevealMode 设置为 Hidden。If the security of your app requires that the password is always obscured, be sure to set PasswordRevealMode to Hidden.

隐藏和可见模式Hidden and Visible modes

其他 PasswordRevealMode 枚举值(HiddenVisible)会隐藏密码显示按钮,并允许你以编程方式管理是否掩盖密码。The other PasswordRevealMode enumeration values, Hidden and Visible, hide the password reveal button and let you programmatically manage whether the password is obscured.

若要始终掩盖密码,请将 PasswordRevealMode 设置为 Hidden。To always obscure the password, set PasswordRevealMode to Hidden. 如果你不需要始终掩盖密码,可以提供自定义 UI,使用户在 Hidden 和 Visible 之间切换 PasswordRevealMode。Unless you need the password to be always obscured, you can provide a custom UI to let the user toggle the PasswordRevealMode between Hidden and Visible. 例如,可以使用复选框来切换是否遮盖密码,如下例所示。For example, you can use a check box to toggle whether the password is obscured, as shown in the following example. 你还可以使用其他控件(例如 ToggleButton)以使用户切换模式。You can also use other controls, like ToggleButton, to let the user switch modes.

此示例展示了如何使用 CheckBox 使用户切换 PasswordBox 的显示模式。This example shows how to use a CheckBox to let a user switch the reveal mode of a 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 的外观如下所示。This PasswordBox looks like this.

带有自定义显示按钮的密码框

为文本控件选择正确的键盘Choose the right keyboard for your text control

若要帮助用户使用触摸键盘或软输入面板 (SIP) 输入数据,你可以将文本控件的输入范围设置为与期望用户输入的数据类型匹配。To help users to enter data using the touch keyboard, or Soft Input Panel (SIP), you can set the input scope of the text control to match the kind of data the user is expected to enter. PasswordBox 仅支持 PasswordNumericPin 输入范围值。PasswordBox supports only the Password and NumericPin input scope values. 将忽略任何其他值。Any other value is ignored.

有关如何使用输入范围的详细信息,请参阅使用输入范围更改触摸键盘For more info about how to use input scopes, see Use input scope to change the touch keyboard.

建议Recommendations

  • 如果密码框的用途不甚清楚,请使用标签或占位符文本。Use a label or placeholder text if the purpose of the password box isn't clear. 无论文本输入框是否具有值,标签都可见。A label is visible whether or not the text input box has a value. 占位符文本显示在文本输入框内,并在输入值后立即消失。Placeholder text is displayed inside the text input box and disappears once a value has been entered.
  • 针对可输入值的范围,为密码框提供适当的宽度。Give the password box an appropriate width for the range of values that can be entered. 单词长度因语言而异,因此如果希望应用世界通用,请将本地化考虑在内。Word length varies between languages, so take localization into account if you want your app to be world-ready.
  • 不要紧挨密码输入框放置另一个控件。Don't put another control right next to a password input box. 密码框具有密码显示按钮,供用户验证已键入的密码。紧挨密码输入框放置其他控件会使用户在尝试与其他控件交互时,不小心显示其密码。The password box has a password reveal button for users to verify the passwords they have typed, and having another control right next to it might make users accidentally reveal their passwords when they try to interact with the other control. 为了防止出现这种情况,请在输入框中的密码和另一个控件之间设置一些间距,或者将另一个控件放在下一行中。To prevent this from happening, put some spacing between the password in put box and the other control, or put the other control on the next line.
  • 请考虑为帐户创建显示两个密码框:一个用于新密码,第二个用于确认新密码。Consider presenting two password boxes for account creation: one for the new password, and a second to confirm the new password.
  • 仅为登录显示单个密码框。Only show a single password box for logins.
  • 当密码框用于输入 PIN 时,请考虑在输入最后一个数字后立即提供即时响应,而不是使用确认按钮。When a password box is used to enter a PIN, consider providing an instant response as soon as the last number is entered instead of using a confirmation button.

获取示例代码Get the sample code

文本控件Text controls