Главная / Action Script 3
Пакетflash.desktop
Классpublic class Clipboard
НаследованиеClipboard Inheritance Object

Язык версии : ActionScript 3.0
Версии среды выполнения:  10, 1.0

Класс Clipboard предоставляет контейнер для передачи данных и объектов через буфер обмена и во время выполнения операций перетаскивания (только AIR). Получить доступ к буферу обмена ОС можно через статическое свойство generalClipboard.

В объекте Clipboard одна и та же хранимая информация может быть в различных форматах. Такая организация хранения данных предусмотрена для обеспечения максимальной совместимости с различными приложениями. Для добавления данных в объект Clipboard, используйте метод setData() или setDataHandler().

Стандартными форматами являются следующие:

Константы этих форматов заданы в классе ClipboardFormats.

Если передача выполняется между Flash Player или приложением AIR и операционной системой, преобразование стандартных форматов между типами данных JavaScript ActionScript и системным буфером обмена происходит автоматически.

Для добавления объектов JavaScript ActionScript в объект Clipboard можно использовать форматы, определенные приложением. Если объект сериализуемый, доступными могут быть и ссылка на объект и клон объекта. Ссылки на объекты действуют только в пределах исходного приложения.

Если для преобразования передаваемой информации в определенный формат требуется очень большой объем вычислений, можно указать имя функции для выполнения такого преобразования. Данную функцию можно вызвать только в том случае, если требуемый формат может быть распознан принимающим компонентом или приложением. Добавьте функцию отложенной визуализации в объект Clipboard, используя метод setDataHandler().

Примечание для приложений AIR. Тип объектов Clipboard, на которые ссылаются объекты событий, отправляемые для событий перетаскивания и копирования-вставки HTML, отличается от типа объектов Clipboard AIR. Объекты буфера обмена JavaScript рассматриваются в Руководстве для разработчика приложений AIR.

Посмотреть примеры

См. также

flash.desktop.NativeDragManager
flash.desktop.ClipboardFormats
flash.desktop.ClipboardTransferMode


Общедоступные свойства
 СвойствоОпределено
 Inheritedconstructor : Object
Ссылка на объект класса или функцию конструктора для данного экземпляра объекта.
Object
  formats : Array
[только для чтения] В этом объекте Clipboard находится массив строк, в котором содержатся имена поддерживаемых форматов данных.
Clipboard
  generalClipboard : Clipboard
[статические] [только для чтения] Буфер обмена ОС.
Clipboard
 Inheritedprototype : Object
[статические] Ссылка на модель объекта класса или функции.
Object
Общедоступные методы
 МетодОпределено
  
Создает пустой объект Clipboard.
Clipboard
  
Удаляет все представления данных из этого объекта Clipboard.
Clipboard
  
Удаляет представления данных заданного формата.
Clipboard
  
getData(format:String, transferMode:String = "originalPreferred"):Object
Определяет данные из буфера обмена, если они существуют в указанном формате.
Clipboard
  
Проверяет наличие данных указанного формата в данном объекте Clipboard.
Clipboard
 Inherited
Показывает, определено ли заданное свойство для объекта.
Object
 Inherited
Показывает, есть ли экземпляр класса Object в цепи прототипов объекта, заданного в качестве параметра.
Object
 Inherited
Показывает наличие заданного свойства и его перечисляемость.
Object
  
setData(format:String, data:Object, serializable:Boolean = true):Boolean
Добавляет представление информации для передачи данных в указанном формате данных.
Clipboard
  
setDataHandler(format:String, handler:Function, serializable:Boolean = true):Boolean
Добавляет ссылку на функцию обработчика, который по требованию создает данные в указанном формате.
Clipboard
 Inherited
Задает доступность динамического свойства для операций цикла.
Object
 Inherited
Возвращает строковое представление заданного объекта.
Object
 Inherited
Возвращает элементарное значение заданного объекта.
Object
Сведения о свойстве
formatsсвойство
formats:Array  [только для чтения]

Язык версии : ActionScript 3.0
Версии среды выполнения:  10, 1.0

В этом объекте Clipboard находится массив строк, в котором содержатся имена поддерживаемых форматов данных.

Константы имен стандартных форматов содержатся в классе ClipboardFormats. Задаваемые приложением строки могут также использоваться в качестве имен форматов для передачи данных в виде объектов.



Реализация
    public function get formats():Array

См. также


Пример
В следующем примере происходит считывание массива formats из буфера обмена ОС:
 var availableFormats:Array = Clipboard.generalClipboard.formats;
generalClipboardсвойство 
generalClipboard:Clipboard  [только для чтения]

Язык версии : ActionScript 3.0
Версии среды выполнения:  10, 1.0

Буфер обмена ОС.

Любые данные, передаваемые в буфер обмена, доступны другим приложениям. По этой причине возможно удаленное выполнение вредоносного кода в веб-обозревателе.

Примечание. В приложениях Flash Player 10 перед использованием операции вставки из буфера обмена требуется наличие пользовательского события (такого как нажатие комбинации клавиш для команды вставки или выбор команды вставки в контекстном меню щелчком мыши). Метод Clipboard.getData() возвратит содержимое буфера обмена только в том случае, если InteractiveObject получил и обрабатывает событие paste. При любых обстоятельствах вызов метода Clipboard.getData() ни к чему не приведет.

Объект generalClipboard создается автоматически. Присвоить данному свойству другой экземпляр объекта Clipboard невозможно. Вместо этого для чтения и записи данных в уже существующий объект используйте методы getData() и setData().

Перед тем как записывать в буфер обмена новые данные, следует удалить из него предыдущие данные всех форматов.



Реализация
    public static function get generalClipboard():Clipboard

Пример
Порядок записи в буфер обмена операционной системы:
 import flash.desktop.ClipboardFormats;
 
 var copy:String = "A string to copy to the system clipboard.";
 Clipboard.generalClipboard.clear();
 Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, copy);
Порядок чтения из буфера обмена операционной системы:
 import flash.desktop.ClipboardFormats;
 
 var pasteData:String  = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT) as String;
Сведения о конструкторе
Clipboard()Конструктор
public function Clipboard()

Язык версии : ActionScript 3.0
Версии среды выполнения:  10, 1.0

Создает пустой объект Clipboard.


Выдает
IllegalOperationError — Flash Player не поддерживает метод new Clipboard(), так как здесь может использоваться только буфер обмена ОС. Для осуществления операций копирования/вставки с использованием буфера обмена ОС, используйте уже существующий объект Clipboard.generalClipboard. Это не приводит к ошибке в приложении AIR.

См. также

Сведения о методе
clear()метод
public function clear():void

Язык версии : ActionScript 3.0
Версии среды выполнения:  10, 1.0

Удаляет все представления данных из этого объекта Clipboard.


Пример

В следующем примере производится очистка буфера обмена ОС:
 Clipboard.generalClipboard.clear();
clearData()метод 
public function clearData(format:String):void

Язык версии : ActionScript 3.0
Версии среды выполнения:  10, 1.0

Удаляет представления данных заданного формата.

Параметры

format:String — Формат данных для удаления.


Пример

В следующем примере из буфера обмена производится удаление всех данных в формате ClipboardFormats.TEXT_FORMAT.
 import flash.desktop.ClipboardFormats;
 
 Clipboard.generalClipboard.clearData(ClipboardFormats.TEXT_FORMAT);
getData()метод 
public function getData(format:String, transferMode:String = "originalPreferred"):Object

Язык версии : ActionScript 3.0
Версии среды выполнения:  10, 1.0

Определяет данные из буфера обмена, если они существуют в указанном формате. В приложении Flash Player перед использованием метода getData() требуется наличие пользовательского события (такого как нажатие клавиши или щелчок мыши). Метод getData() необходимо вызывать в обработчике инициированного события вставки. В приложении AIR это ограничение применяется только к содержимому, находящемуся за пределами изолированной программной среды безопасности.

При доступе к данным стандартного формата, данные возвращаются в качестве нового объекта соответствующего типа Flash Player или AIR.

При доступе к данным в формате, указанном приложением, значение параметра transferMode определяет, возвращать ли ссылку на исходный объект или анонимный объект, содержащий сериализованную копию исходного объекта. Если при использовании режима originalPreferred или clonePreferred предпочтительная версия недоступна, Flash Player или AIR возвращает альтернативную версию. Если при использовании режима originalOnly или cloneOnly запрашиваемая версия недоступна, Flash Player или AIR возвращает значение null.

Параметры

format:String — Возвращаемый формат данных. В строке формата может содержаться одно их стандартных имен, определенных в классе ClipboardFormats, или имя, задаваемое приложением.
 
transferMode:String (default = "originalPreferred") — Указывает, возвращать ли ссылку или сериализованную копию при доступе к формату данных, заданному приложением. Данное значение должно быть из списка заданных имен в классе ClipboardTransferMode. При использовании стандартных форматов данных это значение игнорируется.

Возвращает
Object — Объект данного типа, соответствующий формату данных.

Выдает
Error transferMode не является одним из имен, определенных в классе ClipboardTransferMode.
 
IllegalOperationError — Запрошенный объект Clipboard больше не находится в области действия (только для AIR).
 
SecurityError — В данном контексте операции чтения и записи в буфер обмена запрещены. В приложении Flash Player этот метод можно вызывать только во время обработки пользовательского события (в виде нажатия клавиши или щелчка мыши). В приложении AIR это ограничение применяется только к содержимому, находящемуся за пределами изолированной программной среды безопасности.

См. также


Пример

В следующем примере происходит считывание текста из буфера обмена ОС, если он существует:
 import flash.desktop.ClipboardFormats;

 var pasteData:String = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT) as String;
hasFormat()метод 
public function hasFormat(format:String):Boolean

Язык версии : ActionScript 3.0
Версии среды выполнения:  10, 1.5

Проверяет наличие данных указанного формата в данном объекте Clipboard.

Для проверки наличия данных стандартных форматов используйте константы класса ClipboardFormats.

Параметры

format:String — Проверяемый тип формата.

Возвращает
Booleantrue, если данные в указанном формате существуют.

Выдает
IllegalOperationError — Запрошенный объект Clipboard больше не находится в области действия (только для AIR).
 
SecurityError — В данном контексте операции чтения и записи в буфер обмена запрещены.

См. также


Пример

В следующем примере производится проверка наличия в буфере обмена ОС данных в текстовом формате:
if(Clipboard.generalClipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){
    //do something 
}
setData()метод 
public function setData(format:String, data:Object, serializable:Boolean = true):Boolean

Язык версии : ActionScript 3.0
Версии среды выполнения:  10, 1.0

Добавляет представление информации для передачи данных в указанном формате данных. В приложении Flash Player перед использованием метода setData() требуется наличие пользовательского события (такого как нажатие клавиши или щелчок мыши). В приложении AIR это ограничение применяется только к содержимому, находящемуся за пределами изолированной программной среды безопасности.

Различные представления одной и той же информации может храниться в буфере обмена в нескольких форматах. Это сделано для того, чтобы различные приложения или компоненты смогли воспользоваться доступными данными. Например, в приложении AIR изображение может быть добавлено: в растровом формате для использования в редакторах изображений, в качестве объекта Bitmap для использования в любом другом приложении AIR, в качестве закодированного PNG-файла для передачи в собственную файловую систему.

Параметр data должен относиться к типу данных, соответствующему указанному формату.

ФорматТипОписание
ClipboardFormats.TEXT_FORMATStringстроковые данные
ClipboardFormats.HTML_FORMATStringстроковые данные HTML
ClipboardFormats.URL_FORMATStringстрока URL (только для AIR)
ClipboardFormats.RICH_TEXT_FORMATByteArrayДанные в формате RTF
ClipboardFormats.BITMAP_FORMATBitmapDataданные растрового изображения (только для AIR)
ClipboardFormats.FILE_LIST_FORMATмассив Fileмассив файлов (только для AIR)
Имя пользовательского форматалюбыессылка на объект и сериализованный клон

Имя пользовательского формата не может начинаться со слов "air:" или "flash:". В приложении AIR, во избежание совпадения имен при использовании пользовательских форматов, в качестве префикса к формату можно добавить идентификатор вашего приложения или имя пакета, например com.example.applicationName.dataPacket.

При передаче данных внутри или между приложениями Flash Player или AIR параметр serializable определяет, являются ли доступными и ссылка, и копия или только ссылка на объект. Задайте для параметра serializable значение true, чтобы сделать доступными и ссылку и копию объекта данных. Задайте для параметра serializable значение false, чтобы сделать доступной только ссылку на объект. Ссылки на объекты действуют только в текущем приложении, поэтому установка параметра serializable на значение false, также означает, что данные такого формата недоступны для других приложений Flash Player или AIR. Компонент может выбрать между получением ссылки на объект или копии объекта, установив соответствующий режим передачи данных для буфера обмена при доступе к данным формата.

Примечание. Стандартные форматы всегда преобразуются в собственные форматы системы при вставке или перетаскивании (только для AIR) данных вне поддерживаемого приложения, поэтому значение параметра serializable не влияет на доступность данных стандартного формата для приложений, отличных от приложений Flash Player или AIR.

Для отложенной визуализации данных формата используйте метод setDataHandler(). Если оба метода — setData() и setDataHandler() — используются для добавления представления данных с одинаковым именем формата, то функция обработчика не будет вызвана.

Параметры

format:String — Добавляемая информация.
 
data:Object — Формат данных.
 
serializable:Boolean (default = true) — Укажите значение true для тех объектов, которые можно сериализовать (и десериализовать).

Возвращает
Boolean — Если данные были записаны успешно, true. В противном случае — false. Flash Player возвращает значение false, если элемент format не поддерживается классом ClipboardFormats. (Flash Player не поддерживает следующие элементы: ClipboardFormats.URL_FORMAT, ClipboardFormats.FILE_LIST_FORMAT и ClipboardFormats.BITMAP_FORMAT.)

Выдает
IllegalOperationError — Запрошенный объект Clipboard больше не находится в области действия (только для AIR).
 
SecurityError — В данном контексте операции чтения и записи в буфер обмена запрещены. В приложении Flash Player этот метод можно вызывать только во время обработки пользовательского события (в виде нажатия клавиши или щелчка мыши). В приложении AIR это ограничение применяется только к содержимому, находящемуся за пределами изолированной программной среды безопасности.
 
TypeError — Свойство format или свойство data имеет значение null.

См. также


Пример

В следующем примере происходит добавление в буфер обмена одного и того же содержимого в текстовом формате и формате HTML:
 import flash.desktop.ClipboardFormats;
 
 var htmlString:String = "<html><body>Body content</body></html>";
 Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, urlString);
 Clipboard.generalClipboard.setData(ClipboardFormats.HTML_FORMAT, urlString);
setDataHandler()метод 
public function setDataHandler(format:String, handler:Function, serializable:Boolean = true):Boolean

Язык версии : ActionScript 3.0
Версии среды выполнения:  10, 1.0

Добавляет ссылку на функцию обработчика, который по требованию создает данные в указанном формате. Используйте данный метод для того, чтобы отложить создание или визуализацию данных до момента доступа к ним. В приложении Flash Player перед использованием метода setDataHandler() требуется наличие пользовательского события (такого как нажатие клавиши или щелчок мыши). В приложении AIR это ограничение применяется только к содержимому, находящемуся за пределами изолированной программной среды безопасности.

Функция обработчика должна возвращать соответствующий заданному формату тип данных.

ФорматВозвращаемый тип
ClipboardFormats.TEXT_FORMATString
ClipboardFormats.HTML_FORMATString
ClipboardFormats.URL_FORMATString (только для AIR)
ClipboardFormats.RICH_TEXT_FORMATByteArray
ClipboardFormats.BITMAP_FORMATBitmapData (только для AIR)
ClipboardFormats.FILE_LIST_FORMATМассив объектов File (только для AIR)
Имя пользовательского форматаНепустой

Функция обработчика вызывается только в том случае, если данные заданного формата распознаются. Обратите внимание на то, что данные могут измениться с момента добавления обработчика до момента их считывания, если только ваше приложение не обеспечивает защиту данных. Поведение при многократном считывании данных буфера обмена, представленных функцией обработчика, не гарантировано. Flash Player ли AIR может возвратить данные, созданные при первом вызове функции, или выполнить повторный вызов функции. Не следует полагаться ни на одно из этих поведений.

Для добавления данных непосредственно в этот объект Clipboard используйте метод setData(). Если вызываются оба метода — setData() и setDataHandler() — с одинаковым именем формата, то функция обработчика не будет вызвана.

Параметры

format:String — Функция, при вызове которой возвращаются передаваемые данные.
 
handler:Function — Формат данных.
 
serializable:Boolean (default = true) — Задайте значение true, если объект, возвращаемый обработчиком, можно сериализовать (и десериализовать).

Возвращает
Boolean — Если обработчик были настроен успешно, true. В противном случае — false.

Выдает
TypeError — Свойство format или свойство handler имеет значение null.
 
IllegalOperationError — Запрошенный объект Clipboard больше не находится в области действия (только для AIR).
 
SecurityError — В данном контексте операции чтения и записи в буфер обмена запрещены. В приложении Flash Player этот метод можно вызывать только во время обработки пользовательского события (такого как нажатие клавиши или щелчок мыши). В приложении AIR это ограничение применяется только к содержимому, находящемуся за пределами изолированной программной среды безопасности.

См. также


Пример

В данном примере происходит добавление произвольного числа в буфер обмена ОС с использованием функции отложенных данных:
 import flash.desktop.ClipboardFormats;
 
 Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, randomNumberGenerator);

 public function randomNumberGenerator():String{
     return Math.random().toString();
 }
Примеры Как пользоваться примерами
ClipboardExample.as

В следующем примере происходит копирование строки из одной переменной в другую через буфер обмены ОС с использованием класса ClipboardExample. Это можно сделать, выполнив следующие действия.
  1. Произведите запись данных (в данном случае строковых данных) в Clipboard.generalClipboard.
  2. Произведите считывание содержимого буфера обмена из Clipboard.generalClipboard.
package
{
    import flash.display.Sprite;
    import flash.desktop.Clipboard;
    import flash.desktop.ClipboardFormats;
    import flash.desktop.ClipboardTransferMode;

    public class ClipboardExample extends Sprite
    {
        public function ClipboardExample()
        {
            var sally:String = "Sally";
            var person:String;
            
            copy(sally);
            person = paste();
            trace(person); //traces: "Sally"
        }

        private function copy(text:String):void{
            Clipboard.generalClipboard.clear();
            Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, text);
        }
        
        private function paste():String{
            if(Clipboard.generalClipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){
                return String(Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT));
            } else {return null;}
        }
        
    }
}