格線
固定欄數:4 欄(手機 2 欄)
自動填滿:每欄至少 140px,放得下幾欄就排幾欄
用法
章節連結:用法格線把同一種內容排成整齊的幾欄,例如一排文章卡片、一組書籍封面或幾個重點數字。它有兩種排法:「固定欄數」由你決定桌機排幾欄,螢幕變窄到平板以下時自動改成比較少的欄數(預設一欄);「自動填滿」只設定每一欄最少要多寬,畫面寬就多排幾欄、窄就少排幾欄,適合數量不固定的內容。格線本身看不見,也不限制內容的最大寬度,那是「版心容器」的工作,所以格線通常放在版心容器裡面。
組成
章節連結:組成| 部位 | 說明 |
|---|---|
| 格線容器 | 佔滿它所在位置的整個寬度,把裡面的東西排成欄和列。 |
| 欄 | 固定欄數時是幾欄(桌機預設 12 欄,平板以下另外設定,預設 1 欄);自動填滿時由每欄的最小寬度和畫面寬度決定。 |
| 格子 | 放進格線的每一個項目佔一格,依放進去的順序,從左到右、從上到下排。 |
| 間距 | 格子之間的距離,從間距刻度選(例如 16、24),欄和列之間一樣寬。 |
| 對齊 | 同一列的格子預設拉成一樣高;也可以改成靠上、置中或靠下。 |
該做與不該做
章節連結:該做與不該做| 類型 | 說明 |
|---|---|
| 建議 | 每一格放同一種東西(例如都是文章卡片),讀者比較容易一格一格比較和瀏覽。 |
| 建議 | 內容的數量會變動時(例如最新消息),用「自動填滿」並設定每欄的最小寬度,不必為每種螢幕另外設計。 |
| 建議 | 設計時也畫出手機版:固定欄數在平板以下預設會變成一欄,小的項目(例如書籍封面)可以改成兩欄。 |
| 建議 | 格子之間的間距從間距刻度選,同一個網站的格線用一樣的間距。 |
| 避免 | 不要用格線把有先後順序的內容排成多欄,又期待讀者由上往下讀:格線是從左到右、一列一列排的。 |
| 避免 | 不要在手機上排太多欄;欄太窄時文字會一直斷行,圖片也會太小。 |
在目前主題下的樣子
章節連結:在目前主題下的樣子目前顯示:DefaultGreen Natural(示意)。在頁首的「主題」可以切換。 查看所有主題
- 預設變體: 用元件本身的預設變體。
- 和預設主題不同的地方: 沒有。這就是預設主題,其他主題沒有特別指定的地方都沿用它。
- 預設變體: 主題不決定預設變體:用元件本身的預設變體(各網站自己的預設變體要等網站設定檔,還沒有實作)。
- 和預設主題不同的地方: 沒有。這個元件本身沒有顏色,主題不會改變它。
格線的欄數和間距目前所有主題都一樣;上方預覽裡的色塊會跟著頁首的「主題」和「色彩模式」一起變。
給工程師
章節連結:給工程師以下是給工程師的安裝與 API 說明,美編(設計)、網站的編輯和致遠(廠商)可以略過。
Storybook(給工程師逐一檢查元件狀態的工具網站,在本機用 pnpm run heroui:storybook 開啟)目前只收錄 HeroUI 的元件,還沒有 <tc-grid> 的頁面;這一段的範例和 API 表就是它的說明。
<tc-grid> 是 layout 原語:以單一預設插槽包裹直接子元素,套用 CSS Grid。預設為固定欄數模式(columns,預設 12),於平板斷點(768px)以下收合為 mobile-columns(預設 1)欄以利閱讀。設定 min-col-width 後改用 auto-fit/minmax 自動填滿模式(此時 columns 不生效)。下方為可互動的真實元件:
自動填滿模式(auto-fit / minmax)
章節連結:自動填滿模式(auto-fit / minmax)設定 min-col-width(CSS 長度,如 240px)後,版面以 repeat(auto-fit, minmax(min-col-width, 1fr)) 自動依容器寬度增減欄數,無需斷點。此模式優先於 columns:
間距(gap)
章節連結:間距(gap)gap 接受 space token 名稱(如 "16"、"24",對應 --tc-space-*)或任意 CSS 長度(如 2rem)。未設定時採用 --tc-grid-gap-default(預設 --tc-space-16)。
行動裝置欄數(mobile-columns)
章節連結:行動裝置欄數(mobile-columns)固定欄數模式下,平板斷點(768px)以下會收合為 mobile-columns 欄(預設 1)。例如桌機 4 欄、行動 2 欄:
純 HTML
章節連結:純 HTML<link rel="stylesheet" href="@tzuchi/tokens/tokens.css" /><script type="module" src="@tzuchi/components/cdn"></script>
<!-- 固定 3 欄、行動 1 欄 --><tc-grid columns="3" gap="24"> <div>項目 1</div> <div>項目 2</div> <div>項目 3</div></tc-grid>
<!-- 自動填滿:每欄至少 240px --><tc-grid min-col-width="240px" gap="16"> <div>項目 A</div> <div>項目 B</div></tc-grid>React
章節連結:Reactimport { TcGrid } from '@tzuchi/react';
<TcGrid columns={3} gap="24" mobileColumns={1}> <div>項目 1</div> <div>項目 2</div></TcGrid>;API
章節連結:API下表自 Custom Elements Manifest 自動產生:
| Attribute | Type | Default | Description |
|---|---|---|---|
columns | number | 12 | 桌機固定欄數。設定 `min-col-width` 後此值不生效。 |
mobile-columns | number | 1 | 平板斷點(768px)以下使用的固定欄數(僅固定欄數模式生效)。 |
min-col-width | string | '' | 每欄最小寬度(CSS 長度,如 `"240px"`)。設定後改用 `repeat(auto-fit, minmax(min-col-width, 1fr))` 響應式自動填滿模式,並覆寫固定欄數。 |
gap | string | '' | 欄列間距:space token 名稱(如 `"16"`)或任意 CSS 長度。預設對應 `var(--tc-space-16)`。 |
align | 'stretch' | 'start' | 'center' | 'end' | undefined | — | 各列項目的區塊方向對齊。未設定時 grid 預設為 `stretch`。 |
無障礙(Accessibility)
章節連結:無障礙(Accessibility)tc-grid為純視覺版面容器,不引入 ARIA 角色,子元素的語意與順序維持原樣(DOM 順序即視覺順序)。- 固定欄數模式於小螢幕自動收合為
mobile-columns,避免欄位過窄影響可讀性。