样式

如何使用 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 冲突

开箱即用，portalled Radix Themes 组件可以任意顺序嵌套和堆叠，而不会发生冲突。例如，您可以打开一个弹出框，该弹出框会打开一个对话框，而该对话框又会打开另一个弹出框。它们都按照打开的顺序相互堆叠在顶部

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

• 除非在极少数情况下，否则不要使用 auto、0 或 -1 以外的 z-index 值。
• 在 portals 中渲染应该相互堆叠的元素。

您的主要内容和 portalled 内容由根 <Theme> 组件的样式创建的堆叠上下文分隔。这允许您将 portalled 内容堆叠在主要内容之上，而无需担心 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 的 button reset 样式可能会干扰 Radix Themes 按钮，从而导致某些按钮在没有背景颜色的情况下渲染。

解决方法

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

portals 中缺少样式

当您在 Radix Themes 项目中渲染自定义 portal 时，它自然会出现在根 <Theme> 组件之外，这意味着它将无法访问大多数主题标记和样式。要解决此问题，请用另一个 <Theme> 包裹 portal 内容

// Implementation example of a custom dialog using the low-level Dialog primitive
// Refer to https://radix-ui.com.cn/primitives/docs/components/dialog
import { Dialog } from "radix-ui";
import { Theme } from "@radix-ui/themes";

function MyCustomDialog() {
	return (
		<Dialog.Root>
			<Dialog.Trigger>Open</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 等组件已经为您处理了这个问题，因此这仅在创建您自己的 portalled 组件时才是必要的。

复杂的 CSS 优先级

通常，您希望您的自定义 CSS 覆盖 Radix Themes 样式。但是，在某些情况下，期望相反的情况是很自然的。

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

.my-paragraph {
	margin: 0;
}

您可能会通过 asChild 将 Box 的 margin 属性应用于您的自定义段落

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

function MyApp() {
	return (
		<Theme>
			<Box asChild m="5">
				<p className="my-paragraph">My custom paragraph</p>
			</Box>
		</Theme>
	);
}

然而，这不会直观地工作。自定义样式是在 Radix Themes 样式之后导入的，因此它们将覆盖 margin 属性。作为一种解决方法，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";