Caixa numérica

Representa um controle que pode ser usado para exibir e editar números. Isso suporta validação, incremento gradual e a realização de cálculos inline de equações básicas, como multiplicação, divisão, adição e subtração.

Será este o controlo correto?

Você pode usar um controle NumberBox para capturar e exibir entrada matemática. Se precisar de uma caixa de texto editável que aceite mais do que números, use o controlo TextBox. Se você precisar de uma caixa de texto editável que aceite senhas ou outras entradas confidenciais, consulte PasswordBox. Se precisar de uma caixa de texto para introduzir termos de pesquisa, consulte AutoSuggestBox. Se você precisar inserir ou editar texto formatado, consulte RichEditBox.

Recommendations

• Text e Value facilitam a captura do valor de um NumberBox como String ou Double sem a necessidade de converter o valor entre tipos. Ao alterar programaticamente o valor de um NumberBox, é recomendável fazê-lo através da propriedade Value. Value substituirá Text na configuração inicial. Após a configuração inicial, as alterações em um serão propagadas para o outro, mas fazer alterações programáticas consistentemente através Value ajuda a evitar qualquer mal-entendido conceitual de que NumberBox aceitará caracteres não numéricos através Text.
• Use Header ou PlaceholderText para informar aos usuários que NumberBox aceita apenas caracteres numéricos como entrada. A representação ortográfica de números, como "um", não será resolvida para um valor aceito.

Criar uma Caixa de Números

O aplicativo WinUI 3 Gallery inclui exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 3. Obtenha o aplicativo no da Microsoft Store ou obtenha o código-fonte em do GitHub

Aqui está o XAML para um NumberBox básico que demonstra a aparência padrão. Use x:Bind para garantir que os dados exibidos ao usuário permaneçam sincronizados com os dados armazenados em seu aplicativo.

<NumberBox Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}" />

Etiquetagem NumberBox

Use Header ou PlaceholderText se a finalidade da NumberBox não estiver clara. Header é visível se a NumberBox tem ou não um valor.

<NumberBox Header="Enter a number:"
    Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}" />

PlaceholderText é exibido dentro da NumberBox e só aparecerá quando Value estiver definido como NaN ou quando a entrada for limpa pelo usuário.

<NumberBox PlaceholderText="1+2^2"
    Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}" />

Ativar suporte de cálculo

Definir a propriedade AcceptsExpression como true permite que NumberBox avalie expressões embutidas básicas, como multiplicação, divisão, adição e subtração usando a ordem padrão de operações. A avaliação é desencadeada na perda de foco ou quando o usuário pressiona a tecla "Enter". Uma vez avaliada uma expressão, a forma original da expressão não é preservada.

<NumberBox Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}"
    AcceptsExpression="True" />

Incremento e decréscimo em etapas

Use a propriedade SmallChange para configurar o quanto o valor dentro de um NumberBox é alterado quando o NumberBox está em foco e o usuário:

• pergaminhos
• pressiona a tecla de seta para cima
• pressiona a tecla de seta para baixo

Use a propriedade LargeChange para configurar o quanto o valor dentro de um NumberBox é alterado quando o NumberBox está em foco e o usuário pressiona a tecla PageUp ou PageDown.

Use a propriedade SpinButtonPlacementMode para habilitar botões que podem ser clicados para incrementar ou diminuir o valor na NumberBox pela quantidade especificada pela propriedade SmallChange. Esses botões serão desativados se um valor máximo ou mínimo for ultrapassado com outro passo.

Defina SpinButtonPlacementMode como Inline para permitir que os botões apareçam ao lado do controle.

<NumberBox Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}"
    SmallChange="10"
    LargeChange="100"
    SpinButtonPlacementMode="Inline" />

Defina SpinButtonPlacementMode como Compact para permitir que os botões apareçam como um Flyout apenas quando a NumberBox estiver em foco.

<NumberBox Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}"
    SmallChange="10"
    LargeChange="100"
    SpinButtonPlacementMode="Compact" />

Habilitando a validação de entrada

Definir ValidationMode como InvalidInputOverwritten permitirá que NumberBox substitua entradas inválidas que não são numéricas nem legalmente formulaicas com o último valor válido quando a avaliação é acionada na perda de foco ou pressionando a tecla "Enter".

<NumberBox Header="Quantity"
    Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}"
    ValidationMode="InvalidInputOverwritten" />

Definir ValidationMode como Disabled permite que a validação de entrada personalizada seja configurada.

Com relação a pontos decimais e vírgulas, a formatação usada por um usuário será substituída pela formatação configurada para o NumberBox. Um erro de validação de entrada não será acionado.

Formatação de entrada

Formatação de número pode ser utilizada para formatar o valor de um NumberBox ao configurar uma instância de uma classe de formatação e atribuí-la à propriedade NumberFormatter. Decimal, moeda, porcentagem e números significativos são algumas das classes de formatação de números disponíveis. Observe que o arredondamento também é definido pelas propriedades de formatação de número.

Aqui está um exemplo de uso de DecimalFormatter para formatar o valor de um NumberBox para ter um dígito inteiro, dois dígitos de fração e arredondar para o 0,25 mais próximo:

<NumberBox  x:Name="FormattedNumberBox"
    Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}" />

private void SetNumberBoxNumberFormatter()
{
    IncrementNumberRounder rounder = new IncrementNumberRounder();
    rounder.Increment = 0.25;
    rounder.RoundingAlgorithm = RoundingAlgorithm.RoundUp;

    DecimalFormatter formatter = new DecimalFormatter();
    formatter.IntegerDigits = 1;
    formatter.FractionDigits = 2;
    formatter.NumberRounder = rounder;
    FormattedNumberBox.NumberFormatter = formatter;
}

Com relação a pontos decimais e vírgulas, a formatação usada por um usuário será substituída pela formatação configurada para o NumberBox. Um erro de validação de entrada não será acionado.

Observações

Escopo de entrada

Number será usado no escopo de entrada . Este escopo de entrada destina-se a trabalhar com dígitos 0-9. Isso pode ser substituído, mas os tipos alternativos de InputScope não serão explicitamente suportados.

Não é um número

Quando um NumberBox é limpo de entrada, Value será definido como NaN para indicar que nenhum valor numérico está presente.

Avaliação da expressão

NumberBox usa notação infix para avaliar expressões. Por ordem de precedência, os operadores permitidos são:

• ^
• */
• +-

Observe que os parênteses podem ser usados para substituir as regras de precedência.

UWP e WinUI 2

O NumberBox para aplicativos UWP requer WinUI 2. Para obter mais informações, incluindo instruções de instalação, consulte WinUI 2. As APIs para esse controle existem no namespace Microsoft.UI.Xaml.Controls.

Para usar o código neste artigo com WinUI 2, use um alias em XAML (usamos muxc) para representar as APIs da Biblioteca da Interface do Usuário do Windows incluídas em seu projeto. Consulte Introdução ao WinUI 2 para obter mais informações.

xmlns:muxc="using:Microsoft.UI.Xaml.Controls"

<muxc:NumberBox />