تکمیل خودکار در نوشتن

برخی از برنامه‌ها، مانند مدیران رمز عبور، می‌توانند اجزای برنامه‌های دیگر را با داده‌های ارائه شده توسط کاربر پر کنند. برنامه‌هایی که اجزای برنامه‌های دیگر را پر می‌کنند، سرویس‌های تکمیل خودکار نامیده می‌شوند. چارچوب تکمیل خودکار، ارتباط بین یک برنامه و یک سرویس تکمیل خودکار را مدیریت می‌کند.

پر کردن اطلاعات کاربری و فرم‌ها کاری زمان‌بر و مستعد خطا است. تکمیل خودکار به کاربران این امکان را می‌دهد که در زمان صرف شده برای پر کردن فیلدها صرفه‌جویی کنند و خطاهای ورودی کاربر را به حداقل برسانند.

تنها با چند خط کد، می‌توانید قابلیت تکمیل خودکار را در Compose پیاده‌سازی کنید. این ویژگی مزایای زیر را برای کاربران فراهم می‌کند:

مدارک تحصیلی را پر کنید

تکمیل خودکار به کاربران اجازه می‌دهد تا اعتبارنامه‌های خود را به روش‌های زیر پر کنند:

• سیستم وقتی کاربر به فیلدی که معانی Autofill در آن تنظیم شده است، ضربه می‌زند، پیشنهادهای Autofill را به او نمایش می‌دهد.
• سیستم پیشنهادهای تکمیل خودکار را برای کاربر نمایش می‌دهد و آنها را بر اساس آنچه کاربر تایپ می‌کند فیلتر می‌کند.

ذخیره اعتبارنامه‌ها

کاربران می‌توانند از طریق تکمیل خودکار، اعتبارنامه‌ها را به روش‌های زیر ذخیره کنند:

• سیستم یک پنجره‌ی محاوره‌ای ذخیره را فعال می‌کند که از کاربر می‌خواهد هنگام وارد کردن اطلاعات جدید یا به‌روزرسانی‌شده در فیلدی که قابلیت تکمیل خودکار دارد، اطلاعات را ذخیره کند. ذخیره کردن می‌تواند به دو روش انجام شود:
  • به طور صریح، با ثبت اطلاعات (برای مثال، از طریق کلیک روی یک دکمه)
  • به طور ضمنی، وقتی کاربر از صفحه خارج می‌شود
• بسته به ارائه‌دهنده‌ی اعتبارنامه‌ی شما، سیستم ممکن است در صورتی که فیلدی با ContentType.NewPassword تنظیم شده باشد، یک رمز عبور قوی به کاربر پیشنهاد دهد.

شما می‌توانید از قابلیت تکمیل خودکار (Autofill) در برنامه خود برای ساده‌سازی بازیابی داده‌های ذخیره شده برای کاربران استفاده کنید. تکمیل خودکار از طریق BasicTextField و تمام فیلدهای متنی Material که بر اساس آن مؤلفه ساخته می‌شوند، از اجزای متنی پشتیبانی می‌کند.

تنظیم تکمیل خودکار

قبل از استفاده از APIهای Autofill در دستگاه یا شبیه‌ساز خود، باید Autofill را در تنظیمات فعال کنید. در آنجا می‌توانید یک ارائه‌دهنده اعتبارنامه برای Autofill جهت ذخیره اعتبارنامه‌های خود مشخص کنید.

شکل ۱. صفحه تنظیمات که نحوه تعیین ارائه‌دهنده اعتبارنامه را نشان می‌دهد.

با استفاده از نوع محتوا، تکمیل خودکار را به فیلد متن خود اضافه کنید

برای نشان دادن اینکه یک TextField قابلیت تکمیل خودکار را دارد، مقدار ContentType را با انواع داده‌هایی که فیلد می‌تواند بپذیرد تنظیم کنید. این به سرویس‌های تکمیل خودکار نشان می‌دهد که چه نوع داده‌های کاربری ممکن است به این فیلد خاص مرتبط باشد. از ContentType.Username برای تنظیم TextField که کاربران می‌توانند آن را با نام کاربری خود پر کنند، استفاده کنید.

با تنظیم مفهوم ContentType ، کاربران شما می‌توانند به اطلاعات Autofill که از قبل در ارائه‌دهنده اعتبارنامه دستگاهشان ذخیره شده است، دسترسی پیدا کنند. برای مثال، اگر کاربری قبلاً از طریق مرورگر کروم روی لپ‌تاپ خود وارد برنامه شما شده و رمز عبور خود را از طریق ارائه‌دهنده اعتبارنامه ذخیره کرده باشد، اعتبارنامه‌های او از طریق Autofill به او ارائه می‌شود.

فیلد متنی مبتنی بر مقدار

TextField(
    value = textFieldValue.value,
    onValueChange = {textFieldValue.value = it},
    modifier = Modifier.semantics { contentType = ContentType.Username }
)
AutofillSnippets.kt

فیلد متنی مبتنی بر حالت

TextField(
    state = rememberTextFieldState(),
    modifier = Modifier.semantics { contentType = ContentType.Username }
)
AutofillSnippets.kt

فیلدهای تکمیل خودکار با انواع مختلف را اضافه کنید

در برخی موارد، ممکن است بخواهید TextField شما بیش از یک ContentType را بپذیرد. برای مثال، یک فیلد ورود می‌تواند آدرس ایمیل یا نام کاربری را بپذیرد. می‌توانید با استفاده از عملگر + ، چندین نوع محتوا را به TextField خود اضافه کنید.

برای مشاهده‌ی تمام انواع داده‌های موجود برای ذخیره با Autofill، به مرجع ContentType مراجعه کنید.

فیلد متنی مبتنی بر مقدار

TextField(
    value = textFieldValue.value,
    onValueChange = { textFieldValue.value = it },
    modifier = Modifier.semantics {
        contentType = ContentType.Username + ContentType.EmailAddress
    }
)
AutofillSnippets.kt

فیلد متنی مبتنی بر حالت

TextField(
    state = rememberTextFieldState(),
    modifier = Modifier.semantics {
        contentType = ContentType.Username + ContentType.EmailAddress
    }
)
AutofillSnippets.kt

پر کردن داده‌ها با قابلیت Autofill

وقتی یک ContentType در TextField اضافه می‌کنید، برای اینکه کاربران بتوانند اطلاعات ورود را وارد کنند، نیازی به انجام کار دیگری ندارید.

وقتی کاربری روی فیلدی که قابلیت تکمیل خودکار دارد کلیک می‌کند، اگر داده‌های مرتبطی ذخیره شده باشد، تراشه‌ای را در نوار ابزار بالای صفحه‌کلید مشاهده می‌کند که از او می‌خواهد اطلاعات کاربری را وارد کند.

شکل ۲. علامت‌های روی نوار ابزار متنی که اعتبارنامه‌های ذخیره‌شده را نشان می‌دهند.

ذخیره داده‌ها با قابلیت تکمیل خودکار از طریق پیمایش

Compose به طور خودکار سعی می‌کند تشخیص دهد که چه زمانی کاربر از یک صفحه خارج می‌شود و اطلاعات ورود اطلاعات را ثبت کند. هنگامی که قابلیت تکمیل خودکار برای یک فیلد فعال باشد، وقتی کاربر از صفحه خارج می‌شود، بدون نیاز به هیچ کد اضافی، اطلاعات مربوط به اطلاعات ورود را به طور خودکار ذخیره می‌کند.

ذخیره صریح داده‌ها با Autofill

برای ذخیره صریح اعتبارنامه‌های جدید از طریق فیلدهای متنی با Autofill، زمینه Autofill باید توسط مدیر Autofill تأیید (یا لغو) شود. سپس مدیر Autofill محلی در صورت لزوم با چارچوب Autofill ارتباط برقرار می‌کند. اگر می‌خواهید اعتبارنامه‌هایی را که کاربر وارد کرده است حذف کنید، AutofillManager.cancel را فراخوانی کنید تا هرگونه داده در حال انتظار را بدون ذخیره آن حذف کنید.

قطعه کدهای زیر نحوه ذخیره داده‌ها با Autofill را به طور صریح با استفاده از یک دکمه نشان می‌دهند:

1. یک متغیر محلی برای نگهداری مدیر تکمیل خودکار ایجاد کنید که می‌تواند به روش زیر بازیابی شود:

   val autofillManager = LocalAutofillManager.current
   AutofillSnippets.kt

2. در TextField(s) ، نوع محتوای انتخابی خود را از طریق Modifier.semantics اضافه کنید:

   • با فیلدهای متنی مبتنی بر مقدار:

     val autofillManager = LocalAutofillManager.current
     
     Column {
         TextField(
             value = textFieldValue.value,
             onValueChange = { textFieldValue.value = it },
             modifier = Modifier.semantics { contentType = ContentType.NewUsername }
         )
     
         Spacer(modifier = Modifier.height(16.dp))
     
         TextField(
             value = textFieldValue.value,
             onValueChange = { textFieldValue.value = it },
             modifier = Modifier.semantics { contentType = ContentType.NewPassword }
         )
     }
     AutofillSnippets.kt

   • با فیلدهای متنی مبتنی بر وضعیت:

     val autofillManager = LocalAutofillManager.current
     
     Column {
         TextField(
             state = rememberTextFieldState(),
             modifier = Modifier.semantics { contentType = ContentType.NewUsername }
         )
     
         Spacer(modifier = Modifier.height(16.dp))
     
         TextField(
             state = rememberTextFieldState(),
             modifier = Modifier.semantics { contentType = ContentType.NewPassword }
         )
     }
     AutofillSnippets.kt

3. در صورت نیاز، با کلیک روی دکمه، زمینه‌ی تکمیل خودکار (Autofill) را اعمال کنید:

   • با فیلدهای متنی مبتنی بر مقدار:

     val autofillManager = LocalAutofillManager.current
     
     Column {
         TextField(
             value = textFieldValue.value,
             onValueChange = { textFieldValue.value = it },
             modifier = Modifier.semantics { contentType = ContentType.NewUsername },
         )
     
         Spacer(modifier = Modifier.height(16.dp))
     
         TextField(
             value = textFieldValue.value,
             onValueChange = { textFieldValue.value = it },
             modifier = Modifier.semantics { contentType = ContentType.NewPassword },
         )
     
         // Submit button
         Button(onClick = { autofillManager?.commit() }) { Text("Reset credentials") }
     }
     AutofillSnippets.kt

   • با فیلدهای متنی مبتنی بر وضعیت:

     val autofillManager = LocalAutofillManager.current
     
     Column {
         TextField(
             state = rememberTextFieldState(),
             modifier = Modifier.semantics { contentType = ContentType.NewUsername },
         )
     
         Spacer(modifier = Modifier.height(16.dp))
     
         TextField(
             state = rememberTextFieldState(),
             modifier = Modifier.semantics { contentType = ContentType.NewPassword },
         )
     
         // Submit button
         Button(onClick = { autofillManager?.commit() }) { Text("Reset credentials") }
     }
     AutofillSnippets.kt

هر زمان که کاربر از صفحه نمایش خارج شود، دکمه‌ی «ارسال» فراخوانی می‌شود. اگر دکمه‌ی «ارسال» به ناوبری لینک شده باشد، نیازی به فراخوانی «ارسال» نیست. اگر همچنان می‌خواهید با کلیک روی «ارسال» کادر محاوره‌ای ذخیره فعال شود، «ارسال» را اینجا اضافه کنید.

وقتی کاربر روی دکمه کلیک می‌کند، این برگه پایانی را مشاهده می‌کند که از او می‌خواهد اعتبارنامه‌ها را در ارائه‌دهنده اعتبارنامه انتخاب‌شده ذخیره کند:

شکل ۳. برگه پایینی که از کاربران می‌خواهد رمز عبور را ذخیره کنند.

ذخیره داده‌ها با قابلیت تکمیل خودکار از طریق پیشنهاد رمز عبور قوی

بسته به ارائه‌دهنده‌ی اعتبارنامه‌ی شما، وقتی از انواع محتوای NewUsername و NewPassword استفاده می‌کنید، کاربران ممکن است دکمه‌ای را در صفحه‌کلید برای پیشنهاد رمز عبور قوی ببینند. وقتی روی این دکمه کلیک می‌کنند، یک برگه‌ی پایین ظاهر می‌شود که به آنها امکان می‌دهد اعتبارنامه‌های خود را ذخیره کنند. برای اینکه کاربران این تجربه را داشته باشند، نیازی به پیاده‌سازی چیز دیگری ندارید.

شکل ۴. تراشه پیشنهاد رمز عبور قوی در نوار ابزار صفحه کلید.

شکل ۵. برگه پایینی که کاربران را به استفاده از رمز عبور قوی ترغیب می‌کند.

عیب‌یابی

هنگام فراخوانی مسیر کاربر «ذخیره»، اگر بیش از یک بار روی «الان نه» کلیک کنید، ارائه‌دهنده اعتبارنامه شما ممکن است دیگر برگه پایین را نمایش ندهد. برای فعال کردن مجدد آن و نمایش دوباره آن، باید برنامه‌های خاصی را که «این رمز عبور را به خاطر دارید؟» را مسدود کرده‌اند، حذف کنید.

شکل ۶. برگه پایینی که از کاربران می‌خواهد رمز عبور را ذخیره کنند.

سفارشی‌سازی بیشتر Autofill

در یک مسیر معمول کاربر برای تکمیل خودکار، وقتی یک کامپوننت با قابلیت تکمیل خودکار با اطلاعات کاربری پر می‌شود، رنگ آن تغییر می‌کند و هایلایت می‌شود تا به کاربر نشان دهد که تکمیل خودکار با موفقیت انجام شده است.

برای سفارشی‌سازی این رنگ هایلایت، از CompositionLocal استفاده کنید و هر رنگی که دوست دارید را وارد کنید. رنگ پیش‌فرض هایلایت Autofill به صورت Color(0x4dffeb3b) تعریف شده است.

فیلدهای متنی مبتنی بر مقدار

val customHighlightColor = Color.Red

CompositionLocalProvider(LocalAutofillHighlightColor provides customHighlightColor) {
    TextField(
        value = textFieldValue.value,
        onValueChange = { textFieldValue.value = it },
        modifier = Modifier.semantics { contentType = ContentType.Username }
    )
}
AutofillSnippets.kt

فیلدهای متنی مبتنی بر وضعیت

val customHighlightColor = Color.Red

CompositionLocalProvider(LocalAutofillHighlightColor provides customHighlightColor) {
    TextField(
        state = rememberTextFieldState(),
        modifier = Modifier.semantics { contentType = ContentType.Username }
    )
}
AutofillSnippets.kt