@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/linear-layout.md

@@ -0,0 +1,355 @@
+# Linear 布局（默认布局）
+
+Linear 是 Lynx 的默认布局系统，类似于 Android 的 LinearLayout。当你不设置 `display` 属性时，默认使用 Linear 布局。
+
+## 基本用法
+
+```jsx
+// 默认情况下，子元素垂直排列
+<view className="container">
+  <text>Item 1</text>
+  <text>Item 2</text>
+  <text>Item 3</text>
+</view>
+```
+
+```css
+.container {
+  /* 无需设置 display，默认就是 linear */
+  padding: 16px;
+}
+```
+
+## 方向设置
+
+```css
+.row {
+  display: linear;
+  linear-orientation: horizontal; /* 或 row */
+}
+```
+
+**linear-orientation 所有可选值**:
+
+- `horizontal` / `row` - 水平排列
+- `vertical` / `column` - 垂直排列（默认）
+- `horizontal-reverse` / `row-reverse` - 水平反向排列
+- `vertical-reverse` / `column-reverse` - 垂直反向排列
+
+```jsx
+<view className="row">
+  <text>Left</text>
+  <text>Center</text>
+  <text>Right</text>
+</view>
+```
+
+## 权重分配
+
+使用 `linear-weight` 分配剩余空间：
+
+```css
+.container {
+  display: linear;
+  linear-orientation: horizontal;
+}
+
+.sidebar {
+  width: 200px; /* 固定宽度 */
+}
+
+.main {
+  linear-weight: 1; /* 占据剩余所有空间 */
+}
+
+.aside {
+  linear-weight: 0.5; /* 占据 1/3 剩余空间 */
+}
+```
+
+```jsx
+<view className="container">
+  <view className="sidebar">
+    <text>Sidebar</text>
+  </view>
+  <view className="main">
+    <text>Main Content</text>
+  </view>
+  <view className="aside">
+    <text>Aside</text>
+  </view>
+</view>
+```
+
+## 对齐方式
+
+```css
+/* 子元素整体居中 */
+.center-container {
+  display: linear;
+  linear-gravity: center;
+}
+
+/* 水平居中 */
+.horizontal-center {
+  display: linear;
+  linear-gravity: center-horizontal;
+}
+
+/* 垂直居中 */
+.vertical-center {
+  display: linear;
+  linear-gravity: center-vertical;
+}
+
+/* 子元素拉伸填满 */
+.stretch-container {
+  display: linear;
+  linear-orientation: horizontal;
+}
+
+.stretch-container .item {
+  linear-layout-gravity: stretch;
+}
+```
+
+## 属性值参考
+
+### linear-orientation
+
+控制布局方向：
+
+| 值                                    | 说明             |
+| ------------------------------------- | ---------------- |
+| `horizontal` / `row`                  | 水平排列         |
+| `vertical` / `column`                 | 垂直排列（默认） |
+| `horizontal-reverse` / `row-reverse`  | 水平反向         |
+| `vertical-reverse` / `column-reverse` | 垂直反向         |
+
+### linear-direction
+
+**Lynx 2.2+** 替代 `linear-orientation` 的属性，语义更清晰：
+
+| 值               | 说明             |
+| ---------------- | ---------------- |
+| `row`            | 水平排列         |
+| `column`         | 垂直排列（默认） |
+| `row-reverse`    | 水平反向         |
+| `column-reverse` | 垂直反向         |
+
+### linear-gravity（容器属性）
+
+控制子元素在主轴上的对齐：
+
+| 值                  | 说明                   |
+| ------------------- | ---------------------- |
+| `none`              | 无特殊对齐             |
+| `top`               | 顶部对齐（垂直布局时） |
+| `bottom`            | 底部对齐（垂直布局时） |
+| `left`              | 左侧对齐（水平布局时） |
+| `right`             | 右侧对齐（水平布局时） |
+| `center-vertical`   | 垂直居中               |
+| `center-horizontal` | 水平居中               |
+| `center`            | 主轴居中               |
+| `start`             | 主轴起点对齐           |
+| `end`               | 主轴终点对齐           |
+| `space-between`     | 两端对齐，中间等分     |
+
+> **注意**: `top`/`bottom`/`left`/`right` 是物理方向值，会根据 `linear-orientation` 自动映射到逻辑方向。
+
+### linear-layout-gravity（子元素属性）
+
+控制单个子元素在交叉轴上的对齐：
+
+| 值                  | 说明                  |
+| ------------------- | --------------------- |
+| `none`              | 无特殊对齐            |
+| `top`               | 顶部对齐              |
+| `bottom`            | 底部对齐              |
+| `left`              | 左侧对齐              |
+| `right`             | 右侧对齐              |
+| `center-vertical`   | 垂直居中              |
+| `center-horizontal` | 水平居中              |
+| `center`            | 交叉轴居中            |
+| `fill-vertical`     | 垂直方向填充          |
+| `fill-horizontal`   | 水平方向填充          |
+| `stretch`           | 拉伸填满（Lynx 1.6+） |
+| `start`             | 起点对齐（Lynx 1.6+） |
+| `end`               | 终点对齐（Lynx 1.6+） |
+
+> **注意**: `stretch`、`fill-vertical`、`fill-horizontal` 是不同的值。`stretch` 是逻辑方向填充，根据布局方向自动决定。
+
+### linear-cross-gravity（容器属性）
+
+控制所有子元素在交叉轴上的默认对齐（Lynx 1.6+）：
+
+| 值        | 说明       |
+| --------- | ---------- |
+| `none`    | 无特殊对齐 |
+| `start`   | 起点对齐   |
+| `end`     | 终点对齐   |
+| `center`  | 居中对齐   |
+| `stretch` | 拉伸填满   |
+
+### linear-weight
+
+数字类型，指定子元素占据剩余空间的比例。
+
+```css
+.item {
+  linear-weight: 1; /* 占据一份剩余空间 */
+}
+```
+
+### linear-weight-sum
+
+**高级属性** 设置权重计算的总和。默认自动计算所有子元素 weight 之和。
+
+```css
+.container {
+  linear-weight-sum: 100; /* 设置总权重为100 */
+}
+
+.item1 {
+  linear-weight: 30; /* 占据 30% */
+}
+
+.item2 {
+  linear-weight: 70; /* 占据 70% */
+}
+```
+
+## Linear vs Flex 对比
+
+| 特性       | Linear           | Flex               |
+| ---------- | ---------------- | ------------------ |
+| 性能       | 更快（简单场景） | 稍慢               |
+| 换行       | 不支持           | 支持 wrap          |
+| 多行对齐   | 不支持           | 支持 align-content |
+| 子元素排序 | 不支持           | 支持 order         |
+| 适用场景   | 简单列表         | 复杂弹性布局       |
+
+**建议**: 简单列表用 Linear，复杂布局用 Flex。
+
+## 与 Web Block Layout 的差异（迁移要点）
+
+**这是从 Web 迁移到 Lynx 时最常见的陷阱之一**。
+
+### 默认布局差异
+
+| 特性                 | Web Block Layout                           | Lynx Linear Layout（默认）                     |
+| -------------------- | ------------------------------------------ | ---------------------------------------------- |
+| 默认 display         | `block`（flow layout）                     | `linear`（类似 flex column）                   |
+| 子元素宽度           | 默认 `width: 100%`，自动填满父元素         | 默认由内容决定，**不会自动填满**               |
+| 子元素高度           | 由内容决定                                 | 由内容决定                                     |
+| 嵌套元素尺寸         | 继承父元素尺寸（逐层填满）                 | **不会自动继承**，需要显式设置                 |
+| 空元素尺寸           | 可能为 0（取决于 overflow 和 min-height）  | **通常为 0**（无内容且无显式宽高时）           |
+
+### 子元素尺寸问题示例
+
+```css
+/* Web: 子元素自动填满父元素 */
+.parent { width: 200px; }
+.child { /* 默认 width: 100%，实际 200px */ }
+
+/* Lynx: 子元素不会自动填满 */
+.parent { width: 200px; display: linear; }
+.child { /* 默认宽度由内容决定，可能远小于 200px */ }
+
+/* Lynx 修复方案 1：显式设置 width */
+.child { width: 100%; }
+
+/* Lynx 修复方案 2：使用 linear-layout-gravity */
+.child { linear-layout-gravity: stretch; }
+
+/* Lynx 修复方案 3：父元素设置 linear-cross-gravity */
+.parent { linear-cross-gravity: stretch; }
+```
+
+### 嵌套元素尺寸问题示例
+
+```css
+/* Web: 嵌套 div 自动填满 */
+.grandparent { width: 100px; height: 100px; }
+.parent { /* 自动 100x100 */ }
+.child { /* 自动 100x100 */ }
+
+/* Lynx: 需要每层都显式设置 */
+.grandparent { width: 100px; height: 100px; display: linear; }
+.parent { width: 100%; height: 100%; }
+.child { width: 100%; height: 100%; }
+
+/* 或者使用 stretch */
+.grandparent {
+  width: 100px;
+  height: 100px;
+  display: linear;
+  linear-cross-gravity: stretch;
+}
+```
+
+## 常见布局模式
+
+### 垂直列表
+
+```css
+.list {
+  display: linear;
+  /* 默认就是垂直 */
+  gap: 12px;
+  padding: 16px;
+}
+
+.list-item {
+  padding: 12px;
+  background-color: #f5f5f5;
+  border-radius: 8px;
+}
+```
+
+### 水平按钮组
+
+```css
+.button-group {
+  display: linear;
+  linear-orientation: horizontal;
+  gap: 8px;
+  padding: 16px;
+}
+
+.button-group .button {
+  linear-weight: 1; /* 等分宽度 */
+}
+```
+
+### 侧边栏 + 主内容
+
+```css
+.layout {
+  display: linear;
+  linear-orientation: horizontal;
+  height: 100vh;
+}
+
+.sidebar {
+  width: 250px;
+}
+
+.main {
+  linear-weight: 1; /* 占据剩余空间 */
+}
+```
+
+### 使用 linear-cross-gravity 的列表
+
+```css
+.list {
+  display: linear;
+  linear-orientation: horizontal;
+  linear-cross-gravity: stretch; /* 所有子元素等高 */
+}
+
+.list-item {
+  /* 子元素会自动拉伸到容器高度 */
+}
+```

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

@@ -0,0 +1,189 @@
+# Relative 布局
+
+Lynx 特有的布局系统，类似于 Android 的 RelativeLayout。适用于需要相对定位的复杂布局。
+
+## 核心概念
+
+每个元素通过 `relative-id` 标识，然后引用其他元素的 ID 进行定位。
+
+## 基本用法
+
+```css
+.container {
+  display: relative;
+  width: 100%;
+  height: 400px;
+}
+
+/* 左上角头像 */
+.avatar {
+  relative-id: 1;
+  relative-align-left: parent;
+  relative-align-top: parent;
+  width: 80px;
+  height: 80px;
+}
+
+/* 用户名在头像右边 */
+.username {
+  relative-id: 2;
+  relative-right-of: 1; /* 在 ID 1 的右边 */
+  relative-align-top: 1; /* 顶部与 ID 1 对齐 */
+}
+
+/* 描述在用户名下方 */
+.description {
+  relative-id: 3;
+  relative-right-of: 1;
+  relative-bottom-of: 2; /* 在 ID 2 的下方 */
+}
+
+/* 关闭按钮右上角 */
+.close {
+  relative-id: 4;
+  relative-align-right: parent;
+  relative-align-top: parent;
+}
+```
+
+```jsx
+<view className="container">
+  <image className="avatar" src="avatar.png" />
+  <text className="username">Username</text>
+  <text className="description">Description here</text>
+  <text className="close">×</text>
+</view>
+```
+
+## 对齐方式
+
+```css
+/* 水平居中 */
+.center-horizontal {
+  relative-id: 1;
+  relative-center: horizontal;
+}
+
+/* 垂直居中 */
+.center-vertical {
+  relative-id: 1;
+  relative-center: vertical;
+}
+
+/* 完全居中 */
+.center-both {
+  relative-id: 1;
+  relative-center: both;
+}
+```
+
+## 相对定位属性
+
+| 属性                    | 说明           | 值                               |
+| ----------------------- | -------------- | -------------------------------- |
+| `relative-id`           | 元素唯一标识   | 数字                             |
+| `relative-align-top`    | 顶部对齐       | parent 或 其他元素 ID            |
+| `relative-align-bottom` | 底部对齐       | parent 或 其他元素 ID            |
+| `relative-align-left`   | 左对齐         | parent 或 其他元素 ID            |
+| `relative-align-right`  | 右对齐         | parent 或 其他元素 ID            |
+| `relative-top-of`       | 位于某元素上方 | 其他元素 ID                      |
+| `relative-bottom-of`    | 位于某元素下方 | 其他元素 ID                      |
+| `relative-left-of`      | 位于某元素左侧 | 其他元素 ID                      |
+| `relative-right-of`     | 位于某元素右侧 | 其他元素 ID                      |
+| `relative-center`       | 居中           | none, vertical, horizontal, both |
+
+### relative-center 可选值
+
+| 值           | 说明             |
+| ------------ | ---------------- |
+| `none`       | 不居中（默认）   |
+| `vertical`   | 垂直居中         |
+| `horizontal` | 水平居中         |
+| `both`       | 水平和垂直都居中 |
+
+## 适用场景
+
+- 卡片式布局（头像+文字+按钮）
+- 聊天界面
+- 复杂的表单项
+- 任何需要"相对某个元素定位"的场景
+
+## 注意事项
+
+1. 每个 `relative-id` 在同一父容器内必须唯一
+2. 循环引用会导致布局错误（A 依赖 B，B 又依赖 A）
+3. 如果不设置任何相对属性，元素会堆叠在左上角
+
+## 高级用法
+
+### RTL 支持（Lynx 2.0+）
+
+对于需要适配从右到左（RTL）语言（如阿拉伯语、希伯来语）的布局，可以使用逻辑方向属性：
+
+| 物理方向               | 逻辑方向（推荐）              |
+| ---------------------- | ----------------------------- |
+| `relative-align-left`  | `relative-align-inline-start` |
+| `relative-align-right` | `relative-align-inline-end`   |
+| `relative-left-of`     | `relative-inline-start-of`    |
+| `relative-right-of`    | `relative-inline-end-of`      |
+
+```css
+/* 推荐：使用逻辑方向，自动适配 RTL */
+.card {
+  display: relative;
+}
+
+.avatar {
+  relative-id: 1;
+  relative-align-inline-start: parent; /* LTR时左对齐，RTL时右对齐 */
+  relative-align-top: parent;
+}
+
+.username {
+  relative-id: 2;
+  relative-inline-start-of: 1; /* LTR时在左边，RTL时在右边 */
+  relative-align-top: 1;
+}
+```
+
+### relative-layout-once（内部属性）
+
+```css
+.container {
+  relative-layout-once: true; /* 默认值，优化性能 */
+}
+```
+
+> **注意**: 这是内部优化属性，通常不需要手动设置。
+
+## 实际案例：聊天消息
+
+```css
+.chat-message {
+  display: relative;
+  padding: 12px;
+}
+
+.avatar {
+  relative-id: 1;
+  relative-align-left: parent;
+  relative-align-top: parent;
+  width: 40px;
+  height: 40px;
+}
+
+.username {
+  relative-id: 2;
+  relative-right-of: 1;
+  relative-top-of: 3;
+  margin-left: 8px;
+}
+
+.message-bubble {
+  relative-id: 3;
+  relative-right-of: 1;
+  relative-bottom-of: 2;
+  margin-left: 8px;
+  margin-top: 4px;
+}
+```