Metin alanlarını yapılandırma

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

TextField, kullanıcıların metin girmesine ve metni 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ı. İçerik göstermek istediğiniz türü seçin:

TextField durumunu yönetmek için daha kapsamlı ve güvenilir bir yaklaşım sundukları için duruma dayalı metin alanları kullanmanızı öneririz. Aşağıdaki tabloda bu metin alanı türleri arasındaki farklar özetlenmiştir ve duruma dayalı metin alanlarının sunduğu temel avantajlar belirtilmiştir:

Bu sayfada, TextField'ü nasıl uygulayabileceğiniz, TextField girişini nasıl biçimlendirebileceğ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'ün iki düzeyde uygulanması vardır:

1. TextField, Materyal Tasarım uygulamasıdır. Materyal Tasarım yönergelerine uygun olduğu için bu uygulamayı seçmenizi öneririz:
   • Varsayılan stil dolu'dur.
   • OutlinedTextField, kenarlıklı stil versiyonudur
2. BasicTextField, kullanıcıların donanım veya yazılım klavyesi aracılığıyla metni 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 parametreyi paylaşır. TextField için tam listeyi TextField kaynak kodunda bulabilirsiniz. Aşağıda, yararlı 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ız için TextField veya OutlinedTextField malzemesi gerektiğinde BasicTextField yerine TextField kullanmanızı öneririz. Ancak BasicTextField, malzeme spesifikasyonundaki süslemelere ihtiyaç duymayan tasarımlar oluştururken kullanılmalıdır.

Brush API ile stil girişi

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

Metne stil uygulamak için Brush API'yi kullanma hakkında daha fazla bilgi edinmek isterseniz Brush API ile gelişmiş stillendirmeyi etkinleştirme başlıklı makaleyi inceleyin.

TextStyle kullanarak renkli degradeler uygulama

Bir TextField içinde yazarken renkli degrade uygulamak için tercih ettiğiniz fırçayı TextField için TextStyle olarak ayarlayın. Bu örnekte, TextField alanına metin girilirken gökkuşağı degrade efektini görüntülemek için linearGradient içeren 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

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 yere yerleştirilmek üzere tasarlanmıştır. TextFieldState tarafından sağlanan 2 ana özellik vardır:

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

TextFieldState'ü onValueChange geri çağırma gibi diğer yaklaşımlardan ayıran özellik, TextFieldState'ün giriş akışının tamamını tamamen kapsamasıdır. Doğru destekleyici veri yapılarını kullanma, filtreleri ve biçimlendiricileri satır içi olarak yerleştirme ve farklı kaynaklardan gelen tüm düzenlemeleri senkronize etme de bu kapsamdadır.

TextField'te durumu kaldırmak için TextFieldState() öğesini kullanabilirsiniz. Bunun için rememberTextFieldState() işlevini kullanmanızı öneririz. rememberTextFieldState(), bileşeninizde TextFieldState örneğini oluşturur, durum nesnesinin hatırlanmasını sağlar ve yerleşik kayıt ve geri yükleme işlevi sunar:

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

rememberTextFieldState, boş bir parametreye sahip olabilir veya metnin ilk değerindeki değerini temsil etmek için iletilen bir başlangıç değerine sahip olabilir. 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

TextFieldBuffer ile metni değiştirme

TextFieldBuffer, StringBuilder'a benzer işlevlere sahip 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.

TextFieldState.edit, InputTransformation.transformInput veya OutputTransformation.transformOutput gibi işlevlerde genellikle alıcı kapsamı olarak TextFieldBuffer ile karşılaşırsınız. Bu işlevlerde, TextFieldBuffer değerini gerektiği gibi okuyabilir veya güncelleyebilirsiniz. Daha sonra bu değişiklikler TextFieldState için TextFieldState'e bağlanır veya OutputTransformation için oluşturma ardışık düzenine aktarılır.

Tamponun 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ıç dizininin dahil ve bitiş dizininin hariç olduğu bir TextRange ile temsil edilir. Başlangıç ve bitiş değerleri aynı olan bir TextRange ((3, 3) gibi), şu anda seçili karakter bulunmayan bir imleç konumunu gösterir.

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'teki metni düzenleme

Durumu doğrudan durum değişkeniniz aracılığıyla düzenlemenize olanak tanıyan birkaç yöntem vardır:

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

  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 sonuna getirir.

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

• clearText: Tüm metni temizler.

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

Diğer TextFieldState işlevleri için TextFieldState referansına göz atı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üşümü, kullanıcı yazarken TextField girişini filtrelemenize olanak tanır. Çıkış dönüşümü 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 filtrelemenize olanak tanır. Örneğin, TextField işlevi ABD telefon numarası alıyorsa yalnızca 10 haneli sayıları kabul etmek isteyebilirsiniz. InputTransformation sonuçları TextFieldState'a kaydedilir.

Yaygın InputTransformation kullanım alanları için yerleşik filtreler vardır. 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 işlevli bir arayüzdür. Özel InputTransformation'inizi uygularken TextFieldBuffer.transformInput'i geçersiz kılmanız gerekir:

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

Telefon numarası için, yalnızca TextField alanına 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'leri birbirine bağlayın. Filtreler sırayla yürütülür. En iyi uygulama olarak, nihayetinde filtrelenecek verilerde gereksiz dönüşümleri önlemek için önce en seçici filtreleri 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 basamak kabul eder.

Giriş gösterilmeden önce biçimlendirme

OutputTransformation, kullanıcı girişinin ekranda oluşturulmadan önce biçimlendirilmesine olanak tanır. InputTransformation'ten farklı olarak, OutputTransformation aracılığıyla yapılan biçimlendirme TextFieldState'ye kaydedilmez. Önceki telefon numarası örneğini temel alarak, uygun yerlere parantez ve kısa çizgi eklemeniz gerekir:

Bu, değere dayalı TextField'lerde VisualTransformation'leri işlemenin güncellenmiş yoludur. Buradaki 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 değerinize 0. dizinde bir açılış parantezi, 4. dizinde bir kapanış parantezi ve 8. dizinde bir kısa çizgi 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 dosyanızı TextField'a ekleyin:

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

Dönüşümlerin birlikte çalışma şekli

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

1. Giriş, giriş kaynağından alınır.
2. Giriş, TextFieldState'e kaydedilen bir InputTransformation aracılığıyla filtrelenir.
3. Giriş, biçimlendirme için bir OutputTransformation üzerinden iletilir.
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 sağlanan seçeneklere uygun değilse bazı seçenekler garanti edilmeyebilir. Desteklenen klavye seçeneklerinin listesi aşağıda verilmiştir:

• capitalization
• autoCorrect
• keyboardType
• imeAction

Ek kaynaklar

• Metin alanındaki telefon numaraları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