Textruta

Textbox-kontrollen låter en användare skriva text i en app. Den används vanligtvis för att avbilda en enda textrad, men kan konfigureras för att avbilda flera textrader. Texten visas på skärmen i ett enkelt, enhetligt format i klartext.

Textbox har ett antal funktioner som kan förenkla textposten. Den levereras med en välbekant, inbyggd snabbmeny som har stöd för att kopiera och klistra in text. Med knappen "rensa alla" kan en användare snabbt ta bort all text som har angetts. Den har också funktioner för stavningskontroll inbyggda och aktiverade som standard.

Är det här rätt kontroll?

Använd en TextBox-kontroll som låter användaren ange och redigera oformaterad text, till exempel i ett formulär. Du kan använda egenskapen Text för att hämta och ange texten i en textruta.

Du kan göra en textruta skrivskyddad, men detta bör vara ett tillfälligt villkorstillstånd. Om texten aldrig kan redigeras bör du överväga att använda en TextBlock- i stället.

Använd en PasswordBox- kontroll för att samla in ett lösenord eller andra privata data, till exempel ett personnummer. En lösenordsruta ser ut som en textinmatningsruta, förutom att den återger punkter i stället för den text som har angetts.

Använd kontrollen AutoSuggestBox för att låta användaren ange söktermer eller för att visa användaren en lista med förslag att välja mellan när de skriver.

Använd en RichEditBox- för att visa och redigera RTF-filer.

Mer information om hur du väljer rätt textkontroll finns i artikeln Textkontroller.

Rekommendationer

• Använd en etikett eller platshållartext om syftet med textrutan inte är klar. En etikett visas oavsett om textinmatningsrutan har ett värde eller inte. Platshållartext visas i textinmatningsrutan och försvinner när ett värde har angetts.
• Ge textrutan en lämplig bredd för det värdeintervall som kan anges. Ordlängden varierar mellan språk, så ta hänsyn till lokalisering om du vill att din app ska vara världsklar.
• En textinmatningsruta är vanligtvis enkelrad (TextWrap = "NoWrap"). När användarna behöver ange eller redigera en lång sträng anger du textinmatningsrutan till flera rader (TextWrap = "Wrap").
• I allmänhet används en textinmatningsruta för redigerbar text. Men du kan göra en textinmatningsruta skrivskyddad så att innehållet kan läsas, väljas och kopieras, men inte redigeras.
• Om du behöver minska oredan i en vy kan du överväga att göra så att en uppsättning textinmatningsrutor bara visas när en kontrollerande kryssruta är markerad. Du kan också binda det aktiverade tillståndet för en textinmatningsruta till en kontroll, till exempel en kryssruta.
• Överväg hur du vill att en textinmatningsruta ska fungera när den innehåller ett värde och användaren trycker på den. Standardbeteendet är lämpligt för att redigera värdet i stället för att ersätta det. Insättningspunkten placeras mellan ord och ingenting är markerat. Om byte är det vanligaste användningsfallet för en viss textinmatningsruta kan du markera all text i fältet när kontrollen får fokus och skriva ersätter markeringen.

Inmatningsrutor med en rad

• Använd flera textrutor med en rad för att samla in många små textuppgifter. Om textrutorna är relaterade till naturen grupperar du dem tillsammans.

• Gör storleken på textrutor med en rad något bredare än den längsta förväntade inmatningen. Om det gör kontrollen för bred, dela upp den i två kontroller. Du kan till exempel dela upp en enda adressinmatning i "Adressrad 1" och "Adressrad 2".

• Ange en maximal längd för tecken som kan anges. Om den säkerhetskopierade datakällan inte tillåter en lång indatasträng begränsar du indata och använder ett popup-fönster för validering för att meddela användarna när de når gränsen.

• Använd textinmatningskontroller med en rad för att samla in små textstycken från användare.

  I följande exempel visas en textruta med en rad för att samla in ett svar på en säkerhetsfråga. Svaret förväntas vara kort, så en textruta med en rad är lämplig här.

  

• Använd en uppsättning korta textinmatningskontroller med fast storlek för en rad för att ange data med ett visst format.

  

• Använd en enkellinjig, obegränsad textinmatningskontroll för att ange eller redigera strängar, kombinerat med en kommandoknapp som hjälper användarna att välja giltiga värden.

  

Textinmatningskontroller med flera rader

• När du skapar en RTF-ruta anger du formatknappar och implementerar deras åtgärder.

• Använd ett teckensnitt som överensstämmer med appens stil.

• Gör textkontrollens höjd tillräckligt hög för att hantera typiska inmatningar.

• När du samlar in långa textintervall med maximalt antal tecken eller ord använder du en oformaterad textruta och anger en räknare som körs live för att visa användaren hur många tecken eller ord de har kvar innan de når gränsen. Du måste skapa räknaren själv. placera den under textrutan och uppdatera den dynamiskt när användaren anger varje tecken eller ord.

  

• Låt inte textinmatningskontrollerna växa i höjd medan användarna skriver.

• Använd inte en textruta med flera rader när användarna bara behöver en enda rad.

• Använd inte en RTF-kontroll om en oformaterad textkontroll är tillräcklig.

Skapa en textruta

WinUI 3 Gallery-appen innehåller interaktiva exempel på de flesta WinUI 3-kontroller, funktioner och funktioner. Hämta appen från Microsoft Store- eller hämta källkoden på GitHub-

Här är XAML för en enkel textruta med en rubrik och platshållartext.

<TextBox Width="500" Header="Notes" PlaceholderText="Type your notes here"/>

TextBox textBox = new TextBox();
textBox.Width = 300;
textBox.Header = "Notes";
textBox.PlaceholderText = "Type your notes here";
// Add the TextBox to the visual tree.
rootGrid.Children.Add(textBox);

Här är textrutan som är resultatet av denna XAML.

Använda en textruta för datainmatning i ett formulär

Det är vanligt att använda en textruta för att acceptera dataindata i ett formulär och använda egenskapen Text för att hämta den fullständiga textsträngen från textrutan. Du använder vanligtvis en händelse som en skicka-knapp för att komma åt egenskapen Text, men du kan hantera TextChanged eller TextChanging händelse om du behöver göra något när texten ändras.

Det här exemplet visar hur du hämtar och anger det aktuella innehållet i en textruta.

<TextBox name="SampleTextBox" Text="Sample Text"/>

string sampleText = SampleTextBox.Text;
...
SampleTextBox.Text = "Sample text retrieved";

Du kan lägga till en rubrik (eller etikett) och PlaceholderText- (eller vattenstämpel) i textrutan för att ge användaren en indikation på vad textrutan är till för. Om du vill anpassa rubrikens utseende kan du ange egenskapen HeaderTemplate i stället för Rubrik. Information om design finns i Riktlinjer för etiketter.

Du kan begränsa antalet tecken som användaren kan skriva genom att ange egenskapen MaxLength. MaxLength begränsar dock inte längden på klistrad text. Använd händelsen Klistra in för att ändra klistrad text om det är viktigt för din app.

Textrutan innehåller en avmarkerad alla-knapp ("X") som visas när text anges i rutan. När en användare klickar på "X" rensas texten i textrutan. Det ser ut så här.

Knappen Rensa alla visas endast för redigerbara textrutor med en rad som innehåller text och har fokus.

Knappen Rensa alla visas inte i något av följande fall:

• IsReadOnly är sant
• AcceptsReturn är sant
• TextWrap har ett annat värde än NoWrap

Det här exemplet visar hur du hämtar och anger det aktuella innehållet i en textruta.

<TextBox name="SampleTextBox" Text="Sample Text"/>

string sampleText = SampleTextBox.Text;
...
SampleTextBox.Text = "Sample text retrieved";

Gör en textruta skrivskyddad

Du kan göra en textruta skrivskyddad genom att ställa in egenskapen IsReadOnly till true. Du växlar vanligtvis den här egenskapen i din appkod baserat på villkor i din app. Om du behöver text som alltid är skrivskyddad bör du överväga att använda en TextBlock i stället.

Du kan göra en textruta skrivskyddad genom att ange egenskapen IsReadOnly till true. Du kan till exempel ha en textruta där en användare kan ange kommentarer som endast är aktiverade under vissa villkor. Du kan göra textrutan skrivskyddad tills villkoren är uppfyllda. Om du bara behöver visa text kan du överväga att använda en TextBlock eller RichTextBlock i stället.

En skrivskyddad textruta ser likadan ut som en skriv-/läsbar textruta, så det kan vara förvirrande för en användare. En användare kan välja och kopiera text. ÄrAktiverad

Aktivera flerradig inmatning

Det finns två egenskaper som du kan använda för att styra om textrutan visar text på mer än en rad. Du ställer vanligtvis in båda egenskaperna för att skapa en textruta med flera rader.

• Om du vill att textrutan ska möjliggöra och visa radbrytningar eller returtecken anger du egenskapen AcceptsReturn till true.
• Om du vill aktivera radbrytning anger du egenskapen TextWrapping till Wrap. Detta gör att texten radbryts när den når textrutans kant, oberoende av radavgränsningstecken.

En textruta med flera rader fortsätter att växa lodrätt när text anges om den inte begränsas av dess height eller MaxHeight egenskap eller av en överordnad container. Du bör testa att en textruta med flera rader inte växer utanför det synliga området och begränsa dess tillväxt om den gör det. Vi rekommenderar att du alltid anger en lämplig höjd för en textruta med flera rader och inte låter den växa när användaren skriver.

Rullning med rullningshjul eller pekfunktioner aktiveras automatiskt när det behövs. De lodräta rullningslisterna visas dock inte som standard. Du kan visa de lodräta rullningslisterna genom att ange ScrollViewer.VerticalScrollBarVisibility till Auto på den inbäddade ScrollViewer, som du ser här.

<TextBox AcceptsReturn="True" TextWrapping="Wrap"
         MaxHeight="172" Width="300" Header="Description"
         ScrollViewer.VerticalScrollBarVisibility="Auto"/>

TextBox textBox = new TextBox();
textBox.AcceptsReturn = true;
textBox.TextWrapping = TextWrapping.Wrap;
textBox.MaxHeight = 172;
textBox.Width = 300;
textBox.Header = "Description";
ScrollViewer.SetVerticalScrollBarVisibility(textBox, ScrollBarVisibility.Auto);

Så här ser textrutan ut när text har lagts till.

Formatera textvisningen

Använd egenskapen TextAlignment för att justera text i en textruta. Om du vill justera textrutan i sidans layout använder du egenskaperna HorizontalAlignment och VerticalAlignment.

Textrutan stöder endast oformaterad text, men du kan anpassa hur texten visas i textrutan så att den matchar ditt varumärke. Du kan ange standardegenskaper för Control som FontFamily, FontSize, FontStyle, Background, Foregroundoch CharacterSpacing för att ändra textens utseende. Dessa egenskaper påverkar bara hur textrutan visar texten lokalt, så om du kopierar och klistrar in texten i en RTF-kontroll, till exempel, skulle ingen formatering tillämpas.

Det här exemplet visar en skrivskyddad textruta med flera egenskaper inställda för att anpassa textens utseende.

<TextBox Text="Sample Text" IsReadOnly="True"
         FontFamily="Verdana" FontSize="24"
         FontWeight="Bold" FontStyle="Italic"
         CharacterSpacing="200" Width="300"
         Foreground="Blue" Background="Beige"/>

TextBox textBox = new TextBox();
textBox.Text = "Sample Text";
textBox.IsReadOnly = true;
textBox.FontFamily = new FontFamily("Verdana");
textBox.FontSize = 24;
textBox.FontWeight = Windows.UI.Text.FontWeights.Bold;
textBox.FontStyle = Windows.UI.Text.FontStyle.Italic;
textBox.CharacterSpacing = 200;
textBox.Width = 300;
textBox.Background = new SolidColorBrush(Windows.UI.Colors.Beige);
textBox.Foreground = new SolidColorBrush(Windows.UI.Colors.Blue);
// Add the TextBox to the visual tree.
rootGrid.Children.Add(textBox);

Den resulterande textrutan ser ut så här.

Ändra snabbmenyn

Som standard beror kommandona som visas i snabbmenyn i textrutan på textrutans tillstånd. Följande kommandon kan till exempel visas när textrutan kan redigeras.

Om du vill ändra kommandona som visas på snabbmenyn hanterar du händelsen ContextMenuOpening. Ett exempel på detta kan du se i Anpassning av RichEditBox CommandBarFlyout – lägga till "Dela" exemplet i WinUI 2 Gallery. Designinformation finns i Riktlinjer för snabbmenyer.

Välj, kopiera och klistra in

Du kan hämta eller ange den markerade texten i en textruta med egenskapen SelectedText. Använd egenskaperna SelectionStart och SelectionLength och metoderna Select och SelectAll för att ändra textmarkeringen. Hantera händelsen SelectionChanged för att göra något när användaren väljer eller avmarkerar text. Du kan ändra den färg som används för att markera den markerade texten genom att ange egenskapen SelectionHighlightColor.

Textbox stöder kopiering och klistra in som standard. Du kan ange anpassad hantering av händelsen Klistra in på redigerbara textkontroller i appen. Du kan till exempel ta bort radbrytningarna från en adress med flera rader när du klistrar in den i en sökruta med en rad. Eller så kan du kontrollera längden på den inklistrade texten och varna användaren om den överskrider den maximala längd som kan sparas i en databas. Mer information och exempel finns i händelsen Klistra in.

Här har vi ett exempel på de här egenskaperna och metoderna som används. När du markerar text i den första textrutan visas den markerade texten i den andra textrutan, som är skrivskyddad. Värdena för egenskaperna SelectionLength och SelectionStart visas i två textblock. Detta görs med hjälp av händelsen SelectionChanged.

<StackPanel>
   <TextBox x:Name="textBox1" Height="75" Width="300" Margin="10"
         Text="The text that is selected in this TextBox will show up in the read only TextBox below."
         TextWrapping="Wrap" AcceptsReturn="True"
         SelectionChanged="TextBox1_SelectionChanged" />
   <TextBox x:Name="textBox2" Height="75" Width="300" Margin="5"
         TextWrapping="Wrap" AcceptsReturn="True" IsReadOnly="True"/>
   <TextBlock x:Name="label1" HorizontalAlignment="Center"/>
   <TextBlock x:Name="label2" HorizontalAlignment="Center"/>
</StackPanel>

private void TextBox1_SelectionChanged(object sender, RoutedEventArgs e)
{
    textBox2.Text = textBox1.SelectedText;
    label1.Text = "Selection length is " + textBox1.SelectionLength.ToString();
    label2.Text = "Selection starts at " + textBox1.SelectionStart.ToString();
}

Här är resultatet av den här koden.

Välj rätt tangentbord för textkontrollen

För att hjälpa användarna att ange data med hjälp av pektangentbordet eller soft input panel (SIP) kan du ange textkontrollens indataomfång så att det matchar den typ av data som användaren förväntas ange.

Pektangentbordet kan användas för textinmatning när appen körs på en enhet med en pekskärm. Pektangentbordet anropas när användaren trycker på ett redigerbart indatafält, till exempel en textruta eller RichEditBox. Du kan göra det mycket snabbare och enklare för användare att ange data i din app genom att ange textkontrollens indataomfång så att det matchar den typ av data som du förväntar dig att användaren ska ange. Indataomfånget ger ett tips till systemet om vilken typ av textinmatning som förväntas av kontrollen så att systemet kan tillhandahålla en specialiserad pektangentbordslayout för indatatypen.

Om en textruta till exempel bara används för att ange en 4-siffrig PIN-kod anger du egenskapen InputScope till Number. Detta talar om för systemet att visa nummerknappsatslayouten, vilket gör det enklare för användaren att ange PIN-koden.

Viktigt Indataomfånget gör inte att någon indataverifiering utförs och hindrar inte användaren från att ange några indata via ett maskinvarutangentbord eller någon annan indataenhet. Du ansvarar fortfarande för att verifiera indata i koden efter behov.

Andra egenskaper som påverkar pektangentbordet är IsSpellCheckEnabled, IsTextPredictionEnabledoch PreventKeyboardDisplayOnProgrammaticFocus. (IsSpellCheckEnabled påverkar även textrutan när ett maskinvarutangentbord används.)

Mer information och exempel finns i Använd indataomfång för att ändra pektangentbordet och i egenskapsdokumentationen.

UWP och WinUI 2

API:er för den här kontrollen finns i Windows.UI.Xaml.Controls namnområde.

Vi rekommenderar att du använder den senaste WinUI 2- för att få de senaste formaten och mallarna för alla kontroller. WinUI 2.2 eller senare innehåller en ny mall för den här kontrollen som använder rundade hörn. Mer information finns i hörnradie.

Relaterade artiklar

• Textkontroller
• Riktlinjer för stavningskontroll
• Lägga till sökning
• Riktlinjer för textinmatning
• TextBox-klass
• PasswordBox-klass
• egenskapen String.Length