Cuadro de contraseñaPassword box

Un cuadro de contraseña es un cuadro de entrada de texto que oculta los caracteres escritos para asegurar la privacidad.A password box is a text input box that conceals the characters typed into it for the purpose of privacy. Un cuadro de contraseña parece un cuadro de texto, salvo en que representa caracteres de marcador de posición en vez del texto que se ha escrito.A password box looks like a text box, except that it renders placeholder characters in place of the text that has been entered. Puedes configurar el carácter de marcador de posición.You can configure the placeholder character.

De manera predeterminada, el cuadro de contraseña proporciona un método para que el usuario pueda ver su contraseña si mantiene presionado el botón Mostrar.By default, the password box provides a way for the user to view their password by holding down a reveal button. Puedes deshabilitar el botón Mostrar, o proporcionar un mecanismo alternativo para mostrar la contraseña como, por ejemplo, una casilla.You can disable the reveal button, or provide an alternate mechanism to reveal the password, such as a check box.

Obtención de la biblioteca de la interfaz de usuario de WindowsGet the Windows UI Library

Logotipo de WinUI

La biblioteca de interfaz de usuario de Windows 2.2 o posterior incluye una nueva plantilla para este control que usa esquinas redondeadas.Windows UI Library 2.2 or later includes a new template for this control that uses rounded corners. Para obtener más información, consulta Radio de redondeo.For more info, see Corner radius. WinUI es un paquete NuGet que contiene nuevas características de interfaz de usuario y controles para aplicaciones de Windows.WinUI is a NuGet package that contains new controls and UI features for Windows apps. Para obtener más información e instrucciones sobre la instalación, consulta el artículo Windows UI Library (Biblioteca de interfaz de usuario de Windows).For more info, including installation instructions, see Windows UI Library.

API de plataforma: Clase PasswordBox, Propiedad Password, Propiedad PasswordChar, Propiedad PasswordRevealMode y Evento PasswordChangedPlatform APIs: PasswordBox class, Password property, PasswordChar property, PasswordRevealMode property, PasswordChanged event

¿Es este el control adecuado?Is this the right control?

Usa un control PasswordBox para recopilar la contraseña u otros datos privados, como el número de la Seguridad Social.Use a PasswordBox control to collect a password or other private data, such as a Social Security number.

Para obtener más información sobre cómo elegir el control de texto correcto, consulta el artículo Controles de texto.For more info about choosing the right text control, see the Text controls article.

EjemplosExamples

XAML Controls GalleryXAML Controls Gallery
XAML controls gallery

Si tienes instalada la aplicación XAML Controls Gallery, haz clic aquí para abrir la aplicación y ver PasswordBox en acción.If you have the XAML Controls Gallery app installed, click here to open the app and see the PasswordBox in action.

El cuadro de contraseña tiene varios estados, incluidos estos tan importantes.The password box has several states, including these notable ones.

Un cuadro de contraseña en reposo puede mostrar un texto de sugerencia para que el usuario conozca su propósito:A password box at rest can show hint text so that the user knows its purpose:

Cuadro de contraseña en reposo con texto de sugerencia

Cuando el usuario escribe en un cuadro de contraseña, el comportamiento predeterminado es mostrar viñetas que oculten el texto que se escribe:When the user types in a password box, the default behavior is to show bullets that hide the text being entered:

Cuadro de contraseña con el foco y texto escribiéndose

Si se presiona el botón "Mostrar" de la derecha, se puede ver el texto de la contraseña que se está escribiendo:Pressing the "reveal" button on the right gives a peek at the password text being entered:

Texto del cuadro de contraseña revelado

Crear un cuadro de contraseña.Create a password box

Usa la propiedad Password para obtener o establecer el contenido de la clase PasswordBox.Use the Password property to get or set the contents of the PasswordBox. Puedes hacerlo en el controlador del evento PasswordChanged y así realizar la validación mientras el usuario escribe la contraseña.You can do this in the handler for the PasswordChanged event to perform validation while the user enters the password. Igualmente, también puedes usar otro evento, como un botón de clase Click, para realizar la validación después de que el usuario termine de escribir.Or, you can use another event, like a button Click, to perform validation after the user completes the text entry.

Este es el lenguaje XAML de un control de cuadro de contraseña que muestra el aspecto predeterminado de PasswordBox.Here's the XAML for a password box control that demonstrates the default look of the PasswordBox. Cuando el usuario escribe una contraseña, debes comprobar si es el valor literal, "Password".When the user enters a password, you check to see if it's the literal value, "Password". Si lo es, entonces le muestras un mensaje al usuario.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;
    }
}

Esto es lo que se obtiene cuando se ejecuta este código y el usuario escribe "Password" (Contraseña).Here's the result when this code runs and the user enters "Password".

Cuadro de contraseña con un mensaje de validación

Carácter de contraseñaPassword character

Para cambiar el carácter que se usa para enmascarar la contraseña, puedes establecer la propiedad PasswordChar.You can change the character used to mask the password by setting the PasswordChar property. Aquí, la viñeta predeterminada se reemplaza por un asterisco.Here, the default bullet is replaced with an asterisk.

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

El resultado tiene el siguiente aspecto.The result looks like this.

Cuadro de contraseña con un carácter personalizado

Encabezados y texto del marcador de posiciónHeaders and placeholder text

Puedes usar las propiedades Header y PlaceholderText para proporcionar el contexto de PasswordBox.You can use the Header and PlaceholderText properties to provide context for the PasswordBox. Esto es especialmente útil si tienes varios cuadros, como sucede en un formulario para cambiar una contraseña.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"/>

Cuadro de contraseña en reposo con texto de sugerencia

Longitud máximaMaximum length

Puedes especificar el número máximo de caracteres que el usuario puede escribir mediante la propiedad MaxLength.Specify the maximum number of characters that the user can enter by setting the MaxLength property. No hay ninguna propiedad para especificar una longitud mínima, pero puedes comprobar la longitud de la contraseña y realizar cualquier otra validación en el código de la aplicación.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.

Modo de revelación de contraseñaPassword reveal mode

La clase PasswordBox tiene un botón integrado que el usuario puede presionar para visualizar el texto de la contraseña.The PasswordBox has a built-in button that the user can press to display the password text. Esto es lo que se obtiene una vez el usuario decide presionar el botón.Here's the result of the user's action. Cuando lo suelta, la contraseña vuelve a ocultarse automáticamente.When the user releases it, the password is automatically hidden again.

Texto del cuadro de contraseña revelado

Modo de informaciónPeek mode

De manera predeterminada, se muestra el botón Mostrar (o botón "ojear").By default, the password reveal button (or "peek" button) is shown. El usuario debe presionar continuamente el botón para ver la contraseña, de modo que se mantiene un alto nivel de seguridad.The user must continuously press the button to view the password, so that a high level of security is maintained.

El valor de la propiedad PasswordRevealMode no es el único factor que determina si un botón para mostrar la contraseña debe ser visible para el usuario.The value of the PasswordRevealMode property is not the only factor that determines whether a password reveal button is visible to the user. Otros factores aclaran si el control debe mostrarse sobre un ancho mínimo, si PasswordBox debe tener el foco y si el campo de entrada de texto debe contener al menos un carácter.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. El botón para mostrar la contraseña solo se muestra cuando PasswordBox recibe el foco por primera vez y se escribe un carácter.The password reveal button is shown only when the PasswordBox receives focus for the first time and a character is entered. Si PasswordBox pierde el foco y luego lo recupera, no se vuelve a visualizar el botón Mostrar, a menos que la contraseña se borre y se vuelva a escribir.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.

Precaución  En versiones anteriores a Windows 10, el botón para mostrar la contraseña no aparecía de forma predeterminada.Caution  Prior to Windows 10, the password reveal button was not shown by default. Si la seguridad de la aplicación requiere que la contraseña esté siempre oculta, asegúrate de establecer el valor de PasswordRevealMode en Oculta.If the security of your app requires that the password is always obscured, be sure to set PasswordRevealMode to Hidden.

Modos Oculta y VisibleHidden and Visible modes

Otros valores de enumeración de la propiedad PasswordRevealMode, como Oculta y Visible, ocultan el botón para mostrar la contraseña y te permiten decidir mediante programación si la contraseña debe permanecer oculta.The other PasswordRevealMode enumeration values, Hidden and Visible, hide the password reveal button and let you programmatically manage whether the password is obscured.

Para ocultar siempre la contraseña, debes establecer la propiedad PasswordRevealMode en Oculta.To always obscure the password, set PasswordRevealMode to Hidden. A menos que necesites que la contraseña siempre esté oculta, puedes proporcionar una interfaz de usuario personalizada para permitir que el usuario cambie la propiedad PasswordRevealMode entre las opciones Oculta y Visible.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. Por ejemplo, puede usar una casilla para alternar si la contraseña está oculta, tal y como se muestra en el ejemplo siguiente.For example, you can use a check box to toggle whether the password is obscured, as shown in the following example. Asimismo, también puedes usar otros controles, como ToggleButton, para permitir al usuario cambiar de modo.You can also use other controls, like ToggleButton, to let the user switch modes.

Este ejemplo muestra cómo usar una clase CheckBox para permitir al usuario cambiar el modo de mostrar la contraseña en una clase 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;
    }
}

Esta clase PasswordBox tiene el aspecto siguiente.This PasswordBox looks like this.

Cuadro de contraseña con un botón Mostrar personalizado.

Elección del teclado adecuado para el control de textoChoose the right keyboard for your text control

Para ayudar a los usuarios a escribir datos con el teclado táctil o con el panel de entrada de software (SIP), puedes establecer el ámbito de entrada del control de texto para que coincida con el tipo de datos que se espera que escriba el usuario.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 solo es compatible con los valores de ámbito de entrada Password y NumericPin.PasswordBox supports only the Password and NumericPin input scope values. Se ignorará cualquier otro valor.Any other value is ignored.

Para obtener más información sobre cómo usar los ámbitos de entrada, consulta Usar el ámbito de entrada para cambiar el teclado táctil.For more info about how to use input scopes, see Use input scope to change the touch keyboard.

RecomendacionesRecommendations

  • Usa una etiqueta o un texto de marcador de posición si el propósito del cuadro de contraseña no está claro.Use a label or placeholder text if the purpose of the password box isn't clear. Una etiqueta es visible, tenga o no un valor el cuadro de entrada de texto.A label is visible whether or not the text input box has a value. El texto de marcador de posición se muestra dentro del cuadro de entrada y desaparece una vez que se ha escrito un valor.Placeholder text is displayed inside the text input box and disappears once a value has been entered.
  • Dota al cuadro de contraseña de un ancho apropiado para los valores que se pueden escribir.Give the password box an appropriate width for the range of values that can be entered. La longitud de las palabras varía según el lenguaje, así que tenlo en cuenta si quieres que tu aplicación sea internacional.Word length varies between languages, so take localization into account if you want your app to be world-ready.
  • No pongas otro control justo al lado de un cuadro de entrada de contraseñas.Don't put another control right next to a password input box. El cuadro de contraseña tiene un botón Mostrar para que el usuario pueda comprobar las contraseñas escritas. Si sitúas al lado otro control, podrías provocar que las contraseñas se muestren de forma accidental al intentar interactuar con él.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. Para evitar que esto suceda, deja un poco de espacio entre el cuadro de entrada de contraseña y el otro control, o pon el otro control en la siguiente línea.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.
  • También puedes tener en cuenta la posibilidad de presentar dos cuadros de contraseña para la creación de cuentas: uno para la nueva contraseña y otro para confirmarla.Consider presenting two password boxes for account creation: one for the new password, and a second to confirm the new password.
  • Muestra un cuadro de contraseña único para los inicios de sesión.Only show a single password box for logins.
  • Cuando se usa un cuadro de contraseña para escribir un PIN, tienes la posibilidad de proporcionar una respuesta instantánea tan pronto como se escriba el último número, en lugar de tener que usar un botón de confirmación.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.

Obtención del código de ejemploGet the sample code

Controles de textoText controls