--- url: https://nsh.dev/zh-HK/elements/select description: "Select 元件:從項目清單中選取單一數值,在桌面平台於觸發元素旁顯示彈出視窗,在手機上則以底部面板呈現,支援鍵盤操作、輸入即時跳選、搜尋及分組,並由應用程式自行設定樣式。" demo: https://nsh.dev/play/index.html#el-select --- # Select Select 讓使用者從一列項目中選出一個值，例如設定、篩選條件、國家或時區。應用程式的觸發元素會開啟列表，並按各種裝置的慣例呈現： - 在桌面平台及桌面瀏覽器上，彈出視窗會疊在觸發元素之上，已選取的列覆蓋在觸發元素的位置，使所選標題停留在原處（shadcn/ui 的 `item-aligned` 定位）。視窗寬度與觸發元素相同（應用程式的 `popupStyle` / `popupClass` 寬度可另行指定，一如 `gpui-component` 的 `menu_width`），高度隨各列而定，上限為螢幕可用的空間。未選取任何項目時，視窗會在觸發元素下方開啟。鍵盤可在項目之間移動並選取其中一項。 - 在手機及平板電腦上，列表以螢幕底部的面板呈現，並置於背景遮罩之上。 Select 負責行為：值（由應用程式持有，或由 Select 自行持有）、開啟狀態、鍵盤、輸入即選（typeahead）、搜尋、分組、高亮列，以及螢幕閱讀器讀出的內容。外觀則由應用程式負責：它為觸發元素、彈出視窗、列表、各列、分組標題和搜尋欄設定樣式，或自行繪製各列。 ```rust use nsh_base::{SelectEntry, SelectItem, select, theme}; use nsh_core::prelude::*; const FRUITS: [(&str, &str); 5] = [ ("apple", "Apple"), ("banana", "Banana"), ("blueberry", "Blueberry"), ("grapes", "Grapes"), ("pineapple", "Pineapple"), ]; fn fruit_select() -> impl IntoElement { let fruit = signal(None::); let title = move || { let chosen = fruit.get(); FRUITS .iter() .find(|(value, _)| Some(*value) == chosen.as_deref()) .map_or("Pick a fruit", |(_, title)| *title) .to_string() }; select() .items( FRUITS .iter() .map(|&(value, title)| SelectItem::new(value, title).disabled(value == "grapes")) .collect::>(), ) .value(move || fruit.get()) .on_change(move |next: &Option| fruit.set(next.clone())) .accessibility_label("Fruit") .offset(px(4.0)) .popup_style(|s| { s.p_1() .rounded_lg() .border_1() .border_color(move || theme().border) .bg(move || theme().popover) .text_color(move || theme().popover_foreground) .shadow_md() }) .item_class("rounded-md focus:bg-accent selected:font-medium disabled:opacity-50") .trigger( view() .h_9() .w_48() .flex_row() .items_center() .justify_between() .px_3() .rounded_md() .border_1() .border_color(move || theme().input) .hover(|s| s.bg(move || theme().accent)) .child(text(title)) .child(text("▾").text_color(move || theme().muted_foreground)), ) .render_item(|item: &SelectEntry| { view() .flex_row() .items_center() .px_2() .py_1p5() .child(text(item.title.clone()).text_sm()) }) } ``` ```tsx import { mount, signal, Text, View } from "nsh"; import { Select } from "nsh/base"; const FRUITS = [ { value: "apple", title: "Apple" }, { value: "banana", title: "Banana" }, { value: "blueberry", title: "Blueberry" }, { value: "grapes", title: "Grapes", disabled: true }, { value: "pineapple", title: "Pineapple" }, ]; function App() { const fruit = signal(null); const title = () => FRUITS.find((f) => f.value === fruit())?.title; return ( ``` 各列是彈出視窗捲動視圖中的虛擬化列表：即使列表有數千個項目，也只會建立可見範圍內的列；當各列高於可用空間時，彈出視窗會捲動。 ## 值 使用 `value` 時，所選項目由應用程式持有：Select 顯示該值對應的項目，並以 `onChange({ value })` 回報選取操作；應用程式可設定 `value` 以跟隨該操作，也可保留自己的值。`value={null}` 表示未選取任何項目。如果省略，Select 會自行保存值，起始值來自 `defaultValue`。`onChange` 會回報變更：再次選取已選的項目只會關閉列表。 `cleanable` 會在已選取項目時加入清除按鈕：按下後會清除該值，並以 `onChange({ value: null })` 回報，列表保持關閉。此按鈕位於 Select 視圖中觸發元素之後，而不在觸發元素內，因此按下它不會開啟列表；其位置和內容由應用程式決定（以 `absolute` 置於觸發元素的末端，即原本箭嘴所在處）： ```tsx No time zone found} trigger={trigger} /> ``` 在桌面平台上，列表開啟時搜尋欄會取得鍵盤；在觸控螢幕上，按下搜尋欄後才會彈出鍵盤。每次開啟時，搜尋內容都會重新清空。 ## 由應用程式繪製的列 `itemClass` 為每個項目的列設定樣式，列預設顯示項目的標題，直至 `renderItem` 接手繪製：`focus:` 套用於高亮列（按鍵或指標所在之處），`selected:` 套用於已選取的列，`disabled:` 套用於已停用的列。若要自行繪製列，請提供 `renderItem`：它會取得該項目的資料（[`SelectEntry`](#types)），並傳回該列的內容，且只為可見的列執行。它永遠不會取得列的狀態：只要在 `itemClass` 中使用 `group`，內容就會透過 `group-focus:`、`group-selected:` 和 `group-disabled:` class 跟隨列的狀態，因此每個項目只會繪製一次，高亮移動或作出選取時不會重新繪製。`renderGroup` 以同樣方式繪製分組標題： ```tsx