برای پیادهسازی عملکرد جستجو، از نوار جستجو استفاده کنید. نوار جستجو فیلد جستجوی پایداری است که به کاربران امکان میدهد کلیدواژه یا عبارتی را وارد کنند تا نتایج مرتبط در برنامه شما نمایش داده شود، و زمانی توصیه میشود که جستجو تمرکز اصلی برنامه شما باشد.
سطح میانای برنامهسازی کاربردی
برای پیادهسازی نوار جستجو، از عنصر ترکیبی SearchBar استفاده کنید. پارامترهای کلیدی برای
این عنصر ترکیبی شامل موارد زیر است:
inputField: فیلد ورودی نوار جستجو را تعریف میکند. این نما معمولاً ازSearchBarDefaults.InputFieldاستفاده میکند که امکان سفارشیسازی موارد زیر را فراهم میکند:query: نوشتار پُرسمان برای نمایش در فیلد ورودی.-
onQueryChange: لامبدا برای مدیریت تغییرات در رشته پُرسمان.
expanded: مقدار بولی که نشان میدهد آیا نوار جستجو ازهم باز شده است تا پیشنهادها یا نتایج فیلترشده را نشان دهد یا نه.
onExpandedChange: لامبدا برای مدیریت تغییرات در وضعیت ازهم بازشده منو کرکرهای.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«فعالیت» میزبان مینویسد.- توصیفگر
semanticsترتیب پیمایش TalkBack را کنترل میکند.-
isTraversalGroupبرایBoxتنظیم شده است تا همه عناصر ترکیبی فرزندش را گروهبندی کند. traversalIndexتنظیم شده است تا ترتیب خواندن اطلاعات دسترسپذیری از هر همتای گروه را مشخص کند. 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) ) } } } } }
نکات کلیدی درباره کد
- هرگاه کاربر در نوار جستجو نوشتار تایپ کند یا آن را حذف کند، تابع لامبدای
onQueryChangeفراخوانده میشود. -
SearchBarDefaults.InputFieldحاویleadingIconاست که نماد جستجو را به ابتدای فیلد ورودی اضافه میکند وtrailingIconکه نماد «گزینههای بیشتر» را به انتهای فیلد ورودی اضافه میکند. در اینجا میتوانید گزینههای مرتبسازی و فیلتر کردن را به کاربر ارائه دهید. - وقتی جستجو ارسال میشود،
onSearch = { … }لامبدایonSearchرا فرا میخواند و نوار جستجو را جمع میکند. LazyColumnبهطور کارآمد تعداد بالقوه زیادی از نتایج جستجو را مدیریت میکند. این گره در فهرستsearchResultsتکرار میکند و هر نتیجه را بهعنوانListItemنمایش میدهد.- هر
ListItemقابلساخت نوشتار مورد، نوشتار نشاندهنده اطلاعات اضافی، و نماد ستاره را بهعنوانleadingContentمورد نشان میدهد. در این مثال، گزینهای برای افزودن مورد به موارد دلخواه ارائه میشود. - برای منطق فیلتر کردن،
CustomizableSearchBarExampleرا در کد منبع کامل در GitHub ببینید.
نتیجه
منابع بیشتر
- طراحی سهبعدی: نوار جستجو