Back to Qt.io
Contact Us Blog Download Qt

QClipboard Class

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

Header： #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 = QApplication::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 没有所有权的概念；剪贴板是完全全局的资源，因此所有应用程序都会收到更改通知。

安卓用户注意事项

安卓系统只支持以下 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 上和使用 4.3 或更高版本的 Active Qt 时，只有在激活应用程序时才能检测到其他应用程序对剪贴板所做的更改。

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

[signal] void QClipboard::findBufferChanged()

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

使用 4.3 或更高版本的 Qt，只有在激活应用程序时，才能检测到其他应用程序对剪贴板所做的更改。

另请参阅 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 ，数据将从全局剪贴板获取。如果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 位；如果图像有 alpha 通道，则结果只有一个掩码。

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()。

© 2025 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.