Руководство по платформе 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 Store. Удаление этих возможностей обычно не препятствует доступу к определённым функциям, но может потребовать использования другой комбинации API или тактик.

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

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

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

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

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

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

При построении приложений для Windows 10, если одна из этих возможностей обнаружена в манифесте приложения, будет отображено предупреждение.

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

В то время как прокрутка WebView включена по умолчанию в «удаленном режиме» и на других платформах, в «локальном режиме» это не так. Если прокрутка требуется в «локальном режиме», она может быть включена с помощью свойства CSS overflow.