樣式參考

本頁列出 style prop 的每個鍵,以及 Styled 中在 Rust 裏設定該鍵的方法。Rust 元件以具類型的方法為元素設定樣式,這些方法以 Tailwind 的 utility 命名(.p_4()、.rounded(px(12.0))、.bg(color),來自 nsh_core::prelude),並會轉換為相同的鍵;TSX 則傳入 style 物件(以及 class)。「Rust」一欄列出方法名稱;大部分方法可接受數值、signal 或閉包,而 .style_when(…) / .style_with(…) 可令其中任何一個方法按條件生效。鍵及其類型來自 .nsh/types/nsh/types.d.ts 中生成的宣告,因此編輯器會在你輸入時進行檢查。樣式鍵代表與其同名的 CSS 屬性,效果與設定該屬性的 class 相同:paddingLeft 即 CSS 的 padding-left 和 pl-4,boxShadow 即 box-shadow 和 shadow-md;少數鍵採用應用程式較常用的簡單名稱(paddingHorizontal 代表 padding-inline、marginStart 代表 margin-inline-start、numberOfLines 代表 line-clamp)。數字以點(point)為單位,同時亦支援各項 CSS 功能:grid、漸變、box shadow、濾鏡、混合模式、outline、transform、transition 和 keyframe 動畫。

如需了解如何套用樣式、如何與 class 結合以及如何繼承文字樣式,請參閱樣式。如需了解 class 語法,請參閱 Tailwind 參考。

#五個介面

每個介面都會擴充前一個介面:

use nsh_core::prelude::*;

fn card() -> View {
    view().p_4().rounded(px(12.0)).bg(white()).shadow([BoxShadow {
        offset_y: px(4.0),
        blur: px(12.0),
        color: rgba(0x00000014).into(),
        ..BoxShadow::default()
    }])
}

fn title(label: &str) -> Text {
    text(label.to_string()).text_size(px(17.0)).font_weight(FontWeight::SEMIBOLD).text_color(rgb(0x111111))
}

card().child(title("Hello"))

import type { ViewStyle, TextStyle } from "nsh";
import { Text, View } from "nsh";

const card: ViewStyle = {
  padding: 16,
  borderRadius: 12,
  backgroundColor: "#fff",
  boxShadow: "0 4px 12px rgb(0 0 0 / 0.08)",
};

const title: TextStyle = { fontSize: 17, fontWeight: "600", color: "#111" };

<View style={card}>
  <Text style={title}>Hello</Text>
</View>;

style 亦接受陣列;各項目由左至右合併,假值(falsy)項目會被略過,因此條件樣式無需展開。在 Rust 中,.style_when(condition, …) 會在條件成立期間加入樣式:

card().style_when(selected, |s| s.border_color(rgb(0x2563eb)).border(px(2.0)))

<View style={[card, selected() && { borderColor: "#2563eb", borderWidth: 2 }]} />

#樣式鍵的解讀方式

樣式鍵遵循 CSS,因此指向同一屬性的樣式與 class 效果相同:

• 版面方向。 未設定 display 的 view 會以直欄方式排列其子元素。display: "flex" 為橫列,除非設定了 flexDirection,這與 CSS 及 flex class 相同。flexShrink 預設為 0。
• 實體邊與邏輯邊。 left、right、marginLeft、paddingRight、borderLeftWidth、borderTopLeftRadius 和 textAlign: "left" 在由右至左的版面中仍保持其所屬的邊。start 與 end 鍵(marginStart、paddingEnd、start、end、borderStartWidth 等)、borderTopStartRadius 系列及 textAlign: "start" | "end" 則跟隨方向:inline start 在由左至右的版面中為左邊,在由右至左的版面中為右邊。
• 邊框顏色。 已設定寬度但未設定顏色的邊框或 outline,會以文字顏色繪製(即 CSS 的 currentColor)。
• Transform。 translate、rotate 和 scale 是各自獨立的屬性,而 transform 接受 CSS 的函式字串,或由多個步驟組成的清單,其數量可以是動畫值。它們按以下順序組合:translate、rotate、scale,然後是 transform。

#值的類型

採用 CSS 語法的字串(boxShadow、textShadow、backgroundImage、filter、gridTemplateColumns 等)接受以下單位的長度:px 及純數字(兩者皆為點)、pt(如 CSS 般為一點的 4/3),或 rem(16 點)。

#LayoutStyle

版面配置在 Rust 中計算(flexbox 和 CSS grid)。未設定 display 的 view 是一個 flex 容器,其子元素以直欄方式堆疊;display: "flex" 會令其成為橫列,除非設定了 flexDirection,這與 CSS 相同。元素的預設值為 flexShrink: 0、alignContent: "flex-start"(grid:CSS 的 "normal")、alignItems: "stretch",且沒有自動最小尺寸。請參閱版面配置。

#Display 與 position

#Flexbox

#Grid

設定 display: "grid" 即可以 CSS grid 排列子元素。Track 清單使用 CSS 語法。

view()
    .grid()
    .grid_template_columns("repeat(3, 1fr)")
    .gap_2()
    .child(view().col_span(2).h(px(60.0)).bg(rgb(0xc7d2fe)))
    .child(view().h(px(60.0)).bg(rgb(0xa5b4fc)))

<View style={{ display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: 8 }}>
  <View style={{ gridColumn: "span 2", height: 60, backgroundColor: "#c7d2fe" }} />
  <View style={{ height: 60, backgroundColor: "#a5b4fc" }} />
</View>

#Size

#Margin

Margin 接受 "auto"(吸收剩餘空間,與 flexbox 相同)及負值。實體鍵(除 marginStart / marginEnd 外)亦接受 EnvValue:marginBottom: "env(keyboard-inset-height)"(Rust 為 .mb_keyboard()、.mt_safe_area() 等)。

#Padding

實體鍵(除 paddingStart / paddingEnd 外)亦接受 EnvValue:paddingTop: "env(safe-area-inset-top)"、paddingBottom: "calc(env(safe-area-inset-bottom) + 16px)"(Rust 為 .pt_safe_area()、.pb_safe_area_plus(px(16.0))、.pb_keyboard() 等)。Padding 最小為 0。

#ViewStyle

由 view 繪製的所有內容。LayoutStyle 的所有鍵同樣適用。

#Background

view().h(px(120.0)).rounded(px(16.0)).bg_linear(deg(135.0)).gradient_from(rgb(0x6366f1)).gradient_to(rgb(0xec4899))

<View style={{ height: 120, borderRadius: 16, backgroundImage: "linear-gradient(135deg, #6366f1, #ec4899)" }} />

#邊框

若某一邊設定了寬度，但沒有任何地方設定其顏色，則以文字顏色繪製，即 CSS 的 currentColor：{ borderWidth: 1, color: "#2563eb" } 會繪製藍色邊框。外框線同樣採用文字顏色。

#圓角

#外框線

外框線繪製於邊框之外，不佔用佈局空間。

#陰影

視圖使用 CSS 的 boxShadow 投射陰影：支援多層、擴展（spread）及內陰影。過渡可為其加入動畫（transitionProperty: "boxShadow"）。

view().p_4().rounded(px(12.0)).bg(white()).shadow([
    BoxShadow { offset_y: px(1.0), blur: px(2.0), color: rgba(0x0000000f).into(), ..BoxShadow::default() },
    BoxShadow { offset_y: px(8.0), blur: px(24.0), spread: px(-4.0), color: rgba(0x0000001f).into(), ..BoxShadow::default() },
])

<View style={{ padding: 16, borderRadius: 12, backgroundColor: "#fff",
  boxShadow: "0 1px 2px rgb(0 0 0 / 0.06), 0 8px 24px -4px rgb(0 0 0 / 0.12)" }} />

#不透明度、可見性與溢出

#變形

變形與 CSS 相同：translate、rotate 和 scale 屬性以及 transform，按此順序組合。每項都是獨立的屬性，因此樣式的 scale 會取代 class 的 scale-* 並保留其 rotate-*，而樣式的 transform 會取代 class 的變形函數（rotate-x-*、skew-*）。

TransformStep 是只有一個鍵的物件，按列表的順序套用：

view().perspective(px(600.0)).child(view().rotate_y(deg(20.0)).scale(0.95))

<View style={{ transform: "perspective(600px) rotateY(20deg) scale(0.95)" }} />

動畫值可直接驅動 translate、rotate 和 scale，以及 transform 列表中的各個步驟：

const x = createAnimatedValue(0);
const angle = createAnimatedValue(0);

<View style={{ translate: [x, 0], rotate: angle }} />
<View style={{ transform: [{ perspective: 800 }, { rotateY: angle }] }} />

#濾鏡與混合

#過渡

當被設定過渡的屬性改變時（來自新樣式、class 或變體，例如 active:），平台會以原生方式為其加入動畫。動畫期間不會執行任何 JS。

view()
    .on_press(move || open.update(|o| *o = !*o))
    .h(move || px(if open.get() { 160.0 } else { 56.0 }))
    .opacity(move || if open.get() { 1.0 } else { 0.8 })
    .transition()
    .duration(200.0)

<View
  onPress={() => open.set(!open())}
  style={{ height: open() ? 160 : 56, opacity: open() ? 1 : 0.8,
    transitionProperty: "opacity, transform", transitionDuration: 200 }}
/>

#關鍵影格動畫

內置的關鍵影格動畫，以原生方式執行（Tailwind 的 animate-*）。

如需由數值、手勢或彈簧驅動的動畫，請改用 nsh 的動畫 API。

#指標與選取

#SVG 繪製

SVG 圖形的 CSS 繪製屬性，任何元素都可設定，其內部的元素會像在瀏覽器中一樣繼承這些屬性。 它們用於繪製 Rust 元件在 canvas 上繪製的內容。

#TextStyle

文字樣式適用於 <Text> 和 <Input>。它們也會像 CSS 一樣被繼承：設定在視圖上的文字屬性會傳遞給其內部的文字和輸入框，而巢狀的 <Text> span 會繼承其父文字。ViewStyle 的所有鍵同樣適用。請參閱文字。

#字體

#間距與對齊

#行數與溢出

#裝飾

#預留位置文字、游標與選取

placeholderColor 和 caretColor 屬於 InputStyle，即 <Input> 的樣式；selectionColor 屬於 TextStyle，因為可選取的文字也會用到它。

#文字陰影

text("Title").text_shadow([TextShadow {
    offset_y: px(1.0),
    radius: px(2.0),
    color: rgba(0x0000004d).into(),
    ..TextShadow::default()
}])

<Text style={{ textShadow: "0 1px 2px rgb(0 0 0 / 0.3)" }}>Title</Text>

#ImageStyle

ViewStyle 的所有鍵，另加：

objectFit 也適用於 <Video>；請參閱 image 和 video。

#看似樣式的 props

Android 的 material shadow 是平台 prop，與樣式分開設定：

#相關內容

• 樣式設定：style、class、繼承與優先順序。
• Tailwind 參考：所有支援的 utility 和 variant。
• 版面配置：flexbox 和 grid 的實際應用。
• view、text、image：這些樣式所適用的元素。

width、height 和 flexBasis 也接受 "min-content"、"max-content" 和 "fit-content"，由 Taffy 計算。