Twin.macro 属性样式化完全指南：从 tw prop 到条件样式、变体与自定义 CSS

• 前端
• 开发工具

Twin.macro 将 Tailwind 的类名体系与 emotion、styled-components 等 css-in-js 方案融合，在编译期把 Tailwind 类直接转换成 CSS 对象。本文是官方 prop 样式指南的深度讲解，覆盖twprop 的基础用法、条件样式、样式覆盖、JSX 整洁化、多值变体、插值约束、任意变体/任意值与自定义 CSS 的完整实践，读完即可在真实组件中落地一套可维护的 Tailwind + css-in-js 样式方案。

Basic styling：用twprop 为 JSX 元素添加 Tailwind 类

Twin 最基础的用法是把 Tailwind 类放进 JSX 元素的twprop，无需任何函数调用：

import 'twin.macro' const Component = () => ( <div tw="flex w-full"> <div tw="w-1/2"></div> <div tw="w-1/2"></div> </div> )

使用要点：

• 适用场景：仅当不需要条件样式时使用twprop，它是静态样式的最高效表达；
• 触发机制：任何来自twin.macro的 import 都会激活twprop 的处理（包括import 'twin.macro'这种副作用式导入）；
• 免导入方案：结合 babel-plugin-twin 可以省略导入语句，直接使用tw和cssprop。

从源码看，twprop 的处理位于 src/macro/tw.ts 的handleTwProperty。当元素上不存在cssprop 时，Twin 直接把tw属性替换为css属性（src/macro/tw.ts）；当元素同时带有cssprop 时，则调用mergeIntoCssAttribute把tw的样式合并进现有的css数组中（src/macro/tw.ts）。类名经由getStyles解析为 CSS 对象后，再用astify生成 AST 节点。

值得注意的错误提示：handleTwProperty中明确断言twprop 只接受纯字符串（如tw="text-black"或tw={"text-black"}），传入表达式会被拒绝并给出修复建议（src/macro/tw.ts）。

Conditional styling：用cssprop 组合数组实现条件样式

当需要根据状态切换样式时，把样式嵌套进数组并用cssprop：

import tw from 'twin.macro' const Component = ({ hasBg }) => ( <div css={[ tw`flex w-full`, // 先写基础样式 hasBg && tw`bg-black`, // 再追加条件样式 ]} > <div tw="w-1/2" /> <div tw="w-1/2" /> </div> )

TypeScript 版本：

import tw from 'twin.macro' interface ComponentProps { hasBg?: string } const Component = ({ hasBg }: ComponentProps) => ( <div css={[ tw`flex w-full`, // Add base styles first hasBg && tw`bg-black`, // Then add conditional styles ]} > <div tw="w-1/2" /> <div tw="w-1/2" /> </div> )

三条关键认知：

• cssprop 的所有权不在 Twin：这个 prop 由你的 css-in-js 库（emotion、styled-components 等）提供，Twin 只负责把tw模板字符串转成这些库能识别的样式对象/数组；
• 数组化组织：把值放进数组，便于在同一位置依次定义基础样式、条件样式和原生 css，优先级由数组顺序自然决定；
• 模板字符串内多行书写：在反引号（template literals）内可以用多行组织类名，源码侧的expandVariantGroups会把换行符归一化为空格后展开（src/core/lib/expandVariantGroups.ts）。

Overriding styles：twprop 后置覆盖

如果元素同时带有cssprop 与twprop，tw会追加在css之后，从而覆盖之前定义的样式：

import tw from 'twin.macro' const Component = () => ( <div css={tw`text-white`} tw="text-black"> Has black text </div> )

这里css={twtext-white}先渲染白色文字，随后tw="text-black"在编译期被合并到css数组的末尾（src/macro/tw.ts 的isBeforeCssAttribute判断决定了tw在数组中的插入位置），最终文字显示为黑色——利用合并顺序实现覆盖。

Keeping jsx clean：把样式提到对象中保持 JSX 整洁

当类名集合变大时，tw字符串会遮挡 JSX 中其他 prop 的可读性。此时可以把样式提升出来，按命名分组放进一个styles对象：

import tw from 'twin.macro' const styles = { container: ({ hasBg }) => [ tw`flex w-full`, // Add base styles first hasBg && tw`bg-black`, // Then add conditional styles ], column: tw`w-1/2`, } const Component = ({ hasBg }) => ( <section css={styles.container({ hasBg })}> <div css={styles.column} /> <div css={styles.column} /> </section> )

TypeScript 版本：

import tw from 'twin.macro' interface ContainerProps { hasBg?: boolean; } const styles = { container: ({ hasBg }: ContainerProps) => [ tw`flex w-full`, // Add base styles first hasBg && tw`bg-black`, // Then add conditional styles ], column: tw`w-1/2`, } const Component = ({ hasBg }: ContainerProps) => ( <section css={styles.container({ hasBg })}> <div css={styles.column} /> <div css={styles.column} /> </section> )

这种模式的收益在于：样式与 JSX 结构解耦，函数型的命名条目（如container）可以接收 props 返回动态数组，静态条目（如column）直接持有tw结果，多个元素可复用同一个样式入口。

Variants with many values：用命名类集合 + prop 驱动多值变体

当某个变体有很多取值（如variant="light/dark/etc"）时，把各类样式放进命名对象，再用 prop 索引取值：

import tw from 'twin.macro' const containerVariants = { // Named class sets light: tw`bg-white text-black`, dark: tw`bg-black text-white`, crazy: tw`bg-yellow-500 text-red-500`, } const styles = { container: ({ variant = 'dark' }) => [ tw`flex w-full`, containerVariants[variant], // Grab the variant style via a prop ], column: tw`w-1/2`, } const Component = ({ variant }) => ( <section css={styles.container({ variant })}> <div css={styles.column} /> <div css={styles.column} /> </section> )

TypeScript 版本可以使用TwStyle类型约束tw块的类型：

import tw, { TwStyle } from 'twin.macro' type WrapperVariant = 'light' | 'dark' | 'crazy' interface ContainerProps { variant?: WrapperVariant } const containerVariants: Record<WrapperVariant, TwStyle> = { // Named class sets light: tw`bg-white text-black`, dark: tw`bg-black text-white`, crazy: tw`bg-yellow-500 text-red-500`, } const styles = { container: ({ variant = 'dark' }: ContainerProps) => [ tw`flex w-full`, containerVariants[variant], // Grab the variant style via a prop ], column: tw`w-1/2`, } const Component = ({ variant }: ContainerProps) => ( <section css={styles.container({ variant })}> <div css={styles.column} /> <div css={styles.column} /> </section> )

TwStyle在 types/index.d.ts 中定义为{ [key: string]: string | number | TwStyle }，递归地描述 CSS 对象结构，可对tw模板字符串的产物做类型标注。利用Record<WrapperVariant, TwStyle>可以让“变体名 → 样式”的映射获得完整的类型检查，未定义的变体名会在编译期直接报错。

Interpolation workaround：Babel 限制与动态值的三种出路

由于 Babel 无法在编译期得知运行时变量的值，Tailwind 类和任意属性都不允许任何一部分被动态拼接。以下写法不会生效：

<div tw="mt-${spacing === 'sm' ? 2 : 4}" /> // Won't work with tailwind classes <div tw="[margin-top:${spacing === 'sm' ? 2 : 4}rem]" /> // Won't work with arbitrary properties

原因正如官方文档所释：babel 不知道变量的值，Twin 也就无法完成到 CSS 的转换。handleTwProperty中的断言逻辑会拦截这类非纯字符串用法并提示改用tw="text-black"形式（src/macro/tw.ts）。

官方推荐以下三种替代方案：

方案一：类定义 + prop 索引

import tw from 'twin.macro' const styles = { sm: tw`mt-2`, lg: tw`mt-4` } const Component = ({ spacing = 'sm' }) => <div css={styles[spacing]} />

方案二：theme导入 + 原生 css 对象

import { theme } from 'twin.macro' // Use theme values from your tailwind config const styles = { sm: theme`spacing.2`, lg: theme`spacing.4` } const Component = ({ spacing = 'sm' }) => ( <div css={{ marginTop: styles[spacing] }} /> )

theme标签模板在 src/macro/theme.ts 的handleThemeFunction中处理：它把theme调用（标签模板或theme('colors.black')函数形式）中的路径解析成来自 Tailwind 配置的具体值，若路径在配置中匹配不到会直接断言报错。

方案三：退回原生 css（可插值任意值）

import 'twin.macro' const Component = ({ width = 5 }) => <div css={{ maxWidth: `${width}rem` }} />

原生 CSS 对象字面量不受编译期限制，可以自由使用运行时插值，是动态尺寸等场景的最终兜底。

Custom selectors：用任意变体书写自定义选择器

方括号形式的任意变体（Arbitrary variants）可以按自定义选择器来定位元素：

import tw from 'twin.macro' const buttonStyles = tw` bg-black [> i]:block [> span]:(text-blue-500 w-10) ` const Component = () => ( <button css={buttonStyles}> <i>Icon</i> <span>Label</span> </button> )

更多示例：

// Style the current element based on a theming/scoping className ;<body className="dark-theme"> <div tw="[.dark-theme &]:(bg-black text-white)">Dark theme</div> </body> // Add custom group selectors ;<button className="group" disabled> <span tw="[.group:disabled &]:text-gray-500">Text gray</span> </button> // Add custom height queries ;<div tw="[@media (min-height: 800px)]:hidden"> This window is less than 800px height </div> // Use custom at-rules like @supports ;<div tw="[@supports (display: grid)]:grid">A grid</div> // Style the current element based on a dynamic className const Component = ({ isLarge }) => ( <div className={isLarge && 'is-large'} tw="text-base [&.is-large]:text-lg"> ... </div> )

这些写法背后的转换逻辑在 src/core/lib/convertClassName.ts 的sassifyArbitraryVariants中实现：它会把无父选择器的任意变体自动补上&（例如[> i]变体推导为子元素选择器，[@media ...]、[@supports ...]这类 at-rule 原样保留），并把逗号分隔的多个选择器转义合并，同时保持 Tailwind 能识别的方括号语法。这也解释了为什么[.group:disabled &]能把「父级.group处于:disabled状态」作为前置条件。

Custom class values：用任意值注入自定义类值

许多动态类（如top-*、mt-*）都支持用方括号注入自定义值：

;<div tw="top-[calc(100vh - 2rem)]" /> // ↓ ↓ ↓ ↓ ↓ ↓ <div css={{ "top": "calc(100vh - 2rem)" }} />

官方还针对任意值给出两个额外细节（见 docs/arbitrary-values.md）：

• 支持空格：Twin 不受classNameprop 的空格限制，tw="h-[calc(1000px - 4rem)]"可以直接书写带空格的值，也可以在多行模板字符串中使用，还能配合变体组first:(h-[calc(1000px - 4rem)] mt-5)；
• 禁止动态值：tw标签模板内的任意值同样不能动态拼接（如tw`mt-[${size === 'lg' ? '22px' : '17px'}]`不会生效），必须写成完整类定义的条件选择：css={[size === 'lg' ? tw`mt-[22px]` : tw`mt-[17px]`]}。

Custom css：从简单样式到高级 Sass 风格样式

基础的自定义 CSS 可以用任意属性（Arbitrary properties）完成，复杂场景则交给原生 css 或css导入。

Simple css styling：任意属性

// Set css variables <div tw="[--my-width-variable:calc(100vw - 10rem)]" /> // Set vendor prefixes <div tw="[-webkit-line-clamp:3]" /> // Set grid areas <div tw="[grid-area:1 / 1 / 4 / 2]" />

任意属性可以和变体或 Twin 的分组特性组合：

<div tw="block md:(relative [grid-area:1 / 1 / 4 / 2])" />

任意属性同样支持tw导入（标签模板形式）：

import tw from 'twin.macro' ;<div css={tw` block md:(relative [grid-area:1 / 1 / 4 / 2]) `} />

两个实用规则：

• 加!前缀可使自定义 css 生效为!important：![grid-area:1 / 1 / 4 / 2]；
• 任意属性支持驼峰命名属性：[gridArea:1 / 1 / 4 / 2]。

分组语法（如md:(...)）的展开逻辑见 src/core/lib/expandVariantGroups.ts：它按分隔符切分类名，把括号内的类逐一追加到前面的变体上，同时把!important的前后置位置归一化。

Advanced css styling：css导入与 Sass 风格语法

cssprop 接受类似 Sass 的语法，允许同时混写自定义 CSS 和带配置值的 Tailwind 样式：

import tw, { css, theme } from 'twin.macro' const Components = () => ( <input css={[ tw`text-blue-500 border-2`, css` -webkit-tap-highlight-color: transparent; /* add css styles */ background-color: ${theme`colors.red.500`}; /* use the theme import to add config values */ &::selection { ${tw`text-purple-500`}; /* style with tailwind classes */ } `, ]} /> )

不过官方建议：用对象形式往往更干净，可以避免上面模板插值带来的语法噪音：

import tw, { css, theme } from 'twin.macro' const Components = () => ( <input css={[ tw`text-blue-500 border-2`, css({ WebkitTapHighlightColor: 'transparent', // css properties are camelCased backgroundColor: theme`colors.red.500`, // values don’t require interpolation '&::selection': tw`text-purple-500`, // single line tailwind selector styling }), ]} /> )

对象形式下：CSS 属性走驼峰命名（WebkitTapHighlightColor），theme值不需要插值直接作为值使用，选择器（'&::selection'）可以一行内嵌套一个tw结果——整个数组依然保持「基础样式在前、扩展样式在后」的顺序。css导入在 src/macro/css.ts 的addCssImport中按需注入：仅当源码里真的使用了css引用且尚未存在同名导入时，才会把css从对应 css-in-js 库导入进来。

深入原理：编译期管线与相关配置项

把以上用法串起来看，Twin 的编译管线大致是：tw/css的 AST 引用（src/macro/tw.ts、src/macro/css.ts）→ 类名字符串交给 src/core/getStyles.ts 解析 → 经convertClassName归一化任意变体/任意值/主题值（src/core/lib/convertClassName.ts）→ 最终产物替换为 css-in-js 库可消费的样式对象。调试时可在 Twin 配置中开启debug: true查看类名转换前后的差异。

几个与本文用法强相关的 Twin 配置项（默认值见 src/core/lib/twinConfig.ts，完整说明见 docs/options.md）：

• dataTwProp/dataCsProp：默认在开发环境为true，把原始类名写入data-tw/data-cs属性便于调试定位，可设为"all"让生产环境也保留；
• sassyPseudo：把hover:这类伪类变体转成&:hover的 Sass 风格，styled-components 与 goober 预设默认开启；
• disableCsProp：默认true，用于关闭过时的csprop；
• moveTwPropToStyled/convertHtmlElementToStyled：solid 与 stitches 预设默认开启，会把twprop 迁移为 styled 组件定义，进一步把样式从 JSX 中移走（对应 src/macro/tw.ts 的moveTwPropToStyled）。

总结：选择哪种样式写法

关联的进阶阅读：Styled component guide（用 styled-components 高效工作的必读指南）、Arbitrary values（任意值语法细节）与 Theming with css variables（css 变量主题化）。

• 前端
• 开发工具