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

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

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

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

تکمیل اطلاعات کاربری

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

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

ذخیره اطلاعات اعتباری

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

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

می‌توانید از «تکمیل خودکار» در برنامه‌تان استفاده کنید تا بازیابی داده‌های ذخیره‌شده را برای کاربران ساده‌تر کنید. «تکمیل خودکار» از مؤلفه‌های نوشتاری ازطریق BasicTextField و همه فیلدهای نوشتاری Material که براساس آن مؤلفه ساخته شده‌اند پشتیبانی می‌کند.

راه‌اندازی تکمیل خودکار

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

افزودن «تکمیل خودکار» به فیلد نوشتار بااستفاده از نوع محتوا

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

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

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

افزودن فیلدهای «تکمیل خودکار» با انواع مختلف

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

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

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

تکمیل داده‌ها با «تکمیل خودکار»

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

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

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

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

ذخیره صریح داده‌ها با «تکمیل خودکار»

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

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

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

   val autofillManager = LocalAutofillManager.current
   AutofillSnippets.kt

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

   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. بافت «تکمیل خودکار» را درصورت نیاز با کلیک روی دکمه‌ای ثبت کنید:

   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

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

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

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

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

عیب‌یابی

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

سفارشی‌سازی بیشتر «تکمیل خودکار»

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

برای سفارشی‌سازی این رنگ برجسته‌سازی، از CompositionLocal استفاده کنید و رنگ موردنظرتان را ارائه دهید. رنگ برجسته‌سازی «تکمیل خودکار» پیش‌فرض به‌صورت Color(0x4dffeb3b) تعریف شده است.

val customHighlightColor = Color.Red

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