Метод Clipboard: read()
Базовая версия 2024 *
Новое
Начиная с июня 2024 года, эта функция работает на последних устройствах и версиях браузеров. Возможно, эта функция не будет работать на старых устройствах или браузерах.
* Некоторые части этой функции могут иметь различный уровень поддержки.
Безопасный контекст: Эта функция доступна только в безопасных контекстах (HTTPS), в некоторых или во всех поддерживающих браузерах.
Метод read() интерфейса Clipboard запрашивает копию содержимого буфера обмена, выполняя возвращаемое значение Promise с данными.
Метод теоретически может возвращать произвольные данные (в отличие от readText(), который может возвращать только текст). Браузеры обычно поддерживают чтение данных в формате текста, HTML и PNG-изображений.
Синтаксис
read() read(formats)
Параметры
formatsНеобязательно-
Необязательный объект со следующими свойствами:
unsanitizedНеобязательно-
Массив
Arrayстрок, содержащих MIME-типы форматов данных, которые не должны быть очищены при чтении из буфера обмена.Некоторые браузеры могут очищать данные буфера обмена при чтении, чтобы предотвратить вставку вредоносных данных в документ. Например, Chrome (и другие браузеры на основе Chromium) очищает HTML-данные, удаляя теги
<script>и другие потенциально опасные данные. Используйте массивunsanitizedдля указания списка MIME-типов, которые не должны очищаться.
Возвращаемое значение
Обещание Promise, которое разрешается массивом объектов ClipboardItem, содержащих содержимое буфера обмена.
Исключения
-
NotAllowedErrorDOMException -
Выбрасывается, если чтение из буфера обмена запрещено.
Соображения безопасности
Чтение из буфера обмена может выполняться только в безопасном контексте.
Дополнительные требования к безопасности описаны в разделе «Соображения безопасности» в обзоре API.
Примеры
Чтение данных изображения из буфера обмена
В этом примере используется метод read() для чтения данных изображения из буфера обмена и вставки их в элемент <img>.
HTML
<img id="source" src="butterfly.jpg" alt="A butterfly" /> <img id="destination" /> <button id="reload" type="button">Reload</button> <p id="log"></p>
CSS
img {
height: 100px;
width: 100px;
margin: 0 1rem;
border: 1px solid black;
}
#reload {
display: block;
margin: 0 1rem;
}
JavaScript
Этот код предоставляет механизм для регистрации любых ошибок в элементе с id log.
const logElement = document.querySelector("#log");
function log(text) {
logElement.innerText = `Error: ${text}`;
}
Мы также добавим код для перезагрузки и очистки примера при нажатии на кнопку «Перезагрузить».
const reload = document.querySelector("#reload");
reload.addEventListener("click", () => {
window.location.reload(true);
});
Остальной код читает буфер обмена при нажатии на целевой элемент и копирует данные изображения в элемент destinationImage. Он регистрирует ошибку, если не может использовать метод read() или если буфер обмена не содержит данных в формате PNG.
const destinationImage = document.querySelector("#destination");
destinationImage.addEventListener("click", pasteImage);
async function pasteImage() {
try {
const clipboardContents = await navigator.clipboard.read();
for (const item of clipboardContents) {
if (!item.types.includes("image/png")) {
throw new Error("Clipboard does not contain PNG image data.");
}
const blob = await item.getType("image/png");
destinationImage.src = URL.createObjectURL(blob);
}
} catch (error) {
log(error.message);
}
}
Результат
Скопируйте изображение бабочки слева, щелкнув правой кнопкой мыши и выбрав «Копировать изображение» в контекстном меню. Затем нажмите на пустое поле справа. Пример получит данные изображения из буфера обмена и отобразит изображение в пустом поле.
Примечание: Если потребуется, предоставьте разрешение для вставки изображения.
Чтение данных из буфера обмена
В этом примере используется метод read() для чтения данных из буфера обмена и регистрации любых данных в буфере обмена.
Это отличается от предыдущей версии тем, что будет отображать текстовые, HTML и изображенные ClipboardItem объекты (а не только изображения).
HTML
<img id="source_jpg" src="butterfly.jpg" alt="JPG butterfly image" /> <div id="destination">Click here to copy clipboard data.</div> <button id="reload" type="button">Reload</button> <p id="log"></p>
CSS
img {
height: 100px;
width: 100px;
margin: 0 1rem;
border: 1px solid black;
}
#destination {
min-height: 300px;
min-width: 90%;
margin: 0 1rem;
border: 1px solid black;
}
#reload {
display: block;
margin: 0 1rem;
}
JavaScript
Этот код предоставляет механизм для регистрации любых ошибок в элементе с id log.
const logElement = document.querySelector("#log");
function log(text) {
logElement.innerText = `Error: ${text}`;
}
Мы также добавим код для перезагрузки и очистки примера при нажатии на кнопку «Перезагрузить».
const reload = document.querySelector("#reload");
reload.addEventListener("click", () => {
window.location.reload(true);
});
Остальной код считывает буфер обмена при нажатии на целевой элемент и отображает каждый элемент ClipboardItem вместе с его MIME-типом. Он регистрирует ошибку, если не может использовать метод read(), или если буфер обмена содержит какой-либо другой MIME-тип.
const destinationDiv = document.querySelector("#destination");
destinationDiv.addEventListener("click", pasteData);
async function pasteData() {
destinationDiv.innerText = ""; //Clear inner text
try {
const clipboardContents = await navigator.clipboard.read();
for (const item of clipboardContents) {
for (const mimeType of item.types) {
const mimeTypeElement = document.createElement("p");
mimeTypeElement.innerText = `MIME type: ${mimeType}`;
destinationDiv.appendChild(mimeTypeElement);
if (mimeType === "image/png") {
const pngImage = new Image(); // Image constructor
pngImage.src = "image1.png";
pngImage.alt = "PNG image from clipboard";
const blob = await item.getType("image/png");
pngImage.src = URL.createObjectURL(blob);
destinationDiv.appendChild(pngImage);
} else if (mimeType === "text/html") {
const blob = await item.getType("text/html");
const blobText = await blob.text();
const clipHTML = document.createElement("pre");
clipHTML.innerText = blobText;
destinationDiv.appendChild(clipHTML);
} else if (mimeType === "text/plain") {
const blob = await item.getType("text/plain");
const blobText = await blob.text();
const clipPlain = document.createElement("pre");
clipPlain.innerText = blobText;
destinationDiv.appendChild(clipPlain);
} else {
throw new Error(`${mimeType} not supported.`);
}
}
}
} catch (error) {
log(error.message);
}
}
Результат
Скопируйте текст или изображение бабочки (JPG) ниже (для копирования изображений щелкните правой кнопкой мыши и выберите «Копировать изображение» в контекстном меню). Выберите указанную ниже рамку, чтобы вставить эту информацию из буфера обмена в рамку.
Примечания:
- Несмотря на то, что изображение бабочки является файлом JPG, при чтении из буфера обмена оно является PNG.
- Если потребуется, предоставьте разрешение для вставки изображения.
- Это может не работать в браузерах на основе Chromium, так как рамке примера не предоставлены разрешения Permissions-Policy
clipboard-readиclipboard-write(требуемые браузерами Chromium).
Чтение неочищенного HTML из буфера обмена
В этом примере параметр formats используется для чтения HTML-данных из буфера обмена и получения кода в исходной форме без предварительной очистки браузером.
HTML
<textarea id="source" rows="5">
<style>h1 {color: red;} p {color: blue;}</style>
<h1>Hello world!</h1>
<p>This is a test.</p>
<script>alert('Hello world!');</script>
</textarea>
<button id="copy">Copy HTML</button>
<button id="paste_normal">Paste HTML</button>
<button id="paste_unsanitized">Paste unsanitized HTML</button>
<textarea id="destination" rows="5"></textarea>
CSS
body {
display: grid;
grid-template-columns: repeat(3, 1fr);
gap: 5px;
}
textarea {
grid-column: 1 / span 3;
}
JavaScript
const copyButton = document.getElementById("copy");
const pasteButton = document.getElementById("paste_normal");
const pasteUnsanitizedButton = document.getElementById("paste_unsanitized");
const sourceTextarea = document.getElementById("source");
const destinationTextarea = document.getElementById("destination");
copyButton.addEventListener("click", async () => {
const text = sourceTextarea.value;
const type = "text/html";
const blob = new Blob([text], { type });
const data = [new ClipboardItem({ [type]: blob })];
try {
await navigator.clipboard.write(data);
} catch (error) {
destinationTextarea.value = `Clipboard write failed: ${error}`;
}
});
async function getHTMLFromClipboardContents(clipboardContents) {
for (const item of clipboardContents) {
if (item.types.includes("text/html")) {
const blob = await item.getType("text/html");
const blobText = await blob.text();
return blobText;
}
}
return null;
}
pasteButton.addEventListener("click", async () => {
try {
const clipboardContents = await navigator.clipboard.read();
const html = await getHTMLFromClipboardContents(clipboardContents);
destinationTextarea.value =
html || "Could not find HTML data in the clipboard.";
} catch (error) {
destinationTextarea.value = `Clipboard read failed: ${error}`;
}
});
pasteUnsanitizedButton.addEventListener("click", async () => {
try {
const clipboardContents = await navigator.clipboard.read({
unsanitized: ["text/html"],
});
const html = await getHTMLFromClipboardContents(clipboardContents);
destinationTextarea.value =
html || "Could not find HTML data in the clipboard.";
} catch (error) {
destinationTextarea.value = `Clipboard read failed: ${error}`;
}
});
Результат
Сначала нажмите кнопку «Копировать HTML», чтобы записать HTML-код из первой области ввода в буфер обмена. Затем нажмите либо кнопку «Вставить HTML», либо кнопку «Вставить неочищенный HTML», чтобы вставить очищенный или неочищенный HTML-код во вторую область ввода.
Спецификации
| Спецификация |
|---|
| Clipboard API и события # dom-clipboard-read |
Совместимость браузеров
| Рабочий стол | Мобильный | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari на IOS | Samsung Internet | WebView Android | |
read |
76Пользователь должен предоставить разрешениеclipboard-read. |
79Пользователь должен предоставить разрешениеclipboard-read. |
127["Этот метод должен вызываться внутри обработчиков событий пользовательских жестов.", "Расширения веб-браузера требуют разрешенияclipboardRead в манифесте для чтения данных. С этим разрешением расширение не требует взаимодействия пользователя и не отображает запрос на вставку.", "Запрос на вставку отображается при чтении буфера обмена. Если буфер обмена содержит контент из того же источника, запрос подавляется."] |
63Пользователь должен предоставить разрешениеclipboard-read. |
13.1 | 76Пользователь должен предоставить разрешениеclipboard-read. |
127["Этот метод должен вызываться внутри обработчиков событий пользовательских жестов.", "Расширения веб-браузера требуют разрешенияclipboardRead в манифесте для чтения данных. С этим разрешением расширение не требует взаимодействия пользователя и не отображает запрос на вставку.", "Запрос на вставку отображается при чтении буфера обмена. Если буфер обмена содержит контент из того же источника, запрос подавляется."] |
54Пользователь должен предоставить разрешениеclipboard-read. |
13.4 | 12.0Пользователь должен предоставить разрешениеclipboard-read. |
76Пользователь должен предоставить разрешениеclipboard-read. |
formats_unsanitized_parameter |
122 | 122 | Нет | 108 | Нет | 122 | Нет | 81 | Нет | 26.0 | 122 |
См. также
© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/read
