Metin alanlarını yapılandırma

TextField, kullanıcıların metin girmesine ve değiştirmesine olanak tanır. Kullanabileceğiniz iki tür metin alanı vardır: duruma dayalı metin alanları ve değere dayalı metin alanları. İçeriğini göstermek istediğiniz türü seçin:

Duruma dayalı metin alanları Değere dayalı metin alanları

TextField durumunu yönetmek için daha eksiksiz ve güvenilir bir yaklaşım sunduklarından duruma dayalı metin alanlarını kullanmanızı öneririz. Aşağıdaki tabloda, bu tür metin alanları arasındaki farklar özetlenmekte ve durum tabanlı metin alanlarının sunduğu temel avantajlar yer almaktadır:

Deneysel: Duruma dayalı metin alanları, Material 3 sürüm 1.4.0-alpha14'e dayanır. Hataları sorun izleyiciye bildirin.

Özellik	Değere dayalı metin alanları	Eyalete dayalı metin alanları	Eyalet bazlı avantaj
Durum yönetimi	onValueChange geri çağırma işleviyle metin alanı durumunu günceller. onValueChange tarafından bildirilen değişikliklere göre kendi eyaletinizdeki value dosyasını güncellemek sizin sorumluluğunuzdadır.	Metin girişi durumunu (değer, seçim, kompozisyon) yönetmek için açıkça bir TextFieldState nesnesi kullanır. Bu durum hatırlanabilir ve paylaşılabilir.	onValueChange geri çağırma işlevi kaldırıldığından eşzamansız davranışlar uygulayamazsınız. Durum, yeniden oluşturma, yapılandırma ve işlem sonlandırma işlemlerinden sonra da korunur.
Görsel dönüştürme	Gösterilen metnin görünümünü değiştirmek için VisualTransformation kullanılır. Bu işlev genellikle hem giriş hem de çıkış biçimlendirmesini tek bir adımda gerçekleştirir.	Kullanıcı girişini duruma aktarılmadan önce değiştirmek için InputTransformation, temel durum verilerini değiştirmeden metin alanı içeriğini biçimlendirmek için OutputTransformation kullanılır.	Artık OutputTransformation ile orijinal ham metin ve dönüştürülmüş metin arasındaki ofset eşlemesini sağlamanız gerekmiyor.
Satır sınırları	Satır sayısını kontrol etmek için singleLine: Boolean, maxLines: Int ve minLines: Int değerlerini kabul eder.	Metin alanının kaplayabileceği minimum ve maksimum satır sayısını yapılandırmak için lineLimits: TextFieldLineLimits kullanılır.	lineLimits türünde bir TextFieldLineLimits parametresi sağlayarak satır sınırları yapılandırılırken belirsizliği ortadan kaldırır.
Güvenli metin alanı	Yok	SecureTextField, şifre alanı yazmak için durum tabanlı metin alanlarının üzerine oluşturulmuş bir composable'dır.	Motorun altındaki güvenlik için optimizasyon yapmanıza olanak tanır ve textObfuscationMode ile önceden tanımlanmış bir kullanıcı arayüzü içerir.

Bu sayfada, TextField nasıl uygulayabileceğiniz, TextField girişini nasıl stilize edebileceğiniz ve klavye seçenekleri ile kullanıcı girişini görsel olarak dönüştürme gibi diğer TextField seçeneklerini nasıl yapılandırabileceğiniz açıklanmaktadır.

TextField uygulamasını seçin

TextField uygulamasının iki düzeyi vardır:

1. TextField, Materyal Tasarım uygulamasıdır. Material Design yönergelerine uygun olduğu için bu uygulamayı seçmenizi öneririz:
   • Varsayılan stil dolu'dur.
   • OutlinedTextField, ana hatlı stil sürümüdür.
2. BasicTextField, kullanıcıların metni donanım veya yazılım klavyesi aracılığıyla düzenlemesine olanak tanır ancak ipucu veya yer tutucu gibi süslemeler sağlamaz.

TextField(
    state = rememberTextFieldState(initialText = "Hello"),
    label = { Text("Label") }
)
StateBasedText.kt

OutlinedTextField(
    state = rememberTextFieldState(),
    label = { Text("Label") }
)
StateBasedText.kt

Stil TextField

TextField ve BasicTextField, özelleştirme için birçok ortak parametreye sahiptir. TextField ile ilgili tüm liste TextField kaynak kodunda mevcuttur. Aşağıda, faydalı parametrelerden bazılarının kapsamlı olmayan bir listesi verilmiştir:

• textStyle
• lineLimits

TextField(
    state = rememberTextFieldState("Hello\nWorld\nInvisible"),
    lineLimits = TextFieldLineLimits.MultiLine(maxHeightInLines = 2),
    placeholder = { Text("") },
    textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
    label = { Text("Enter text") },
    modifier = Modifier.padding(20.dp)
)
StateBasedText.kt

Tasarımınızda TextField veya OutlinedTextField kullanılması gerektiğinde TextField yerine BasicTextField kullanmanızı öneririz. Ancak Material spesifikasyonundaki süslemelere ihtiyaç duyulmayan tasarımlar oluşturulurken BasicTextField kullanılmalıdır.

Brush API ile giriş stilini belirleme

TextField öğenizde daha gelişmiş stil oluşturmak için Brush API'yi kullanabilirsiniz. Aşağıdaki bölümde, TextField girişine renkli bir gradyan eklemek için fırçayı nasıl kullanabileceğiniz açıklanmaktadır.

Metinleri stilize etmek için Brush API'yi kullanma hakkında daha fazla bilgi edinmek için Enable advanced styling with Brush API (Brush API ile gelişmiş stil oluşturmayı etkinleştirme) başlıklı makaleyi inceleyin.

TextStyle kullanarak renk geçişleri uygulama

TextField içine yazarken renkli bir gradyan uygulamak için istediğiniz fırçayı TextField için TextStyle olarak ayarlayın. Bu örnekte, linearGradient içine metin yazılırken gökkuşağı gradyanı efektini görüntülemek için TextField ile yerleşik bir fırça kullanıyoruz.

val brush = remember {
    Brush.linearGradient(
        colors = listOf(Color.Red, Color.Yellow, Color.Green, Color.Blue, Color.Magenta)
    )
}
TextField(
    state = rememberTextFieldState(), textStyle = TextStyle(brush = brush)
)
StateBasedText.kt

1. şekil. TextField içerikleri için gökkuşağı renkleriyle degrade efekti.

Metin alanı durumunu yönetme

TextField, içeriği ve mevcut seçimi için TextFieldState adlı özel bir durum tutucu sınıf kullanır. TextFieldState, mimarinize uygun olan her yerde kullanılacak şekilde tasarlanmıştır. TextFieldState tarafından sağlanan 2 temel özellik vardır:

• initialText: TextField içeriği.
• initialSelection: İmlecin veya seçimin şu anda nerede olduğunu gösterir.

TextFieldState'yı onValueChange geri çağırma gibi diğer yaklaşımlardan ayıran özellik, TextFieldState'nın giriş akışının tamamını tamamen kapsıyor olmasıdır. Bu kapsamda, doğru destekleyici veri yapılarını kullanma, filtreleri ve biçimlendiricileri satır içi yapma ve farklı kaynaklardan gelen tüm düzenlemeleri senkronize etme yer alır.

Not: TextFieldState, Compose Foundation modülüne ait olsa da kullanıcı arayüzü bağımlılıkları yoktur ve güçlü bir durum tutucu olarak tasarlanmıştır. TextFieldState yalnızca Compose'un anlık görüntü sistemi tarafından sağlanan veri yapılarını kullanır. TextFieldState örneklerini ViewModels'inizde oluşturmanız ve tutmanız önerilir.

TextFieldState() kullanarak TextField'de durumu yükseltebilirsiniz. Bunun için rememberTextFieldState() işlevini kullanmanızı öneririz. rememberTextFieldState(), composable'ınızda TextFieldState örneğini oluşturur, durum nesnesinin hatırlanmasını sağlar ve yerleşik kaydetme ve geri yükleme işlevleri sunar:

val usernameState = rememberTextFieldState()
TextField(
    state = usernameState,
    lineLimits = TextFieldLineLimits.SingleLine,
    placeholder = { Text("Enter Username") }
)
StateBasedText.kt

rememberTextFieldState boş bir parametreye sahip olabilir veya başlatma sırasında metnin değerini temsil etmek için başlangıç değeri iletilebilir. Sonraki bir yeniden oluşturma işleminde farklı bir değer iletilirse durumun değeri güncellenmez. Durumu başlatıldıktan sonra güncellemek için TextFieldState üzerinde düzenleme yöntemlerini çağırın.

TextField(
    state = rememberTextFieldState(initialText = "Username"),
    lineLimits = TextFieldLineLimits.SingleLine,
)
StateBasedText.kt

Şekil 2. TextField ile "Kullanıcı adı" başlangıç metni olarak.

TextFieldBuffer ile metni değiştirme

TextFieldBuffer, StringBuilder işlevine benzer şekilde düzenlenebilir bir metin kapsayıcısı görevi görür. Hem metin içeriğini hem de mevcut seçimle ilgili bilgileri içerir.

TextFieldBuffer, TextFieldState.edit veya InputTransformation.transformInput gibi işlevlerde alıcı kapsamı olarak OutputTransformation.transformOutput ile sık sık karşılaşırsınız. Bu işlevlerde, TextFieldBuffer gerektiği şekilde okuyabilir veya güncelleyebilirsiniz. Ardından, bu değişiklikler TextFieldState için işlenir veya OutputTransformation durumunda oluşturma işlem hattına aktarılır.

Arabelleğin içeriğini değiştirmek için append, insert, replace veya delete gibi standart düzenleme işlevlerini kullanabilirsiniz. Seçim durumunu değiştirmek için doğrudan selection: TextRange değişkenini ayarlayın veya placeCursorAtEnd ya da selectAll gibi yardımcı işlevleri kullanın. Seçim, başlangıç dizini dahil ve bitiş dizini hariç olmak üzere TextRange ile gösterilir. TextRange ile aynı başlangıç ve bitiş değerlerine sahip bir (3, 3), şu anda karakter seçilmemiş bir imleç konumunu ifade eder.

val phoneNumberState = rememberTextFieldState()

LaunchedEffect(phoneNumberState) {
    phoneNumberState.edit { // TextFieldBuffer scope
        append("123456789")
    }
}

TextField(
    state = phoneNumberState,
    inputTransformation = InputTransformation { // TextFieldBuffer scope
        if (asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    },
    outputTransformation = OutputTransformation {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
)
StateBasedText.kt

TextFieldState içindeki metni düzenleme

Durumu doğrudan durum değişkeniniz üzerinden düzenlemenize olanak tanıyan çeşitli yöntemler vardır:

• edit: Durum içeriklerini düzenlemenize olanak tanır ve insert, replace, append gibi yöntemleri kullanabilmeniz için TextFieldBuffer işlevleri sunar.

  val usernameState = rememberTextFieldState("I love Android")
  // textFieldState.text : I love Android
  // textFieldState.selection: TextRange(14, 14)
  usernameState.edit { insert(14, "!") }
  // textFieldState.text : I love Android!
  // textFieldState.selection: TextRange(15, 15)
  usernameState.edit { replace(7, 14, "Compose") }
  // textFieldState.text : I love Compose!
  // textFieldState.selection: TextRange(15, 15)
  usernameState.edit { append("!!!") }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(18, 18)
  usernameState.edit { selectAll() }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(0, 18)
  StateBasedText.kt

• setTextAndPlaceCursorAtEnd: Mevcut metni temizler, verilen metinle değiştirir ve imleci sona yerleştirir.

  usernameState.setTextAndPlaceCursorAtEnd("I really love Android")
  // textFieldState.text : I really love Android
  // textFieldState.selection : TextRange(21, 21)
  StateBasedText.kt

• clearText: Tüm metinleri temizler.

  usernameState.clearText()
  // textFieldState.text :
  // textFieldState.selection : TextRange(0, 0)
  StateBasedText.kt

Diğer TextFieldState işlevleri için TextFieldState referansına bakın.

Kullanıcı girişini değiştirme

Aşağıdaki bölümlerde, kullanıcı girişinin nasıl değiştirileceği açıklanmaktadır. Giriş dönüştürme, kullanıcı yazarken TextField girişini filtrelemenize olanak tanır. Çıkış dönüştürme ise kullanıcı girişini ekranda gösterilmeden önce biçimlendirir.

Giriş dönüşümleriyle kullanıcı girişini filtreleme

Giriş dönüşümü, kullanıcıdan gelen girişi filtrelemenizi sağlar. Örneğin, TextField işleviniz ABD telefon numarası alıyorsa yalnızca 10 haneli numaraları kabul etmek istersiniz. InputTransformation sonuçları TextFieldState dosyasına kaydedilir.

Not: InputTransformation.transformInput() çağrısı içinde durumu değiştirmeyin. Bunun yerine, metni düzenlemek için alıcı kapsamını TextFieldBuffer kullanın.

Yaygın InputTransformation kullanım alanları için yerleşik filtreler bulunur. Uzunluğu sınırlamak için InputTransformation.maxLength() numaralı telefonu arayın:

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine,
    inputTransformation = InputTransformation.maxLength(10)
)
StateBasedText.kt

Özel giriş dönüşümleri

InputTransformation tek bir işlev arayüzüdür. Özel InputTransformation öğenizi uygularken TextFieldBuffer.transformInput öğesini geçersiz kılmanız gerekir:

class CustomInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
    }
}
StateBasedText.kt

Telefon numarası için TextField alanına yalnızca rakam girilmesine izin veren özel bir giriş dönüşümü ekleyin:

class DigitOnlyInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
        if (!TextUtils.isDigitsOnly(asCharSequence())) {
            revertAllChanges()
        }
    }
}
StateBasedText.kt

Zincir giriş dönüşümleri

Metin girişinize birden fazla filtre eklemek için then uzantı işlevini kullanarak InputTransformation'ları zincirleyin. Filtreler sırayla yürütülür. En iyi uygulama olarak, nihayetinde filtrelenecek verilerde gereksiz dönüşümleri önlemek için en seçici filtreleri önce uygulayın.

TextField(
    state = rememberTextFieldState(),
    inputTransformation = InputTransformation.maxLength(6)
        .then(CustomInputTransformation()),
)
StateBasedText.kt

Giriş dönüşümleri eklendikten sonra TextField girişi en fazla 10 basamaklı sayıları kabul eder.

Girişi gösterilmeden önce biçimlendirme

OutputTransformation, kullanıcı girişini ekranda oluşturulmadan önce biçimlendirmenize olanak tanır. InputTransformation'dan farklı olarak, OutputTransformation aracılığıyla yapılan biçimlendirme TextFieldState'a kaydedilmez. Önceki telefon numarası örneğinden yola çıkarak, uygun yerlere parantez ve tire eklemeniz gerekir:

3. şekil. Uygun biçimlendirmeye ve karşılık gelen dizinlere sahip bir ABD telefon numarası

Bu, değer tabanlı VisualTransformationlerdeki TextFieldleri işlemenin güncellenmiş yoludur. Temel fark, ofset eşlemelerini hesaplamanız gerekmemesidir.

OutputTransformation, tek bir soyut yöntem arayüzüdür. Özel bir OutputTransformation uygulamak için transformOutput yöntemini geçersiz kılmanız gerekir:

class CustomOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
    }
}
StateBasedText.kt

Telefon numarasını biçimlendirmek için OutputTransformation öğenize 0 dizininde açma parantezi, 4 dizininde kapama parantezi ve 8 dizininde tire ekleyin:

class PhoneNumberOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
}
StateBasedText.kt

Ardından, OutputTransformation öğenizi TextField öğesine ekleyin:

TextField(
    state = rememberTextFieldState(),
    outputTransformation = PhoneNumberOutputTransformation()
)
StateBasedText.kt

Dönüşümlerin birlikte işleyiş şekli

Aşağıdaki şemada, metin girişinden dönüşüme ve çıkışa kadar olan akış gösterilmektedir:

4. şekil. Metin girişinin, metin çıkışına dönüşmeden önce nasıl dönüştürüldüğünü gösteren bir şema.

1. Giriş, giriş kaynağından alınır.
2. Giriş, TextFieldState'te kaydedilen bir InputTransformation aracılığıyla filtrelenir.
3. Giriş, biçimlendirme için OutputTransformation üzerinden geçirilir.
4. Giriş, TextField içinde sunulur.

Klavye seçeneklerini ayarlama

TextField, klavye düzeni gibi klavye yapılandırma seçeneklerini ayarlamanıza veya klavye tarafından destekleniyorsa otomatik düzeltmeyi etkinleştirmenize olanak tanır. Yazılım klavyesi burada belirtilen seçeneklere uymuyorsa bazı seçenekler garanti edilmeyebilir. Desteklenen klavye seçeneklerinin listesini aşağıda bulabilirsiniz:

• capitalization
• autoCorrect
• keyboardType
• imeAction

Ek kaynaklar

• Metin alanındaki telefon numarasını otomatik olarak biçimlendirme
• Kullanıcı açma/kapatma düğmesine göre şifreyi gösterme veya gizleme
• Kullanıcı yazarken girişi doğrulama