样式

如何使用 Radix 主题进行样式设计。

简介

Radix 主题没有内置的样式系统。没有 css 或 sx 属性，并且它在内部不使用任何样式库。在幕后，它使用的是原生 CSS。

在为您的应用程序选择样式技术时没有额外开销。

您获得的内容

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

但是，您还可以访问与 Radix 主题组件相同的 CSS 变量。您可以使用这些标记创建自定义组件，这些组件在原始主题中自然显得和谐。对标记系统所做的更改将被视为重大更改。

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

覆盖样式

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

大多数组件确实具有 className 和 style 属性，但是如果您发现自己需要覆盖很多样式，这可能表明您应该

• 尝试使用现有的属性和主题配置来实现您的需求。
• 看看您是否可以通过调整底层标记系统来实现您的设计。
• 使用更低级别的构建块创建您自己的组件，例如 基本元素 和 颜色。
• 重新考虑 Radix 主题是否适合您的项目。

Tailwind

Tailwind 很棒。但是，如果您计划将 Radix 主题与 Tailwind 一起使用，请记住其人体工程学可能会鼓励您动态创建复杂的样式，有时会无缝地进入组件内部。

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

自定义组件

如果您需要创建自定义组件，请使用 Radix 主题使用的相同构建块

• 主题 标记，为组件提供动力
• Radix 基本元素，一个包含无样式可访问组件的库
• Radix 颜色，一个用于构建精美网站和应用程序的颜色系统

随时探索 源代码 来了解 Radix 主题是如何构建的。

常见问题

z-index 冲突

开箱即用，传送门式的 Radix 主题组件可以以任何顺序嵌套和堆叠，而不会发生冲突。例如，您可以打开一个弹出框，该弹出框会打开一个对话框，该对话框又会打开另一个弹出框。它们都按照打开的顺序彼此叠加。

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

• 不要使用除 auto、0 或 在极少数情况下为 -1 以外的 z-index 值。
• 将应该彼此叠加的元素渲染到传送门中。

您的主要内容和传送门式内容通过根 <Theme> 组件的样式创建的堆叠上下文来隔开。这使您可以将传送门式内容叠加在主要内容之上，而无需担心 z-index。

Next.js 导入顺序

从 Next.js 13.0 到 14.1 开始，app/**/layout.tsx 中 CSS 文件的导入顺序不受保证，因此即使编写正确，Radix 主题也可能会覆盖您自己的样式。

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

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

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

Tailwind 基础样式

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

解决方法

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

门户中缺少样式

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

// Implementation example of a custom dialog using the low-level Dialog primitive
// Refer to https://www.radix-ui.com.cn/primitives/docs/components/dialog
import * as Dialog from '@radix-ui/react-dialog';
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 主题中的 Dialog 和 Popover 等组件已经为您处理了这个问题，因此只有在创建您自己的门户组件时才需要这样做。

复杂的 CSS 优先级

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

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

.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 主题样式之后导入的，因此它们将覆盖 margin 属性。作为解决方法，Radix 主题提供了单独的 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';