استخدِم شريط بحث لتنفيذ وظيفة البحث. شريط البحث هو حقل بحث دائم يتيح للمستخدمين إدخال كلمة رئيسية أو عبارة لعرض نتائج ذات صلة داخل تطبيقك، ويُنصح باستخدامه عندما يكون البحث هو التركيز الأساسي لتطبيقك.
مساحة واجهة برمجة التطبيقات
استخدِم 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إدخال النص وتعدّل الحالة كلما تغيّر النص في حقل الإدخال. - تتحكّم حالة
The 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.
النتيجة
مراجع إضافية
- Material Design: شريط البحث