Back to Qt.io
Contact Us Blog Download Qt
本页内容

QClipboard Class

QClipboard 类提供了对窗口系统剪贴板的访问。更多内容...

头文件： #include <QClipboard>
CMake： find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake： QT += gui
继承自： QObject

公共类型

enum Mode { Clipboard, Selection, FindBuffer }

公共函数

void clear(QClipboard::Mode mode = Clipboard)
QImage image(QClipboard::Mode mode = Clipboard) const
const QMimeData *mimeData(QClipboard::Mode mode = Clipboard) const
bool ownsClipboard() const
bool ownsFindBuffer() const
bool ownsSelection() const
QPixmap pixmap(QClipboard::Mode mode = Clipboard) const
void setImage(const QImage &image, QClipboard::Mode mode = Clipboard)
void setMimeData(QMimeData *src, QClipboard::Mode mode = Clipboard)
void setPixmap(const QPixmap &pixmap, QClipboard::Mode mode = Clipboard)
void setText(const QString &text, QClipboard::Mode mode = Clipboard)
bool supportsFindBuffer() const
bool supportsSelection() const
QString text(QClipboard::Mode mode = Clipboard) const
QString text(QString &subtype, QClipboard::Mode mode = Clipboard) const

信号

void changed(QClipboard::Mode mode)
void dataChanged()
void findBufferChanged()
void selectionChanged()

详细说明

剪贴板提供了一种在应用程序之间复制和粘贴数据的简单机制。

QClipboard 支持与 `QDrag ` 相同的数据类型，并使用类似的机制。有关剪贴板的高级用法，请阅读“拖放”。

一个应用程序中仅有一个 QClipboard 对象，可通过QGuiApplication::clipboard() 访问。

示例：

QClipboard *clipboard = QGuiApplication::clipboard();
QString originalText = clipboard->text();
// etc.
clipboard->setText(newText);

QClipboard 提供了一些便捷函数来访问常见的数据类型：setText() 允许在应用程序之间交换 Unicode 文本，而setPixmap() 和setImage() 则允许在应用程序之间交换 QPixmaps 和 QImages。setMimeData() 函数具有极高的灵活性：它允许您将任何QMimeData 添加到剪贴板中。 对于上述每个函数，都有相应的获取函数，例如text()、image() 和pixmap()。您可以通过调用clear() 来清空剪贴板。

以下是一个使用这些函数的典型示例：

void DropArea::paste()
{
    const QClipboard *clipboard = QGuiApplication::clipboard();
    const QMimeData *mimeData = clipboard->mimeData();

    if (mimeData->hasImage()) {
        setPixmap(qvariant_cast<QPixmap>(mimeData->imageData()));
    } else if (mimeData->hasHtml()) {
        setText(mimeData->html());
        setTextFormat(Qt::RichText);
    } else if (mimeData->hasText()) {
        setText(mimeData->text());
        setTextFormat(Qt::PlainText);
    } else {
        setText(tr("Cannot display data"));
    }
}

X11 用户须知

  • X11 窗口系统引入了独立的“选择”和“剪贴板”概念。当文本被选中时，它会立即作为全局鼠标选择内容出现。该全局鼠标选择内容随后可被复制到剪贴板中。按惯例，使用鼠标中键可粘贴全局鼠标选择内容。
  • X11 还具有“所有权”的概念；若在某个窗口内更改选区，X11 只会将此变更通知该窗口的所有者和前任所有者，即不会通知所有应用程序选区或剪贴板数据已发生变化。
  • 最后，X11 剪贴板是事件驱动的，即如果事件循环未运行，剪贴板将无法正常工作。同样，建议在直接响应用户输入事件（例如鼠标按钮或按键的按下和释放）时，对剪贴板内容进行存储或检索。 不应通过定时器或非用户输入事件来存储或检索剪贴板内容。
  • 由于在 X11 上尚无在应用程序之间复制和粘贴文件的标准方法，目前正在使用各种 MIME 类型和约定。例如，Nautilus 期望文件采用x-special/gnome-copied-files MIME 类型，且数据以剪切/复制操作、换行符以及文件 URL 开头。

macOS 用户须知

macOS 支持一个独立的查找缓冲区，用于存储“查找”操作中的当前搜索字符串。通过指定FindBuffer 模式，可以访问此查找剪贴板。

Windows 和 macOS 用户注意事项

  • Windows 和 macOS 不支持全局鼠标选区；它们仅支持全局剪贴板，即只有在明确执行复制或剪切操作时，才会将文本添加到剪贴板中。
  • Windows 和 macOS 没有“所有权”的概念；剪贴板是一个完全全局的资源，因此所有应用程序都会收到更改通知。

Android 用户注意事项

在 Android 上仅支持以下 MIME 类型：text/plain、text/html 和 text/uri-list。

另请参阅 QGuiApplication 。

成员类型文档

enum QClipboard::Mode

此枚举类型用于控制QClipboard::mimeData()、QClipboard::setMimeData()及相关函数使用系统剪贴板的哪个部分。

常量常量值描述
QClipboard::Clipboard0表示应从全局剪贴板存储和检索数据。
QClipboard::Selection1表示应从全局鼠标选择区存储和检索数据。仅在具有全局鼠标选择区的系统（例如 X11）上才支持Selection 。
QClipboard::FindBuffer2表示应将数据存储到“查找”缓冲区并从中检索。此模式用于在 macOS 上保存搜索字符串。

另请参阅 QClipboard::supportsSelection()。

成员函数文档

[signal] void QClipboard::changed(QClipboard::Mode mode)

当指定剪贴板mode 的数据发生变化时，会发出此信号。

另请参阅 dataChanged()、selectionChanged() 和findBufferChanged()。

void QClipboard::clear(QClipboard::Mode mode = Clipboard)

清除剪贴板内容。

mode 参数用于控制使用系统剪贴板的哪个部分。如果mode 的值为QClipboard::Clipboard ，则该函数将清除全局剪贴板的内容。如果mode 的值为QClipboard::Selection ，则该函数将清除全局鼠标选择的内容。如果mode 的值为QClipboard::FindBuffer ，则该函数将清除搜索字符串缓冲区。

另请参阅 QClipboard::Mode 和supportsSelection()。

[signal] void QClipboard::dataChanged()

当剪贴板数据发生变化时，会发出此信号。

在 macOS 系统上，且使用 Qt 4.3 或更高版本时，只有当应用程序处于活动状态时，才会检测到其他应用程序对剪贴板所做的更改。

另请参阅 findBufferChanged()、selectionChanged() 和changed()。

[signal] void QClipboard::findBufferChanged()

当查找缓冲区发生变化时，会发出此信号。这仅适用于 macOS。

在 Qt 4.3 及更高版本中，只有当应用程序处于活动状态时，才会检测到其他应用程序对剪贴板所做的更改。

另请参阅 dataChanged()、selectionChanged() 和changed()。

QImage QClipboard::image(QClipboard::Mode mode = Clipboard) const

返回剪贴板中的图像；如果剪贴板中没有图像，或者包含的图像格式不受支持，则返回空图像。

mode 参数用于控制使用系统剪贴板的哪个部分。如果mode 的值为QClipboard::Clipboard ，则从全局剪贴板中获取图像；如果mode 的值为QClipboard::Selection ，则从全局鼠标选择中获取图像。

另请参阅 setImage()、pixmap()、mimeData() 和QImage::isNull()。

const QMimeData *QClipboard::mimeData(QClipboard::Mode mode = Clipboard) const

返回指向当前剪贴板数据QMimeData 表示形式的指针（如果给定的mode 不受平台支持，则可能为nullptr ）。

mode 参数用于控制使用系统剪贴板的哪个部分。如果mode 的QClipboard::Clipboard 为“system-clipboard”，则数据从全局剪贴板中获取；如果mode 的 为“QClipboard::Selection ”，则数据从全局鼠标选择区中获取；如果mode 的 为“QClipboard::FindBuffer ”，则数据从搜索字符串缓冲区中获取。

text()、image() 和pixmap() 函数是用于获取文本、图像和位图数据的更简单的封装函数。

注意： 当剪贴板内容发生变化时（无论是通过调用某个设置函数，还是外部系统剪贴板发生变化），返回的 指针可能会失效。

另请参阅 setMimeData()。

bool QClipboard::ownsClipboard() const

如果该剪贴板对象拥有剪贴板数据，则返回true ；否则返回false 。

bool QClipboard::ownsFindBuffer() const

如果此剪贴板对象拥有查找缓冲区数据，则返回true ；否则返回false 。

bool QClipboard::ownsSelection() const

如果该剪贴板对象拥有鼠标选中数据，则返回true ；否则返回false 。

QPixmap QClipboard::pixmap(QClipboard::Mode mode = Clipboard) const

返回剪贴板的位图，如果剪贴板中不包含位图，则返回 null。请注意，此操作可能会丢失信息。例如，如果图像为 24 位而显示为 8 位，则结果将被转换为 8 位；如果图像具有透明度通道，则结果仅包含蒙版。

mode 参数用于控制系统剪贴板的哪个部分被使用。如果mode 的值为QClipboard::Clipboard ，则从全局剪贴板中获取位图；如果mode 的值为QClipboard::Selection ，则从全局鼠标选择区中获取位图。

另请参阅 setPixmap()、image()、mimeData() 以及QPixmap::convertFromImage()。

[signal] void QClipboard::selectionChanged()

当选择范围发生变化时，会发出此信号。这仅适用于支持选择功能的窗口系统，例如 X11。Windows 和 macOS 不支持选择功能。

另请参阅 dataChanged()、findBufferChanged() 和changed()。

void QClipboard::setImage(const QImage &image, QClipboard::Mode mode = Clipboard)

将image 复制到剪贴板。

参数mode 用于控制使用系统剪贴板的哪个部分。如果mode 的值为QClipboard::Clipboard ，则图像将存储在全局剪贴板中；如果mode 的值为QClipboard::Selection ，则数据将存储在全局鼠标选择区中。

这是以下内容的简写：

QMimeData *data = new QMimeData;
data->setImageData(image);
clipboard->setMimeData(data, mode);

另请参阅 image()、setPixmap() 和setMimeData()。

void QClipboard::setMimeData(QMimeData *src, QClipboard::Mode mode = Clipboard)

将剪贴板数据设置为src 。数据的所有权将转移至剪贴板。若要删除该数据，请调用clear()，或使用新数据再次调用 setMimeData()。

参数mode 用于控制使用系统剪贴板的哪个部分。如果mode 的值为QClipboard::Clipboard ，则数据将存储在全局剪贴板中；如果mode 的值为QClipboard::Selection ，则数据将存储在全局鼠标选择区中；如果mode 的值为QClipboard::FindBuffer ，则数据将存储在搜索字符串缓冲区中。

setText()、setImage() 和setPixmap() 函数分别是用于设置文本、图像和位图数据的更简单的封装函数。

另请参阅 mimeData()。

void QClipboard::setPixmap(const QPixmap &pixmap, QClipboard::Mode mode = Clipboard)

将pixmap 复制到剪贴板。请注意，此操作比setImage() 慢，因为它需要先将QPixmap 转换为QImage 。

参数mode 用于控制使用系统剪贴板的哪个部分。如果mode 设置为QClipboard::Clipboard ，则位图将存储在全球剪贴板中；如果mode 设置为QClipboard::Selection ，则位图将存储在全球鼠标选择区中。

另请参阅 pixmap()、setImage() 和setMimeData()。

void QClipboard::setText(const QString &text, QClipboard::Mode mode = Clipboard)

将text 作为纯文本复制到剪贴板中。

参数mode 用于控制使用系统剪贴板的哪个部分。如果mode 为QClipboard::Clipboard ，则文本将存储在全局剪贴板中。如果mode 为QClipboard::Selection ，则文本将存储在全局鼠标选择区中。如果mode 为QClipboard::FindBuffer ，则文本将存储在搜索字符串缓冲区中。

另请参阅 text() 和setMimeData()。

bool QClipboard::supportsFindBuffer() const

如果剪贴板支持单独的搜索缓冲区，则返回true ；否则返回false 。

bool QClipboard::supportsSelection() const

如果剪贴板支持鼠标选择，则返回 `true `；否则返回 `false`。

QString QClipboard::text(QClipboard::Mode mode = Clipboard) const

返回剪贴板中的文本（以纯文本形式），如果剪贴板中没有文本，则返回空字符串。

mode 参数用于控制使用系统剪贴板的哪个部分。如果mode 的值为QClipboard::Clipboard ，则从全局剪贴板中获取文本；如果mode 的值为QClipboard::Selection ，则从全局鼠标选择区中获取文本；如果mode 的值为QClipboard::FindBuffer ，则从搜索字符串缓冲区中获取文本。

另请参阅 setText() 和mimeData()。

QString QClipboard::text(QString &subtype, QClipboard::Mode mode = Clipboard) const

返回子类型为subtype 的剪贴板文本；如果剪贴板中不包含任何文本，则返回空字符串。如果subtype 为空，则接受任何子类型，且subtype 将被设置为所选子类型。

mode 参数用于控制使用系统剪贴板的哪个部分。如果mode 为QClipboard::Clipboard ，则从全局剪贴板中获取文本；如果mode 为QClipboard::Selection ，则从全局鼠标选区中获取文本。

subtype 的常用取值为“plain”和“html”。

请注意，反复调用此函数（例如在键事件处理程序中）可能会导致运行缓慢。在这种情况下，应改用dataChanged() 信号。

这是一个重载函数。

另请参阅 setText() 和mimeData()。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.