styled-components 原生背景简写React Native 中background的多层渐变、position/size 与平台差异解析【免费下载链接】styled-componentsFast, expressive styling for React. Server components, client components, streaming SSR, React Native—one API.项目地址: https://gitcode.com/gh_mirrors/st/styled-components导读本文围绕 styled-components 的native-background变更集系统讲解background简写在 React Native 上的支持边界与实现细节多层背景、position / size拆分、末层颜色、不支持属性的开发警告、重复值折叠与center top归一化以及cover/contain在原生与 react-native-web 上的不同处理路径。读完本文你将掌握在 iOS/Android 与 rn-web 双端安全书写背景样式的能力并理解这些行为背后的源码实现依据。一、能力总览background简写在原生端的支持矩阵变更集明确宣告了background简写在 React Native 上的能力边界支持多层逗号分隔背景、position / size用/拆分、末层可携带颜色不支持原生端开发警告background-attachment、background-origin、background-clipweb 构建则保留完整声明宽容处理非法的 position、size、repeat 值会被忽略非法的分层 longhand 在开发模式下给出警告语义折叠所有逗号分隔层若重复相同 position/size/repeat则折叠为单值center top这类简单居中组合折叠为单个关键字top且不影响布局尺寸关键字background-size: cover与contain对渐变背景生效——渐变会铺满整个元素区域在 react-native-web 上由浏览器直接处理关键字0 0、50% 50%、top left等background-position值无警告直接透传。这一整套行为由原生变换管线native transform pipeline中的background简写处理器实现注册于 shorthands.register.tsregister(background, backgroundShorthand); register(backgroundAttachment, backgroundAttachmentLonghand); register(backgroundOrigin, backgroundOriginLonghand); register(backgroundClip, backgroundClipLonghand);核心实现位于 handlers/background.ts下面逐层展开。二、简写解析分层、position / size与末层颜色2.1 整体流程先按顶层逗号切层backgroundShorthand的入口先把整个声明值按顶层逗号切分为多个层splitTopLevelCommas括号内渐变函数的逗号不会误切然后逐层调用parseLayerconst raw tokens.map(t t.raw).join( ).trim(); const layerSources splitTopLevelCommas(raw, true); for (let i 0; i layerSources.length; i) { const parsed parseLayer(layerSources[i], i layerSources.length - 1); if (parsed null) return null; layers.push(parsed); }注意parseLayer的第二个参数isFinal只有最后一层允许出现颜色这是 CSSbackground简写的核心语法约束。任何非末层尝试声明颜色都会导致整个声明解析失败返回null从而被忽略。2.2 层内词法斜杠进入 size 子状态parseLayer不剥离斜杠而是直接对层源码做 tokenize并在循环中按TokenKind.Slash切换状态斜杠前收集 1–4 个 position tokentop/right/bottom/left/center关键字或长度/百分比/数值斜杠后进入 size 子状态消费 1–2 个 size tokencover/contain/auto或长度/百分比然后回到主循环图像linear-gradient()、radial-gradient()、conic-gradient()、repeating-*系列及url()函数或none关键字repeat单形式关键字repeat-x/repeat-y只占一个槽位双值形式repeat/no-repeat/space/round最多两个且禁止单形式与双形式混用代码中有显式注释说明这一规范约束box 关键字第一个content-box/padding-box/border-box同时写入 origin 与 clip第二个仅覆盖 clip颜色consumeColor消费颜色 token仅末层允许且每个层只能有一个。2.3 末层颜色折叠与简写重置语义解析完成后处理器把颜色单独取出写入backgroundColor并把纯颜色末层从图像层列表中剔除避免产生多余的none尾项const imageLayers finalLayer.color ! null finalLayer.image null ? layers.slice(0, -1) : layers; const out: Dictany {}; out.backgroundColor finalLayer.color ! null ? cssColorRawToRnStyleValue(finalLayer.color) : transparent;同时由于简写会重置其控制的全部 longhandbackground: url(...)仅图像会清除先前设置的background-color输出为transparent——这与 CSS 简写的重置语义一致。2.4 输出映射双键发射dual-emit处理结果按 host 平台做双键发射这是理解原生背景的关键。PASSTHROUGH_PROPS在 passthrough.ts 中定义[backgroundImage, [experimental_backgroundImage, backgroundImage]], [backgroundSize, [experimental_backgroundSize, backgroundSize]], [backgroundPosition,[experimental_backgroundPosition,backgroundPosition]], [backgroundRepeat, [experimental_backgroundRepeat, backgroundRepeat]],iOS / Android读取experimental_*键react-native-web读取标准键名两侧对另一组键静默忽略。简写处理器生成的输出结构handlers/background.tsout.experimental_backgroundImage __NATIVE_WEB__ ? images : maybeExpandBackgroundImageSystemColors(images); out.backgroundImage images; out.experimental_backgroundPosition positions; if (!isMultiTokenPosition(positions)) out.backgroundPosition positions; out.experimental_backgroundSize substituteBackgroundSizeKeywordsForNative(sizes); out.backgroundSize sizes; out.experimental_backgroundRepeat repeats; out.backgroundRepeat repeats; if (__NATIVE_WEB__) { out.backgroundAttachment attachments; out.backgroundOrigin origins; out.backgroundClip clips; }可以看出backgroundAttachment、backgroundOrigin、backgroundClip三个键仅在 rn-web 上发射原生端完全不输出——这正是web 保留完整声明、原生忽略的落地方式。三、平台差异attachment / origin / clip 的警告路径RN 0.85 没有暴露background-attachment / origin / clip的渲染表面见 handlers/background.ts 的模块注释因此原生端对非默认值发出一次性警告warnOnce避免重复刷屏属性原生端行为警告标识提示内容要点background-attachment: fixed忽略native-background-attachment-fixediOS/Android 不暴露滚动锚定背景background-attachment: local忽略native-background-attachment-local不暴露内容锚定背景rn-web 保留background-origin非padding-box忽略native-background-origin-unsupported原生背景从默认盒子绘制background-clip非border-box忽略native-background-clip-unsupportedbackground-clip: text请使用专用原生文本渲染库对应 longhand 处理器backgroundAttachmentLonghand等在原生端只做校验合法值仅scroll/padding-box/border-box时静默接受其余值警告后返回空对象{}而在 rn-web 上则原样透传。另外原生端对conic-gradient()含repeating-conic-gradient()有专门的警告函数warnIfConicGradientNativeRN 渐变仅覆盖linear-gradient()与radial-gradient()圆锥渐变在 iOS/Android 上静默渲染为空但 webrn-web与服务端仍会渲染因此只警告不删除发射handlers/background.ts。四、分层值的折叠与归一化4.1 相同分层值的折叠collapseIdenticalCommasCSS Backgrounds 规范中background-position/-size/-repeat的分层值是循环复用的——单个值会作用于所有层。当书写background-position: 0% 0%, 0% 0%这类每个层都相同的值时react-native-web 的 StyleSheet 校验器会直接拒绝报Invalid style property of backgroundPosition. Value is 0% 0%,0% 0%。因此管线在 passthrough.ts 提供collapseIdenticalCommas当所有顶层逗号分隔的值完全相同时折叠为单值只要有任何一层不同体现真实分层意图或根本没有顶层逗号则原样返回。export function collapseIdenticalCommas(value: string): string { if (value.indexOf(,) -1) return value; const parts splitTopLevelCommas(value, true); if (parts.length 1) return value; const first parts[0]; for (let i 1; i parts.length; i) { if (parts[i] ! first) return value; } return first; }该折叠仅作用于三个分层属性backgroundPosition/backgroundSize/backgroundRepeat定义于LAYERED_COMMA_PROPS。测试 passthrough.test.ts 验证了background-repeat: no-repeat,no-repeat,no-repeat→no-repeat、background-size: cover, cover→ 原生键折叠为auto等场景并强调不折叠非分层透传属性以防回归。注意简写路径中同样应用了这一折叠——例如background: linear-gradient(...) center / cover, linear-gradient(...) center / cover的 position 与 size 部分都会各自折叠。4.2center top→top的关键字归一化normalizeBackgroundPositionValue对两 token 均为关键字、且其一为center的层做折叠center top→top、left center→left、center center→center。折叠后布局完全等价center与另一轴的组合不改变该轴位置见 passthrough.ts。测试 passthrough.test.ts 对三种组合均有断言。4.3 合法性与宽容处理在 transform/index.ts 的透传分支中任何background*属性在进入发射前都要通过isValidLayeredBackgroundValue校验if (!isValidLayeredBackgroundValue(camel, rawValue)) { if (__DEV__) { warnOnce(native-shorthand-parse, the value ${rawValue} could not be parsed for property ${prop}. The declaration was ignored., ...); } return {}; }校验器在 passthrough.ts 中实现覆盖三条语法规则position单值必须是长度/百分比或关键字双值要满足轴合法性如50% left非法——百分比后不能跟水平关键字1–4 token 的边缘偏移形式如right 3em bottom 10px受支持size单值为非负长度/百分比或auto/cover/contain双值中除auto外不得出现关键字且不能混入cover/containcover auto、10px contain非法负尺寸被拒绝repeat禁止repeat-x repeat-y、repeat-x space等混用形式。测试 passthrough.test.ts 覆盖了这些拒绝与接受用例。简写处理器自身解析失败时同样走native-shorthand-parse警告后整体忽略transform/index.ts。五、cover/contain原生端的崩溃规避与 rn-web 直通5.1 背景RN 0.85 的原生解析缺陷experimental_backgroundSize上的cover/contain折叠substituteBackgroundSizeKeywordsForNative背后是一个真实且严重的问题。passthrough.ts 的注释记录了完整调查RN 0.85 的BackgroundSize.kt解析器只接受ReadableType.Map{x, y}JS 侧的processBackgroundSize.js却把cover/contain作为裸字符串保留导致原生解析返回 null当所有层的 size 都是关键字形式时得到的列表为空BackgroundImageDrawable.kt在绘制时执行index % size触发ArithmeticException: divide by zero进程被 SIGKILL——用户看到的是应用直接消失。5.2 为何折叠为auto是正确的对渐变而言BackgroundImageDrawable.calculateBackgroundImageSize以imageWidth 容器宽、imageHeight 容器高调用渐变没有固有尺寸当 size 为 null 或两轴均为auto时跳过覆盖分支返回(containerWidth, containerHeight)。因此在渐变上cover ≡ contain ≡ auto——三者都铺满整个元素区域。auto是诚实的折叠它请求渲染器按图像自然尺寸处理而原生侧对无纵横比的图像本就解析为容器填充。字面量100% 100%虽然绘制相同但对未来可能的非渐变图像路径做出了更强也可能误导的尺寸声明。v7 中url()图像路径不经过experimental_*由applyBackgroundBlendModePolyfill直接重建为Image resizeMode。标准backgroundSize键仍保留原始关键字供 rn-web 交给浏览器原生处理cover/contain语义。测试断言passthrough.test.tstransformDecl(background-size, cover) // → { experimental_backgroundSize: auto, backgroundSize: cover } transformDecl(background-size, cover, 50% 50%) // → { experimental_backgroundSize: auto, 50% 50%, backgroundSize: cover, 50% 50% } transformDecl(background-size, 50% 50%) // → { experimental_backgroundSize: 50% 50%, backgroundSize: 50% 50% }一旦 RN 原生解析器能直接处理cover/contain字符串该替换即可移除注释中已标注。5.3 rn-web 的 position 直通与校验器规避react-native-web 的validate.js会在backgroundPosition含多个顶层值时打印console.error并丢弃该 prop。但原生端iOS/Android接受完整的双轴语法。解决方案是不对称双键发射isMultiTokenPositionpassthrough.ts双 token 形式0 0、0% 0%、top left、50% 50%或多层字符串含逗号跳过backgroundPositionrn-web 键只发experimental_backgroundPosition——iOS/Android 仍能收到完整语法单 token 形式center、top、left、0两个键都发。rn-web 因此静默回落到其 CSS 默认值0% 0%——与丢弃非法值后的绘制结果相同且消除了警告。测试 passthrough.test.ts 验证了0 0、50% 50%、top left只发experimental_*键而center双键发射。这正是变更集中0 0、50% 50%、top left在 rn-web 上无警告直通的实现机制。六、渐变中的系统颜色experimental_backgroundImage的结构化改写原生端还有一处精细处理当linear-gradient()的色标使用 CSS 系统颜色关键字时RN 的字符串解析器会拒绝它们processColor失败。为此 backgroundGradientNative.ts 的maybeExpandBackgroundImageSystemColors会在原生端把含系统颜色的线性渐变改写为结构化对象数组{ type: linear-gradient, direction, colorStops }其中颜色经cssColorRawToRnStyleValue折叠为PlatformColor对象仅当确认存在系统颜色时才返回数组否则保持原始字符串。radial-gradient()不参与此改写rn-web 上则始终保留原始字符串交由浏览器解析backgroundGradientNative.ts。七、实践建议与总结综合变更集与源码在 styled-components 的 React Native 场景中书写背景样式时放心使用background简写书写多层渐变、position / size与末层颜色例如background: linear-gradient(to right, rgba(255,255,255,.4), transparent) 50% 50% / cover no-repeat, linear-gradient(to bottom, #ff0000, #0000ff);原生端会正确映射到experimental_*键并折叠语义等价的部分。避免在原生依赖 attachment/origin/clip 视觉结果它们只在 rn-web 上生效原生端忽略并给出开发警告如需background-clip: text请使用专门的文本渲染方案。cover/contain只用于渐变背景原生端折叠为auto等效铺满非渐变图像路径走url()resizeMode的既有机制。重复的分层值放心书写管线会自动折叠规避 rn-web 校验器拒绝center top这类组合也会归一化为top。若需在开发期排查留意native-background-attachment-*、native-background-origin-unsupported、native-background-clip-unsupported、native-conic-gradient-unsupported、native-shorthand-parse等一次性警告标识handlers/background.ts 与 transform/index.ts 中定义。延伸阅读完整的简写注册清单见 shorthands.register.ts透传属性与折叠逻辑见 passthrough.ts单条声明变换的完整派发流程见 transform/index.ts行为验证测试见 passthrough.test.ts。【免费下载链接】styled-componentsFast, expressive styling for React. Server components, client components, streaming SSR, React Native—one API.项目地址: https://gitcode.com/gh_mirrors/st/styled-components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
styled-components 原生背景简写：React Native 中 `background` 的多层渐变、position/size 与平台差异解析
styled-components 原生背景简写React Native 中background的多层渐变、position/size 与平台差异解析【免费下载链接】styled-componentsFast, expressive styling for React. Server components, client components, streaming SSR, React Native—one API.项目地址: https://gitcode.com/gh_mirrors/st/styled-components导读本文围绕 styled-components 的native-background变更集系统讲解background简写在 React Native 上的支持边界与实现细节多层背景、position / size拆分、末层颜色、不支持属性的开发警告、重复值折叠与center top归一化以及cover/contain在原生与 react-native-web 上的不同处理路径。读完本文你将掌握在 iOS/Android 与 rn-web 双端安全书写背景样式的能力并理解这些行为背后的源码实现依据。一、能力总览background简写在原生端的支持矩阵变更集明确宣告了background简写在 React Native 上的能力边界支持多层逗号分隔背景、position / size用/拆分、末层可携带颜色不支持原生端开发警告background-attachment、background-origin、background-clipweb 构建则保留完整声明宽容处理非法的 position、size、repeat 值会被忽略非法的分层 longhand 在开发模式下给出警告语义折叠所有逗号分隔层若重复相同 position/size/repeat则折叠为单值center top这类简单居中组合折叠为单个关键字top且不影响布局尺寸关键字background-size: cover与contain对渐变背景生效——渐变会铺满整个元素区域在 react-native-web 上由浏览器直接处理关键字0 0、50% 50%、top left等background-position值无警告直接透传。这一整套行为由原生变换管线native transform pipeline中的background简写处理器实现注册于 shorthands.register.tsregister(background, backgroundShorthand); register(backgroundAttachment, backgroundAttachmentLonghand); register(backgroundOrigin, backgroundOriginLonghand); register(backgroundClip, backgroundClipLonghand);核心实现位于 handlers/background.ts下面逐层展开。二、简写解析分层、position / size与末层颜色2.1 整体流程先按顶层逗号切层backgroundShorthand的入口先把整个声明值按顶层逗号切分为多个层splitTopLevelCommas括号内渐变函数的逗号不会误切然后逐层调用parseLayerconst raw tokens.map(t t.raw).join( ).trim(); const layerSources splitTopLevelCommas(raw, true); for (let i 0; i layerSources.length; i) { const parsed parseLayer(layerSources[i], i layerSources.length - 1); if (parsed null) return null; layers.push(parsed); }注意parseLayer的第二个参数isFinal只有最后一层允许出现颜色这是 CSSbackground简写的核心语法约束。任何非末层尝试声明颜色都会导致整个声明解析失败返回null从而被忽略。2.2 层内词法斜杠进入 size 子状态parseLayer不剥离斜杠而是直接对层源码做 tokenize并在循环中按TokenKind.Slash切换状态斜杠前收集 1–4 个 position tokentop/right/bottom/left/center关键字或长度/百分比/数值斜杠后进入 size 子状态消费 1–2 个 size tokencover/contain/auto或长度/百分比然后回到主循环图像linear-gradient()、radial-gradient()、conic-gradient()、repeating-*系列及url()函数或none关键字repeat单形式关键字repeat-x/repeat-y只占一个槽位双值形式repeat/no-repeat/space/round最多两个且禁止单形式与双形式混用代码中有显式注释说明这一规范约束box 关键字第一个content-box/padding-box/border-box同时写入 origin 与 clip第二个仅覆盖 clip颜色consumeColor消费颜色 token仅末层允许且每个层只能有一个。2.3 末层颜色折叠与简写重置语义解析完成后处理器把颜色单独取出写入backgroundColor并把纯颜色末层从图像层列表中剔除避免产生多余的none尾项const imageLayers finalLayer.color ! null finalLayer.image null ? layers.slice(0, -1) : layers; const out: Dictany {}; out.backgroundColor finalLayer.color ! null ? cssColorRawToRnStyleValue(finalLayer.color) : transparent;同时由于简写会重置其控制的全部 longhandbackground: url(...)仅图像会清除先前设置的background-color输出为transparent——这与 CSS 简写的重置语义一致。2.4 输出映射双键发射dual-emit处理结果按 host 平台做双键发射这是理解原生背景的关键。PASSTHROUGH_PROPS在 passthrough.ts 中定义[backgroundImage, [experimental_backgroundImage, backgroundImage]], [backgroundSize, [experimental_backgroundSize, backgroundSize]], [backgroundPosition,[experimental_backgroundPosition,backgroundPosition]], [backgroundRepeat, [experimental_backgroundRepeat, backgroundRepeat]],iOS / Android读取experimental_*键react-native-web读取标准键名两侧对另一组键静默忽略。简写处理器生成的输出结构handlers/background.tsout.experimental_backgroundImage __NATIVE_WEB__ ? images : maybeExpandBackgroundImageSystemColors(images); out.backgroundImage images; out.experimental_backgroundPosition positions; if (!isMultiTokenPosition(positions)) out.backgroundPosition positions; out.experimental_backgroundSize substituteBackgroundSizeKeywordsForNative(sizes); out.backgroundSize sizes; out.experimental_backgroundRepeat repeats; out.backgroundRepeat repeats; if (__NATIVE_WEB__) { out.backgroundAttachment attachments; out.backgroundOrigin origins; out.backgroundClip clips; }可以看出backgroundAttachment、backgroundOrigin、backgroundClip三个键仅在 rn-web 上发射原生端完全不输出——这正是web 保留完整声明、原生忽略的落地方式。三、平台差异attachment / origin / clip 的警告路径RN 0.85 没有暴露background-attachment / origin / clip的渲染表面见 handlers/background.ts 的模块注释因此原生端对非默认值发出一次性警告warnOnce避免重复刷屏属性原生端行为警告标识提示内容要点background-attachment: fixed忽略native-background-attachment-fixediOS/Android 不暴露滚动锚定背景background-attachment: local忽略native-background-attachment-local不暴露内容锚定背景rn-web 保留background-origin非padding-box忽略native-background-origin-unsupported原生背景从默认盒子绘制background-clip非border-box忽略native-background-clip-unsupportedbackground-clip: text请使用专用原生文本渲染库对应 longhand 处理器backgroundAttachmentLonghand等在原生端只做校验合法值仅scroll/padding-box/border-box时静默接受其余值警告后返回空对象{}而在 rn-web 上则原样透传。另外原生端对conic-gradient()含repeating-conic-gradient()有专门的警告函数warnIfConicGradientNativeRN 渐变仅覆盖linear-gradient()与radial-gradient()圆锥渐变在 iOS/Android 上静默渲染为空但 webrn-web与服务端仍会渲染因此只警告不删除发射handlers/background.ts。四、分层值的折叠与归一化4.1 相同分层值的折叠collapseIdenticalCommasCSS Backgrounds 规范中background-position/-size/-repeat的分层值是循环复用的——单个值会作用于所有层。当书写background-position: 0% 0%, 0% 0%这类每个层都相同的值时react-native-web 的 StyleSheet 校验器会直接拒绝报Invalid style property of backgroundPosition. Value is 0% 0%,0% 0%。因此管线在 passthrough.ts 提供collapseIdenticalCommas当所有顶层逗号分隔的值完全相同时折叠为单值只要有任何一层不同体现真实分层意图或根本没有顶层逗号则原样返回。export function collapseIdenticalCommas(value: string): string { if (value.indexOf(,) -1) return value; const parts splitTopLevelCommas(value, true); if (parts.length 1) return value; const first parts[0]; for (let i 1; i parts.length; i) { if (parts[i] ! first) return value; } return first; }该折叠仅作用于三个分层属性backgroundPosition/backgroundSize/backgroundRepeat定义于LAYERED_COMMA_PROPS。测试 passthrough.test.ts 验证了background-repeat: no-repeat,no-repeat,no-repeat→no-repeat、background-size: cover, cover→ 原生键折叠为auto等场景并强调不折叠非分层透传属性以防回归。注意简写路径中同样应用了这一折叠——例如background: linear-gradient(...) center / cover, linear-gradient(...) center / cover的 position 与 size 部分都会各自折叠。4.2center top→top的关键字归一化normalizeBackgroundPositionValue对两 token 均为关键字、且其一为center的层做折叠center top→top、left center→left、center center→center。折叠后布局完全等价center与另一轴的组合不改变该轴位置见 passthrough.ts。测试 passthrough.test.ts 对三种组合均有断言。4.3 合法性与宽容处理在 transform/index.ts 的透传分支中任何background*属性在进入发射前都要通过isValidLayeredBackgroundValue校验if (!isValidLayeredBackgroundValue(camel, rawValue)) { if (__DEV__) { warnOnce(native-shorthand-parse, the value ${rawValue} could not be parsed for property ${prop}. The declaration was ignored., ...); } return {}; }校验器在 passthrough.ts 中实现覆盖三条语法规则position单值必须是长度/百分比或关键字双值要满足轴合法性如50% left非法——百分比后不能跟水平关键字1–4 token 的边缘偏移形式如right 3em bottom 10px受支持size单值为非负长度/百分比或auto/cover/contain双值中除auto外不得出现关键字且不能混入cover/containcover auto、10px contain非法负尺寸被拒绝repeat禁止repeat-x repeat-y、repeat-x space等混用形式。测试 passthrough.test.ts 覆盖了这些拒绝与接受用例。简写处理器自身解析失败时同样走native-shorthand-parse警告后整体忽略transform/index.ts。五、cover/contain原生端的崩溃规避与 rn-web 直通5.1 背景RN 0.85 的原生解析缺陷experimental_backgroundSize上的cover/contain折叠substituteBackgroundSizeKeywordsForNative背后是一个真实且严重的问题。passthrough.ts 的注释记录了完整调查RN 0.85 的BackgroundSize.kt解析器只接受ReadableType.Map{x, y}JS 侧的processBackgroundSize.js却把cover/contain作为裸字符串保留导致原生解析返回 null当所有层的 size 都是关键字形式时得到的列表为空BackgroundImageDrawable.kt在绘制时执行index % size触发ArithmeticException: divide by zero进程被 SIGKILL——用户看到的是应用直接消失。5.2 为何折叠为auto是正确的对渐变而言BackgroundImageDrawable.calculateBackgroundImageSize以imageWidth 容器宽、imageHeight 容器高调用渐变没有固有尺寸当 size 为 null 或两轴均为auto时跳过覆盖分支返回(containerWidth, containerHeight)。因此在渐变上cover ≡ contain ≡ auto——三者都铺满整个元素区域。auto是诚实的折叠它请求渲染器按图像自然尺寸处理而原生侧对无纵横比的图像本就解析为容器填充。字面量100% 100%虽然绘制相同但对未来可能的非渐变图像路径做出了更强也可能误导的尺寸声明。v7 中url()图像路径不经过experimental_*由applyBackgroundBlendModePolyfill直接重建为Image resizeMode。标准backgroundSize键仍保留原始关键字供 rn-web 交给浏览器原生处理cover/contain语义。测试断言passthrough.test.tstransformDecl(background-size, cover) // → { experimental_backgroundSize: auto, backgroundSize: cover } transformDecl(background-size, cover, 50% 50%) // → { experimental_backgroundSize: auto, 50% 50%, backgroundSize: cover, 50% 50% } transformDecl(background-size, 50% 50%) // → { experimental_backgroundSize: 50% 50%, backgroundSize: 50% 50% }一旦 RN 原生解析器能直接处理cover/contain字符串该替换即可移除注释中已标注。5.3 rn-web 的 position 直通与校验器规避react-native-web 的validate.js会在backgroundPosition含多个顶层值时打印console.error并丢弃该 prop。但原生端iOS/Android接受完整的双轴语法。解决方案是不对称双键发射isMultiTokenPositionpassthrough.ts双 token 形式0 0、0% 0%、top left、50% 50%或多层字符串含逗号跳过backgroundPositionrn-web 键只发experimental_backgroundPosition——iOS/Android 仍能收到完整语法单 token 形式center、top、left、0两个键都发。rn-web 因此静默回落到其 CSS 默认值0% 0%——与丢弃非法值后的绘制结果相同且消除了警告。测试 passthrough.test.ts 验证了0 0、50% 50%、top left只发experimental_*键而center双键发射。这正是变更集中0 0、50% 50%、top left在 rn-web 上无警告直通的实现机制。六、渐变中的系统颜色experimental_backgroundImage的结构化改写原生端还有一处精细处理当linear-gradient()的色标使用 CSS 系统颜色关键字时RN 的字符串解析器会拒绝它们processColor失败。为此 backgroundGradientNative.ts 的maybeExpandBackgroundImageSystemColors会在原生端把含系统颜色的线性渐变改写为结构化对象数组{ type: linear-gradient, direction, colorStops }其中颜色经cssColorRawToRnStyleValue折叠为PlatformColor对象仅当确认存在系统颜色时才返回数组否则保持原始字符串。radial-gradient()不参与此改写rn-web 上则始终保留原始字符串交由浏览器解析backgroundGradientNative.ts。七、实践建议与总结综合变更集与源码在 styled-components 的 React Native 场景中书写背景样式时放心使用background简写书写多层渐变、position / size与末层颜色例如background: linear-gradient(to right, rgba(255,255,255,.4), transparent) 50% 50% / cover no-repeat, linear-gradient(to bottom, #ff0000, #0000ff);原生端会正确映射到experimental_*键并折叠语义等价的部分。避免在原生依赖 attachment/origin/clip 视觉结果它们只在 rn-web 上生效原生端忽略并给出开发警告如需background-clip: text请使用专门的文本渲染方案。cover/contain只用于渐变背景原生端折叠为auto等效铺满非渐变图像路径走url()resizeMode的既有机制。重复的分层值放心书写管线会自动折叠规避 rn-web 校验器拒绝center top这类组合也会归一化为top。若需在开发期排查留意native-background-attachment-*、native-background-origin-unsupported、native-background-clip-unsupported、native-conic-gradient-unsupported、native-shorthand-parse等一次性警告标识handlers/background.ts 与 transform/index.ts 中定义。延伸阅读完整的简写注册清单见 shorthands.register.ts透传属性与折叠逻辑见 passthrough.ts单条声明变换的完整派发流程见 transform/index.ts行为验证测试见 passthrough.test.ts。【免费下载链接】styled-componentsFast, expressive styling for React. Server components, client components, streaming SSR, React Native—one API.项目地址: https://gitcode.com/gh_mirrors/st/styled-components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
