Entrada de texto com a visualização de escrita manual

Observação

Não há suporte para o modo de exibição de manuscrito por controles de texto no WinUI no SDK do Aplicativo do Windows. Este artigo se aplica somente a aplicativos UWP.

A caixa de texto se expande quando tocada com caneta

Personalize o modo de exibição de escrita manual (de tinta para texto) integrado aos controles de entrada de texto UWP, como TextBox, RichEditBox e AutoSuggestBox.

Visão geral

Os controles de entrada de texto UWP dão suporte à entrada de caneta usando o Windows Ink transformando-se em uma superfície de manuscrito quando um usuário toca em uma caixa de entrada de texto usando uma caneta.

O texto é reconhecido enquanto o usuário escreve em qualquer lugar na superfície de escrita manual, enquanto uma janela de sugestão mostra os resultados do reconhecimento. O usuário pode tocar em um resultado para escolhê-lo ou continuar escrevendo para aceitar o candidato proposto. Os resultados do reconhecimento literal (letra a letra) são incluídos na janela de candidatos, portanto, o reconhecimento não se limita a palavras de um dicionário. Conforme o usuário escreve, a entrada de texto aceita é convertida em uma fonte cursiva que mantém a sensação de escrita natural.

Observação

O modo de exibição de manuscrito é habilitado por padrão, mas você pode desabilitá-lo por controle e reverter para o painel de entrada de texto.

Caixa de texto com tinta e sugestões

Um usuário pode editar seu texto usando gestos e ações padrão:

atacar ouarranhar - desenhar através para excluir uma palavra ou parte de uma palavra
junção – desenhar um arco entre palavras para excluir o espaço entre elas
insert - desenhar um símbolo de careta para inserir um espaço
substituir – gravar sobre o texto existente para substituí-lo

Caixa de texto com correção de tinta

Desativar a visualização de manuscrito

A visualização de manuscrito integrada é habilitada por padrão.

Talvez você queira desabilitar a visualização de manuscrito se já fornecer funcionalidade equivalente de conversão de tinta para texto em seu aplicativo ou se sua experiência de entrada de texto depender de algum tipo de formatação ou caractere especial (como tabulação) que não esteja disponível por meio da escrita manual.

Neste exemplo, desabilitamos o modo de exibição de manuscrito definindo a propriedade IsHandwritingViewEnabled do controle TextBox como false. Todos os controles de texto que dão suporte à exibição de manuscrito dão suporte a uma propriedade semelhante.

<TextBox Name="SampleTextBox"
    Height="50" Width="500" 
    FontSize="36" FontFamily="Segoe UI" 
    PlaceholderText="Try taping with your pen" 
    IsHandwritingViewEnabled="False">
</TextBox>

Especificar o alinhamento da visualização de manuscrito

O modo de exibição de manuscrito está localizado acima do controle de texto subjacente e dimensionado para acomodar as preferências de manuscrito do usuário (consulte Configurações -> Bluetooth &dispositivos -> Caneta &Windows Ink -> Manuscrito -> Tamanho da fonte). A visualização também é alinhada automaticamente em relação ao controle de texto e à sua posição no aplicativo.

A interface de usuário do aplicativo não se ajusta para acomodar o controle maior, o que pode ocultar partes importantes da interface de usuário.

O snippet a seguir mostra como usar a propriedade PlacementAlignment de um TextBox HandwritingView para especificar qual âncora no controle de texto subjacente é usada para alinhar o modo de exibição de manuscrito.

<TextBox Name="SampleTextBox"
    Height="50" Width="500" 
    FontSize="36" FontFamily="Segoe UI" 
    PlaceholderText="Try taping with your pen">
        <TextBox.HandwritingView>
            <HandwritingView PlacementAlignment="TopLeft"/>
        </TextBox.HandwritingView>
</TextBox>

Desabilitar candidatos de preenchimento automático

O pop-up de sugestão de texto está habilitado por padrão. Ele fornece uma lista dos principais candidatos ao reconhecimento de tinta dos quais o usuário pode selecionar caso o candidato primário esteja incorreto.

Se o aplicativo já fornecer uma funcionalidade de reconhecimento personalizada robusta, você poderá usar a propriedade AreCandidatesEnabled para desabilitar as sugestões internas, conforme mostrado no exemplo a seguir.

<TextBox Name="SampleTextBox"
    Height="50" Width="500" 
    FontSize="36" FontFamily="Segoe UI" 
    PlaceholderText="Try taping with your pen">
        <TextBox.HandwritingView>
            <HandwritingView AreCandidatesEnabled="False"/>
        </TextBox.HandwritingView>
</TextBox>

Usar preferências de fonte de manuscrito

Um usuário pode escolher entre uma coleção predefinida de fontes baseadas em manuscrito para usar ao renderizar texto com base no reconhecimento de tinta (consulte Configurações -> Bluetooth &dispositivos -> Caneta &Windows Ink -> Manuscrito -> Fonte).

Seu aplicativo pode acessar essa configuração e usar a fonte selecionada para o texto reconhecido no controle de texto.

Neste exemplo, ouvimos o evento TextChanged de um TextBox e aplicamos a fonte selecionada do usuário se a alteração de texto se originou do HandwritingView (ou uma fonte padrão, se não).

private void SampleTextBox_TextChanged(object sender, TextChangedEventArgs e)
{
    ((TextBox)sender).FontFamily = 
        ((TextBox)sender).HandwritingView.IsOpen ?
            new FontFamily(PenAndInkSettings.GetDefault().FontFamilyName) : 
            new FontFamily("Segoe UI");
}

Acesse o HandwritingView em controles compostos

Controles compostos que usam o controle TextBox ou RichEditBox (como AutoSuggestBox), também dão suporte a um HandwritingView.

Para acessar o HandwritingView em um controle composto, use a API VisualTreeHelper.

O snippet XAML a seguir exibe um controle AutoSuggestBox .

<AutoSuggestBox Name="SampleAutoSuggestBox" 
    Height="50" Width="500" 
    PlaceholderText="Auto Suggest Example" 
    FontSize="16" FontFamily="Segoe UI"  
    Loaded="SampleAutoSuggestBox_Loaded">
</AutoSuggestBox>

No code-behind correspondente, mostramos como desabilitar o HandwritingView na AutoSuggestBox.

Primeiro, manipulamos o evento Loaded do elemento e chamamos uma FindInnerTextBox função para iniciar a passagem da árvore visual.

private void SampleAutoSuggestBox_Loaded(object sender, RoutedEventArgs e)
{
    if (FindInnerTextBox((AutoSuggestBox)sender))
        autoSuggestInnerTextBox.IsHandwritingViewEnabled = false;
}

Na função FindInnerTextBox, iteramos pela árvore visual (começando por uma AutoSuggestBox) chamando a função FindVisualChildByName.

private bool FindInnerTextBox(AutoSuggestBox autoSuggestBox)
{
    if (autoSuggestInnerTextBox == null)
    {
        // Cache textbox to avoid multiple tree traversals. 
        autoSuggestInnerTextBox = 
            (TextBox)FindVisualChildByName<TextBox>(autoSuggestBox);
    }
    return (autoSuggestInnerTextBox != null);
}
```

Por fim, a FindVisualChildByName função itera por meio da árvore visual até que o TextBox seja recuperado.

private FrameworkElement FindVisualChildByName<T>(DependencyObject obj)
{
    FrameworkElement element = null;
    int childrenCount = 
        VisualTreeHelper.GetChildrenCount(obj);
    for (int i = 0; (i < childrenCount) && (element == null); i++)
    {
        FrameworkElement child = 
            (FrameworkElement)VisualTreeHelper.GetChild(obj, i);
        if ((child.GetType()).Equals(typeof(T)) || (child.GetType().GetTypeInfo().IsSubclassOf(typeof(T))))
        {
            element = child;
        }
        else
        {
            element = FindVisualChildByName<T>(child);
        }
    }
    return (element);
}
```

Reposicionar o HandwritingView

Em alguns casos, talvez seja necessário garantir que o HandwritingView cubra elementos da interface do usuário que, de outra forma, não seriam cobertos.

Aqui, criamos um TextBox que dá suporte ao ditado (implementado colocando um TextBox e um botão de ditado em um StackPanel).

Captura de tela de uma Caixa de Texto que dá suporte ao ditado

Como o StackPanel agora é maior que o TextBox, o HandwritingView pode não ocluir todo o controle composto.

Captura de tela de um controle HandwritingView que cobre parcialmente um TextBox, e que é reposicionado para cobrir totalmente o TextBox

Para resolver isso, defina a propriedade PlacementTarget do HandwritingView como o elemento de interface do usuário ao qual ele deve ser alinhado.

<StackPanel Name="DictationBox" 
    Orientation="Horizontal" 
    VerticalAlignment="Top" 
    HorizontalAlignment="Left" 
    BorderThickness="1" BorderBrush="DarkGray" 
    Height="55" Width="500" Margin="50">
    <TextBox Name="DictationTextBox" 
        Width="450" BorderThickness="0" 
        FontSize="24" VerticalAlignment="Center">
        <TextBox.HandwritingView>
            <HandwritingView PlacementTarget="{Binding ElementName=DictationBox}"/>
        </TextBox.HandwritingView>
    </TextBox>
    <Button Name="DictationButton" 
        Height="48" Width="48" 
        FontSize="24" 
        FontFamily="Segoe MDL2 Assets" 
        Content="&#xE720;" 
        Background="White" Foreground="DarkGray"     Tapped="DictationButton_Tapped" />
</StackPanel>

Redimensionar o HandwritingView

Você também pode definir o tamanho do HandwritingView, o que pode ser útil quando você precisar garantir que a visualização não oclua a interface do usuário importante.

Como no exemplo anterior, criamos um TextBox que dá suporte ao ditado (implementado colocando um TextBox e um botão de ditado em um StackPanel).

Captura de tela de um TextBox que dá suporte ao ditado

Nesse caso, redimensionamos o HandwritingView para garantir que o botão de ditado esteja visível.

Captura de tela de um controle HandwritingView que bloqueia o botão de ditado e outro que foi redimensionado para garantir que o botão de ditado esteja visível

Para fazer isso, associamos a propriedade MaxWidth do HandwritingView à largura do elemento de interface do usuário que ele deve ocluir.

<StackPanel Name="DictationBox" 
    Orientation="Horizontal" 
    VerticalAlignment="Top" 
    HorizontalAlignment="Left" 
    BorderThickness="1" 
    BorderBrush="DarkGray" 
    Height="55" Width="500" 
    Margin="50">
    <TextBox Name="DictationTextBox" 
        Width="450" 
        BorderThickness="0" 
        FontSize="24" 
        VerticalAlignment="Center">
        <TextBox.HandwritingView>
            <HandwritingView 
                PlacementTarget="{Binding ElementName=DictationBox}"
                MaxWidth="{Binding ElementName=DictationTextBox, Path=Width"/>
        </TextBox.HandwritingView>
    </TextBox>
    <Button Name="DictationButton" 
        Height="48" Width="48" 
        FontSize="24" 
        FontFamily="Segoe MDL2 Assets" 
        Content="&#xE720;" 
        Background="White" Foreground="DarkGray" 
        Tapped="DictationButton_Tapped" />
</StackPanel>

Reposicionar a interface do usuário personalizada

Se você tiver uma interface personalizada do usuário que aparece em resposta à entrada de texto, como um pop-up informativo, talvez seja necessário reposicionar essa interface para que ela não bloqueie a visualização de manuscrito.

TextBox com interface do usuário personalizada

O exemplo a seguir mostra como escutar os eventos Abertos, Fechados e SizeChanged do HandwritingView para definir a posição de um pop-up.

private void Search_HandwritingViewOpened(
    HandwritingView sender, HandwritingPanelOpenedEventArgs args)
{
    UpdatePopupPositionForHandwritingView();
}

private void Search_HandwritingViewClosed(
    HandwritingView sender, HandwritingPanelClosedEventArgs args)
{
    UpdatePopupPositionForHandwritingView();
}

private void Search_HandwritingViewSizeChanged(
    object sender, SizeChangedEventArgs e)
{
    UpdatePopupPositionForHandwritingView();
}

private void UpdatePopupPositionForHandwritingView()
{
if (CustomSuggestionUI.IsOpen)
    CustomSuggestionUI.VerticalOffset = GetPopupVerticalOffset();
}

private double GetPopupVerticalOffset()
{
    if (SearchTextBox.HandwritingView.IsOpen)
        return (SearchTextBox.Margin.Top + SearchTextBox.HandwritingView.ActualHeight);
    else
        return (SearchTextBox.Margin.Top + SearchTextBox.ActualHeight);    
}

Reconfigurar o controle HandwritingView

Assim como acontece com todos os controles da estrutura XAML, você pode personalizar a estrutura visual e o comportamento visual de um HandwritingView para seus requisitos específicos.

Para ver um exemplo completo de criação de um modelo personalizado, confira como criar controles de transporte personalizados ou o exemplo de Controle de Edição Personalizado.

Comentários

Esta página foi útil?

Last updated on 2025-12-02