استخدِم شريط بحث لتنفيذ وظيفة البحث. شريط البحث هو حقل بحث دائم يتيح للمستخدمين إدخال كلمة رئيسية أو عبارة لعرض نتائج ذات صلة داخل تطبيقك، ويُنصح باستخدامه عندما يكون البحث هو التركيز الأساسي لتطبيقك.
مساحة عرض واجهة برمجة التطبيقات
استخدِم العنصر القابل للإنشاء SearchBar لتنفيذ أشرطة البحث. تشمل المَعلمات الرئيسية لهذا العنصر القابل للإنشاء ما يلي:
-
inputField: يحدّد حقل الإدخال في شريط البحث. تستخدِم هذه الميزة عادةًSearchBarDefaults.InputField، ما يتيح تخصيص ما يلي:-
query: نص طلب البحث المطلوب عرضه في حقل الإدخال. -
onQueryChange: دالة Lambda للتعامل مع التغييرات في سلسلة طلب البحث
-
expanded: قيمة منطقية تشير إلى ما إذا كان شريط البحث موسّعًا لعرض الاقتراحات أو النتائج التي تمّت فلترتها.
onExpandedChange: دالة Lambda للتعامل مع التغييرات في حالة القائمة المنسدلة الموسّعةcontent: محتوى شريط البحث هذا لعرض نتائج البحث أسفلinputField.
شريط البحث مع الاقتراحات
يوضّح المقتطف التالي عملية تنفيذ أساسية للسمة SearchBar مع اقتراحات:
@OptIn(ExperimentalMaterial3Api::class) @Composable fun SimpleSearchBar( textFieldState: TextFieldState, onSearch: (String) -> Unit, searchResults: List<String>, modifier: Modifier = Modifier ) { // Controls expansion state of the search bar var expanded by rememberSaveable { mutableStateOf(false) } Box( modifier .fillMaxSize() .semantics { isTraversalGroup = true } ) { SearchBar( modifier = Modifier .align(Alignment.TopCenter) .semantics { traversalIndex = 0f }, inputField = { SearchBarDefaults.InputField( query = textFieldState.text.toString(), onQueryChange = { textFieldState.edit { replace(0, length, it) } }, onSearch = { onSearch(textFieldState.text.toString()) expanded = false }, expanded = expanded, onExpandedChange = { expanded = it }, placeholder = { Text("Search") } ) }, expanded = expanded, onExpandedChange = { expanded = it }, ) { // Display search results in a scrollable column Column(Modifier.verticalScroll(rememberScrollState())) { searchResults.forEach { result -> ListItem( headlineContent = { Text(result) }, modifier = Modifier .clickable { textFieldState.edit { replace(0, length, result) } expanded = false } .fillMaxWidth() ) } } } } }
نقاط أساسية حول الرمز
- تضمن السمة
rememberSaveableالحفاظ على حالة شريط البحث، سواء كان موسّعًا أو مصغّرًا، عند إجراء تغييرات على الإعدادات. تكتب هذه السمة القيمة التي تم تذكّرها في حزمةsavedInstanceStateالخاصة بـ Activity المضيفة قبل أن يتم إيقاف Activity نهائيًا أثناء تغيير الإعدادات. - يتحكّم مفتاح التعديل
semanticsفي ترتيب التنقّل في TalkBack.- يتم ضبط
isTraversalGroupعلىBoxلتجميع جميع العناصر القابلة للإنشاء الفرعية. - يتم ضبط
traversalIndexلتحديد الترتيب الذي يقرأ به TalkBack معلومات تسهيل الاستخدام من كل جهاز تابع للمجموعة. يقرأ TalkBack معلومات تسهيل الاستخدام الخاصة بعنصر ذي قيمة سالبة، مثل-1، قبل قراءة معلومات عنصر ذي قيمة موجبة، مثل1. بما أنّ القيمة هي عدد عشري، يمكنك تحديد ترتيب مخصّص للعديد من العناصر المشابهة من خلال ضبط قيم بين-1.0و1.0لكل عنصر مشابه.
- يتم ضبط
- يحتوي
SearchBarعلىinputFieldلبيانات أدخلها المستخدم وColumnلعرض اقتراحات البحث.- تنشئ
SearchBarDefaults.InputFieldحقل الإدخال وتتعامل مع التغييرات التي تطرأ على طلب بحث المستخدم. - تعالج الدالة
onQueryChangeإدخال النص وتعدّل الحالة كلما تغيّر النص في حقل الإدخال. - تتحكّم حالة
expandedفي مستوى ظهور قائمة الاقتراحات.
- تنشئ
- تكرّر
searchResults.forEach { result -> … }القائمةsearchResultsوتنشئListItemلكل نتيجة.- عند النقر على
ListItem، يتم تعديلtextFieldStateوتصغير شريط البحث وملءtextFieldبنتيجة البحث المحدّدة.
- عند النقر على
النتيجة
شريط البحث مع قائمة تمت فلترتها
يعرض هذا المثال SearchBar يفلتر قائمة استنادًا إلى طلب بحث المستخدم:
@OptIn(ExperimentalMaterial3Api::class) @Composable fun CustomizableSearchBar( query: String, onQueryChange: (String) -> Unit, onSearch: (String) -> Unit, searchResults: List<String>, onResultClick: (String) -> Unit, modifier: Modifier = Modifier, // Customization options placeholder: @Composable () -> Unit = { Text("Search") }, leadingIcon: @Composable (() -> Unit)? = { Icon(Icons.Default.Search, contentDescription = "Search") }, trailingIcon: @Composable (() -> Unit)? = null, supportingContent: (@Composable (String) -> Unit)? = null, leadingContent: (@Composable () -> Unit)? = null, ) { // Track expanded state of search bar var expanded by rememberSaveable { mutableStateOf(false) } Box( modifier .fillMaxSize() .semantics { isTraversalGroup = true } ) { SearchBar( modifier = Modifier .align(Alignment.TopCenter) .semantics { traversalIndex = 0f }, inputField = { // Customizable input field implementation SearchBarDefaults.InputField( query = query, onQueryChange = onQueryChange, onSearch = { onSearch(query) expanded = false }, expanded = expanded, onExpandedChange = { expanded = it }, placeholder = placeholder, leadingIcon = leadingIcon, trailingIcon = trailingIcon ) }, expanded = expanded, onExpandedChange = { expanded = it }, ) { // Show search results in a lazy column for better performance LazyColumn { items(count = searchResults.size) { index -> val resultText = searchResults[index] ListItem( headlineContent = { Text(resultText) }, supportingContent = supportingContent?.let { { it(resultText) } }, leadingContent = leadingContent, colors = ListItemDefaults.colors(containerColor = Color.Transparent), modifier = Modifier .clickable { onResultClick(resultText) expanded = false } .fillMaxWidth() .padding(horizontal = 16.dp, vertical = 4.dp) ) } } } } }
نقاط أساسية حول الرمز
- يتم استدعاء دالة
onQueryChangeLambda كلما كتب المستخدم نصًا أو حذفه في شريط البحث. - يحتوي
SearchBarDefaults.InputFieldعلىleadingIcon، ما يضيف رمز بحث إلى بداية حقل الإدخال، وtrailingIcon، ما يضيف رمز "المزيد من الخيارات" إلى نهاية حقل الإدخال. يمكنك هنا توفير خيارات الفرز والفلترة للمستخدم. - تستدعي الدالة
onSearch = { … }دالة lambdaonSearchوتصغّر شريط البحث عند إرسال طلب البحث. - يتعامل
LazyColumnمع عدد كبير محتمل من نتائج البحث بكفاءة. تتكرّر هذه الدالة خلال قائمةsearchResultsوتعرض كل نتيجة كـListItem. - يعرض كل عنصر
ListItemمركّب نص العنصر ونصًا يعرض معلومات إضافية ورمز نجمة كعنصرleadingContent. في هذا المثال، يتم عرض خيار لإضافة السلعة إلى المفضّلة. - للاطّلاع على منطق الفلترة، يُرجى الرجوع إلى
CustomizableSearchBarExampleفي رمز المصدر الكامل على GitHub.
النتيجة
مراجع إضافية
- التصميم المتعدد الأبعاد: شريط البحث