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, and this page is available as Markdown at /apps-plugin/docs/client-framework/styling.md.

样式与布局差异

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

本章按开发行为说明布局、尺寸与盒模型、定位、选择器、文本和动画的主要差异,并提供可直接采用的写法。需要确认某个 CSS 属性或取值时,统一查询 CSS 能力清单。

注意

  • 本章说明常用能力、主要差异和推荐写法。完整支持范围请查询 CSS 能力清单;未列入清单的属性或取值,当前不属于支持范围,不能默认与 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:

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

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

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

关键容器与 Flex 示例

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

.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 分配横向空间:缩略图和操作按钮保持固定宽度,中间文本区域占用剩余空间,并在内容过长时显示省略号。

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>
  );
}
.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 能力清单。

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

Flex 尺寸分配

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

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

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

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

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

尺寸与盒模型

不同单位对应不同计算基准:% 跟随父元素,vw / vh 跟随布局 viewport,rem / em 跟随字体基准,rpx 跟随设计宽度。一个组件内应先确定尺寸策略,避免无规则混用导致溢出、裁剪或意外换行。支持的单位和函数以 CSS 能力清单 为准。

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

百分比尺寸

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

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

.middle {
  height: 50%;
}

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

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

.middle {
  height: 50%;
}

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

.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。建议在跨端组件中显式声明:

.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 等定位边声明吸附阈值:

<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>
.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 元素

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

<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
<view className="summary">
  <text className="summary-text">需要展示的文本内容</text>
</view>
.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 能力清单。

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

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

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

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

.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. 是否已经在真实目标端检查布局、文本和动画效果;