样式

¥Styling

如何使用 Radix Themes 进行样式设置。

简介

¥Introduction

Radix Themes 没有内置样式系统。没有 css 或 sx 属性，并且它内部不使用任何样式库。底层使用原生 CSS 构建。

¥Radix Themes does not come with a built-in styling system. There’s no css or sx prop, and it does not use any styling libraries internally. Under the hood, it’s built with vanilla CSS.

为你的应用选择样式技术时无需任何额外开销。

¥There’s no overhead when it comes to picking a styling technology for your app.

你获取

¥What you get

Radix 主题中的组件相对封闭 - 它们带有一组不易覆盖的样式。它们可以在其属性和主题配置允许的范围内进行自定义。

¥The components in Radix Themes are relatively closed—they come with a set of styles that aren’t always easily overridden. They are customizable within what’s allowed by their props and the theme configuration.

然而，你也可以访问 Radix Themes 组件所使用的 CSS 变量。你可以使用这些令牌创建与原始主题自然契合的自定义组件。对令牌系统的更改将被视为中断。

¥However, you also get access to the same CSS variables that power the Radix Themes components. You can use these tokens to create custom components that naturally feel at home in the original theme. Changes to the token system are treated as breaking.

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

¥For more information on specific tokens, refer to the corresponding guides in the Theme section.

覆盖样式

¥Overriding styles

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

¥Beyond simple style overrides, we recommend using the components as-is, or create your own versions using the same building blocks.

大多数组件确实有 className 和 style props，但如果你发现自己需要覆盖大量样式，则表明你应该：

¥Most components do have className and style props, but if you find yourself needing to override a lot of styles, it’s a good sign that you should either:

• 尝试使用现有的 props 和主题配置来实现你的需求。

  ¥Try to achieve what you need with the existing props and theme configuration.

• 看看你是否可以通过调整底层令牌系统来实现你的设计。

  ¥See whether you can achieve your design by tweaking the underlying token system.

• 使用更底层的构建块（例如 基础组件 和 颜色）创建你自己的组件。

  ¥Create your own component using lower-level building blocks, such Primitives and Colors.

• 重新考虑 Radix 主题是否适合你的项目。

  ¥Reconsider whether Radix Themes is the right fit for your project.

Tailwind

Tailwind 很棒。但是，如果你计划将 Radix Themes 与 Tailwind 结合使用，请记住，其人机工程学设计可能会鼓励你即时创建复杂的样式，有时甚至可以轻松深入组件内部。

¥Tailwind is great. Yet, if you plan to use Radix Themes with Tailwind, keep in mind how its ergonomics may encourage you to create complex styles on the fly, sometimes reaching into the component internals without friction.

Tailwind 是一种不同的样式范例，它可能与封闭组件系统的理念不太相符。在封闭组件系统中，定制是通过属性、令牌以及在一组共享的构建块之上创建新组件来实现的。

¥Tailwind is a different styling paradigm, which may not mix well with the idea of a closed component system where customization is achieved through props, tokens, and creating new components on top of a shared set of building blocks.

自定义组件

¥Custom components

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

¥If you need to create a custom component, use the same building blocks that Radix Themes uses:

• 支持组件的 主题 令牌

  ¥Theme tokens that power the components

• Radix 基础组件，一个可访问、无样式组件库

  ¥Radix Primitives, a library of accessible, unstyled components

• Radix 颜色，一个用于构建美观网站和应用的颜色系统

  ¥Radix Colors, a color system for building beautiful websites and apps

欢迎探索 Radix Themes 的 源代码，了解其构建方式。

¥Feel free to explore the source code of Radix Themes to see how it is built.

常见问题

¥Common issues

z-index 冲突

¥z-index conflicts

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

¥Out of the box, portalled Radix Themes components can be nested and stacked in any order without conflicts. For example, you can open a popover that opens a dialog, which in turn opens another popover. They all stack on top of each other in the order they were opened:

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

¥When building your own components, use the following rules to avoid z-index conflicts:

• 在极少数情况下，请勿使用除 auto、0 或 -1 以外的 z-index 值。

  ¥Don’t use z-index values other than auto, 0, or -1 in rare cases.

• 渲染门户中应堆叠的元素。

  ¥Render the elements that should stack on top of each other in portals.

你的主内容和门户内容由根 <Theme> 组件的样式创建的堆叠上下文分隔。这使你可以将门户内容堆叠在主内容之上，而无需担心 z 索引。

¥Your main content and portalled content are separated by the stacking context that the styles of the root <Theme> component create. This allows you to stack portalled content on top of the main content without worrying about z-indices.

Next.js 导入顺序

¥Next.js import order

从 Next.js 13.0 到 14.1 版本开始，app/**/layout.tsx 中 CSS 文件的导入顺序无法保证，因此即使编写正确，Radix Themes 也可能会覆盖你自己的样式：

¥As of Next.js 13.0 to 14.1, the import order of CSS files in app/**/layout.tsx is not guaranteed, so Radix Themes may overwrite your own styles even when written correctly:

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

此 Next.js 问题可能偶尔出现，或仅在开发或生产过程中发生。

¥This Next.js issue may come and go sporadically, or happen only in development or production.

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

¥As a workaround, you can merge all the CSS into a single file first via postcss-import and import just that into your layout. Alternatively, importing the styles directly in page.tsx files also works.

Tailwind 基础样式

¥Tailwind base styles

从 Tailwind v3 开始，由 @tailwind 指令生成的样式通常会附加在任何导入的 CSS 之后，无论原始导入顺序如何。特别是，Tailwind 的 按钮重置 样式可能会干扰 Radix 主题按钮，导致某些按钮渲染时没有背景色。

¥As of Tailwind v3, styles produced by the @tailwind directive are usually appended after any imported CSS, no matter the original import order. In particular, Tailwind’s button reset style may interfere with Radix Themes buttons, rendering certain buttons without a background color.

解决方法：

¥Workarounds:

• 请勿使用 @tailwind base

  ¥Don’t use @tailwind base

• 为 Tailwind 和 Radix 主题设置单独的 CSS layers

  ¥Set up separate CSS layers for Tailwind and Radix Themes

• 设置 postcss-import，并在 Radix Themes 样式之前通过 @import tailwindcss/base 手动导入 Tailwind 基本样式。示例设置

  ¥Set up postcss-import and manually import Tailwind base styles via @import tailwindcss/base before Radix Themes styles. Example setup

门户中缺少样式

¥Missing styles in portals

在 Radix Themes 项目中渲染自定义门户时，它会自然地出现在根 <Theme> 组件之外，这意味着它无法访问大多数主题标记和样式。要解决此问题，请使用另一个 <Theme> 封装门户网站内容：

¥When you render a custom portal in a Radix Themes project, it will naturally appear outside of the root <Theme> component, which means it won’t have access to most of the theme tokens and styles. To fix that, wrap the portal content with another <Theme>:

// Implementation example of a custom dialog using the low-level Dialog primitive
// Refer to 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>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 等组件已经为你处理了这些，因此只有在创建你自己的门户组件时才需要这样做。

¥Components like Dialog and Popover in Radix Themes already handle this for you, so this is only necessary when creating your own portalled components.

复杂的 CSS 优先级

¥Complex CSS precedence

通常，你希望你的自定义 CSS 覆盖 Radix Themes 样式。然而，在某些情况下，我们自然会期待相反的结果。

¥Usually, you’d want your custom CSS to override Radix Themes styles. However, there are cases when it is natural to expect the opposite.

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

¥Consider a simple paragraph style that just resets the browser’s default margin:

.my-paragraph {
	margin: 0;
}

你可以通过 asChild 将 Box 的 margin 属性应用到你的自定义段落上：

¥You might apply the margin prop from a Box onto your custom paragraph via asChild:

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 正是基于这些文件构建的：

¥Yet, this won’t work intuitively. The custom styles are imported after Radix Themes styles, so they will override the margin prop. As a workaround, Radix Themes provides separate tokens.css, components.css, and utilities.css files that the original styles.css is built upon:

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

你可以在自定义样式之后导入 utilities.css，以确保布局属性能够与你的自定义样式一起正常工作。但是，如果你使用 Next.js，请记住上面提到的 import order issue。

¥You can import utilities.css after your custom styles to ensure that the layout props work as expected with your custom styles. However, if you use Next.js, keep in mind the import order issue that’s mentioned above.

如果你使用 独立布局组件，也可以使用拆分的 CSS 文件：

¥If you use standalone layout components, split CSS files are also available for them:

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