@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/lynx/layout/grid-layout.md

@@ -0,0 +1,408 @@
+# Grid 布局
+
+Lynx 支持 CSS Grid 的子集，适用于二维布局。
+
+## 支持的特性
+
+```css
+.container {
+  display: grid;
+
+  /* 定义列 */
+  grid-template-columns: 200px 1fr 2fr;
+  grid-template-columns: repeat(3, 1fr);
+  grid-template-columns: 100px repeat(2, 1fr);
+
+  /* 定义行 */
+  grid-template-rows: 100px auto;
+
+  /* 间距 */
+  gap: 10px;
+  row-gap: 10px;
+  column-gap: 10px;
+
+  /* 自动排列 */
+  grid-auto-flow: row | column | dense | row dense | column dense;
+}
+```
+
+## 常见布局
+
+### 三列等宽
+
+```css
+.grid-3 {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 16px;
+}
+```
+
+```jsx
+<view className="grid-3">
+  <text className="item">1</text>
+  <text className="item">2</text>
+  <text className="item">3</text>
+  <text className="item">4</text>
+  <text className="item">5</text>
+  <text className="item">6</text>
+</view>
+```
+
+### 侧边栏 + 主内容
+
+```css
+.layout {
+  display: grid;
+  grid-template-columns: 200px 1fr;
+  gap: 20px;
+}
+```
+
+```jsx
+<view className="layout">
+  <view className="sidebar">
+    <text>Sidebar</text>
+  </view>
+  <view className="main">
+    <text>Main Content</text>
+  </view>
+</view>
+```
+
+### 固定头部和底部
+
+```css
+.page {
+  display: grid;
+  grid-template-rows: 60px 1fr 60px;
+  height: 100vh;
+}
+
+.header {
+  /* 第一行 */
+}
+
+.content {
+  /* 中间 */
+}
+
+.footer {
+  /* 底部 */
+}
+```
+
+### 网格项定位
+
+```css
+.grid {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 10px;
+}
+
+/* 大图跨越 2x2 */
+.grid-item-large {
+  grid-column: span 2;
+  grid-row: span 2;
+}
+
+/* 横图跨越 2 列 */
+.grid-item-wide {
+  grid-column: span 2;
+}
+```
+
+```jsx
+<view className="grid">
+  <text className="grid-item-large">Large</text>
+  <text>Small 1</text>
+  <text>Small 2</text>
+  <text className="grid-item-wide">Wide</text>
+</view>
+```
+
+## 属性值参考
+
+### grid-template-columns / grid-template-rows
+
+定义网格的列和行轨道。
+
+```css
+.container {
+  /* 固定大小 */
+  grid-template-columns: 100px 200px 100px;
+
+  /* 比例分配 */
+  grid-template-columns: 1fr 2fr 1fr;
+
+  /* 重复模式 */
+  grid-template-columns: repeat(3, 1fr);
+  grid-template-columns: repeat(2, 100px 1fr);
+
+  /* 混合使用 */
+  grid-template-columns: 200px 1fr 1fr;
+}
+```
+
+### grid-auto-columns / grid-auto-rows
+
+定义隐式创建的网格轨道大小。
+
+```css
+.container {
+  grid-auto-columns: 100px;
+  grid-auto-rows: minmax(50px, auto);
+}
+```
+
+### grid-auto-flow
+
+控制自动布局算法。
+
+| 值             | 说明                       |
+| -------------- | -------------------------- |
+| `row`          | 按行填充（默认）           |
+| `column`       | 按列填充                   |
+| `dense`        | 紧凑填充（尽可能填充空洞） |
+| `row dense`    | 按行紧凑填充               |
+| `column dense` | 按列紧凑填充               |
+
+```css
+.container {
+  grid-auto-flow: dense; /* 填充网格中的所有空洞 */
+}
+```
+
+### grid-column-start / grid-column-end
+
+定义网格项的列起始和结束位置。
+
+```css
+.item {
+  grid-column-start: 1; /* 从第1列开始 */
+  grid-column-end: 3; /* 到第3列结束（跨越2列） */
+}
+
+/* 简写 */
+.item {
+  grid-column: 1 / 3;
+}
+```
+
+### grid-row-start / grid-row-end
+
+定义网格项的行起始和结束位置。
+
+```css
+.item {
+  grid-row-start: 1;
+  grid-row-end: 3; /* 跨越2行 */
+}
+
+/* 简写 */
+.item {
+  grid-row: 1 / 3;
+}
+```
+
+### grid-column-span / grid-row-span
+
+定义网格项跨越的列数或行数（Lynx 特有语法）。
+
+```css
+.item {
+  grid-column-span: 2; /* 跨越2列 */
+  grid-row-span: 2; /* 跨越2行 */
+}
+```
+
+> **注意**: Lynx **不支持** `grid-column: span 2` 简写语法。请使用 `grid-column-start: span 2` 或 `grid-column-span: 2`。
+
+### justify-items
+
+定义网格项在单元格内的水平对齐方式（容器属性）。
+
+| 值        | 说明             |
+| --------- | ---------------- |
+| `stretch` | 拉伸填满（默认） |
+| `start`   | 左对齐           |
+| `center`  | 居中对齐         |
+| `end`     | 右对齐           |
+
+```css
+.container {
+  justify-items: center; /* 所有网格项水平居中 */
+}
+```
+
+### justify-self
+
+定义单个网格项在单元格内的水平对齐方式。
+
+| 值        | 说明                 |
+| --------- | -------------------- |
+| `auto`    | 继承自父元素（默认） |
+| `stretch` | 拉伸填满             |
+| `start`   | 左对齐               |
+| `center`  | 居中对齐             |
+| `end`     | 右对齐               |
+
+```css
+.special-item {
+  justify-self: end; /* 此项目右对齐 */
+}
+```
+
+### align-items
+
+定义网格项在单元格内的垂直对齐方式（容器属性）。
+
+| 值           | 说明                   |
+| ------------ | ---------------------- |
+| `stretch`    | 拉伸填满（默认）       |
+| `flex-start` | 顶部对齐               |
+| `center`     | 垂直居中对齐           |
+| `flex-end`   | 底部对齐               |
+| `baseline`   | 基线对齐               |
+
+```css
+.container {
+  align-items: center; /* 所有网格项垂直居中 */
+}
+```
+
+> **注意**: Lynx 使用 Flexbox 的 align 值（`flex-start`/`flex-end`）而非 Web Grid 的 `start`/`end`。
+
+### align-self
+
+定义单个网格项在单元格内的垂直对齐方式。
+
+| 值           | 说明                   |
+| ------------ | ---------------------- |
+| `auto`       | 继承自父元素（默认）   |
+| `stretch`    | 拉伸填满               |
+| `flex-start` | 顶部对齐               |
+| `center`     | 垂直居中对齐           |
+| `flex-end`   | 底部对齐               |
+| `baseline`   | 基线对齐               |
+
+```css
+.special-item {
+  align-self: center; /* 此项目垂直居中 */
+}
+```
+
+### gap / row-gap / column-gap
+
+定义网格轨道之间的间距。
+
+```css
+.container {
+  gap: 16px; /* 行列间距都是16px */
+  row-gap: 8px; /* 行间距8px */
+  column-gap: 12px; /* 列间距12px */
+}
+```
+
+## 限制
+
+以下特性**不支持**：
+
+- ❌ 命名网格线: `grid-template-columns: [start] 1fr [end]`
+- ❌ grid-column 简写: `grid-column: 1 / 3` 或 `grid-column: span 2`
+- ❌ grid-row 简写: `grid-row: 1 / 3` 或 `grid-row: span 2`
+- ❌ grid-area 简写: `grid-area: 1 / 1 / 2 / 3`
+- ❌ subgrid
+
+⚠️ **部分支持**：
+
+- `minmax()`: 支持基本用法，但复杂场景下行为可能与 Web 不同
+  ```css
+  /* ✅ 基本支持 */
+  grid-template-columns: minmax(100px, 1fr) 2fr;
+  grid-auto-rows: minmax(50px, auto);
+
+  /* ⚠️ 谨慎使用 - 可能与 Web 行为不一致 */
+  grid-template-columns: minmax(min-content, max-content) 1fr;
+  ```
+
+## 从 Table 布局迁移
+
+Lynx **完全不支持** `display: table*` 及相关属性（`border-spacing`、`border-collapse`、`table-layout` 等）。Grid 布局是 Table 的最佳替代方案。
+
+### 简单表格 → Grid
+
+**Web:**
+```html
+<table>
+  <tr><td>A</td><td>B</td><td>C</td></tr>
+  <tr><td>D</td><td>E</td><td>F</td></tr>
+</table>
+```
+```css
+table { border-spacing: 2px; }
+td { border: 1px solid; width: 50px; height: 30px; }
+```
+
+**Lynx:**
+```jsx
+<view className="grid-table">
+  <view className="cell"><text>A</text></view>
+  <view className="cell"><text>B</text></view>
+  <view className="cell"><text>C</text></view>
+  <view className="cell"><text>D</text></view>
+  <view className="cell"><text>E</text></view>
+  <view className="cell"><text>F</text></view>
+</view>
+```
+```css
+.grid-table {
+  display: grid;
+  grid-template-columns: repeat(3, 50px);
+  gap: 2px;  /* 替代 border-spacing */
+}
+.cell {
+  border: 1px solid;
+  height: 30px;
+}
+```
+
+### 关键映射
+
+| Table 特性 | Grid 替代 |
+|-----------|----------|
+| `<table>` | `display: grid` 容器 |
+| `<tr>` | 自动换行（由 `grid-template-columns` 控制） |
+| `<td>` | 子 `<view>` 元素 |
+| `border-spacing` | `gap` |
+| `border-collapse` | 移除子元素 border，改用容器 gap + 背景色模拟 |
+| 固定列宽 | `grid-template-columns: repeat(N, width)` |
+
+### 何时不能迁移
+
+如果 Web 中的核心语义**依赖 table 特性本身**（如 `display: table-cell` 的垂直对齐行为、table 的自动列宽分配算法），则该布局无法在 Lynx 中准确还原。
+
+## 响应式网格
+
+```css
+/* 注意：Lynx 不支持 @media，请使用视口单位或 JavaScript 动态调整 */
+
+/* 移动端/默认：1列 */
+.grid {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 16px;
+}
+
+/* 响应式：使用 flex-wrap 或 JavaScript 动态调整列数 */
+.responsive-grid {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 16px;
+}
+
+.responsive-grid > .item {
+  flex: 1 1 40vw; /* 根据视口宽度自动调整 */
+}
+```