Tailwind 參考

每個元素都接受 Tailwind CSS class,透過其 class prop 傳入(條件式 class 則透過 classList)。NSH 以 Rust 針對 Tailwind 4 的預設主題解析這些 class:JS 只傳遞字串,每個不同的字串只會解析一次並快取,而 dark: 或 active: 這類 variant 會在外觀、視窗大小或按壓狀態改變時於原生端重新求值,完全不需執行任何 JS。

每個 utility 所設定的內容與 Tailwind CSS 4 為其產生的完全一致,含義也與瀏覽器中相同。本頁列出所支援的項目。入門介紹請參閱 Tailwind;關於這些 utility 所設定的樣式鍵,請參閱樣式參考。

Rust 元件不接受 class 字串:它們使用 Styled(nsh_core::prelude)的型別化方法來設定元素樣式,方法名稱取自這些 utility,解析出的值也相同,包含 Tailwind 的預設級距(px-4 即 .px_4()、rounded-2xl 即 .rounded_2xl()、shadow-md 即 .shadow_md()、bg-linear-to-br 即 .bg_linear_to_br())。顏色是值:可為主題顏色,或以 nsh_core::element::palette 表示的 Tailwind 色盤(ZINC.shade(800) 即 zinc-800)。Variant 是接受樣式閉包的方法:.active(|s| …)、.hover(…)、.focus(…)、.disabled_style(…)、.dark(…)、.group_active(…),其餘的則使用 .style_when(condition, …)。樣式參考列出了各樣式鍵對應的方法名稱。

use nsh_core::{element::palette::{RED, ZINC}, prelude::*};

view()
    .flex_row()
    .items_center()
    .gap_3()
    .rounded_2xl()
    .bg(white())
    .p_4()
    .shadow_md()
    .active(|s| s.scale(0.98))
    .transition()
    .dark(|s| s.bg(ZINC.shade(800)))
    .child(
        text("Inbox")
            .text_base()
            .font_weight(FontWeight::SEMIBOLD)
            .text_color(ZINC.shade(900))
            .dark(|s| s.text_color(white())),
    )
    .child(
        text(move || unread.get().to_string())
            .text_color(move || if unread.get() > 0 { RED.shade(500) } else { ZINC.shade(400) }),
    )

<View class="flex-row items-center gap-3 rounded-2xl bg-white p-4 shadow-md active:scale-[0.98] transition dark:bg-zinc-800">
  <Text class="text-base font-semibold text-zinc-900 dark:text-white">Inbox</Text>
  <Text classList={{ "text-red-500": unread() > 0, "text-zinc-400": unread() === 0 }}>{unread()}</Text>
</View>

#class 如何組合

• 後者優先。 在相同 variant 層級的 utility 中,字串中較後面的優先:"p-4 p-2" 等同於 p-2。元件可以接受 class prop,並將其附加在自身 class 之後,無需 tailwind-merge。
• Variant 在一般 utility 之後套用,依 Tailwind 的 variant 順序:group-*:(依其狀態,再依群組名稱)、selection:、placeholder:、位置(first: …)、checked:、indeterminate:、selected:、focus-within:、hover:、focus:、focus-visible:、active:、enabled:、disabled:、aria-busy:、aria-checked:、aria-expanded:、aria-pressed:、aria-selected:、data-*:(依名稱)、動態效果、max-*: 斷點(由寬到窄),接著是升冪斷點、方向(orientation)、書寫方向(direction)、dark:,最後是平台。一個 class 先由其最高階的 variant 決定順序,再由次高階的決定,多出的一個 variant 則排在更後面(dark:hover: 排在 dark: 之後),與 Tailwind 的排序方式相同。因此 "active:bg-red-500 bg-blue-500" 在按壓時為紅色。
• style 優先於 class。 行內的 style 會套用在解析後的 class 之上。樣式鍵就是同名的 CSS 屬性,也就是 utility 所設定的那一個,因此它只會取代該屬性,不影響其他屬性:style={{ paddingLeft: 8 }} 會勝過 pl-4,並保留 pr-4。important utility(!p-4 或 p-4!)同樣會勝過行內樣式。
• 文字樣式會繼承。 view 上的文字 utility(text-white、font-bold、text-center 等)會傳遞給其內部的 <Text> 與 <Input> 元素,與 CSS 相同。
• Display 依 CSS 規則。 flex 與 inline-flex 會形成 row,除非有方向 utility 另行指定,無論它在字串中的位置為何(flex-col flex 為 column)。樣式的 display: "flex" 同樣是 row;未設定 display 的 view 則維持 NSH 預設的 column。

#單位與主題

長度單位為點(1 = iOS 上的一點、Android 上的一 dp)。Tailwind 的 1rem 為 16 點,因此在相同密度下,主題與網頁一致:一個間距級距為 4 點(p-4 = 16 點),text-base 為 16 點。

#間距值

接受間距值的 utility(padding、margin、gap、inset、width、height、basis、translate、leading)可使用:

Margin、inset、translate、rotate、skew、scale、z、hue-rotate、tracking、underline-offset、outline-offset、grid 線與漸層角度可在前面加上 - 表示負值:-mt-2、-translate-x-1/2、-rotate-6。Tailwind 對其他項目(-p-4、-gap-2、-w-4)沒有負值形式,NSH 亦然。

#顏色

內建完整的 Tailwind 4 色盤:red、orange、amber、yellow、lime、green、emerald、teal、cyan、sky、blue、indigo、violet、purple、fuchsia、pink、rose、slate、gray、zinc、neutral、stone、mauve、olive、mist、taupe,每種顏色都有 50、100–900、950 等色階;另有 black、white 與 transparent。自訂顏色來自 nsh.json(請參閱主題自訂)。

每個顏色 utility 都接受:

currentColor 與 inherit 不是顏色值。與瀏覽器相同,沒有顏色 class 的 border、outline 或 ring 會以元素的文字顏色繪製,即其自身設定或繼承而來的顏色(<View class="text-white"><View class="border ring-2" /></View> 會將兩者都畫成白色);由 style prop 設定寬度但未指定顏色的 border 也是如此。

#任意值

方括號可傳入主題中沒有的值:w-[37px]、grid-cols-[200px_1fr]、bg-[linear-gradient(45deg,red,blue)]。

• _ 代表空格(grid-cols-[1fr_2fr]);若要表示實際的底線,請寫 \_。
• 長度:純數字或 px(點)、pt(如 CSS 中的 4/3 點)、rem(16 點),以及在百分比有意義之處可用 %。
• 角度(rotate-[...]、hue-rotate-[...]、bg-linear-[...]):deg、rad、grad、turn。
• 時間(duration-[...]、delay-[...]):ms 或 s;純數字為毫秒。
• 型別提示用於釐清有歧義的值:text-[length:22px] 是尺寸,text-[color:#333] 是顏色;border-[length:3px] 亦同。

不支援任意 CSS 屬性([mask-type:luminance])。

#版面配置

捲動是元素而非 class:不支援 overflow-auto 與 overflow-scroll;請使用 scroll。

#Flexbox 與 grid

#間距

#尺寸

容器寬度(點):3xs 256、2xs 288、xs 320、sm 384、md 448、lg 512、xl 576、2xl 672、3xl 768、4xl 896、5xl 1024、6xl 1152、7xl 1280;prose 為元素字型的 0 寬度的 65 倍(即 CSS 的 65ch),與 Tailwind CSS 相同。

#字體排印

#字型

#大小、顏色與行高

text-<size> 會設定字型大小以及 Tailwind 對應的行高;leading-* class 會取代該行高,無論它在字串中的位置或其 variant 為何(leading-tight md:text-lg 保留緊密的行距):

#對齊、大小寫與換行

#裝飾與陰影

Tailwind 的文字陰影有多個層；原生端只繪製一個陰影，即最寬的那一層。

#輸入

#背景

漸層工具類別以 Oklab 混合其顏色，與 Tailwind CSS 的寫法一致（in oklab）；在任意位置（bg-linear-[25deg]、bg-conic-[0.25turn]）時則遵循 CSS 的預設：色票中的顏色使用 Oklab，而當每個色標都是十六進位、rgb()、hsl() 或具名顏色時使用 sRGB。

view()
    .h_32()
    .rounded_2xl()
    .bg_linear_to_br()
    .gradient_from(INDIGO.shade(500))
    .gradient_via(PURPLE.shade(500))
    .gradient_via_position(percentage(0.4))
    .gradient_to(PINK.shade(500))

<View class="h-32 rounded-2xl bg-linear-to-br from-indigo-500 via-purple-500 via-40% to-pink-500" />

#邊框

圓角尺寸（點）：xs 2、sm 4、md 6、lg 8、xl 12、2xl 16、3xl 24、4xl 32、full 9999。

#環框

環框是帶有擴展半徑的盒狀陰影，繪製於邊框外側，不佔用空間。

#效果

陰影、環框與內嵌陰影會如同 CSS 一樣合併為單一 boxShadow 清單。陰影顏色會取代每一層的顏色，包括 alpha，與 Tailwind 的 --tw-shadow-color 相同：shadow-md shadow-red-500 是不透明的紅色陰影，shadow-md/20 shadow-red-500 則是 alpha 為 20% 的紅色陰影。

#濾鏡

#變形

變形工具類別的組合方式與 CSS 相同：translate-*、rotate-* 與 scale-* 分別設定 translate、rotate 與 scale 屬性，且不論順序皆會合併，接著再套用 transform（rotate-x-*、skew-*）。style prop 中同名的鍵只會取代各自的屬性：style={{ scale: 1.1 }} 會取代 scale-95，並保留 rotate-3。transform、transform-gpu、transform-cpu 與 transform-flat 可被接受但不會有任何作用：NSH 以相同方式組合所有變形，且為平面。以尺寸比例表示的平移會依元素的 frame 解析，並在元素調整大小時隨之變動。

#轉場與動畫

轉場會在值變更時於 UI 執行緒上執行，包括變體開始或停止符合時，因此 transition active:scale-95 可在不需要 JS 的情況下為按壓加上動畫。請將動畫包在 motion-safe: 中，以遵循減少動態效果的設定。

#互動性

#SVG

#圖片

#接受但無作用

這些工具類別屬於渲染提示，或是每個原生檢視本來就具備的行為；它們解析時不會產生警告，也不會改變任何內容：antialiased, subpixel-antialiased, isolation-auto, box-border, appearance-none, appearance-auto, will-change-auto, will-change-scroll, will-change-contents, will-change-transform, will-change-[<value>], transform, transform-gpu, transform-cpu, transform-flat。捲動、吸附與過度捲動是 scroll 的 props。

#不支援

peer-* 變體、偽元素（before:、after:）、任意屬性（[prop:value]）、overflow-auto / overflow-scroll、divide-*、columns-*、float-*、container、容器查詢、order-*、transform-3d、select-all、border-double / outline-double、固有最小／最大限制（例如 max-w-max）、snap-*、scroll-*、overscroll-*、touch-* 與 isolate 皆屬於未知的類別。nsh build 與 nsh dev 會對在原始碼中發現的未知類別發出警告（file:line:col: unknown class '...'），而執行階段會將每個未知類別僅記錄一次。

#變體

變體可讓工具類別具有條件性：dark:bg-zinc-900、md:flex-row、active:opacity-70。它們可以疊加（dark:active:bg-zinc-700），並在其所依賴的內容變更時於原生端重新評估。

#外觀與環境

#斷點

斷點會比較視窗寬度（以點為單位）。

直向的手機（寬 390 點）不符合任何預設斷點；平板或橫向的手機則會符合多個斷點。在 Rust 中，斷點是視窗上的條件：.style_when(move || window().width >= px(768.0), |s| s.p_8()) 即 md:p-8。

#互動狀態

平台只會針對其類別有用到這些狀態的元素追蹤狀態，且變更會在原生端套用，不需往返 JS。

相同的狀態以樣式物件的形式，即為每個元素的 activeStyle、hoverStyle、focusStyle、disabledStyle、checkedStyle、indeterminateStyle、expandedStyle 與 pressedStyle props（以及 Button 的 selectedStyle）；它們會疊加在元素的樣式與類別之上。

disabled 適用於任何元素：它會套用 disabled: 並移除元素的按壓處理常式，因此也不會顯示按壓回饋。

view()
    .on_press(save)
    .disabled(saving)
    .rounded_lg()
    .bg(BLUE.shade(600))
    .px_4()
    .py_2()
    .transition()
    .active(|s| s.scale(0.95).bg(BLUE.shade(700)))
    .disabled_style(|s| s.opacity(0.4))
    .child(text("Save").font_weight(FontWeight::MEDIUM).text_color(white()))

<View
  onPress={save}
  disabled={saving()}
  class="rounded-lg bg-blue-600 px-4 py-2 transition active:scale-95 active:bg-blue-700 disabled:opacity-40"
>
  <Text class="font-medium text-white">Save</Text>
</View>

#群組

以 group 標記祖先元素，並以 group-<state>: 依其狀態為子孫元素設定樣式。為群組命名即可巢狀使用：group/card 與 group-hover/card:。

view()
    .on_press(open)
    .group_named("row")
    .flex_row()
    .items_center()
    .gap_3()
    .p_3()
    .active(|s| s.bg(ZINC.shade(100)))
    .child(
        text("Settings")
            .flex_1()
            .text_color(ZINC.shade(900))
            .group_active_named("row", |s| s.text_color(BLUE.shade(600))),
    )
    .child(
        text("›")
            .text_color(ZINC.shade(400))
            .group_active_named("row", |s| s.translate_x(px(4.0)))
            .transition_transform(),
    )

<View onPress={open} class="group/row flex-row items-center gap-3 p-3 active:bg-zinc-100">
  <Text class="flex-1 text-zinc-900 group-active/row:text-blue-600">Settings</Text>
  <Text class="text-zinc-400 group-active/row:translate-x-1 transition-transform">›</Text>
</View>

#同層元素中的位置

each(items, |item: &Item| item.id, move |item, index| {
    text(move || item.with(|i| i.name.clone()))
        .border_b(px(1.0))
        .border_color(ZINC.shade(200))
        .py_3()
        .style_when(move || index.get() + 1 == items.with(Vec::len), |s| s.border_b(px(0.0)))
})

<Each of={items()}>{(item) => <Text class="border-b border-zinc-200 py-3 last:border-b-0">{item().name}</Text>}</Each>

#預留位置文字與選取

placeholder: 套用於 <Input> 的預留位置文字，且只接受文字顏色：placeholder:text-zinc-400（樣式鍵 placeholderColor）。selection: 套用於 <Input> 或可選取的 <Text> 中被選取的內容；若用在任何元素上，則作用於其內部的元素（即 Tailwind 的 & *::selection；以最近的元素為準），並接受背景色作為醒目提示：selection:bg-violet-200（樣式鍵 selectionColor；在平台以單一顏色繪製輸入框插入符號的情況下，它也會為插入符號著色）。

#重要

將 ! 加在工具類別之前或之後（!p-4、p-4!），可使其優先於所有其他類別以及行內的 style。

#主題自訂

在應用程式 nsh.json 的 "tailwind" 物件中擴充主題。名稱為新的項目會被新增；名稱已存在的項目會取代預設值。長度單位為 point。主題會在應用程式打包時檢查：未知的鍵或無效的值會導致建置錯誤。

{
  "name": "My App",
  "id": "com.example.myapp",
  "tailwind": {
    "colors": {
      "brand": { "50": "#f5f3ff", "500": "#7c3aed", "600": "#6d28d9", "DEFAULT": "#7c3aed" },
      "accent": "#f59e0b"
    },
    "spacing": 4,
    "breakpoints": { "tablet": 600 },
    "fontFamily": { "display": "Inter" },
    "fontSize": { "huge": [48, 1.1] },
    "fontWeight": { "heavy": 850 },
    "radius": { "card": 14 },
    "shadow": { "card": "0 2px 8px rgb(0 0 0 / 0.12)" },
    "insetShadow": { "well": "inset 0 2px 6px rgb(0 0 0 / 0.1)" },
    "dropShadow": { "icon": "0 2px 4px rgb(0 0 0 / 0.2)" },
    "tracking": { "label": 0.08 },
    "leading": { "dense": 1.15 },
    "blur": { "glass": 20 },
    "perspective": { "card": 700 },
    "aspect": { "photo": 1.5 },
    "ease": { "snappy": [0.2, 0, 0, 1] },
    "container": { "content": 680 }
  }
}

使用此主題後，bg-brand-500、bg-brand（DEFAULT 色階）、text-accent、tablet:flex-row、font-display、text-huge、font-heavy、rounded-card、shadow-card、inset-shadow-well、drop-shadow-icon、tracking-label、leading-dense、blur-glass、perspective-card、aspect-photo、ease-snappy 與 max-w-content 皆可使用。

#相關內容

• Tailwind：指南。
• 樣式設計：class、classList、style 以及它們如何組合。
• 樣式參考：工具類別所設定的樣式鍵。