样式与布局差异
豆包应用插件使用 Lynx 作为 UI 渲染器,负责界面的布局与绘制。开发者可以继续使用熟悉的 CSS 写法;当涉及布局模型、选择器、尺寸单位和动画等能力差异时,以豆包应用插件当前支持的 CSS 能力为准。
本章按开发行为说明布局、尺寸与盒模型、定位、选择器、文本和动画的主要差异,并提供可直接采用的写法。需要确认某个 CSS 属性或取值时,统一查询 CSS 能力清单。
注意
- 本章说明常用能力、主要差异和推荐写法。完整支持范围请查询 CSS 能力清单;未列入清单的属性或取值,当前不属于支持范围,不能默认与 Web 一致;
- 关键容器应显式声明布局、尺寸和盒模型,不依赖浏览器默认样式;
- 页面最终由原生视图渲染,需要在真实目标端检查布局、文本和动画效果;
样式方案选择
开发时优先从当前提供的布局、元素和样式能力中选择实现方案。下表按常见需求给出可以直接采用的写法;最后一列用于从 Web 代码迁移时识别需要替换的语法。
布局能力
选择布局模型
选择布局时,可以按结构复杂度判断:
- 只有固定方向的顺序排列时,使用 Linear;
- 需要弹性分配、对齐或换行时,使用 Flex;
- 同时存在行、列关系时,使用 Grid;
Grid 布局
Grid 使用显式轨道以及 grid-column、grid-row 或对应的长写定位属性。跨越多个轨道时,使用标准的 span <number> 取值,不使用非标准的 grid-column-span、grid-row-span:
命名网格线和 subgrid 不属于当前能力。
关键容器与 Flex 示例
页面根节点和关键容器应显式设置布局方式:
豆包应用插件的默认布局不遵循 Web 的 block flow。即使节点未声明 display 时结果符合预期,也应为关键容器显式选择布局模型。
示例:可收缩的商品卡片
下面的卡片使用 Flex 分配横向空间:缩略图和操作按钮保持固定宽度,中间文本区域占用剩余空间,并在内容过长时显示省略号。
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 只有在主轴空间不足时才会生效。如果父容器没有确定尺寸或外部约束,容器会随内容扩展,不会产生需要收缩的负剩余空间。
需要保护文本、图片或固定区域时,显式设置收缩规则和尺寸下限:
Lynx 不会自动套用与 Web 完全相同的内容最小尺寸。需要让 Web 预览与 Lynx 一样允许内容收缩时,可以在 Web 侧按主轴设置 min-width: 0 或 min-height: 0:
尺寸与盒模型
不同单位对应不同计算基准:% 跟随父元素,vw / vh 跟随布局 viewport,rem / em 跟随字体基准,rpx 跟随设计宽度。一个组件内应先确定尺寸策略,避免无规则混用导致溢出、裁剪或意外换行。支持的单位和函数以 CSS 能力清单 为准。
当前不支持使用 @media 切换样式。响应式布局优先使用 %、vw / vh、rem、rpx 和 Flex / Grid;确实需要根据运行环境切换结构时,在业务逻辑中获取对应信息并切换样式或节点结构。
百分比尺寸
百分比尺寸要求祖先具有可以解析的对应尺寸。如果祖先尺寸由内容撑开,而子元素尺寸又依赖祖先百分比,就会形成循环依赖,可能导致百分比不生效或空节点尺寸为 0。
如果中间区域确实需要占父容器高度的一半,应先确定父容器高度:
如果目标是让中间区域占用剩余空间,更适合直接使用 Flex 分配空间:
父容器尺寸已确定、子元素需要固定比例时使用百分比;子元素需要填满剩余空间时使用 Flex 权重。
处理这类布局时:
- 给百分比依赖链上的关键祖先设置明确宽高;
- 分配剩余空间时使用
flex-grow、flex-shrink或linear-weight; - 检查中间层是否使用了不同布局模型或自定义测量组件;
- 为没有内容的容器显式设置主轴尺寸或权重;
盒模型与间距
Lynx 支持 border-box 和 content-box,默认使用 border-box。建议在跨端组件中显式声明:
相邻元素的垂直 margin 不会像 Web 一样合并。两个相邻元素分别设置 margin-bottom: 20px 和 margin-top: 20px 时,最终间距为两者之和。
间距可以采用以下任一策略:
- 只由相邻元素的一侧设置 margin;
- 由父容器统一设置
gap或 padding; - 组件只负责内部间距,外部间距由调用方控制;
定位与层叠
示例:滚动容器中的吸顶标题
sticky 元素需要放在 scroll-view 中,并通过 top 等定位边声明吸附阈值:
当列表滚动到标题的 top: 0 阈值时,标题会吸附在滚动容器顶部。背景色和 z-index 可以避免列表内容从标题下方透出。
绝对定位元素使用 z-index 时,可以在父容器设置 position: relative; z-index: 0,建立明确的父子层叠关系。滚动容器中的层叠效果需要在真实目标端检查。
选择器与节点
业务样式优先使用结构简单、作用域清楚的类选择器。
部分不支持的选择器可以被解析,但不会匹配节点,也不一定产生构建错误。不要把“没有报错”当作“样式已经生效”;状态和结构变化应通过明确的类名表达。
ReactLynx 自定义组件不会隐式生成原生节点。className、style、id 和原生事件必须由组件显式传递给内部 Lynx 元素。
文本与背景
普通文本必须放在 text 元素中,不能直接写在 view 中。
普通 .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 可以直接使用。
上例通过 animation 将关键帧应用到节点,并只使用当前支持的 scale() 完成缩放。
开发检查项
- 页面根节点和关键容器是否显式声明了布局方式、尺寸和盒模型;
- 布局是否使用 Flex、Linear 或 Grid,而不是 block、inline、table 或 float;
- Grid 是否使用当前支持的标准定位属性,跨轨道是否使用
span <number>取值; - 文本是否全部由
text元素承载; - 自定义组件的样式、尺寸、标识和事件是否传递到真实 Lynx 元素;
- Flex 子项是否设置了符合业务需要的收缩规则和尺寸下限;
- 百分比尺寸依赖的祖先是否具有可解析的尺寸;
- margin、fixed、sticky、z-index 和滚动容器的组合是否符合预期;
- 组件是否采用一致的 px、%、vw/vh、rem/em 或 rpx 策略;
- 选择器、Transform 和动画是否只使用当前支持的语法,
steps()是否补全方向参数; - 是否已经在真实目标端检查布局、文本和动画效果;