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

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

Класс URLLoader загружает данные с URL-адреса в виде текста, двоичных данных или переменных в кодировке URL. Это оказывает помощь при загрузке текстовых файлов, XML-объектов или других сведений, которые будут использованы в динамическом приложении по обработке данных.

Объект URLLoader загружает все данные с URL-адреса, прежде чем сделать их доступными для ActionScript. Он отправляет оповещения о состоянии загрузки, которые можно отслеживать с помощью свойств bytesLoaded и bytesTotal, а также посредством отправленных событий.

При загрузке очень больших видеофайлов, таких как FLV, могут возникнуть ошибки из-за нехватки памяти.

При использовании данного объекта необходимо продумать модель безопасности проигрывателя Flash Player:

Дополнительные сведения о безопасности см. в следующих ресурсах.

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

См. также

URLRequest
URLVariables
URLStream
Чтение внешних XML-документов
Работа с внешними данными


Общедоступные свойства
 СвойствоОпределено
  bytesLoaded : uint = 0
Определяет число байт, загруженных до настоящего момента в ходе операции загрузки.
URLLoader
  bytesTotal : uint = 0
Определяет общее число байт загруженных данных.
URLLoader
 Inheritedconstructor : Object
Ссылка на объект класса или функцию конструктора для данного экземпляра объекта.
Object
  data : *
Данные, полученные при загрузке.
URLLoader
  dataFormat : String = "text"
Определяет, в каком виде получаются загружаемые данные: в виде текста (URLLoaderDataFormat.TEXT), необработанных двоичных данных (URLLoaderDataFormat.BINARY) или переменных в кодировке URL (URLLoaderDataFormat.VARIABLES).
URLLoader
 Inheritedprototype : Object
[статические] Ссылка на модель объекта класса или функции.
Object
Общедоступные методы
 МетодОпределено
  
URLLoader(request:URLRequest = null)
Создает объект URLLoader.
URLLoader
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Регистрирует объект прослушивателя события в объекте EventDispatcher, в результате чего прослушиватель будет получать уведомления о событиях.
EventDispatcher
  
Закрывает выполняемую операцию загрузки.
URLLoader
 Inherited
Передает событие в поток событий.
EventDispatcher
 Inherited
Проверяет наличие у объекта EventDispatcher прослушивателей событий, которые зарегистрированы для получения уведомлений о событиях определенного типа.
EventDispatcher
 Inherited
Показывает, определено ли заданное свойство для объекта.
Object
 Inherited
Показывает, есть ли экземпляр класса Object в цепи прототипов объекта, заданного в качестве параметра.
Object
  
Отправляет и загружает данные с заданного URL-адреса.
URLLoader
 Inherited
Показывает наличие заданного свойства и его перечисляемость.
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Удаляет прослушиватель из объекта EventDispatcher.
EventDispatcher
 Inherited
Задает доступность динамического свойства для операций цикла.
Object
 Inherited
Возвращает строковое представление заданного объекта.
Object
 Inherited
Возвращает элементарное значение заданного объекта.
Object
 Inherited
Проверяет, зарегистрирован ли прослушиватель событий в объекте EventDispatcher или в любом из его предков для получения уведомлений о событиях определенного типа.
EventDispatcher
События
 Событие Сводка Определено
 Inherited[многоадресное событие] Отправляется, когда проигрыватель Flash Player перемещается в фокус операционной системы и становится активным.EventDispatcher
  Отправляется после декодирования всех полученных данных и размещения их в свойстве data объекта URLLoader.URLLoader
 Inherited[многоадресное событие] Отправляется, когда проигрыватель Flash Player покидает фокус операционной системы и становится неактивным.EventDispatcher
  Отправляется, если путем вызова метода URLLoader.load() предпринимается попытка доступа к данным по протоколу HTTP, а текущая среда Flash Player может определить и вернуть код состояния для запроса.URLLoader
  Отправляется, если вызов метода URLLoader.load() вызывает неустранимую ошибку, приводящей к прекращению загрузки.URLLoader
  Отправляется, когда операция загрузки начинается после вызова метода URLLoader.load().URLLoader
  Отправляется в случае получения данных в ходе операции загрузки.URLLoader
  Отправляется, если путем вызова метода URLLoader.load() предпринимается попытка загрузить данные с сервера, расположенного за пределами изолированной среды.URLLoader
Сведения о свойстве
bytesLoadedсвойство
public var bytesLoaded:uint = 0

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

Определяет число байт, загруженных до настоящего момента в ходе операции загрузки.

bytesTotalсвойство 
public var bytesTotal:uint = 0

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

Определяет общее число байт загруженных данных. Во время операции загрузки данное свойство имеет значение 0 и заполняется по завершении операции. Вдобавок, отсутствие заголовка Content-Length не позволит определить параметр bytesTotal.

dataсвойство 
public var data:*

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

Данные, полученные при загрузке. Данное свойство заполняется только после завершения операции загрузки. Формат данных зависит от значения свойства dataFormat:

Если свойство dataFormat имеет значение URLLoaderDataFormat.TEXT, то в качестве данных будет получена строка, содержащая текст загруженного файла.

Если свойство dataFormat имеет значение URLLoaderDataFormat.BINARY, то в качестве данных будет получен объект ByteArray, содержащий необработанные двоичные данные.

Если свойство dataFormat имеет значение URLLoaderDataFormat.VARIABLES, то в качестве данных будет получен объект URLVariables, содержащий переменные в кодировке URL-адреса.

См. также

dataFormatсвойство 
public var dataFormat:String = "text"

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

Определяет, в каком виде получаются загружаемые данные: в виде текста (URLLoaderDataFormat.TEXT), необработанных двоичных данных (URLLoaderDataFormat.BINARY) или переменных в кодировке URL (URLLoaderDataFormat.VARIABLES).

Если свойство dataFormat имеет значение URLLoaderDataFormat.TEXT, то в качестве данных будет получена строка, содержащая текст загруженного файла.

Если свойство dataFormat имеет значение URLLoaderDataFormat.BINARY, то в качестве данных будет получен объект ByteArray, содержащий необработанные двоичные данные.

Если свойство dataFormat имеет значение URLLoaderDataFormat.VARIABLES, то в качестве данных будет получен объект URLVariables, содержащий переменные в кодировке URL-адреса.

Значение по умолчанию URLLoaderDataFormat.TEXT

См. также

Сведения о конструкторе
URLLoader()Конструктор
public function URLLoader(request:URLRequest = null)

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

Создает объект URLLoader.

Параметры
request:URLRequest (default = null) — Объект URLRequest, определяющий URL-адрес для загрузки. Если данный оператор пропущен, операция загрузки не начинается. Операция загрузки может начаться сразу же, если таковое указано (дополнительные сведения см. в разделе о load).

См. также

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

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

Закрывает выполняемую операцию загрузки. Любая операция загрузки, выполняемая в данный момент, сразу же прекращается. Если в текущий момент нет потокового воспроизведения с URL-адреса, создается ошибка "недопустимый поток".

load()метод 
public function load(request:URLRequest):void

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

Отправляет и загружает данные с заданного URL-адреса. Данные могут быть получены как текст, необработанные двоичные данные или переменные в кодировке URL. Это зависит от значения, установленного для свойства dataFormat. Обратите внимание на то, что значением свойства dataFormat по умолчанию является текст. Для того чтобы отправить данные на указанный URL-адрес, можно установить свойство data в объекте URLRequest.

Примечание. Если загружаемый файл содержит символы, не принадлежащие коду ASCII (например, во многих языках, кроме английского), рекомендуется сохранить файл в кодировке UTF-8 или UTF-16, как противоположных стандарту ASCII.

SWF-файл в изолированной программной среде, локальной для файловой системы, может не поддерживать загрузку и передачу данных для ресурса, находящегося в сетевой изолированной программной среде.

По умолчанию вызывающий SWF-файл и загружаемый URL-адрес должны находиться в одном и том же домене. Например, SWF-файл на www.adobe.com может загружать данные только из источников, которые также размещены на сайте www.adobe.com. Чтобы загрузить данные с другого домена, разместите файл политики для URL на сервере, где расположены эти данные.

Нельзя подключаться к общепринятым зарезервированным портам. Полный список заблокированных портов см. в разделе "Ограничение API-интерфейсов сетевого подключения" в главе книги Программирование на ActionScript 3.0.

В приложении Flash Player 10 и более поздней версии при использовании типа содержимого multipart (например, multipart/form-data), в котором содержится отправка (обозначена параметром filename в заголовке content-disposition в теле оператора POST), к операции POST применяются правила безопасности для отправок:

Кроме того, все объекты multipart Content-Type должны иметь допустимый синтаксис (в соответствии со стандартами RFC2046). Если синтаксис является недопустимым, к операции POST применяются правила безопасности, действующие для отправок.

Дополнительные сведения о безопасности см. в следующих ресурсах.

Параметры

request:URLRequest — Объект URLRequest, определяющий URL-адрес для загрузки.


События
complete:Event — Отправляется после успешной загрузки данных.
 
httpStatus:HTTPStatusEvent — Если доступ осуществляется по протоколу HTTP и текущая среда Flash Player поддерживает получение кодов состояния, то в дополнении к любым событиям complete или error могут возникнуть следующие события.
 
ioError:IOErrorEvent — Не удается завершить операцию загрузки.
 
progress:ProgressEvent — Отправляется в случае получения данных в ходе операции загрузки.
 
securityError:SecurityErrorEvent — В рамках операции загрузки была произведена попытка извлечь данные с сервера, расположенного за пределами изолированной среды вызывающего объекта. Для решения этой проблемы можно использовать файл политики на сервере.
 
securityError:SecurityErrorEvent — Операция загрузки предприняла попытку загрузить SWZ-файл (компонент платформы Adobe), но сертификат является недействительным или строка дайджеста не соответствует компоненту.
 
open:Event — Отправляется в начале операции загрузки.

Выдает
ArgumentError — Объекты URLRequest.requestHeader могут не содержать определенные запрещенные заголовки запроса HTTP. Дополнительную информацию см. в описании класса URLRequestHeader.
 
MemoryError — Данная ошибка может возникнуть по следующим причинам: 1) Проигрыватель Flash Player не может преобразовать значение параметра URLRequest.data из UTF8 в MBCS. Данная ошибка применяется, если объект URLRequest, переданный методу load(), настроен на выполнение операции GET, а параметр System.useCodePage имеет значение true. 2) Проигрыватель Flash Player не может выделить память для данных POST. Данная ошибка применима, если переданный к загрузке объект URLRequest настроен на выполнение операции POST.
 
SecurityError — Локальные ненадежные SWF-файлы могут быть изолированы от Интернета. Чтобы обойти эту проблему, можно переклассифицировать данный SWF-файл как локальный с сетевым подключением или доверенный.
 
SecurityError — Если вы пытаетесь подключиться к обычно зарезервированному порту. Полный список заблокированных портов см. в разделе "Ограничение сетевых API-интерфейсов" в главе "Безопасность" книги Программирование на ActionScript 3.0.
 
TypeError — Значение параметра запроса или свойства URLRequest.url переданного объекта URLRequest равно null.

См. также


Пример

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

Для определения местоположения XML-файла создается объект URLRequest (например, он может находиться в том же каталоге, где и SWF-файл). Для того чтобы выявить возможные ошибки, файл загружается в блок try...catch. (Здесь выявляются ошибки SecurityError.) При возникновении события IO_ERROR вызывается метод errorHandler(), записывающий сообщение об ошибке в текстовом поле xmlTextField. После того как данные XML-файла получены и помещены в свойство данных URLLoader-объекта loader, отправляется событие Event.COMPLETE и вызывается метод loaderCompleteHandler().

В методе loaderCompleteHandler() блок try...catch используется для выявления любых ошибок анализа, которые могут возникнуть при преобразовании загруженных данных из файла в объект XML. Далее метод readNodes() рекурсивно обрабатывает все элементы в узлах XML-документа и добавляет текстовое поле xmlTextField со списком первых атрибутов всех элементов.

package {
    import flash.display.Sprite;
    import flash.events.Event;
    import flash.net.URLLoader;
    import flash.net.URLRequest;
    import flash.text.TextField;
    import flash.text.TextFieldAutoSize;
    import flash.xml.*;
    import flash.events.IOErrorEvent;
  
    public class URLLoader_loadExample extends Sprite {
        private var xmlTextField:TextField = new TextField();
        private var externalXML:XML;    
        private var loader:URLLoader;

        public function URLLoader_loadExample() {
            var request:URLRequest = new URLRequest("xmlFile.xml");

            loader = new URLLoader();
            
            try {
                loader.load(request);
            }
            catch (error:SecurityError)
            {
                trace("A SecurityError has occurred.");
            }

             loader.addEventListener(IOErrorEvent.IO_ERROR, errorHandler);
            loader.addEventListener(Event.COMPLETE, loaderCompleteHandler);

            xmlTextField.x = 10;
            xmlTextField.y = 10;
            xmlTextField.background = true;
            xmlTextField.autoSize = TextFieldAutoSize.LEFT;

            addChild(xmlTextField);
        }

        private function loaderCompleteHandler(event:Event):void {

                try {
                    externalXML = new XML(loader.data);
                    readNodes(externalXML);    
                } catch (e:TypeError) {
                    trace("Could not parse the XML file.");
                }
        }

        private function readNodes(node:XML):void {

                for each (var element:XML in node.elements()) {
                    xmlTextField.appendText(element.attributes()[0] + "\n");

                    readNodes(element);
                }    
        }

        private function errorHandler(e:IOErrorEvent):void {
            xmlTextField.text = "Had problem loading the XML File.";
        }
    }
}
Сведения о событии
complete Событие
Тип объекта события: flash.events.Event
свойство Event.type = flash.events.Event.COMPLETE

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

Отправляется после декодирования всех полученных данных и размещения их в свойстве data объекта URLLoader. Полученные данные станут доступными, как только будет отправлено это событие.

Константа Event.COMPLETE определяет значение свойства type объекта complete.

Данное событие имеет следующие свойства.

СвойствоЗначение
bubblesfalse
cancelablefalse; нет поведения по умолчанию для отмены.
currentTargetОбъект, активно обрабатывающий объект Event с помощью прослушивателя событий.
targetСетевой объект, который завершил загрузку.

См. также

httpStatus Событие  
Тип объекта события: flash.events.HTTPStatusEvent
свойство HTTPStatusEvent.type = flash.events.HTTPStatusEvent.HTTP_STATUS

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

Отправляется, если путем вызова метода URLLoader.load() предпринимается попытка доступа к данным по протоколу HTTP, а текущая среда Flash Player может определить и вернуть код состояния для запроса. (В среде некоторых обозревателей данная информация не предоставляется.) Обратите внимание на то, что событие httpStatus (при наличии такового) будет отправляться до (как дополнение) любого события complete или error.

Константа HTTPStatusEvent.HTTP_STATUS определяет значение свойства type объекта события httpStatus.

Данное событие имеет следующие свойства.

СвойствоЗначение
bubblesfalse
cancelablefalse; нет поведения по умолчанию для отмены.
currentTargetОбъект, активно обрабатывающий объект Event с помощью прослушивателя событий.
statusКод состояния HTTP, возвращенный сервером.
targetСетевой объект, получающий код состояния НТТР.

См. также

ioError Событие  
Тип объекта события: flash.events.IOErrorEvent
свойство IOErrorEvent.type = flash.events.IOErrorEvent.IO_ERROR

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

Отправляется, если вызов метода URLLoader.load() приводит к неустранимой ошибке, прекращающей загрузку.

Задает значение свойства type для объекта события ioError.

Данное событие имеет следующие свойства.

СвойствоЗначение
bubblesfalse
cancelablefalse; нет поведения по умолчанию для отмены.
currentTargetОбъект, активно обрабатывающий объект Event с помощью прослушивателя событий.
targetСетевой объект, с которым произошла ошибка ввода/вывода.
textТекст, отображаемый в качестве сообщения об ошибке.

См. также

open Событие  
Тип объекта события: flash.events.Event
свойство Event.type = flash.events.Event.OPEN

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

Отправляется, когда операция загрузки начинается после вызова метода URLLoader.load().

Константа Event.OPEN определяет значение свойства type объекта события open.

Данное событие имеет следующие свойства.

СвойствоЗначение
bubblesfalse
cancelablefalse; нет поведения по умолчанию для отмены.
currentTargetОбъект, активно обрабатывающий объект Event с помощью прослушивателя событий.
targetСетевой объект, установивший подключение.

См. также

progress Событие  
Тип объекта события: flash.events.ProgressEvent
свойство ProgressEvent.type = flash.events.ProgressEvent.PROGRESS

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

Отправляется в случае получения данных в ходе операции загрузки.

Обратите внимание на то, что в случае с объектом URLLoader, данные становятся доступными только после полной загрузки. Поэтому событие состояния служит лишь оповещением о том, как проходит загрузка. Для доступа к данным, которые еще не загружены полностью, используйте объект URLStream.

Задает значение свойства type для объекта события progress.

Данное событие имеет следующие свойства.

СвойствоЗначение
bubblesfalse
bytesLoadedЧисло элементов или байт, загруженных на момент обработки события прослушивателем.
bytesTotalОбщее число элементов или байт, которые в итоге будут получены в случае успешного завершения загрузки.
cancelablefalse; нет поведения по умолчанию для отмены.
currentTargetОбъект, активно обрабатывающий объект Event с помощью прослушивателя событий.
targetСетевой объект, сообщающий сведения о прогрессе.

См. также

securityError Событие  
Тип объекта события: flash.events.SecurityErrorEvent
свойство SecurityErrorEvent.type = flash.events.SecurityErrorEvent.SECURITY_ERROR

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

Отправляется, если путем вызова метода URLLoader.load() предпринимается попытка загрузить данные с сервера, расположенного за пределами изолированной среды. Отправка также выполняется, если при вызове URLLoader.load() предпринимается попытка загрузить SWZ-файл и сертификат является недействительным или строка дайджеста не соответствует компоненту.

Константа SecurityErrorEvent.SECURITY_ERROR определяет значение свойства type для объекта события securityError.

Данное событие имеет следующие свойства.

СвойствоЗначение
bubblesfalse
cancelablefalse; нет поведения по умолчанию для отмены.
currentTargetОбъект, активно обрабатывающий объект Event с помощью прослушивателя событий.
targetСетевой объект, сообщающий об ошибке безопасности.
textТекст, отображаемый в качестве сообщения об ошибке.

См. также

Примеры Как пользоваться примерами
URLLoaderExample.as

В следующем примере загружаются и отображаются данные, найденные в локальном текстовом файле. Здесь также отслеживается информация по обработке событий.

Примечание. Чтобы запустить этот пример, поместите файл urlLoaderExample.txt в тот же каталог, где находится ваш SWF-файл. Данный файл должен содержать только следующую строку текста: answer=42&question=unknown

Данный пример кода выполняет следующее:

  1. Функция конструктора создает экземпляр URLLoader под именем loader и экземпляр URLRequest под именем request, в котором указывается место размещения и имя загружаемого файла.
  2. Объект loader передается методу configureListeners(), который добавляет прослушивателей для каждого из поддерживаемых событий URLLoader.
  3. Далее объект request передается методу loader.load(), который загружает текстовый файл.
  4. После того как URLLoader завершит загрузку текстового файла, отправляется событие Event.COMPLETE, которое запускает метод completeHandler(). Метод completeHandler() создает объект URLVariables на основе текста, загруженного из файла. Чтобы облегчить манипулирование загруженными данными, объект URLVariables преобразует пары "имя-значение" (в кодировке URL) в свойства ActionScript.

package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.*;

    public class URLLoaderExample extends Sprite {
        public function URLLoaderExample() {
            var loader:URLLoader = new URLLoader();
            configureListeners(loader);

            var request:URLRequest = new URLRequest("urlLoaderExample.txt");
            try {
                loader.load(request);
            } catch (error:Error) {
                trace("Unable to load requested document.");
            }
        }

        private function configureListeners(dispatcher:IEventDispatcher):void {
            dispatcher.addEventListener(Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(Event.OPEN, openHandler);
            dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            dispatcher.addEventListener(HTTPStatusEvent.HTTP_STATUS, httpStatusHandler);
            dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
        }

        private function completeHandler(event:Event):void {
            var loader:URLLoader = URLLoader(event.target);
            trace("completeHandler: " + loader.data);
    
            var vars:URLVariables = new URLVariables(loader.data);
            trace("The answer is " + vars.answer);
        }

        private function openHandler(event:Event):void {
            trace("openHandler: " + event);
        }

        private function progressHandler(event:ProgressEvent):void {
            trace("progressHandler loaded:" + event.bytesLoaded + " total: " + event.bytesTotal);
        }

        private function securityErrorHandler(event:SecurityErrorEvent):void {
            trace("securityErrorHandler: " + event);
        }

        private function httpStatusHandler(event:HTTPStatusEvent):void {
            trace("httpStatusHandler: " + event);
        }

        private function ioErrorHandler(event:IOErrorEvent):void {
            trace("ioErrorHandler: " + event);
        }
    }
}