--- url: https://nsh.dev/zh-TW/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 的 view 中觸發元件之後，而非其內部，因此按下它不會開啟清單；應用程式負責放置它（以 `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