这是 StyleX 用户界面的样式系统的快速参考指南备忘单
StyleX 是一个 CSS In JS 的用户界面的样式系统
import plg from '@stylexjs/rollup-plugin';
const config = () => ({
plugins: [
plg({ ...options })
]
})
export default config;
import * as React from 'react';
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({ ... });
const colorStyles = stylex.create({ ... });
在 React 中使用
function ReactDemo(
{ color,isActive,style }
) {
return (
<div {...stylex.props(
styles.main,
// 有条件地应用样式
isActive && styles.active,
// 根据属性选择样式变体
colorStyles[color],
// 将样式作为 props 传递
style,
)}
/>
);
}
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
root: {
width: '100%',
maxWidth: 800,
minHeight: 40,
},
});
样式是使用对象语法和 create()
API 定义的
npm install --save @stylexjs/stylex
npm install --save-dev @stylexjs/rollup-plugin
修改 Rollup 配置 rollup.config.js
import stylexPlugin from '@stylexjs/rollup-plugin';
const config = {
input: './index.js',
output: {
file: './.build/bundle.js',
format: 'es',
},
// 确保在 Babel 之前使用 stylex 插件
plugins: [stylexPlugin({
// 必需项。生成的 CSS 文件的文件路径。
fileName: './.build/stylex.css',
// 默认值:false
dev: false,
// 所有生成的类名的前缀
classNamePrefix: 'x',
// CSS 变量支持所必需
unstable_moduleResolution: {
// 类型:'commonJS' | 'haste'
// 默认值:'commonJS'
type: 'commonJS',
// 项目根目录的绝对路径
rootDir: __dirname,
},
})],
};
export default config;
npm install --save-dev @stylexjs/babel-plugin
修改 Babel 配置 (babel.config.js)
import styleX from '@stylexjs/babel-plugin';
const config = {
plugins: [
[styleX, {
dev: true,
// 设置为 true 以进行快照测试
// 默认值:false
test: false,
// CSS 变量支持所必需
unstable_moduleResolution: {
// 类型:'commonJS' | 'haste'
// 默认值:'commonJS'
type: 'commonJS',
// 项目根目录的绝对路径
rootDir: __dirname,
}
}],
],
};
export default config;
npm install --save-dev @stylexjs/webpack-plugin
修改 Webpack 配置 webpack.config.js
const StylexPlugin = require('@stylexjs/webpack-plugin');
const path = require('path');
const config = (env, argv) => ({
entry: {
main: './src/index.js',
},
output: {
path: path.resolve(__dirname, '.build'),
filename: '[name].js',
},
module: {
rules: [
{
test: /\.js$/,
exclude: /node_modules/,
use: 'babel-loader',
},
],
},
plugins: [
// 确保在 Babel 之前使用 stylex 插件
new StylexPlugin({
filename: 'styles.[contenthash].css',
// 获取 webpack 的模式并为开发设置值
dev: argv.mode === 'development',
// 使用静态生成的 CSS 文件,而不是运行时注入的 CSS。
// 即使在开发环境中也是如此。
runtimeInjection: false,
// 可选的。默认值:'x'
classNamePrefix: 'x',
// CSS 变量支持所必需
unstable_moduleResolution: {
// 类型:'commonJS' | 'haste'
// 默认值:'commonJS'
type: 'commonJS',
// 项目根目录的绝对路径
rootDir: __dirname,
},
}),
],
cache: true,
});
module.exports = config;
npm install --save-dev @stylexjs/nextjs-plugin \
@stylexjs/babel-plugin rimraf
在 package.json
添加配置
{
"scripts": {
...,
"predev": "rimraf .next",
"prebuild": "rimraf .next"
}
}
修改 Babel 配置 .babelrc.js
module.exports = {
presets: ["next/babel"],
plugins: [
[
"@stylexjs/babel-plugin", {
dev: process.env.NODE_ENV === "development",
test: process.env.NODE_ENV === "test",
runtimeInjection: false,
genConditionalClasses: true,
treeshakeCompensation: true,
unstable_moduleResolution: {
type: "commonJS",
rootDir: __dirname,
},
},
],
],
};
修改 Next.js 配置 next.config.mjs
/** @type {import('next').NextConfig} */
import stylexPlugin from "@stylexjs/nextjs-plugin";
const nextConfig = {};
const __dirname = new URL(".", import.meta.url).pathname;
export default stylexPlugin({
rootDir: __dirname,
})(nextConfig);
要开始使用 StyleX
而无需配置编译器和构建过程,您可以安装本地开发运行时
npm install --save-dev @stylexjs/dev-runtime
开发运行时必须导入到应用程序的 JavaScript
入口点并进行配置
import inject from '@stylexjs/dev-runtime';
inject({
classNamePrefix: 'x',
dev: true,
test: false,
});
npm install --save-dev @stylexjs/eslint-plugin
StyleX 编译器不会验证您的样式,并且会编译许多无效样式。当您创作样式时,您应该使用 ESLint 插件来捕获这些错误。修改 ESLint 配置 .eslintrc.js
module.exports = {
plugins: ["@stylexjs"],
rules: {
"@stylexjs/valid-styles": "error",
},
};
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
base: {
fontSize: 16,
lineHeight: 1.5,
color: 'rgb(60,60,60)',
},
highlighted: {
color: 'rebeccapurple',
},
});
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
button: {
backgroundColor: 'lightblue',
},
});
样式名为 button
的背景样式上添加 :hover
和 :active
伪类
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
button: {
backgroundColor: {
default: 'lightblue',
':hover': 'blue',
':active': 'darkblue',
},
},
});
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
input: {
// 伪元素
'::placeholder': {
color: '#999',
},
color: {
default: '#333',
// 伪类
':invalid': 'red',
},
},
});
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
base: {
width: {
default: 800,
'@media (max-width: 800px)': '100%',
'@media (min-width: 1540px)': 1366,
},
},
});
同样,媒体查询也可以作为样式值中的 "条件"
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
button: {
color: {
default: 'var(--blue-link)',
':hover': {
default: null,
'@media (hover: hover)': 'scale(1.1)',
},
':active': 'scale(0.9)',
},
},
});
当您需要组合媒体查询和伪选择器时,嵌套超过一层
.header {
position: fixed;
position: -webkit-sticky;
position: sticky;
}
使用 firstThatWorks
函数来实现相同的目的
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
header: {
position: stylex.firstThatWorks('sticky', '-webkit-sticky', 'fixed'),
},
});
import * as stylex from '@stylexjs/stylex';
const fadeIn = stylex.keyframes({
from: {opacity: 0},
to: {opacity: 1},
});
const styles = stylex.create({
base: {
animationName: fadeIn,
animationDuration: '1s',
},
});
使用 stylex.keyframes()
函数来定义关键帧动画
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
// 函数参数必须是简单标识符
// -- 不允许解构或默认值
bar: (height) => ({
height,
// 函数体必须是对象字面量
// -- 不允许使用 { return {} }
}),
});
function MyComponent() {
// `height` 的值在编译时不能确定。
const [height, setHeight] = useState(10);
return <div {...stylex.props(styles.bar(height))} />;
}
注意:动态样式是一项高级功能,应谨慎使用。对于大多数用例,条件样式应该足够了。
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
base: {
fontSize: 16,
lineHeight: 1.5,
color: 'grey',
},
highlighted: {
color: 'rebeccapurple',
},
});
<div {...stylex.props(
styles.base, styles.highlighted
)}
/>;
如果样式的顺序颠倒,文本将为灰色
<div {...stylex.props(
styles.highlighted, styles.base
)}
/>
<div
{...stylex.props(
styles.base,
props.isHighlighted && styles.highlighted,
isActive ? styles.active : styles.inactive,
)}
/>
通过使用常见的 JavaScript 模式(例如三元表达式和 &&
运算符),可以在运行时有条件地应用样式。 stylex.props
忽略虚假值,例如 null
、undefined
或 false
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
violet: {
backgroundColor: {
default: 'blueviolet',
':hover': 'darkviolet',
},
color: 'white',
},
gray: {
backgroundColor: {
default: 'gainsboro',
':hover': 'lightgray',
},
},
// ... more variants here ...
});
然后,通过使用 variant
属性作为样式对象上的键来应用适当的样式
function Button({variant, ...props}) {
return (
<button {...props}
{...stylex.props(styles[variant])}
/>
);
}
<CustomComponent style={styles.base} />
stylex.props
函数返回具有 className
和 style
的对象。当样式要合并到组件内时不要使用它:
// ❌ 不要这样使用! ⚠️
<CustomComponent
style={stylex.props(styles.base)}
/>
<CustomComponent
style={[
styles.base,
isHighlighted && styles.highlighted
]}
/>
import * as stylex from '@stylexjs/stylex';
// Local Styles
const styles = stylex.create({
base: {
/*...*/
},
});
function CustomComponent({style}) {
return (
<div
{...stylex.props(styles.base, style)}
/>
);
}
将其与 stylex.props
函数一起应用
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
base: {
color: null,
},
});
将样式属性设置为 null
会删除 StyleX 之前为其应用的任何样式。
import * as stylex from '@stylexjs/stylex';
// 可以使用常量来避免重复媒体查询
const DARK = '@media (prefers-color-scheme: dark)';
export const colors = stylex.defineVars({
primaryText: {default: 'black', [DARK]: 'white'},
secondaryText: {default: '#333', [DARK]: '#ccc'},
accent: {default: 'blue', [DARK]: 'lightblue'},
background: {default: 'white', [DARK]: 'black'},
lineColor: {default: 'gray', [DARK]: 'lightgray'},
});
import * as stylex from '@stylexjs/stylex';
export const tokens = stylex.defineVars({
primaryText: 'black',
secondaryText: '#333',
borderRadius: '4px',
fontFamily: 'system-ui, sans-serif',
fontSize: '16px',
});
这定义了 HTML 文档的 :root
处的变量。它们可以作为常量导入并在 stylex.create
调用中使用。
import * as stylex from '@stylexjs/stylex';
// 可以使用常量来避免重复媒体查询
const DARK = '@media (prefers-color-scheme: dark)';
export const colors = stylex.defineVars({
primaryText: {default: 'black', [DARK]: 'white'},
secondaryText: {default: '#333', [DARK]: '#ccc'},
accent: {default: 'blue', [DARK]: 'lightblue'},
background: {default: 'white', [DARK]: 'black'},
lineColor: {default: 'gray', [DARK]: 'lightgray'},
});
export const spacing = stylex.defineVars({
none: '0px',
xsmall: '4px',
small: '8px',
medium: '12px',
large: '20px',
xlarge: '32px',
xxlarge: '48px',
xxxlarge: '96px',
});
然后就可以像这样导入和使用这些样式:
import * as stylex from '@stylexjs/stylex';
import {colors, spacing} from '../tokens.stylex';
const styles = stylex.create({
container: {
color: colors.primaryText,
backgroundColor: colors.background,
padding: spacing.medium,
},
});
变量必须定义在 .stylex.js
文件中,变量必须位于具有以下扩展名之一的文件中:
变量必须命名为 exports
// ✅ - 命名导出
export const colors = stylex.defineVars({
/* ... */
});
const sizeVars = { ... };
// ✅ - 另一个命名导出
export const sizes = stylex.defineVars(sizeVars);
不允许:
// ❌ - 只允许命名导出
export default stylex.defineVars({
/* ... */
});
// ❌ - 变量必须直接导出
const x = stylex.defineVars({
/* ... */
});
export const colors = x;
// ❌ - 变量不能嵌套在另一个对象内部
export const colors = {
foregrounds: stylex.defineVars({
/* ... */
}),
backgrounds: stylex.defineVars({
/* ... */
}),
};
import * as stylex from '@stylexjs/stylex';
import {colors, spacing} from './tokens.stylex';
// 可以使用常量来避免重复媒体查询
const DARK = '@media (prefers-color-scheme: dark)';
// Dracula 主题
export const dracula = stylex.createTheme(colors, {
primaryText: {default: 'purple', [DARK]: 'lightpurple'},
secondaryText: {default: 'pink', [DARK]: 'hotpink'},
accent: 'red',
background: {default: '#555', [DARK]: 'black'},
lineColor: 'red',
});
应用主题,主题对象类似于使用 stylex.create()
创建的样式对象。使用 stylex.props()
将它们应用于元素,以覆盖该元素及其所有后代的变量。
<div {...stylex.props(dracula, styles.container)}>
{children}
</div>;
stylex.createTheme()
创建,并在文件或组件之间传递import * as stylex from '@stylexjs/stylex';
export const tokens = stylex.defineVars({
primaryTxt: stylex.types.color('black'),
secondaryTxt: stylex.types.color('#333'),
borderRadius: stylex.types.length('4px'),
angle: stylex.types.angle('0deg'),
int: stylex.types.integer(2),
});
所有值都可以是任意字符串。要将类型分配给变量,可以使用适当的类型函数包装它们
/// tokens.stylex.js
import * as stylex from '@stylexjs/stylex';
export const colors = stylex.defineVars({
primaryText: stylex.types.color({
default: 'black', [DARK]: 'white'
}),
});
用法保持不变,以上内容完全有效
// tokens.stylex.js
import * as stylex from '@stylexjs/stylex';
import {tokens} from './tokens.stylex.js';
export const high = stylex.defineVars({
primaryTxt: stylex.types.color('black'),
secondaryTxt: stylex.types.color('#222'),
borderRadius: stylex.types.length('8px'),
angle: stylex.types.angle('0deg'),
int: stylex.types.integer(4),
});
当在 stylex.defineVars
中使用特定类型声明变量时,静态类型将强制在 stylex.createTheme
调用中为该变量设置主题时使用相同类型的函数
import * as stylex from '@stylexjs/stylex';
import {tokens} from './tokens.stylex';
const rotate = stylex.keyframes({
from: { [tokens.angle]: '0deg' },
to: { [tokens.angle]: '360deg' },
});
const styles = stylex.create({
gradient: {
backgroundImage: `conic-gradient(from ${tokens.angle}, ...colors)`,
animationName: rotate,
animationDuration: '10s',
animationTimingFunction: 'linear',
animationIterationCount: 'infinite',
},
})
可以通过对其中使用的角度进行动画处理来对渐变进行动画处理
现代浏览器开始支持 CSS 中的 round() 函数。
const styles = stylex.create({
gradient: {
// Math.floor
[tokens.int]: `calc(16 / 9)`
// Math.round
[tokens.int]: `calc((16 / 9) + 0.5)`
},
})
该功能通过一个整数类型的变量来模拟
import type {StyleXStyles} from '@stylexjs/stylex';
import * as stylex from '@stylexjs/stylex';
type Props = {
...
style?: StyleXStyles,
};
function MyComponent(
{ style, ...otherProps }: Props
) {
return (
<div
{...stylex.props(
localStyles.foo,
localStyles.bar, style
)}
>
{/* ... */}
</div>
);
}
import type {StyleXStylesWithout} from '@stylexjs/stylex';
import * as stylex from '@stylexjs/stylex';
type NoLayout = StyleXStylesWithout<{
position: unknown,
display: unknown,
top: unknown,
start: unknown,
end: unknown,
bottom: unknown,
border: unknown,
borderWidth: unknown,
borderBottomWidth: unknown,
borderEndWidth: unknown,
borderStartWidth: unknown,
borderTopWidth: unknown,
margin: unknown,
marginBottom: unknown,
marginEnd: unknown,
marginStart: unknown,
marginTop: unknown,
padding: unknown,
paddingBottom: unknown,
paddingEnd: unknown,
paddingStart: unknown,
paddingTop: unknown,
width: unknown,
height: unknown,
flexBasis: unknown,
overflow: unknown,
overflowX: unknown,
overflowY: unknown,
}>;
type Props = {
// ...
style?: NoLayout,
};
function MyComponent({style, ...}: Props) {
return (
<div
{...stylex.props(localStyles.foo, localStyles.bar, style)}
>
{/* ... */}
</div>
);
}
此处对象类型中列出的属性将被禁止,但所有其他样式仍将被接受。
import type {StyleXStyles} from '@stylexjs/stylex';
type Props = {
// ...
style?: StyleXStyles<{
color?: string;
backgroundColor?: string;
borderColor?: string;
borderTopColor?: string;
borderEndColor?: string;
borderBottomColor?: string;
borderStartColor?: string;
}>;
};
import type {StyleXStyles} from '@stylexjs/stylex';
type Props = {
...
// 只接受 marginTop 的样式,其他不接受。
// marginTop 的值只能是 0、4、8 或 16。
style?: StyleXStyles<{
marginTop: 0 | 4 | 8 | 16
}>,
};
import * as stylex from '@stylexjs/stylex';
export const vars = stylex.defineVars({
color: 'red',
backgroundColor: 'blue',
});
export type Vars = typeof vars;
/*
Vars = VarGroup<{
color: string,
backgroundColor: string,
}>
*/
VarGroup 是调用 stylex.defineVars
生成的对象的类型。它将键映射到 CSS 自定义属性的引用
import type {StaticStyles} from '@stylexjs/stylex';
type Props = {
// ...
style?: StaticStyles<{
color?: 'red' | 'blue' | 'green';
padding?: 0 | 4 | 8 | 16 | 32;
backgroundColor?: string;
borderColor?: string;
borderTopColor?: string;
borderEndColor?: string;
borderBottomColor?: string;
borderStartColor?: string;
}>;
};
不允许使用函数定义的动态样式
import type {VarGroup} from '@stylexjs/stylex';
import * as stylex from '@stylexjs/stylex';
import {vars} from './vars.stylex';
export const theme: Theme<typeof vars> = stylex.createTheme(vars, {
color: 'red', // OK
backgroundColor: 'blue', // OK
});