---
title: "集成 Tiptap UI 组件"
description: "使用我们的预构建模板之一或集成单个组件来设置 Tiptap UI 组件。更多内容见文档！"
canonical_url: "https://tiptap.zhcndoc.com/ui-components/getting-started/overview"
---

# 集成 Tiptap UI 组件

使用我们的预构建模板之一或集成单个组件来设置 Tiptap UI 组件。更多内容见文档！

Tiptap 是无头且模块化的，赋予你对 UI 的完全控制权。Tiptap UI 组件库提供预构建界面，因此你无需从零构建所有内容。你可以直接使用它们，或根据你的需求进行自定义。

> **React 19 和框架兼容性:**
>
> 我们目前正在升级对 React 19 及更新框架版本的支持。一些组件可能还未完全兼容。目前，UI 组件在 **React 18**（以及对应的框架版本如 **Next.js 15**）下表现最佳。我们将在新版本完全支持后更新此页面。

[模板使用包含常用功能的预构建编辑器快速开始。](https://tiptap.zhcndoc.com/ui-components/templates/simple-editor.md)

[组件已经在使用 Tiptap ？只引入你需要的部分。](https://tiptap.zhcndoc.com/ui-components/components/overview.md)

## 许可和源代码

Tiptap 的 [UI 组件](https://tiptap.zhcndoc.com/ui-components/components/overview.md) 遵循它们所基于的 [编辑器扩展](https://tiptap.zhcndoc.com/editor/extensions/overview.md) 的相同许可协议。

- 如果扩展是开源的（例如 Bold、Heading 或 Image），则 UI 组件也是 MIT 许可的。
- 你可以自由查看源代码、复制并根据自己的需要自定义。

部分组件构建于付费 **Tiptap 功能** 之上，例如评论或版本历史。

- 这些组件 **不是** 开源的。
- 大多数包含依赖于 Tiptap 后端服务的前端逻辑。
- 需要 Tiptap Cloud 订阅或试用才能使用它们。

无论是免费组件还是云端连接组件，你都可以查看源代码并根据你的需求进行调整。

> **Tiptap Cloud 功能:**
>
> 我们将从开源组件开始。针对 Tiptap Cloud 功能的组件将逐步推出。

## 组件的安装方式

Tiptap UI 组件不会作为 npm 包发布。[CLI](https://tiptap.zhcndoc.com/ui-components/getting-started/cli.md) 会将它们作为你拥有并可编辑的源文件复制到你的项目中：

```bash
npx @tiptap/cli@latest add <component>
```

每个组件还会自动拉取其依赖的其他组件、hooks、icons、libs 和 styles。这就是为什么已安装组件的 imports（例如 `@/components/tiptap-node/image-node/image-node-extension`）会解析到你自己代码库中的文件，而不是 `node_modules` 中的模块。要获得本页面演示所使用的全部内容，请使用上述命令安装对应的组件或模板；每个组件页面都会在 **Referenced Components** 下列出其引用的文件。

## 设计默认值

组件设计风格简洁自然，能够融入你的设计。它们采用中性色调：极简颜色、基础间距，没有强烈的视觉倾向。你可以直接使用，或按照你的品牌风格进行定制。

设计在所有组件中保持一致和协调，因此如果你同时使用多个组件，它们将自然匹配，无需额外调整。

- 不需要复杂的覆盖或 `!important` 技巧
- 直接编辑代码即可，因为它们被设计成可被分叉或扩展

## 组件与低阶组件

为了在你的 Tiptap 编辑器中构建出色的编辑体验，你可以集成 UI 元素。该库提供了不同类型的构建块：**组件**、**节点组件** 和 **低阶组件**。

### 组件

现成的、功能特定的 React 组件，比如标题下拉菜单。每个 UI 组件通常会配合一个 Tiptap 扩展（例如，**ListButton** 依赖于列表相关扩展），并使用 React 钩子与编辑器状态进行交互。

- **与扩展配合使用**：要使用某个组件（例如 `HeadingDropdownMenu`），确保编辑器中启用了对应的 Tiptap 扩展（如 `@tiptap/extension-heading`）。
- **利用钩子**：许多组件内部使用钩子（如 `useTiptapEditor` 或 `useFloatingElement`）来同步编辑器状态、处理位置或管理键盘导航。你也可以在自定义组件中使用这些钩子。
- **易于定制**：默认情况下，这些组件拥有简约的样式，可以融入你的设计。你可以完全覆盖或扩展它们。每个组件的源代码公开可用，可直接编辑，无需 `!important` 技巧。

### 低阶组件

低级别的 UI 元素，如 `Button`、`DropdownMenu`、`Popover` 和 `Spacer`。它们是许多 UI 组件的基础，负责处理无障碍支持和基本行为。你可以将这些低阶组件混合搭配，创建自己的编辑器控件或进一步定制现有组件。