Руководство по платформе Windows

Это руководство показывает, как настроить среду разработки SDK для создания и развертывания приложений Cordova для Windows 8.1, Windows Phone 8.1 и универсальной платформы приложений Windows 10. Оно демонстрирует, как использовать командные утилиты оболочки для генерации и сборки приложений или кроссплатформенный интерфейс командной строки Cordova CLI. (См. Обзор для сравнения этих вариантов разработки). Этот раздел также показывает, как изменять приложения Cordova в Visual Studio. Независимо от выбранного подхода, необходимо установить SDK Visual Studio, как описано ниже.

Разработчики, желающие нацеливаться на Windows Phone 8, должны использовать платформу wp8, см. Руководство по платформе Windows Phone 8 для получения подробностей (Предупреждение: платформа wp8 устарела).

Интерфейсы Cordova WebView, работающие на Windows, полагаются на Internet Explorer 11 (Windows 8.1 и Windows Phone 8.1) в качестве движка рендеринга, поэтому практически вы можете использовать мощный отладчик IE для тестирования любого веб-контента, который не вызывает API Cordova. Блог разработчиков Windows Phone предоставляет полезные рекомендации по поддержке IE наряду с аналогичными браузерами WebKit.

Требования и поддержка

Для разработки приложений для платформы Windows вам необходимо:

• Компьютер под управлением Windows 8.1, 32 или 64 разрядный (изданий Home, Pro или Enterprise) с минимальным объёмом оперативной памяти 4 ГБ вместе с Visual Studio 2015 или Visual Studio 2013. Бесплатная версия Windows 8.1 Enterprise доступна на Microsoft Developer Network.

• Для эмуляторов Windows Phone требуется Windows 8.1 (x64) Professional или выше, а также процессор, поддерживающий Client Hyper-V и Second Level Address Translation (SLAT).

Для разработки приложений для Windows 10:

• Windows 8.1 или Windows 10, 32- или 64-битная система, вместе с Visual Studio 2015 или более поздней версии.

Совместимость приложений определяется ОС, для которой приложение предназначено. Приложения совместимы в будущем, но не в прошлом, поэтому приложение, нацеленное на Windows 10, не может работать на 8.1, но приложение, созданное для 8.1, может работать на 10.

Приложения Cordova, нацеленные на Windows, могут разрабатываться на Mac, либо с помощью виртуальной машины, либо с помощью Boot Camp для двойной загрузки раздела Windows 8.1. Обратитесь к этим ресурсам, чтобы настроить необходимую среду разработки Windows на Mac:

• VMWare Fusion

• Parallels Desktop

• Boot Camp

Установка требований

Установите любую версию Visual Studio, соответствующую перечисленным выше требованиям.

Инструменты и SDK для целевых платформ Windows (UWP, 8.1 и т. д.) также должны быть выбраны в установщике. Они находятся в разделе "Разработка для Windows и веб-приложений".

Настройка проекта

Целевая версия Windows

После установки вы должны быть готовы к разработке приложений, ориентированных на платформу Windows. Обратитесь к руководству Создать ваше первое приложение для получения подробностей.

По умолчанию команда cordova build создаёт два пакета: Windows 8.1 и Windows Phone 8.1. Для обновления пакета Windows до версии 10 необходимо добавить следующую настройку в файл конфигурации (config.xml).

<preference name="windows-target-version" value="10.0" />

После добавления этой настройки build команда начнёт создавать пакеты Windows 10.

Уточнения по целевой версии Windows

Windows 10 поддерживает новый "Удаленный" режим для приложений Cordova (и HTML-приложений в целом). Этот режим позволяет приложениям иметь большую свободу с точки зрения использования манипулирования DOM и общих веб-паттернов, таких как использование встроенных скриптов, но делает это, уменьшая набор возможностей вашего приложения, когда оно подаётся в публичный Windows Store. Для получения более подробной информации о Windows 10 и удалённом режиме, посмотрите раздел Понимание удалённого режима по сравнению с локальным режимом.

При использовании удалённого режима разработчикам рекомендуется применять политику безопасности содержимого (CSP) к своему приложению, чтобы предотвратить атаки со внедрением скриптов.

Параметр --appx

Вы можете решить, что хотите скомпилировать определённую версию вашего приложения для определённой ОС (например, вы можете указать, что хотите нацелиться на Windows 10, но вы хотите скомпилировать для Windows Phone 8.1). Для этого вы можете использовать параметр --appx:

cordova build windows -- --appx=8.1-phone

Система сборки проигнорирует предпочтение, установленное в config.xml, для целевой версии Windows и строго скомпилирует пакет для Windows Phone 8.1.

Допустимые значения для флага --appx — 8.1-win, 8.1-phone, и uap (для универсальных приложений Windows 10). Эти параметры также применяются к команде cordova run.

Параметры развертывания

Для развертывания пакета Windows:

cordova run windows -- --win  # explicitly specify Windows as deployment target
cordova run windows # `run` uses Windows package by default

Для развертывания пакета Windows Phone:

cordova run windows -- --phone  # deploy app to Windows Phone 8.1 emulator
cordova run windows --device -- --phone  # deploy app to connected device

Эта команда покажет список всех доступных целей:

cordova run windows --list

Это позволяет запустить приложение на конкретном устройстве или эмуляторе, в данном случае "Эмулятор 8.1 720p 4.7 дюйма"

cordova run windows --target="Emulator 8.1 720P 4.7 inch" -- --phone

Вы также можете использовать cordova run --help, чтобы увидеть дополнительные параметры сборки и запуска.

Использование Visual Studio для развертывания приложения

После сборки приложения Cordova вы можете открыть его в Visual Studio. Различные build команды генерируют файл решения Visual Studio (.sln). Откройте файл в проводнике, чтобы изменить проект в Visual Studio:

Компонент CordovaApp отображается в решении, а его каталог www содержит веб-исходный код, включая домашнюю страницу index.html:

Проекты для разных версий Windows отображаются раздельно в проводнике решений. Вы можете выбрать целевую версию развертывания, щелкнув правой кнопкой мыши по элементу «решение» (первый элемент в проводнике решений), а затем перейдя в «Свойства». Здесь вы можете обновить поле «Единственный запуск». Элементы управления ниже главного меню Visual Studio позволяют тестировать или развертывать приложение:

При выбранном Локальный компьютер, нажмите зеленую стрелку, чтобы установить приложение на тот же компьютер, на котором запущен Visual Studio. После этого приложение появится в списках приложений Windows:

Каждый раз при пересобирании приложения версия, доступная в интерфейсе, обновляется.

После появления в списках приложений, удерживая клавишу CTRL при выборе приложения, вы можете закрепить его на главном экране:

Обратите внимание, что если вы откроете приложение в среде виртуальной машины, вам может потребоваться щелкнуть в углах или по сторонам окон, чтобы переключаться между приложениями или получать доступ к дополнительным функциям:

В качестве альтернативы выберите вариант развертывания Симулятор, чтобы увидеть приложение, как если бы оно работало на планшетном устройстве:

В отличие от развертывания на настольном компьютере, этот параметр позволяет имитировать ориентацию, местоположение планшета и изменять его сетевые настройки.

ПРИМЕЧАНИЕ: Обратитесь к Обзору за советами по использованию инструментов командной строки Cordova или SDK в вашем рабочем процессе. Интерфейс командной строки Cordova использует кроссплатформенный исходный код, который регулярно перезаписывает платформоспецифические файлы, используемые SDK. Если вы хотите использовать SDK для изменения проекта, используйте инструменты оболочки более низкого уровня в качестве альтернативы интерфейсу командной строки.

Отладка

Visual Studio предоставляет мощные инструменты для отладки вашего приложения. Вы можете обратиться к этой статье, чтобы начать работу с ней.

Примечание: События возобновления и приостановки не срабатывают нормально при отладке приложений с помощью Visual Studio. Это связано с тем, что Windows не приостанавливает ваше приложение при отладке. Единственный способ изменить состояние приложения — через опции «Событие жизненного цикла» внутри Visual Studio. События должны работать как ожидается, когда приложение запускается на устройстве/эмуляторе без подключенного отладчика.

Подписание приложения

Вы можете узнать больше о подписании и упаковке приложений Windows Store на MSDN.

Для правильной упаковки и подписания приложений Windows требуется следующее:

• Сертификат подписи
• Данные идентификации, соответствующие предоставленному сертификату подписи

В проекте Windows данные идентификации хранятся в файле package.appxmanifest. Этот файл автоматически заполняется всякий раз, когда приложение Cordova компилируется. Идентификация содержит 3 важных поля.

• Имя
• Издатель
• Версия

Имя и Версия можно задать в config.xml. Издатель можно указать в качестве параметра сборки или установить в файле build.json.

Имя и Версия также могут быть заданы как платформенно-специфические параметры в config.xml следующим образом:

<widget windows-packageVersion="2.0.0" ...> <!-- windows-packageVersion overrides version -->
<preference name="WindowsStoreIdentityName" value="12345FakeCorp.CoolApp"/> <!-- WindowsStoreIdentityName overrides widget.id -->

PublisherDisplayName и DisplayName также могут быть перезаписаны:

<preference name="WindowsStorePublisherName" value="FakeCorp"/> <!-- WindowsStorePublisherName overrides author -->
<preference name="WindowsStoreDisplayName" value="CoolApp"/> <!-- WindowsStorePublisherName overrides name -->

Сертификат подписи можно предоставить как через интерфейс командной строки, так и через файл build.json. Флаги интерфейса командной строки, связанные с сертификатом:

Пример:

cordova build -- --packageCertificateKeyFile="platforms\windows\CordovaApp_TemporaryKey.pfx" --packageThumbprint="ABCABCABCABC123123123123"

В качестве альтернативы эти значения можно указать, используя файл конфигурации сборки (build.json) с помощью интерфейса командной строки (--buildConfig). Пример файла конфигурации сборки:

{
    "windows": {
        "debug": {
            "packageCertificateKeyFile": "platforms\\windows\\CordovaApp_TemporaryKey.pfx"
        },
        "release": {
            "packageCertificateKeyFile": "c:\\path-to-key\\keycert.pfx",
            "packageThumbprint": "ABCABCABCABC123123123123",
            "publisherId": "CN=FakeCorp.com, L=Redmond, S=Washington, C=US"
        }
    }
}

Также поддерживается сочетание аргументов командной строки и параметров в файле build.json. Значения из аргументов командной строки будут иметь приоритет.

Создание ключа сертификата

Для распространения и установки приложений Windows Store требуется подпись. Этот процесс обычно выполняется Visual Studio при развертывании пакета для выпуска. Чтобы сделать это без Visual Studio, нам нужно создать собственные сертификаты. Эта статья содержит инструкции по этому.

После создания файла pfx и предоставления его в файл build.json, вы можете получить следующую ошибку: «Файл ключа может быть защищен паролем. Чтобы исправить это, попробуйте вручную импортировать сертификат в хранилище личных сертификатов текущего пользователя». Для импорта необходимо использовать certutil из командной строки администратора:

certutil -user -p PASSWORD -importPFX FakeCorp.com.pfx

Где:

• user : Указывает хранилище личных сертификатов «текущего пользователя»
• p : Пароль для файла pfx
• importPfx : Имя файла pfx

После установки, следующим шагом является добавление packageThumbprint и packageCertificateKeyFile в build.json. Чтобы найти packageThumbprint, найдите CommonName, который вы связали с сертификатом:

powershell -Command " & {dir -path cert:\CurrentUser\My | where { $_.Subject -like \"*FakeCorp.com*\" }}"

После предоставления этих окончательных значений Cordova должен успешно упаковать и подписать приложение.

Флаги сборки MSBuild

Аналогично другим платформам (--gradleArg для Android, --buildFlag для iOS) вы можете передавать пользовательские флаги в MSBuild. Для этого у вас есть два варианта:

• Добавьте один или несколько --buildFlag параметров к cordova build windows или cordova run windows командам:

  cordova build windows -- --buildFlag /clp:Verbosity=normal --buildFlag /p:myCustomProperty=Value
  cordova run windows -- --buildFlag /clp:Verbosity=minimal
  

• Добавьте buildFlag параметр к build.json файлу:

  {
    "windows": {
      "debug": {
        "buildFlag": [
            "/clp:Verbosity=normal",
            "/p:myCustomProperty=Value"
        ]
      }
    }
  }
  

Обратите внимание, что cordova-windows добавляет флаги сборки из build.json и аргументы командной строки в определенном порядке. В частности, флаги из build.json добавляются *до* флагов сборки из командной строки, что фактически означает, что флаги командной строки *перезаписывают* флаги из build.json в случае конфликтов.

Список доступных параметров командной строки MSBuild см. в официальной справке по командной строке MSBuild.

Рабочий процесс, ориентированный на платформу

Если вы хотите использовать инструменты оболочки Cordova для Windows совместно с SDK, у вас есть два основных варианта:

• Доступ к ним локально из кода проекта, сгенерированного CLI. Они доступны в каталоге platforms/windows/ после добавления платформы windows , как описано ниже.

• Загрузить их из отдельного дистрибутива здесь. Дистрибутив Cordova содержит отдельные архивы для каждой платформы. Убедитесь, что соответствующий архив cordova-windows распакован в пустой каталог. Соответствующие утилиты командной строки доступны в каталоге package/bin. (Обратитесь к файлу README, если необходимо, для получения более подробных инструкций.)

Эти инструменты оболочки позволяют создавать, компилировать и запускать приложения Windows. Каждая команда cordova соответствует одному из этих скриптов инструментов оболочки.

Например, подход на уровне инструмента оболочки, соответствующий cordova create HelloWorld:

C:\path\to\cordova-windows\package\bin\create.bat C:\path\to\new\hello HelloWorld

Аналогично для cordova build --debug:

C:\path\to\project\cordova\build.bat --debug

Обновление

Обратитесь к статье здесь для получения инструкций по обновлению вашей версии cordova-windows.

Поддержка уведомлений

Windows требует объявления возможности в манифесте приложения для поддержки уведомлений. При использовании плагина cordova-plugin-local-notifications или любого другого плагина, пытающегося использовать уведомления, добавьте следующие настройки в ваш config.xml для включения возможности публикации уведомлений, если плагин не выполняет это изменение самостоятельно:

<preference name="WindowsToastCapable" value="true" />

Эта настройка устанавливает соответствующий флаг в вашем манифесте приложения. Плагины должны выполнить необходимые действия для настройки отображения уведомлений.

Понимание режимов удаленного и локального

Windows 10 вводит новую функцию «Удаленный режим» для HTML-приложений. Ранее приложения Windows 8.1 работали в режиме, который теперь называется «Локальный режим» в Windows 10, в котором HTML-приложения имеют полный доступ к нативной поверхности API Windows и возможностям. Локальный режим не допускает встроенный сценарий для предотвращения атак на внедрение сценариев, которые могут привести к утечке персональной информации из-за вредоносного кода. Он также требует, чтобы разработчики, выполняющие манипуляции с DOM, делали это в явном контексте (MSApp.execUnsafeLocalFunction).

Удаленный режим устраняет эти требования, что позволяет использовать немодифицированные библиотеки, такие как jQuery или AngularJS, непосредственно в вашем коде без каких-либо изменений. Для этого он удаляет вашу возможность объявлять определенные возможности при сертификации вашего приложения в магазине Windows. Удаление этих возможностей обычно не препятствует доступу к определенным функциям, но может потребовать использования другой комбинации API или тактики.

Влияние удаленного режима на возможности

Следующие возможности недоступны при развертывании вашего приложения в удаленном режиме в Магазине Windows:

• Корпоративная аутентификация (enterpriseAuthentication)
• Общие сертификаты пользователей (sharedUserCertificates)
• Библиотека документов (documentsLibrary)
• Библиотека музыки (musicLibrary)
• Библиотека изображений (picturesLibrary)
• Библиотека видео (videosLibrary)
• Съемные хранилища (removableStorage)
• Клиент/сервер Интернета (internetClientServer) — обратите внимание, что internetClient всё ещё разрешено
• Клиент/сервер частной сети (privateNetworkClientServer)

Каждое из ограничений на библиотеки можно обойти, попросив пользователя взаимодействовать с файловой системой через File Picker. Это предотвращает вредоносный введённый код от произвольного доступа к файловой системе.

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

Возможности корпоративной аутентификации и общих сертификатов пользователей специально ориентированы на корпоративные сценарии. Эти возможности поддерживаются в частных/корпоративных магазинах приложений, поэтому, если вы создаёте приложения, которые будут развертываться в внутренней системе, вы всё ещё можете поддерживать их. Однако они не поддерживаются для приложений в удалённом режиме в общедоступном магазине Windows. При создании приложения с целевой платформой Windows 10, если одна из этих возможностей обнаружена в вашем манифесте приложения, будет отображено предупреждение.