Tailwind 參考

每個元素都可以在其 class prop 中接受 Tailwind CSS 類別(條件類別則放在 classList)。NSH 會在 Rust 中根據 Tailwind 4 的預設主題解析這些類別:JS 只傳遞字串,每個不同的字串只會解析一次並加以快取;當外觀、視窗大小或按壓狀態改變時,dark: 或 active: 等變體會以原生方式重新求值,完全不會執行任何 JS。

每個工具類別所設定的內容,與 Tailwind CSS 4 為它產生的完全一致,意義亦與瀏覽器中相同。本頁列出所支援的項目。入門介紹請參閱 Tailwind;工具類別所設定的樣式鍵,請參閱 樣式參考。

Rust 元件不接受 class 字串:它們使用 Styled(nsh_core::prelude)的具型別方法為元素設定樣式,方法名稱取自這些工具類別,解析出的值亦相同,包括 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)。變體是接受樣式閉包的方法:.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>

#類別如何組合

• 後者優先。 在同一變體層級的工具類別中,字串中位置較後者優先:"p-4 p-2" 即 p-2。元件可接受 class prop,並將其附加到自身的類別之後,無須使用 tailwind-merge。
• 變體在一般工具類別之後套用,依 Tailwind 的變體順序: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:,最後是平台。類別先以其最高的變體決定先後,其次再比較次高的變體,多一個變體者排在較後(dark:hover: 排在 dark: 之後),與 Tailwind 的排序方式一致。因此 "active:bg-red-500 bg-blue-500" 在按下時為紅色。
• style 優先於類別。 內聯的 style 會套用在已解析的類別之上。樣式鍵就是同名的 CSS 屬性,亦即工具類別所設定的那一個,所以它只會取代該屬性,不影響其他:style={{ paddingLeft: 8 }} 優先於 pl-4,並保留 pr-4。重要(important)工具類別(!p-4 或 p-4!)同樣優先於內聯樣式。
• 文字樣式會繼承。 view 上的文字工具類別(text-white、font-bold、text-center ……)會傳遞給其內的 <Text> 和 <Input> 元素,與 CSS 相同。
• Display 依 CSS 而定。 flex 和 inline-flex 除非有方向工具類別另行指定(不論其在字串中的位置),否則會形成 row(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 點。

#間距值

接受間距值的工具類別(padding、margin、gap、inset、寬度、高度、basis、translate、leading)可使用:

外距、inset、translate、rotate、skew、scale、z、hue-rotate、tracking、underline-offset、outline-offset、網格線和漸變角度,可在前面加上 - 表示負值:-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(參閱主題自訂)。

每個顏色工具類別都接受:

currentColor 和 inherit 不是顏色值。與瀏覽器一樣,沒有顏色類別的邊框、outline 或 ring,會以元素的文字顏色繪製,即其自身設定的或繼承而來的顏色(<View class="text-white"><View class="border ring-2" /></View> 兩者都繪成白色);由 style prop 設定寬度但沒有指定顏色的邊框亦然。

#任意值

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

• _ 代表空格(grid-cols-[1fr_2fr]);如需字面的底線,請寫 \_。
• 長度:純數字或 px(點)、pt(一點的 4/3,與 CSS 相同)、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])。

#佈局

捲動是以元素而非類別實現:不支援 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-* 類別會取代該行高,不論它在字串中的位置或其變體為何(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。

#外環（Ring）

Ring 是帶有擴展半徑的 box shadow，繪製於邊框外側，不佔用空間。

#效果

陰影、ring 和 inset 陰影會如 CSS 一樣合併為單一 boxShadow 清單。陰影顏色會取代每個圖層的顏色（包括 alpha），與 Tailwind 的 --tw-shadow-color 相同：shadow-md shadow-red-500 是不透明的紅色陰影，shadow-md/20 shadow-red-500 則是 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" 物件中擴充主題。使用新名稱的項目會被新增;使用現有名稱的項目會取代預設值。長度單位為點(points)。主題會在應用程式打包時檢查:未知的鍵或無效的值會導致建置錯誤。

{
  "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 以及它們如何組合。
• 樣式參考:工具類別所設定的樣式鍵。