JavaScript в AIR

AIR помещает содержимое в изолированные программные среды согласно его происхождению. Правила изолированной программной среды соответствуют политике отбора по критерию происхождения, реализуемой большинством обозревателей, а также правилам изолированных программных сред проигрывателя Adobe Flash. Кроме того, AIR предлагает новый тип — изолированную программную среду приложения для хранения и защиты содержимого приложения. Дополнительные сведения о типах изолированных программных сред, встречающихся при разработке приложений AIR, см. в разделе « Изолированные программные среды ».

Доступ к рабочей среде и API-интерфейсам AIR возможен только для кода HTML и JavaScript, исполняемого в рамках изолированной программной среды приложения. В то же время динамическая проверка и исполнение кода JavaScript в самых разных его формах подвергаются серьезным ограничениям внутри изолированной программной среды приложения из соображений безопасности. Эти ограничения применяются независимо от того, загружает ли приложение данные с сервера. (Даже файловое содержимое, вставленные строки и данные, введенные непосредственно пользователем, могут быть небезопасны.)

Изолированная программная среда, в которую помещается содержимое страницы, определяется его происхождением. В изолированную программную среду приложения помещаются только данные, загруженные непосредственно из установочного каталога приложения (установочный каталог приложения отражен в URL-схеме app: ). Содержимое, загружаемое из файловой системы, помещается в локальную изолированную программную среду файловой системы или в локальную доверенную изолированную программную среду , которые разрешают взаимодействие с содержимым в рамках локальной файловой системы, но не с удаленным содержимым. Содержимое, загружаемое из сети, помещается в удаленную изолированную программную среду в соответствии с доменом, с которого оно получено.

Чтобы страница приложения могла свободно обращаться к содержимому в удаленной изолированной программной среде, ее можно сопоставить с тем же доменом, что и удаленное содержимое. Например, если в приложении отображается карта из Интернета, то страница приложения, загружающая и отображающая это содержимое, может сопоставляться с этим доменом. Атрибуты сопоставления страниц с удаленными изолированными программными средами и доменами — новые, они добавляются в элементы frame и iframe в HTML.

Чтобы содержимое изолированной программной среды вне приложения могло безопасно использовать функции AIR, можно установить мост родительской изолированной программной среды. Чтобы содержимое приложения могло безопасно вызывать методы и свойства доступа к другим изолированным программным средам, можно установить мост дочерней изолированной программной среды. Здесь безопасность обеспечивается тем, что удаленное содержимое не может случайным образом получать ссылки на объекты, свойства или методы, не предоставляемые явно. По мосту могут передаваться только данные простого типа, функции и анонимные объекты. Тем не менее следует избегать предоставления потенциально опасных функций. Например, если предоставляется интерфейс, позволяющий удаленному содержимому читать и записывать любые файлы в системе пользователя, то такое удаленное содержимое может серьезно повредить систему.

Использование функции eval() возможно в изолированной программной среде только после загрузки страницы. Некоторые варианты ее использования разрешаются, чтобы данные в формате JSON можно было безопасно разбирать, но любая проверка, итогом которой становится исполнимая инструкция, приведет к ошибке. В разделе « Ограничения по использованию кода в содержимом из различных изолированных программных сред » описываются разрешенные способы использования функции eval() .

В изолированной программной среде приложения конструкторы функций могут запускаться до окончания загрузки страницы. После окончания работы всех обработчиков события load на странице новые функции создавать нельзя.

HTML-страницы в изолированной программной среде приложения не могут использовать тег script для загрузки файлов JavaScript извне каталога приложения. Чтобы страница приложения могла загружать сценарий извне каталога приложения, она должна быть сопоставлена с изолированной программной средой приложения.

AIR предоставляет объект XMLHttpRequest (XHR), который приложения могут использовать для запроса данных. В примере ниже показан простой запрос данных.

xmlhttp = new XMLHttpRequest(); 
xmlhttp.open("GET", "http:/www.example.com/file.data", true); 
xmlhttp.onreadystatechange = function() { 
    if (xmlhttp.readyState == 4) { 
        //do something with data... 
    } 
} 
xmlhttp.send(null); 

В отличие от обозревателей, среда AIR разрешает содержимому, работающему в изолированной программной среде, запрашивать данные с любого домена. Результат исполнения XHR, содержащий JSON-строку, может быть преобразован в данные объектов, если только он не содержит исполняемый код. Если в результате XHR получаются исполняемые инструкции, генерируется ошибка, а завершить проверку не удается.

Для предотвращения случайного внедрения кода из удаленных источников синхронные XHR возвращают пустые результаты, если они выполнены до окончания загрузки страницы. Асинхронные XHR всегда возвращают результат после окончания загрузки страницы.

По умолчанию AIR блокирует междоменные запросы XMLHttpRequest в изолированных программных средах вне приложения. Родительское окно в изолированной программной среде приложения может разрешать междоменные запросы в дочернем фрейме с содержимым из изолированной программной среды вне приложения. Для этого атрибут allowCrossDomainXHR в элементе frame или iframe, добавленный средой AIR, принимает значение true :

<iframe id="mashup" 
    src="http://www.example.com/map.html" 
    allowCrossDomainXHR="true" 
</iframe>

При отправке запроса XMLHttpRequest удаленному серверу из фрейма или встроенного фрейма с содержимым, сопоставленным с удаленной изолированной программной средой, проверьте, чтобы сопоставляемый URL-адрес не маскировал адрес сервера в XHR. Например, рассмотрите следующее определение встроенного фрейма iframe, сопоставляющее содержимое приложения с удаленной изолированной программной средой для домена example.com:

<iframe id="mashup" 
    src="http://www.example.com/map.html" 
    documentRoot="app:/sandbox/" 
    sandboxRoot="http://www.example.com/" 
    allowCrossDomainXHR="true" 
</iframe>

Так как атрибут sandboxRoot повторно сопоставляет корневой URL-адрес www.example.com, все запросы загружаются из каталога приложения, а не с удаленного сервера. Запросы сопоставляются повторно независимо от того, как они появились: в результате перехода по странице или из запроса XMLHttpRequest.

Чтобы нечаянно не заблокировать запросы данных с удаленного сервера, сопоставьте sandboxRoot с подкаталогом удаленного URL-адреса, а не с корневым каталогом. Необязательно, чтобы каталог существовал. Например, чтобы запросы на www.example.com загружались с удаленного сервера, а не из каталога приложения, измените предыдущий встроенный фрейм (iframe), как показано ниже.

<iframe id="mashup" 
    src="http://www.example.com/map.html" 
    documentRoot="app:/sandbox/" 
    sandboxRoot="http://www.example.com/air/" 
    allowCrossDomainXHR="true" 
</iframe>

В этом случае локально будет загружено только содержимое в подкаталоге air .

Дополнительные сведения о сопоставлении изолированных программных сред см. в разделах « Элементы frame и iframe в HTML » и « Безопасность HTML в Adobe AIR ».

В приложениях AIR только содержимое удаленных изолированных программных сред (загруженное по протоколам http: и https:) может использовать файлы cookies (свойство document.cookie ). В изолированной программной среде приложения имеются другие средства хранения постоянных данных, таких как классы EncryptedLocalStore, SharedObject и FileStream.

API-интерфейс Clipboard в WebKit управляется событиями copy , cut и paste . Объект события, передаваемый в ответ на эти события, обеспечивает доступ к буферу обмена через свойство clipboardData . Используйте для чтения и записи данных в буфер обмена методы объекта clipboardData .

Код JavaScript вне изолированной программной среды приложения получает доступ к буферу обмена только через эти события. Тем не менее содержимое изолированной программной среды приложения может обращаться к системному буферу напрямую с помощью класса Clipboard в AIR. Например, с помощью показанной ниже инструкции можно получить данные о формате текста в буфере:

var clipping = air.Clipboard.generalClipboard.getData("text/plain", 
                                air.ClipboardTransferMode.ORIGINAL_ONLY);

Ниже перечислены поддерживаемые MIME-типы данных:

Дополнительные сведения об использовании буфера обмена см. в разделе « Копирование и вставка » и статье « Использование Pasteboard в JavaScript (Центр разработки Apple) ».

Жесты перетаскивания в HTML-документ и обратно вызывают следующие события DOM: dragstart , drag , dragend , dragenter , dragover , dragleave и drop . Объект события, передаваемый в ответ на эти события, обеспечивает доступ к перетаскиваемым данным через свойство dataTransfer . Свойство dataTransfer указывает на объект, предоставляющий те же методы, что и объект clipboardData , связанный с событием clipboard. Например, следующая функция получает данные о формате текста из события drop :

function onDrop(dragEvent){ 
    return dragEvent.dataTransfer.getData("text/plain",  
            air.ClipboardTransferMode.ORIGINAL_ONLY); 
}

Ниже перечислены значимые члены объекта dataTransfer .

Дополнительные сведения о добавлении функции перетаскивания в приложение AIR см. в разделе « Перетаскивание в AIR » и в статье « Использование перетаскивания в JavaScript (Центр разработки Apple) ».

В целях безопасности AIR накладывает ограничения на использование свойств innerHTML и outerHTML содержимым в изолированной программной среде. Перед событием load и во время исполнения любого обработчика события load свойства innerHTML и outerHTML могут использоваться без ограничений. Тем не менее после загрузки страницы свойства innerHTML и outerHTML могут использоваться только для добавления в документ статического содержимого. Все инструкции в строке, назначенные свойствам innerHTML и outerHTML , порождающие исполняемый код, игнорируются. Например, если включить атрибут обратного вызова события в определение элемента, прослушиватель события не будет добавлен. Точно так же вложенные теги <script> не проверяются. Дополнительные сведения см. в разделе « Безопасность HTML в Adobe AIR ».

В изолированной программной среде методы write() и writeln() могут использоваться без ограничений, пока для страницы не будет выполнено событие load . Тем не менее когда страница загружена, вызов этих методов не очистит страницу и не создаст новую. В изолированной программной среде вне приложения, характерной для большинства веб-обозревателей, вызов метода document.write() или writeln() после завершения загрузки страницы очищает текущую страницу и открывает новую, пустую.

Чтобы все элементы документа стали редактируемыми, установите для свойства document.designMode значение on . Встроенный редактор позволяет изменять, копировать, вставлять и перетаскивать текст. Значение on свойства designMode идентично значению true свойства contentEditable элемента body . Свойство contentEditable может использоваться в большинстве HTML-элементов для определения редактируемых областей документа. Дополнительные сведения см. в разделе « Атрибут contentEditable в HTML ».

В теге верхнего уровня frameset или body окна (в т. ч. и главного окна приложения) нельзя использовать событие unload для ответа на закрытие окна (или приложения). Вместо этого используйте событие exiting объекта NativeApplication (для определения момента закрытия приложения). Также может использоваться событие closing объекта NativeWindow (для определения закрытия окна). Например, в следующем коде JavaScript, когда пользователь закрывает приложение, выводится сообщение ( Goodbye. ):

var app = air.NativeApplication.nativeApplication; 
app.addEventListener(air.Event.EXITING, closeHandler); 
function closeHandler(event) 
{ 
    alert("Goodbye."); 
}

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

Объект Window остается глобальным объектом в контексте выполнения JavaScript. В изолированной программной среде приложения AIR добавляет новые свойства в объект JavaScript Window для обеспечения доступа к встроенным классам AIR, а также для важных домашних объектов. Кроме того, некоторые методы и свойства ведут себя по-разному в зависимости от того, находятся ли они внутри изолированной программной среды.

свойство Window.runtime

Свойство runtime позволяет создавать экземпляры и использовать встроенные классы среды выполнения в изолированной программной среде приложения. Эти классы включают API-интерфейсы AIR и проигрывателя Flash Player (но не инфраструктуру Flex). Например, следующая инструкция создает объект файла AIR:

var preferencesFile = new window.runtime.flash.filesystem.File();

Файл AIRAliases.js , включенный в комплект AIR SDK, содержит определения псевдонимов, позволяющих сокращать такие ссылки. Например, при импортировании на страницу файла AIRAliases.js объект File может быть создан с помощью следующей инструкции:

var preferencesFile = new air.File();

Свойство window.runtime определяется только для содержимого внутри изолированной программной среды и только для родительского документа страницы с фреймами, в т. ч. встроенными.

См. Использование файла AIRAliases.js .

Свойство Window.nativeWindow

Свойство nativeWindow содержит ссылку на основной объект исходного окна. С помощью этого свойства можно программировать функции и свойства окон: положение, размер, видимость экрана и др., — а также обрабатывать события окон: закрытие, изменение размера и перемещение. Например, следующая инструкция закрывает окно:

window.nativeWindow.close();

Примечание. Функции управления окнами объекта NativeWindow пересекаются с функциями объекта Window в JavaScript. В этих случаях можно выбрать тот метод, который вам наиболее удобен.

Свойство window.nativeWindow определяется только для содержимого внутри изолированной программной среды и только для родительского документа страницы с фреймами, в т. ч. встроенными.

Свойство Window.htmlLoader

Свойство htmlLoader содержит ссылку на объект AIR HTMLLoader с HTML-содержимым. С помощью этого свойства можно программировать поведение и внешний вид HTML-документа. Например, с помощью свойства htmlLoader.paintsDefaultBackground можно определить, будет ли фон белым (по умолчанию):

window.htmlLoader.paintsDefaultBackground = false;

Примечание. Сам объект HTMLLoader содержит свойство window , ссылающееся на объект JavaScript Window своего HTML-содержимого. Это свойство позволяет получать доступ к среде JavaScript с помощью ссылки на содержащий его HTMLLoader.

Свойство window.htmlLoader определяется только для содержимого внутри изолированной программной среды и только для родительского документа страницы с фреймами, в т. ч. встроенными.

Свойства Window.parentSandboxBridge и Window.childSandboxBridge

Свойства parentSandboxBridge и childSandboxBridge определяют интерфейс взаимодействия родительского и дочернего окон. Дополнительные сведения см. в разделе « Перекрестное выполнение сценариев в содержимом из различных изолированных программных сред безопасности ».

Функции Window.setTimeout() и Window.setInterval()

Среда AIR накладывает ограничения безопасности на использование функций setTimeout() и setInterval() в изолированной программной среде. Код, исполняемый в строке при вызове функций setTimeout() и setInterval() , определить нельзя. Следует использовать обращение к функции. Дополнительную информацию см. в описании функций Функции setTimeout() и setInterval() .

Функция Window.open()

Когда метод open() вызывается кодом, исполняемым в изолированной программной среде вне приложения, он открывает окно, только если он вызван в результате действий пользователя (например, щелчка мыши или нажатия клавиши). Кроме того, перед заголовком окна стоит заголовок приложения (это помогает отличать окна, открытые удаленным содержимым, от окон, открытых приложением). Дополнительные сведения см. в разделе « Ограничения по вызову метода JavaScript window.open() ».

Объект NativeApplication содержит информацию о состоянии приложения, отправляет некоторые важные события (уровня приложения) и содержит ряд функций по управлению поведением приложения. Единственный экземпляр объекта NativeApplication создается автоматически, и доступ к нему осуществляется с помощью свойства NativeApplication.nativeApplication .

Доступ к объекту из кода JavaScript может быть получен следующим образом:

var app = window.runtime.flash.desktop.NativeApplication.nativeApplication;

Или, если импортирован сценарий AIRAliases.js , можно воспользоваться сокращенным вариантом:

var app = air.NativeApplication.nativeApplication;

Доступ к объекту NativeApplication может быть получен только в пределах изолированной программной среды приложения. Дополнительные сведения об объекте NativeApplication см. в разделе « Работа с информацией среды выполнения AIR и операционной системы ».

Исполнение кода, заданного схемой URL-адресов JavaScript (например, href="javascript:alert('Test')" ), блокируется в изолированной программной среде приложения. Ошибка при этом не генерируется.