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