企业官网建设流程全解析

styled-components：text-overflow、direction 与 outline 的跨端一致性（React Native / rn-web / Web）

【免费下载链接】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-text-overflow-and-direction-mirror.md 变更记录，深入解析一次面向 React Native 的 CSS 能力对齐：text-overflow: ellipsis | clip在 iOS、Android 与 Web 上全线可用；direction: ltr | rtl | inherit通过双向文本（bidi-aware）在级联中传播，无需额外属性；同时明确outline中hidden关键字的边界。读完本文，你将掌握这三个 CSS 特性在 styled-components 各端（Web、rn-web、原生 React Native）中的真实支持情况、底层转换原理与开发期警告行为。

背景：styled-components 的一次 minor 变更

.changeset/目录存放着 styled-components 发布时的变更集（changeset）。native-text-overflow-and-direction-mirror.md 声明：

'styled-components': minor

即该变更以minor 版本（向后兼容的新能力）进入发布。全文共三条：

1. CSStext-overflow: ellipsis | clip在每个目标端（Web、React Native、rn-web）都受支持；并建议与line-clamp或text-wrap: nowrap搭配，让内容真正溢出。
2. direction: ltr | rtl | inherit遵循级联，作用于所有目标端的双向文本，无需再设置第二个 prop。
3. 包含hidden关键字的outline声明（如outline: 2px hidden red）不受支持，会在开发模式发出警告后丢弃——因为hidden并非 CSS UI 规范中的合法 outline 样式；移除 outline 应使用outline: none。

目标端划分：Web、React Native 与 rn-web

要理解该变更，必须先分清 styled-components 的编译目标。源码中反复出现__NATIVE_WEB__这个编译期标志：

• Web（浏览器）：CSS 由浏览器原生解析，text-overflow、direction、outline全部按 CSS 规范执行。
• rn-web（React Native Web）：同样由浏览器解析样式，__NATIVE_WEB__为真，多数声明直接透传。
• 原生 React Native（iOS / Android）：CSS 需要被转换成 RN 的 style 对象（如ellipsizeMode、direction、outlineStyle），这是本次变更的主体。

textOverflow.ts 的注释明确写到：rn-web 对每一种形式都输出原始text-overflow值（浏览器实现了完整语法），而ellipsizeMode的提升（lift）是native-only的。

text-overflow：把 CSS 溢出语法映射到 RN 的 ellipsizeMode

CSS Overflow 4 语法 vs RN 能力

React Native 的Text组件只有ellipsizeMode，可取'head'、'middle'、'tail'、'clip'，只能作用于文本末尾边缘。而 CSS 的text-overflow语法（textOverflow.ts 注释，源自 CSS Overflow 4 §4.1）：

text-overflow = [ clip | ellipsis | <string> | fade | <fade()> ]{1,2}

• 一个值时作用于行尾边缘；
• 两个值时，第一个作用于行首（line-left），第二个作用于行尾（line-right）；
• RN 只建模末端边缘，因此两值形式取**第二个（LTR 下的行尾）**值。

逐值的降级映射

polyfills 测试 polyfills.test.ts 中覆盖的映射关系如下：

fade与<string>属于 Level 4 形式（textOverflow.ts 的parseOne：Ident 命中clip/ellipsis/fade，String 命中<string>，Function 命中fade()），RN 无法精确实现，因此在开发模式下会触发一次性警告warnOnce('native-text-overflow-l4', ...)，提示"iOS 和 Android 只在末尾边缘做 clip 或 ellipsis 截断"，并建议要精确匹配就使用clip或ellipsis。

实践：让内容真正溢出

变更说明特别强调：text-overflow只有在内容实际溢出时才可见，所以要搭配：

import styled from 'styled-components/native'; const Truncated = styled.Text` overflow: hidden; white-space: nowrap; /* 或 text-wrap: nowrap */ text-overflow: ellipsis; `;

在 rn-web 上，styled-components 会为text-overflow: ellipsis生成white-space: nowrap基线（web-bridge 测试 web-bridge.test.tsx 验证了numberOfLines与text-overflow的联动，并确认作者书写的text-overflow: clip可以覆盖 rn-web 的基线 ellipsis）。line-clamp或text-wrap: nowrap二者取一即可，让文本保持单行并溢出到截断点。

源码定位：注册机制

polyfill 通过register('textOverflow', textOverflowShorthand)注册（textOverflow.ts），进入shorthands.ts的注册表，在 native 编译管线（compileNative.ts）中被调用。这也解释了为什么它被称为 "textOverflow" 而不是传统意义上的简写属性——它把一条 CSS 声明整体转换为 RN 的 style 键。

direction：级联中的双向文本支持

从"透传"到"级联"

此前，native-direction-passthrough.md 已经以 patch 形式支持了direction: ltr | rtl。本次 minor 变更把direction提升为随级联传播的书写方向，并补充inherit关键字：

direction: ltr | rtl | inheritfollows the cascade through bidi-aware text on every target without having to set a second prop.

这意味着：一个声明了direction的组件，其解析值会传给后代，后代的text-align: start | end、逻辑属性（margin-inline-start、padding-inline-end等）都会依据该方向解析，不需要再为子组件单独传 prop。

底层：NativeCascadeValues.direction

级联方向的载体是 NativeStyleContext.ts 中的NativeCascadeValues接口：

export interface NativeCascadeValues { /** Parent's resolved font-size in px. Anchors `em` resolution. */ fontSize: number; /** Parent's resolved line-height in px. Anchors `lh` resolution. */ lineHeight: number; /** Root font size; anchors `rem` and `rlh`. */ rootFontSize: number; /** * Inherited writing direction. Anchors `text-align: start | end` * resolution under horizontal-tb. */ direction: 'ltr' | 'rtl'; ... }

默认值见同文件的DEFAULT_CASCADE（direction: 'ltr'，字体 16px / 行高 24px / 根字号 16px）。direction 与font-size、line-height一起，构成 styled-components 原生端自定义级联的核心字段——这一点在另一个相关变更 native-cascade-em-lh-direction-aware-text-align.md 中也有印证：text-align: start | end | match-parent在 LTR/RTL 两种书写方向下都能正确解析，且声明了font-size、line-height、direction的组件会把解析值传给后代。

与逻辑属性的协同

由于direction参与级联，同一套声明可以同时服务 LTR 与 RTL 布局。例如：

import styled from 'styled-components/native'; const Card = styled.View` direction: rtl; /* 整个卡片区域切换为从右到左 */ padding-inline-start: 16px; /* 在 RTL 下表现为右侧内边距 */ margin-inline-end: 8px; /* 在 RTL 下表现为左侧外边距 */ text-align: start; /* 解析为右对齐 */ `;

在 iOS、Android、Web（rn-web）上表现一致，无需为 RTL 额外写一套样式或 prop。

outline：hidden 关键字不被支持并触发警告

为什么hidden不合法

CSS UI 规范中，outline-style的取值集合（auto、solid、dotted、dashed、double、groove、ridge、inset、outset、none）不包含hidden——hidden只对border-style合法。因此outline: 2px hidden red在规范层面就是无效声明。

styled-components 的 native 管线对此的处理：

• outline 简写（border.ts 中的outlineShorthand）在解析到hidden样式时，开发模式发出warnOnce('native-outline-style-hidden', ...)："outline: hiddenis invalid CSS;hiddenis not a legal outline style. Useoutline-style: noneto remove the outline."
• outline-style 长属性（logicalBorder.ts 中的outlineStyleHandler）对hidden同样发出warnOnce('native-outline-style-hidden-invalid', ...)并返回空对象，即该声明被丢弃。

原生端 outline 的真实能力边界

同一份源码还揭示了 RN 端 outline 的完整边界（logicalBorder.ts）：

const RN_OUTLINE_STYLES = new Set(['solid', 'dotted', 'dashed']); const WEB_ONLY_OUTLINE_STYLES = new Set(['auto', 'double', 'groove', 'ridge', 'inset', 'outset']);

• 原生 RN（iOS/Android）只渲染solid/dotted/dashed三种 outline 样式；
• auto、double、groove等 Web 专属样式会被忽略，并发出native-outline-style警告；
• outline-style: none被映射为{ outlineStyle: 'solid', outlineWidth: 0 }（宽度为 0，视觉上即移除）；
• outline: none简写（border.ts）映射为{ outlineWidth: 0, outlineStyle: 'solid', outlineColor: 'transparent' }；
• RN 0.85 已注册outlineOffset长属性，通过 passthrough.ts 独立透传（简写处理器不解析 offset）。

所以变更说明给出的建议非常明确：要移除 outline，请使用outline: none（或outline-style: none），而不是outline: hidden。

正确的移除方式

// ❌ 不合法：hidden 不是合法的 outline-style 值，会被丢弃并触发 dev 警告 const Bad = styled.View` outline: 2px hidden red; `; // ✅ 正确：显式关闭 outline const Good = styled.View` outline: none; `;

在 Web / rn-web 上，浏览器同样认为outline: hidden无效；统一使用outline: none才能保证所有目标端行为一致。

测试验证与可复现依据

• text-overflow 映射：polyfills.test.ts 的text-overflow spec compliance (CSS Overflow 4 §4.1)用例群，逐条断言transformDecl('text-overflow', ...)的 native 与 rn-web 输出。
• rn-web 联动：web-bridge.test.tsx 验证numberOfLines、text-overflow与resizeMode的组件 prop 映射。
• outline 警告：polyfills.test.ts 与transform测试中覆盖native-outline-style、native-outline-style-hidden-invalid等警告路径。
• 级联 direction：NativeStyleContext.ts 的DEFAULT_CASCADE与text-align: start | end解析逻辑（参见 native-cascade-em-lh-direction-aware-text-align.md 的说明）。

开发者若需验证，可运行仓库中 jest 相关配置（packages/styled-components/jest.config.native.js等）执行上述测试文件。

小结

这次 minor 变更把三个 CSS 细节能力带到了每个目标端：

1. text-overflow：ellipsis | clip全端支持；Level 4 形式（字符串、fade、两值形式）在原生端降级为ellipsizeMode并在 dev 下给出一次性警告。
2. direction：ltr | rtl | inherit参与级联传播，配合逻辑属性与text-align: start | end，一套声明即可服务 LTR/RTL 双方向布局。
3. outline：hidden关键字非法，开发模式警告后丢弃；移除 outline 请用outline: none。

这些行为都能在仓库源码（textOverflow.ts、border.ts、logicalBorder.ts、NativeStyleContext.ts）与对应测试中逐条找到依据，是"一次编写、多端一致"的又一实例。 </output_article>

【免费下载链接】styled-componentsFast, expressive styling for React. Server components, client components, streaming SSR, React Native—one API.项目地址: https://gitcode.com/gh_mirrors/st/styled-components