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 açıklanmaktadır:

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

Özellik	Değere dayalı metin alanları	Eyalete dayalı metin alanları	Eyalet tabanlı avantaj
Durum yönetimi	Metin alanı durumunu onValueChange geri çağırma işleviyle 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 ve 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ının girişi duruma kaydedilmeden ö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ında güvenliği optimize etmenize 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 klavyesini kullanarak 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 BasicTextField yerine TextField 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çinde yazarken renkli bir gradyan uygulamak için istediğiniz fırçayı TextField için TextStyle olarak ayarlayın. Bu örnekte, TextField alanına metin girilirken gökkuşağı gradyan 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

Şekil 1. TextField içeriği için gökkuşağı renklerinde degrade efekti.

Metin alanı durumunu yönetme

TextField, içeriği ve 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 ana özellik vardır:

• initialText: TextField içeriği.
• initialSelection: İmlecin veya seçimin 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 örneklerinin ViewModel'lerinizde oluşturulması ve tutulması ö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 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

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

Metni TextFieldBuffer ile 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 seçimle ilgili bilgileri içerir.

TextFieldBuffer, InputTransformation.transformInput veya OutputTransformation.transformOutput gibi işlevlerde alıcı kapsamı olarak TextFieldBuffer ile sık sık karşılaşırsınız.TextFieldState.edit 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. (3, 3) gibi aynı başlangıç ve bitiş değerlerine sahip bir TextRange, karakter seçilmemiş bir imleç konumunu ifade eder.

val phoneNumberState = rememberTextFieldState("1234567890")

TextField(
    state = phoneNumberState,
    keyboardOptions = KeyboardOptions(
        keyboardType = KeyboardType.Phone
    ),
    inputTransformation = InputTransformation.maxLength(10).then {
        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şlevlerini sunar.

  // Initial textFieldState text passed in is "I love Android"
  // textFieldState.text : I love Android
  // textFieldState.selection: TextRange(14, 14)
  textFieldState.edit { insert(14, "!") }
  // textFieldState.text : I love Android!
  // textFieldState.selection: TextRange(15, 15)
  textFieldState.edit { replace(7, 14, "Compose") }
  // textFieldState.text : I love Compose!
  // textFieldState.selection: TextRange(15, 15)
  textFieldState.edit { append("!!!") }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(18, 18)
  textFieldState.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.

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

• clearText: Tüm metni temizler.

  textFieldState.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.

Sık kullanılan 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 bir işlev arayüzüdür. Özel InputTransformation uygularken TextFieldBuffer.transformInput 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 (!asCharSequence().isDigitsOnly()) {
            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 haneli sayıları kabul eder.

Girişi görüntülemeden ö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:

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

Bu, değer tabanlı VisualTransformationlerdeki TextFieldleri işlemenin güncellenmiş şeklidir. 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:

Şekil 4. Metin girişinin, metin çıkışına dönüşmeden önce nasıl bir dönüşümden geçtiğini 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