#Vext JSCSS

#目录导航

• 何时使用 JSCSS
• 跑通第一个组件样式
• 构建后如何进入浏览器
• 常见样式任务
• CSS Variables：构建期声明与浏览器改值
• 配置怎么选
• 排错

#何时使用 JSCSS

Vext JSCSS 会在构建期把 TypeScript 对象转换为 CSS class。组件需要有名字的 variants、语义化 CSS variables 或嵌套规则，同时希望浏览器最终加载的是 CSS 而不是 CSS-in-JS runtime 时，就使用它。

按需求选择最小的工具：

Vext 不会编译 Sass 或 SCSS 源文件。如果团队继续使用 Sass，请先在交给 Vext 前编译为 CSS。JSCSS 不是 Sass 的替代品；它是 Vext 内置的、面向组件的类型化生成 CSS 路径。

#跑通第一个组件样式

推荐先走这一条路径：在 *.style.ts 中定义有名字的 recipe，然后在 React 的 className 中调用它。

#1. 定义按钮 recipe

创建 src/frontend/styles/button.style.ts。

import { createVar, recipe } from "vextjs/style";

const colorText = createVar("color-text", "#111827");
const colorPrimary = createVar("color-primary", "#2563eb");
const colorDanger = createVar("color-danger", "#dc2626");

export const button = recipe({
  name: "button",
  base: {
    borderRadius: 8,
    padding: "8px 12px",
    border: 0,
    color: colorText,
  },
  variants: {
    intent: {
      primary: { backgroundColor: colorPrimary },
      danger: { backgroundColor: colorDanger },
    },
  },
  defaultVariants: { intent: "primary" },
});

recipe() 的 base 和 variants 接收的是 rule object。style() 已经返回 class-name 字符串，因此不要在 recipe 内写成 base: style({ ... }) 或 primary: style({ ... })。给 recipe 设置 name，在检查 HTML 或 CSS 时就能识别生成的 class。

#2. 在 React 组件中使用 recipe

创建 src/frontend/components/Button.tsx。

import type { ReactNode } from "react";
import { button } from "../styles/button.style";

export function Button(props: {
  intent?: "primary" | "danger";
  children: ReactNode;
}) {
  return (
    <button className={button({ intent: props.intent ?? "primary" })}>
      {props.children}
    </button>
  );
}

button({ intent: "primary" }) 会返回 base class 和匹配的 variant class。因为示例设置了默认 variant，所以没有选择时调用 button() 也会得到 primary 按钮。

#3. 从页面渲染它

import { Button } from "@components/Button";

export default function SettingsPage() {
  return <Button intent="danger">删除项目</Button>;
}

#构建后如何进入浏览器

执行正常的生产构建：

npm run build

Vext 会发现 src/frontend/** 下匹配 *.style.ts、*.style.js 和 *.css.ts 的文件，在构建期执行其中的样式声明，并将收集到的规则写入生成的 JSCSS CSS。生成的 browser entry 会引用该 CSS，最终 client asset manifest 会把它带入渲染文档。

这条路径不需要默认引入 Emotion 或 styled-components runtime。style() 或 recipe() 返回的 className 就是 React 与抽取 CSS 之间的连接。

*.style.ts 模块在 Node 构建步骤中执行，因此它应当只放声明；不要在模块顶层读取 window、document、请求数据或 server-only service。

#常见样式任务

#生成一个有名字的 class

只有一个 class 时使用 style()：

import { style } from "vextjs/style";

export const card = style(
  {
    padding: 16,
    borderRadius: 12,
    backgroundColor: "white",
  },
  { name: "card" },
);

在 CSS 期望长度的属性上，数字会转为像素值；opacity、zIndex、fontWeight 等无单位属性会保持无单位。

#加入 hover 和 media 规则

嵌套 selector 使用 &，at-rule 仍放在同一个对象中：

export const card = style(
  {
    padding: 12,
    "&:hover": { transform: "translateY(-1px)" },
    "@media (min-width: 640px)": { padding: 16 },
  },
  { name: "card" },
);

#在渲染期选择 variant

有限的视觉选择使用 recipe。选择名应描述组件含义（如 intent、size、state），不要照搬原始 CSS 值。

<Button intent={isDestructive ? "danger" : "primary"}>保存</Button>

#CSS Variables：构建期声明与浏览器改值

createVar() 创建语义化 CSS custom-property 引用。setVar() 返回可放进 JSCSS rule 的对象；它本身不会修改浏览器 document。

import { createVar, setVar, style, vars } from "vextjs/style";

export const accent = createVar("accent", "#4f46e5");

export const panel = style(
  {
    ...vars(setVar(accent, "#4f46e5")),
    borderColor: accent,
  },
  { name: "panel" },
);

上面的例子会在抽取 CSS 中生成初始声明和 var(--vext-accent, #4f46e5)。如果值需要在 hydration 后变化，请在事件处理器或 effect 中使用标准浏览器 CSS API，不要在样式模块或 SSR render 中执行：

document.documentElement.style.setProperty(accent.name, "#7c3aed");

#配置怎么选

JSCSS 默认已经启用。只有在明确的交付约束下才需要改变设置：

完整字段和默认值请查看 前端配置。

#排错

下一步：对比 样式与资源 了解其它受支持的样式路径；需要调节 JSCSS 抽取时阅读 前端配置。