> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# 样式与布局差异

豆包应用插件使用 Lynx 作为 UI 渲染器，负责界面的布局与绘制。开发者可以继续使用熟悉的 CSS 写法；当涉及布局模型、选择器、尺寸单位和动画等能力差异时，以豆包应用插件当前支持的 CSS 能力为准。

本章按开发行为说明布局、尺寸与盒模型、定位、选择器、文本和动画的主要差异，并提供可直接采用的写法。需要确认某个 CSS 属性或取值时，统一查询 [CSS 能力清单](/apps-plugin/docs/client-framework/css-capabilities.md)。

> **注意**
>
> - 本章说明常用能力、主要差异和推荐写法。完整支持范围请查询 [CSS 能力清单](/apps-plugin/docs/client-framework/css-capabilities.md)；未列入清单的属性或取值，当前不属于支持范围，不能默认与 Web 一致；
> - 关键容器应显式声明布局、尺寸和盒模型，不依赖浏览器默认样式；
> - 页面最终由原生视图渲染，需要在真实目标端检查布局、文本和动画效果；

## 样式方案选择

开发时优先从当前提供的布局、元素和样式能力中选择实现方案。下表按常见需求给出可以直接采用的写法；最后一列用于从 Web 代码迁移时识别需要替换的语法。

| 开发需求         | 当前推荐能力                                                                | 从 Web 迁移时                             |
| ------------ | --------------------------------------------------------------------- | ------------------------------------- |
| 普通容器的行列布局    | 使用 Flex 或 Linear                                                      | 将 `display: block` 改为明确的布局模型          |
| 文本与其它内容的行内排列 | 文本使用 `text`，其它结构使用 Flex 或 Linear                                      | 替换 `display: inline` / `inline-block` |
| 表格或二维结构      | 使用 Grid 或 Flex                                                        | 替换 `display: table*`                  |
| 横向排列与左右对齐    | 使用 Flex 的方向、对齐和间距能力                                                   | 替换 `float` / `clear`                  |
| 普通定位与层叠      | 默认使用 `position: relative`；覆盖布局使用 `absolute` / `fixed`，滚动吸附使用 `sticky` | 不依赖 `position: static`                |
| 装饰文字或图形      | 增加实际的 `text`、`view`、`image` 等 SDK 组件                                  | 不使用 `::before` / `::after` 生成内容       |
| 复用或组合选择规则    | 使用简单类选择器，必要时拆分选择器                                                     | 替换 `:is()`、`:where()`、`:has()`        |
| 内容相关的尺寸约束    | 使用明确尺寸、Flex 约束或其它可计算的布局条件                                             | 不使用 `min-content`                     |
| 长度与相对尺寸      | 使用 `px`、`rpx`、`rem`、`em`、`%`、`vw` 或 `vh`                              | 替换 `ch`、`ex` 和物理单位                    |
| 缩放与三维旋转      | 使用 `scale()`、`rotateX/Y/Z()` 或 `matrix3d()`                           | 替换 `scale3d()` / `rotate3d()`         |

## 布局能力

### 选择布局模型

| 布局模型   | 适合场景            | 常用能力                                                                             |
| ------ | --------------- | -------------------------------------------------------------------------------- |
| Flex   | 行列布局、弹性分配、对齐和换行 | `flex-direction`、`flex-grow`、`flex-shrink`、`justify-content`、`align-items`、`gap` |
| Linear | 方向固定的顺序排列       | `linear-direction`、`linear-weight`                                               |
| Grid   | 二维网格结构          | `grid-template-*`、`grid-column`、`grid-row`、`grid-*-start/end`、`gap`              |

选择布局时，可以按结构复杂度判断：

- 只有固定方向的顺序排列时，使用 Linear；
- 需要弹性分配、对齐或换行时，使用 Flex；
- 同时存在行、列关系时，使用 Grid；

### Grid 布局

Grid 使用显式轨道以及 `grid-column`、`grid-row` 或对应的长写定位属性。跨越多个轨道时，使用标准的 `span <number>` 取值，不使用非标准的 `grid-column-span`、`grid-row-span`：

```scss
.grid {
  display: grid;
  grid-template-columns: repeat(2, 1fr);
  gap: 12px;
}

.grid-item--wide {
  grid-column: 1 / 3;
}
```

命名网格线和 `subgrid` 不属于当前能力。

### 关键容器与 Flex 示例

页面根节点和关键容器应显式设置布局方式：

```scss
.page {
  display: flex;
  flex-direction: column;
  width: 100%;
  height: 100%;
  box-sizing: border-box;
}

.content {
  display: flex;
  flex-direction: column;
  min-height: 0;
  flex-grow: 1;
}
```

豆包应用插件的默认布局不遵循 Web 的 block flow。即使节点未声明 `display` 时结果符合预期，也应为关键容器显式选择布局模型。

#### 示例：可收缩的商品卡片

下面的卡片使用 Flex 分配横向空间：缩略图和操作按钮保持固定宽度，中间文本区域占用剩余空间，并在内容过长时显示省略号。

```tsx
function ProductCard() {
  return (
    <view className="product-card">
      <view className="product-card__thumb" />
      <view className="product-card__body">
        <text className="product-card__title">便携咖啡杯</text>
        <text className="product-card__description">双层隔热，适合通勤携带</text>
      </view>
      <button className="product-card__action" text="查看" />
    </view>
  );
}
```

```scss
.product-card {
  display: flex;
  flex-direction: row;
  align-items: center;
  gap: 12px;
  width: 100%;
  padding: 12px;
  box-sizing: border-box;
}

.product-card__thumb {
  width: 48px;
  height: 48px;
  flex-shrink: 0;
  border-radius: 8px;
  background-color: #f2f3f5;
}

.product-card__body {
  display: flex;
  flex-direction: column;
  gap: 4px;
  min-width: 0;
  flex-grow: 1;
}

.product-card__title,
.product-card__description {
  overflow: hidden;
  white-space: nowrap;
  text-overflow: ellipsis;
}

.product-card__action {
  flex-shrink: 0;
}
```

`min-width: 0` 允许文本区域继续收缩；两个固定区域通过 `flex-shrink: 0` 避免被压缩。

### `display` 能力

Lynx 的 `display` 只决定元素内部采用哪种布局模型，也就是如何布局子元素；它不决定元素对外表现为块级元素还是行级元素。

Lynx 不采用 Web 的 Flow（流式布局），不支持 `display: block` 和 `display: inline`。除 `<text>` 组件内的元素外，Lynx 元素均按块级元素处理。需要布局子元素时，使用 `display` 选择 Flex、Linear 或 Grid；需要隐藏节点时使用 `display: none`。具体支持值见 [CSS 能力清单](/apps-plugin/docs/client-framework/css-capabilities.md#显示定位与滚动)。

多层组件嵌套时，真正参与布局的是组件返回的 Lynx 元素。空容器在主轴上没有内容、尺寸或权重时，主轴尺寸可能为 0。

### Flex 尺寸分配

`flex-shrink` 只有在主轴空间不足时才会生效。如果父容器没有确定尺寸或外部约束，容器会随内容扩展，不会产生需要收缩的负剩余空间。

需要保护文本、图片或固定区域时，显式设置收缩规则和尺寸下限：

```scss
.fixed-item {
  flex-shrink: 0;
  min-width: 120px;
}
```

Lynx 不会自动套用与 Web 完全相同的内容最小尺寸。需要让 Web 预览与 Lynx 一样允许内容收缩时，可以在 Web 侧按主轴设置 `min-width: 0` 或 `min-height: 0`：

```scss
.text-item {
  min-width: 0;
  overflow: hidden;
  white-space: nowrap;
  text-overflow: ellipsis;
}
```

## 尺寸与盒模型

不同单位对应不同计算基准：`%` 跟随父元素，`vw` / `vh` 跟随布局 viewport，`rem` / `em` 跟随字体基准，`rpx` 跟随设计宽度。一个组件内应先确定尺寸策略，避免无规则混用导致溢出、裁剪或意外换行。支持的单位和函数以 [CSS 能力清单](/apps-plugin/docs/client-framework/css-capabilities.md#单位与尺寸) 为准。

当前不支持使用 `@media` 切换样式。响应式布局优先使用 `%`、`vw` / `vh`、`rem`、`rpx` 和 Flex / Grid；确实需要根据运行环境切换结构时，在业务逻辑中获取对应信息并切换样式或节点结构。

### 百分比尺寸

百分比尺寸要求祖先具有可以解析的对应尺寸。如果祖先尺寸由内容撑开，而子元素尺寸又依赖祖先百分比，就会形成循环依赖，可能导致百分比不生效或空节点尺寸为 0。

```scss
/* outer 的高度依赖内容，middle 的高度又依赖 outer */
.outer {
  display: linear;
  height: auto;
}

.middle {
  height: 50%;
}
```

如果中间区域确实需要占父容器高度的一半，应先确定父容器高度：

```scss
.outer {
  display: linear;
  height: 400px;
}

.middle {
  height: 50%;
}
```

如果目标是让中间区域占用剩余空间，更适合直接使用 Flex 分配空间：

```scss
.outer {
  display: flex;
  flex-direction: column;
  height: 400px;
}

.middle {
  min-height: 0;
  flex-grow: 1;
}
```

父容器尺寸已确定、子元素需要固定比例时使用百分比；子元素需要填满剩余空间时使用 Flex 权重。

处理这类布局时：

1. 给百分比依赖链上的关键祖先设置明确宽高；
2. 分配剩余空间时使用 `flex-grow`、`flex-shrink` 或 `linear-weight`；
3. 检查中间层是否使用了不同布局模型或自定义测量组件；
4. 为没有内容的容器显式设置主轴尺寸或权重；

### 盒模型与间距

Lynx 支持 `border-box` 和 `content-box`，默认使用 `border-box`。建议在跨端组件中显式声明：

```scss
.card {
  box-sizing: border-box;
  width: 100%;
  padding: 16px;
}
```

相邻元素的垂直 margin 不会像 Web 一样合并。两个相邻元素分别设置 `margin-bottom: 20px` 和 `margin-top: 20px` 时，最终间距为两者之和。

间距可以采用以下任一策略：

- 只由相邻元素的一侧设置 margin；
- 由父容器统一设置 `gap` 或 padding；
- 组件只负责内部间距，外部间距由调用方控制；

## 定位与层叠

| 能力                   | 当前行为                   | 使用方式                                 |
| -------------------- | ---------------------- | ------------------------------------ |
| `position: relative` | 默认定位方式                 | 可以通过定位边相对自身正常位置偏移                    |
| `position: absolute` | 脱离正常布局                 | 相对父级包含块定位，显式设置定位边                    |
| `position: fixed`    | 相对根节点定位                | 显式设置 `top`、`right`、`bottom` 或 `left` |
| `position: sticky`   | 只用于 `scroll-view` 的子元素 | 设置至少一个定位边作为吸附阈值                      |
| `z-index`            | 控制定位元素的层叠关系            | 与定位属性一起使用，并检查父容器层叠关系                 |

### 示例：滚动容器中的吸顶标题

`sticky` 元素需要放在 `scroll-view` 中，并通过 `top` 等定位边声明吸附阈值：

```tsx
<scroll-view className="group-list" scrollOrientation="vertical" enableScroll>
  <view className="group-list__header">
    <text>最近使用</text>
  </view>
  <view className="group-list__content">
    <text>项目 A</text>
    <text>项目 B</text>
  </view>
</scroll-view>
```

```scss
.group-list {
  height: 320px;
}

.group-list__header {
  position: sticky;
  top: 0;
  z-index: 1;
  padding: 12px;
  background-color: #fff;
}

.group-list__content {
  display: flex;
  flex-direction: column;
  gap: 12px;
  padding: 12px;
}
```

当列表滚动到标题的 `top: 0` 阈值时，标题会吸附在滚动容器顶部。背景色和 `z-index` 可以避免列表内容从标题下方透出。

绝对定位元素使用 `z-index` 时，可以在父容器设置 `position: relative; z-index: 0`，建立明确的父子层叠关系。滚动容器中的层叠效果需要在真实目标端检查。

## 选择器与节点

业务样式优先使用结构简单、作用域清楚的类选择器。

| 选择器                                               | 当前能力    | 建议                    |
| ------------------------------------------------- | ------- | --------------------- |
| 元素选择器                                             | 支持      | 适合设置某类 Lynx 元素的基础样式   |
| 类选择器                                              | 支持      | 业务组件的首选方式             |
| ID 选择器                                            | 支持      | 只用于确实唯一的节点            |
| 通配选择器                                             | 支持      | 避免在大型组件树中大量使用         |
| 分组选择器                                             | 支持      | 多个简单选择器可以共用一组声明       |
| 后代、直接子代选择器                                        | 支持      | 只依赖稳定的局部结构            |
| 相邻、通用兄弟选择器                                        | 支持      | 结构变化频繁时仍建议改用语义类名      |
| 属性选择器                                             | 部分支持    | 使用前按实际语法验证，不依赖复杂匹配表达式 |
| `:root`                                           | 支持      | 匹配 Lynx `page` 根节点    |
| `:active`、`:focus`、`:not()`                       | 支持      | 用于按压、聚焦和简单排除条件        |
| `:hover`                                          | 取决于输入设备 | 不作为移动端核心交互状态          |
| `::placeholder`、`::selection`                     | 支持      | 分别用于输入占位符和选中文本样式      |
| `:first-child`、`:last-child`、`:nth-child()` 等结构伪类 | 不支持     | 在渲染时计算类名或拆分组件结构       |
| `:disabled`、`:enabled`、`:checked`                 | 不支持     | 根据组件状态显式切换类名          |
| `:is()`、`:where()`、`:has()`                       | 不支持     | 拆成简单选择器               |
| `::before`、`::after`                              | 不支持生成内容 | 增加真实 Lynx 元素          |

部分不支持的选择器可以被解析，但不会匹配节点，也不一定产生构建错误。不要把“没有报错”当作“样式已经生效”；状态和结构变化应通过明确的类名表达。

```tsx
<view className={`option ${selected ? 'option--selected' : ''}`}>
  <text>选项</text>
</view>
```

ReactLynx 自定义组件不会隐式生成原生节点。`className`、`style`、`id` 和原生事件必须由组件显式传递给内部 Lynx 元素。

## 文本与背景

普通文本必须放在 `text` 元素中，不能直接写在 `view` 中。

| 目标     | 推荐写法                                                             |
| ------ | ---------------------------------------------------------------- |
| 正文换行   | `white-space: normal`                                            |
| 单行省略   | `white-space: nowrap; overflow: hidden; text-overflow: ellipsis` |
| 多行文本   | 使用 `text` 提供的多行文本能力，并检查实际截断效果                                    |
| 页面背景   | 设置在 `page`                                                       |
| 内容区域背景 | 设置在真实根 `view`                                                    |

```tsx
<view className="summary">
  <text className="summary-text">需要展示的文本内容</text>
</view>
```

```scss
.summary-text {
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}
```

普通 `.body` 类名只是业务容器，不具备浏览器 `body` 的默认 margin、字体、滚动和包含块语义。

## Transform 与动画

Transform 函数按声明顺序执行。Transition 和 `@keyframes` 中也只能使用受支持的函数；例如 `scale3d()` 和 `rotate3d()` 不在当前支持范围，应改用受支持的 scale、rotate、translate 或 matrix 函数组合。Lynx 的 `transform-style` 只支持 `flat`，不支持 `preserve-3d`。子元素不会保留三维空间，不能依赖父子节点组成嵌套 3D 场景。完整函数和动画取值见 [CSS 能力清单](/apps-plugin/docs/client-framework/css-capabilities.md#transform动画与过渡)。

`steps()` 必须显式写出方向参数。Web 中可省略第二个参数的 `steps(4)` 在当前能力中无效，应写为 `steps(4, end)`、`steps(4, start)` 或对应的 `jump-*` 形式；`step-start` 和 `step-end` 可以直接使用。

```scss
@keyframes zoom {
  0% {
    transform: scale(0.6, 0.6);
  }
  100% {
    transform: scale(1, 1);
  }
}

.card {
  animation: zoom 200ms ease-out both;
}
```

上例通过 `animation` 将关键帧应用到节点，并只使用当前支持的 `scale()` 完成缩放。

```scss
.sprite {
  animation: play-sprite 800ms steps(4, end) infinite;
}
```

## 开发检查项

1. 页面根节点和关键容器是否显式声明了布局方式、尺寸和盒模型；
2. 布局是否使用 Flex、Linear 或 Grid，而不是 block、inline、table 或 float；
3. Grid 是否使用当前支持的标准定位属性，跨轨道是否使用 `span <number>` 取值；
4. 文本是否全部由 `text` 元素承载；
5. 自定义组件的样式、尺寸、标识和事件是否传递到真实 Lynx 元素；
6. Flex 子项是否设置了符合业务需要的收缩规则和尺寸下限；
7. 百分比尺寸依赖的祖先是否具有可解析的尺寸；
8. margin、fixed、sticky、z-index 和滚动容器的组合是否符合预期；
9. 组件是否采用一致的 px、%、vw/vh、rem/em 或 rpx 策略；
10. 选择器、Transform 和动画是否只使用当前支持的语法，`steps()` 是否补全方向参数；
11. 是否已经在真实目标端检查布局、文本和动画效果；
