样式

如何使用 Radix Themes 进行样式处理。

介绍

Radix Themes 不带有内置的样式系统。没有 css 或 sx 属性，也不在内部使用任何样式库。从底层来看，它是用原生 CSS 构建的。

在为您的应用选择样式技术时，没有额外负担。

您能得到什么

Radix Themes 中的组件相对封闭——它们配有一套样式，这些样式不总是容易覆盖。它们可以在其属性和主题配置允许的范围内进行自定义。

不过，您还可以访问驱动 Radix Themes 组件的 CSS 变量。您可以使用这些令牌创建自定义组件，使其在原主题中感觉自然而舒服。对令牌系统的更改会被视为破坏性更改。

有关特定令牌的更多信息，请参阅 主题部分 中的相应指南。

覆盖样式

除了简单的样式覆盖，我们建议您按原样使用组件，或者使用相同的构建块创建自己的版本。

大多数组件都有 className 和 style 属性，但如果您发现自己需要覆盖很多样式，这很可能是一个信号，表明您应当：

• 尝试使用现有属性和主题配置实现所需效果。
• 查看您是否可以通过调整底层令牌系统来实现您的设计。
• 使用低级构建块创建自己的组件，比如 Primitives 和 Colors。
• 考虑 Radix Themes 是否适合您的项目。

Tailwind

Tailwind 非常出色。然而，如果您计划将 Radix Themes 与 Tailwind 一起使用，请注意其使用便利性可能会鼓励您即时创建复杂样式，有时无缝进入组件内部。

Tailwind 是一种不同的样式范式，可能与使用属性、令牌和在共享构建块之上创建新组件来实现自定义的封闭组件系统的理念不太兼容。

自定义组件

如果您需要创建一个自定义组件，请使用 Radix Themes 使用的相同构建块：

• 支持组件的 主题 令牌
• Radix Primitives，一个可访问的无样式组件库
• Radix Colors，一个用于构建精美网站和应用的色彩系统

随时探索 源代码 以了解 Radix Themes 是如何构建的。

常见问题

z-index 冲突

开箱即用的 Radix Themes 组件可以嵌套并以任意顺序堆叠而不会发生冲突。例如，您可以打开一个弹出框，该弹出框又打开一个对话框，而这个对话框又打开另一个弹出框。它们会按打开的顺序堆叠在一起：

在构建自己的组件时，使用以下规则以避免 z-index 冲突：

• 不要在极少数情况下使用 z-index 值以外的 auto，0 或 -1。
• 将应该堆叠在一起的元素呈现在 portal 中。

您的主内容和门户内容由于根 <Theme> 组件创建的堆叠上下文而分隔开。这使您能够在不担心 z-index 的情况下将门户内容堆叠在主内容之上。

Next.js 导入顺序

在 Next.js 13.0 到 14.1 版本之间，app/**/layout.tsx 中 CSS 文件的导入顺序并不保证，因此 Radix Themes 可能会覆盖您自己的样式，即使它们已正确编写：

import "@radix-ui/themes/styles.css";
import "./my-styles.css";

这个 Next.js 问题可能时隐时现，或者仅在开发或生产中发生。

作为解决方法，您可以首先通过 postcss-import 将所有 CSS 合并到一个文件中，然后仅将该文件导入到布局中。或者，也可以直接在 page.tsx 文件中导入样式。

Tailwind 基础样式

在 Tailwind v3 版本中，通过 @tailwind 指令生成的样式通常会在任何导入的 CSS 后面追加，无论原始的导入顺序如何。特别是，Tailwind 的 按钮重置 样式可能会干扰 Radix Themes 按钮，使某些按钮没有背景颜色。

解决方法：

• 不要使用 @tailwind base
• 为 Tailwind 和 Radix Themes 设置单独的 CSS 层
• 设置 postcss-import 并在 Radix Themes 样式之前手动导入 Tailwind 基础样式，使用 @import tailwindcss/base。 示例设置

门户中缺失的样式

当您在 Radix Themes 项目中呈现自定义门户时，它自然会出现在根 <Theme> 组件之外，这意味着它无法访问大多数主题令牌和样式。要修复此问题，请用另一个 <Theme> 包裹门户内容：

// 低级 Dialog 原语使用的自定义对话框的实现示例
// 参考 https://www.radix-ui.com/primitives/docs/components/dialog
import { Dialog } from "radix-ui";
import { Theme } from "@radix-ui/themes";

function MyCustomDialog() {
	return (
		<Dialog.Root>
			<Dialog.Trigger>打开</Dialog.Trigger>
			<Dialog.Portal>
				<Theme>
					<Dialog.Overlay />
					<Dialog.Content>
						<Dialog.Title />
						<Dialog.Description />
						<Dialog.Close />
					</Dialog.Content>
				</Theme>
			</Dialog.Portal>
		</Dialog.Root>
	);
}

Radix Themes 中的 Dialog 和 Popover 等组件已经为您处理了这件事，因此在创建自己的门户组件时，这仅是必要的。

复杂的 CSS 优先级

通常，您希望自定义 CSS 覆盖 Radix Themes 样式。然而，有些情况下，您可能会自然地期望出现相反的情况。

考虑一个简单的段落样式，该样式只是重置浏览器的默认边距：

.my-paragraph {
	margin: 0;
}

您可能通过 asChild 从 Box 应用边距属性到自定义段落：

import "@radix-ui/themes/styles.css";
import "./my-styles.css";

function MyApp() {
	return (
		<Theme>
			<Box asChild m="5">
				<p className="my-paragraph">我的自定义段落</p>
			</Box>
		</Theme>
	);
}

然而，这样并不会直观地工作。自定义样式在 Radix Themes 样式之后导入，因此它们将覆盖边距属性。作为解决方法，Radix Themes 提供了单独的 tokens.css、components.css 和 utilities.css 文件，这些文件是原始 styles.css 构建的基础：

import "@radix-ui/themes/tokens.css";
import "@radix-ui/themes/components.css";
import "@radix-ui/themes/utilities.css";

您可以在自定义样式之后导入 utilities.css，以确保布局属性与自定义样式按预期工作。然而，如果您使用 Next.js，请记住上面提到的 导入顺序问题。

如果您使用 独立布局组件，也可以为它们提供分开的 CSS 文件：

import "@radix-ui/themes/layout/tokens.css";
import "@radix-ui/themes/layout/components.css";
import "@radix-ui/themes/layout/utilities.css";