简介

这不是组件库。它是你构建组件库的方式。

¥This is not a component library. It is how you build your component library.

你知道大多数传统组件库是如何工作的：你从 NPM 安装包、导入组件并在你的应用中使用它们。

¥You know how most traditional component libraries work: you install a package from NPM, import the components, and use them in your app.

这种方法效果很好，直到你需要自定义组件以适合你的设计系统或需要库中未包含的组件。通常，你最终会封装库组件，编写解决方法来覆盖样式，或者混合来自具有不兼容 API 的不同库的组件。

¥This approach works well until you need to customize a component to fit your design system or require one that isn’t included in the library. Often, you end up wrapping library components, writing workarounds to override styles, or mixing components from different libraries with incompatible APIs.

这就是 shadcn/ui 旨在解决的问题。它围绕以下原则构建：

¥This is what shadcn/ui aims to solve. It is built around the following principles:

• 开放代码：组件代码的顶层可供修改。

  ¥Open Code: The top layer of your component code is open for modification.

• 构图：每个组件都使用一个通用的可组合接口，使其可预测。

  ¥Composition: Every component uses a common, composable interface, making them predictable.

• 分发：扁平文件模式和命令行工具使分发组件变得容易。

  ¥Distribution: A flat-file schema and command-line tool make it easy to distribute components.

• 漂亮的默认值：精心选择的默认样式，让你开箱即用，获得出色的设计。

  ¥Beautiful Defaults: Carefully chosen default styles, so you get great design out-of-the-box.

• AI-Ready：开放代码供 LLM 阅读、理解和改进。

  ¥AI-Ready: Open code for LLMs to read, understand, and improve.

打开代码

¥Open Code

shadcn/ui 为你提供实际的组件代码。你可以完全控制自定义和扩展组件以满足你的需求。这意味着：

¥shadcn/ui hands you the actual component code. You have full control to customize and extend the components to your needs. This means:

• 完全透明：你可以清楚地看到每个组件是如何构建的。

  ¥Full Transparency: You see exactly how each component is built.

• 轻松定制：修改组件的任何部分以满足你的设计和功能要求。

  ¥Easy Customization: Modify any part of a component to fit your design and functionality requirements.

• AI 集成：访问代码使 LLM 能够直接阅读、理解甚至改进你的组件。

  ¥AI Integration: Access to the code makes it straightforward for LLMs to read, understand, and even improve your components.

在典型的库中，如果你需要更改按钮的行为，则必须覆盖样式或封装组件。使用 shadcn/ui，你只需直接编辑按钮代码即可。

¥In a typical library, if you need to change a button’s behavior, you have to override styles or wrap the component. With shadcn/ui, you simply edit the button code directly.

组合

¥Composition

shadcn/ui 中的每个组件都共享一个通用的可组合接口。如果某个组件不存在，我们会将其引入，使其可组合，并调整其样式以匹配和与设计系统的其余部分配合使用。

¥Every component in shadcn/ui shares a common, composable interface. If a component does not exist, we bring it in, make it composable, and adjust its style to match and work with the rest of the design system.

共享、可组合的界面意味着你的团队和 LLM 都可以预测它。你无需为每个新组件学习不同的 API。即使对于第三方也是如此。

¥A shared, composable interface means it's predictable for both your team and LLMs. You are not learning different APIs for every new component. Even for third-party ones.

分发

¥Distribution

shadcn/ui 也是一个代码分发系统。它定义了组件的架构和用于分发它们的 CLI。

¥shadcn/ui is also a code distribution system. It defines a schema for components and a CLI to distribute them.

• 架构：定义组件、其依赖和属性的扁平文件结构。

  ¥Schema: A flat-file structure that defines the components, their dependencies, and properties.

• CLI:一个命令行工具，用于在具有跨框架支持的项目之间分发和安装组件。

  ¥CLI: A command-line tool to distribute and install components across projects with cross-framework support.

你可以使用模式将组件分发到其他项目，或者让 AI 根据现有模式生成全新的组件。

¥You can use the schema to distribute your components to other projects or have AI generate completely new components based on existing schema.

漂亮的默认值

¥Beautiful Defaults

shadcn/ui 附带了大量精心选择的默认样式的组件。它们被设计成单独使用时看起来不错，并能作为一个一致的系统很好地协同工作：

¥shadcn/ui comes with a large collection of components that have carefully chosen default styles. They are designed to look good on their own and to work well together as a consistent system:

• 开箱即用：你的 UI 具有干净简约的外观，无需额外工作。

  ¥Good Out-of-the-Box: Your UI has a clean and minimal look without extra work.

• 统一设计：组件自然地相互契合。每个组件都与其他组件匹配，保持 UI 一致。

  ¥Unified Design: Components naturally fit with one another. Each component is built to match the others, keeping your UI consistent.

• 易于定制：如果你想更改某些内容，覆盖和扩展默认值很简单。

  ¥Easily Customizable: If you want to change something, it's simple to override and extend the defaults.

AI-Ready

shadcn/ui 的设计使 AI 工具可以轻松地使用你的代码。它的开放代码和一致的 API 允许 AI 模型读取、理解甚至生成新组件。

¥The design of shadcn/ui makes it easy for AI tools to work with your code. Its open code and consistent API allow AI models to read, understand, and even generate new components.

AI 模型可以了解你的组件的工作方式并提出改进建议，甚至可以创建与你现有设计集成的新组件。

¥An AI model can learn how your components work and suggest improvements or even create new components that integrate with your existing design.