Просмотр кода страницы Инструментирование элементов управления SwiftUI

'''ЕдиныйАгент для iOS версии 8.249+'''

После инструментирования вашего мобильного приложения с помощью ЕдиныйАгент для iOS, вам может потребоваться также инструментировать SwiftUI-элементы вашего приложения. Эта страница содержит дополнительную информацию о том, как настроить ваш проект, обновить SwiftUI instrumentor, преодолеть некоторые известные ограничения и многое другое.

Для инструментирования элементов управления SwiftUI, SwiftUI instrumentor добавляет дополнительный код в исходный код вашего проекта (файлы '''*.swift''') в процессе сборки. Этот код отслеживает состояние элементов пользовательского интерфейса и уведомляет ЕдиныйАгент для iOS обо всех обновлениях. После завершения процесса сборки все изменения в исходном коде вашего проекта отменяются.

{| class="wikitable"
|❗ '''''Важно'''''

''Для получения подробной информации			о действиях, выполняемых SwiftUI			instrumentor, и копии			измененных файлов кода проверьте			каталог '''Ключ-АСТРОМ_instrumented'''.			SwiftUI instrumentor			создает резервные копии инструментированных			файлов и сгенерированных журналов в			формате ZIP-архива.''
|}

= 1. Требования =

* SwiftUI	version 2.0+
* iOS 14+
* ЕдиныйАгент for	iOS

= 2. Поддерживаемые элементы управления =

* Button
* Stepper
* Picker
* Toggle
* Slider

= 3. Необходимые шаги =

# Создайте	приложение в веб-интерфейсе Ключ-АСТРОМ.
# Настройте	ЕдиныйАгент для своего проекта
# Установите	[[Инструментирование элементов управления SwiftUI#%204.1.%20%D0%A3%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0%20SwiftUI|SwiftUI	instrumentor]]

= 4. Управление SwiftUI instrumentor =

== 4.1. Установка SwiftUI instrumentor ==
Для инструментирования элементов управления SwiftUI в вашем приложении установите

Ключ-АСТРОМ SwiftUI instrumentor. Вы можете сделать это через Homebrew или вручную.
{| class="wikitable"
|+
!'''Homebrew'''
!'''Вручную'''
|-
|
# Запустите	команду '''brew tap	Ключ-АСТРОМ/tools''',	чтобы добавить один из Ключ-АСТРОМ	taps.
# Запустите	команду '''brew install	DTSwiftInstrumentor''', чтобы	установить SwiftUI instrumentor.
# Закройте	Xcode и выполните команду '''DTSwiftInstrumentor	install <PROJECT.xcodeproj> --scheme <SCHEME> --target	<TARGET>'''.
|
# Скачайте	и распакуйте ZIP-файл, содержащий наш	SwiftUI instrumentor. Ссылка на	файл доступна в мастере мобильной	инструментации (mobile	instrumentation wizard).
# Создайте	папку '''.Ключ-АСТРОМ''' в корне вашего проекта	- на том же уровне, что и файл '''*.xcodeproj'''.

❗ '''''Важно'''''

Если вы получаете системное предупреждение о том, что вы не можете создать папку с именем, начинающимся с точки, выполните одно из следующих действий:

* В терминале	запустите команду '''mkdir .Ключ-АСТРОМ''' в корне	проекта, чтобы создать папку '''.Ключ-АСТРОМ'''.
* В терминале	запустите команду '''defaults write com.apple.finder	AppleShowAllFiles true''' и '''killall Finder''', чтобы	показать скрытые папки и файлы. Затем	в Finder создайте папку '''.Ключ-АСТРОМ'''.

Вы также можете выполнить команду '''defaults write com.apple.finder AppleShowAllFiles false''' и '''killall Finder''', чтобы снова скрыть скрытые папки и файлы.

3. Скопируйте	загруженный '''DTSwiftInstrumentor'''	в папку '''.Ключ-АСТРОМ''' и	убедитесь, что файл можно выполнить	(executable).

4. Выйдите	из Xcode и выполните команду	'''.Ключ-АСТРОМ/DTSwiftInstrumentor install	<PROJECT.xcodeproj> --scheme <SCHEME> --target <TARGET>'''.
|}
❗ '''''Важно'''''

Если при реализации возникнет ошибка, проверьте журнал сборки Xcode или журнал инструментации для получения подробной информации об ошибке. Дополнительные подсказки см. в разделе [[Инструментирование элементов управления SwiftUI#%208.%20%D0%A3%D1%81%D1%82%D1%80%D0%B0%D0%BD%D0%B5%D0%BD%D0%B8%D0%B5%20%D0%BD%D0%B5%D0%BF%D0%BE%D0%BB%D0%B0%D0%B4%D0%BE%D0%BA|Устранение неполадок]].

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

== 4.2. Обновление SwiftUI instrumentor ==
Когда новая версия SwiftUI будет доступна, вы сможете обновить ее через Homebrew или вручную.
{| class="wikitable"
!'''Homebrew'''
!'''Вручную'''
|-
|Как только новая версия инструмента будет выпущена, она будет загружаться через добавленный tap. Чтобы обновить SwiftUI instrumentor, запустите команды '''brew update''' и '''brew upgrade DTSwiftInstrumentor'''.
|
# Скачайте	и разархивируйте ZIP-файл, содержащий	новую версию SwiftUI instrumentor.	Ссылка доступна в мастере мобильной	инструментации (mobile	instrumentation wizard).
# Скопируйте	загруженный '''DTSwiftInstrumentor''' в папку	'''.Ключ-АСТРОМ''' и замените существующий файл.
|}
❗ '''''Важно'''''

Если вы видите следующее предупреждение при сборке, вам также нужно обновить скрипты сборки, которые были интегрированы во время установки Ключ-АСТРОМ SwiftUI instrumentor.

Ключ-АСТРОМ: There is an upgrade for your project instrumentation. Please execute "DTSwiftInstrumentor project-upgrade <PROJECT.xcodeproj>" to upgrade your project

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

== 4.3. Удаление SwiftUI instrumentor ==
Если вам больше не нужен Ключ-АСТРОМ SwiftUI instrumentor, вы можете удалить его из системы с помощью Homebrew или вручную удалить его из своего проекта.
{| class="wikitable"
!'''Homebrew'''
!'''Вручную'''
|-
|Выполните команду '''brew remove DTSwiftInstrumentor''' и '''brew untap Ключ-АСТРОМ/tools''', чтобы удалить SwiftUI instrumentor из вашей системы.
|
# Запустите	'''DTSwiftInstrumentor uninstall <PROJECT.xcodeproj>''',	чтобы удалить SwiftUI instrumentor	из вашего проекта.
# (Опционально)	Удалите папки '''.Ключ-АСТРОМ''' и	'''Ключ-АСТРОМ_instrumented''' из вашего проекта.

Эти папки содержат кэш, данные журналов и, при наличии, вручную установленный бинарный файл инструментария. Они содержат кэш инструментария, данные журналов и, при наличии, бинарные файлы инструментария.
|}

= 5. Проверьте различия инструментирования SwiftUI =
'''ЕдиныйАгент для iOS версии 8.257+'''

Для проверки различий между вашим исходным кодом и кодом, измененным SwiftUI instrumentor, выполните одну из следующих команд:

* Из	корневой директории проекта выполните	одну из следующих команд, чтобы проверить	разницу между вашим и измененным	инструментом SwiftUI:
** '''DTSwiftInstrumentor		diff''', если вы установили инструмент с		помощью Homebrew
** '''.Ключ-АСТРОМ/DTSwiftInstrumentor		diff''', если вы установили инструмент		вручную
* Из любой	директории:
** '''DTSwiftInstrumentor		diff		<путь-к-корневой-директории-проекта>'''

= 6. Известные ограничения =

== 6.1. Инструментирование пользовательских элементов управления SwiftUI не поддерживается ==
В настоящее время Ключ-АСТРОМ не поддерживает инструментирование пользовательских элементов управления SwiftUI. Список элементов управления SwiftUI, которые можно инструментировать, можно найти в разделе [[Инструментирование элементов управления SwiftUI#%202.%20%D0%9F%D0%BE%D0%B4%D0%B4%D0%B5%D1%80%D0%B6%D0%B8%D0%B2%D0%B0%D0%B5%D0%BC%D1%8B%D0%B5%20%D1%8D%D0%BB%D0%B5%D0%BC%D0%B5%D0%BD%D1%82%D1%8B|Поддерживаемые элементы управления]].

== 6.2. Проблемы с предпросмотром в Xcode. ==
Когда сборка симулятора включала инструменты SwiftUI, предварительные просмотры не загружались в Xcode. В качестве обходного пути мы отключили инструментарий SwiftUI для сборок симулятора. Если вы хотите добавить инструментарий SwiftUI в сборки симулятора, см. [[Инструментирование элементов управления SwiftUI#%207.3.%20%D0%A1%D0%B1%D0%BE%D1%80%D0%BA%D0%B8%20%D1%81%D0%B8%D0%BC%D1%83%D0%BB%D1%8F%D1%82%D0%BE%D1%80%D0%B0|Сборки симулятора инструментов]].

== 6.3. Только SwiftUI 2.0+ ==
Ключ-АСТРОМ поддерживает инструментирование SwiftUI 2.0+ потому, что listener '''onChange''' недоступен в более ранних версиях SwiftUI. Поэтому требуется версия iOS 14+ для целевой платформы.

== 6.4. Более длительное время сборки ==
В отличие от ЕдиныйАгент для iOS, который изменяет ваше мобильное приложение в памяти во время выполнения, SwiftUI instrumentor изменяет исходный код вашего проекта во время сборки. По этой причине, процесс инструментации SwiftUI существенно влияет на время сборки.

Чтобы сократить время сборки, можно использовать следующие методы:

* Собирайте	приложение только для устройств	('''Device'''). Если вы решили	инструментировать сборки для симулятора,	отключите эту функцию.
* Не	запускайте инструментирование SwiftUI на	каждой возможной сборке. Мы рекомендуем	запускать инструментирование SwiftUI на	ветках, таких как '''main''' или '''release'''.

== 6.5. Несовместимость с watchOS ==
Невозможно скомпилировать проект, содержащий файлы, добавляемые в цель watchOS, поскольку ЕдиныйАгент для watchOS отсутствует. В этом случае [[Инструментирование элементов управления SwiftUI#%207.2.%20%D0%98%D1%81%D0%BA%D0%BB%D1%8E%D1%87%D0%B8%D1%82%D1%8C%20%D1%84%D0%B0%D0%B9%D0%BB%D1%8B|вручную исключите]] все файлы, которые используются совместно или являются частью цели watchOS.

== 6.6. tvOS не поддерживается ==
В настоящее время официальной поддержки сборок tvOS SwiftUI нет.

= 7. Настройка инструментирования SwiftUI =

== 7.1. Включить повтор сеанса (Session Replay) при сбоях ==
Воспроизведение сеанса при сбоях может фиксировать и визуально воспроизводить действия, которые пользователь вашего приложения выполнял до того, как произошел сбой.

== 7.2. Исключить файлы из SwiftUI instrumentor ==
По умолчанию, инструментатор Ключ-АСТРОМ SwiftUI обрабатывает все файлы с расширением '''.swift''', но инструментирует только файлы, содержащие поддерживаемые элементы управления. Если необходимо, вы можете исключить определенные файлы и директории из процесса инструментирования SwiftUI.

Чтобы исключить файлы и директории из процесса инструментирования SwiftUI:

# Добавьте	ключ конфигурации '''DTXExcludedSwiftUIFiles''' в	файл '''Info.plist''' вашего проекта.
# Перечислите	относительные пути ко всем файлам и	каталогам, которые вы не хотите	инструментировать. Пути должны	указываться относительно корня проекта,	то есть каталога, в котором находится	файл '''.xcodeproj'''.

<key>DTXExcludedSwiftUIFiles</key>

<array>

<string>relative/file/path/</string>

<string>relative/file.swift</string>

</array>


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

== 7.3. Сборки симулятора инструментов ==
Мы отключили инструментирование SwiftUI для сборок симулятора, чтобы решить [[Инструментирование элементов управления SwiftUI#%206.2.%20%D0%9F%D1%80%D0%BE%D0%B1%D0%BB%D0%B5%D0%BC%D1%8B%20%D1%81|проблему с предварительным просмотром в Xcode]].

Чтобы включить инструменты SwiftUI для сборок симулятора, добавьте ключ конфигурации '''DTXSwiftUIInstrumentSimulatorBuilds''' в файл '''Info.plist''' вашего проекта и установите для этого ключа значение '''true'''.

<key>DTXSwiftUIInstrumentSimulatorBuilds</key>

<true/>

== 7.4. Создание сборок для неподдерживаемых целей развертывания ==
SwiftUI instrumentor генерирует код, совместимый со SwiftUI 2.0+, который работает только на устройствах с iOS 14+. Попытка создать сборки для целей развертывания iOS 13 и более ранних версий завершится ошибкой.

Чтобы переопределить эту проверку, добавьте ключ конфигурации '''DTXSwiftUIIgnoreDeploymentTarget''' в файл '''Info.plist''' вашего проекта и установите для этого ключа значение '''true'''.

<key>DTXSwiftUIIgnoreDeploymentTarget</key>

<true/>

== 7.5. Включить сопоставление номеров строк для проектов Objective-C ==
Отчеты о сбоях, доступные в Ключ-АСТРОМ, не основаны на исходном коде вашего проекта. Эти отчеты основаны на измененном коде, который Ключ-АСТРОМ генерирует во время инструментирования. Вот почему сопоставление номеров строк добавляется в ваш проект во время инструментирования, а затем передается в Ключ-АСТРОМ при запуске приложения. В противном случае номера строк в отчетах о сбоях будут неверными.

По умолчанию Ключ-АСТРОМ SwiftUI instrumentor создает сопоставление номеров строк и вставляет его в основной класс вашего проекта. Это происходит автоматически для проектов с основным классом Swift, но не для устаревших проектов Objective-C. Для таких проектов вы получите сообщение об ошибке, и наш инструментарий SwiftUI не будет инструментировать ваше мобильное приложение.

Чтобы включить сопоставление номеров строк для проектов Objective-C

# Добавьте	ключ конфигурации '''DTXSwiftUIManualPlaceholder'''	в файл '''Info.plist''' вашего проекта и	установите для этого ключа значение	'''true'''.

<key>DTXSwiftUIManualPlaceholder</key>

<true/>

# Добавьте	в основной класс специальный placeholder	'''AppDelegate.m'''.
# Добавьте	'''[Ключ-АСТРОМ	setSwiftUiMapping:@"_Ключ-АСТРОМ_SWIFTUI_MAPPING_PLACEHOLDER_"];'''	к основному классу либо в методе '''init''',	либо в методе '''didFinishLaunchingWithOptions'''.

Во время сборки, SwiftUI instrumentor заменяет часть этой строки сгенерированным сопоставлением номеров строк.

== 7.6. Включить автоматическую очистку журнала ==
'''ЕдиныйАгент для iOS версии 8.257+'''

После каждой сборки SwiftUI instrumentor создает резервные копии инструментированных файлов и сгенерированных журналов, которые хранятся в каталоге '''Ключ-АСТРОМ_instrumented'''. По умолчанию эти файлы не удаляются, и общий размер каталога со временем будет расти. По этой причине мы рекомендуем вам включить автоматическую очистку журнала.

* Чтобы	удалить журналы SwiftUI instrumentor	после определенного количества сборок,	добавьте ключ конфигурации	'''DTXCleanSwiftUILogsByCount''' в файл '''Info.plist'''	вашего проекта.

<key>DTXCleanSwiftUILogsByCount</key>

<number>10</number>

* Чтобы	удалить журналы через определенное	количество дней, добавьте ключ	конфигурации '''DTXCleanSwiftUILogsByAgeDays'''	в файл '''Info.plist'''.

<key>DTXCleanSwiftUILogsByAgeDays</key>

<number>5</number>


Если вы добавите оба ключа в файл '''Info.plist''', ключ '''DTXCleanSwiftUILogsByAgeDays''' будет иметь приоритет.

= 8. Устранение неполадок =
Мы все еще работаем над улучшением процесса инструментирования SwiftUI. Если у вас возникнут какие-либо проблемы при инструментировании элементов управления SwiftUI, обратитесь в службу поддержки Ключ-АСТРОМ и предоставьте файл журнала затронутой сборки. Вы можете найти файл журнала самой последней сборки по пути '''Ключ-АСТРОМ_instrumented/current/instrumentation.log'''. Файлы журналов предыдущих сборок находятся в архивах с отметками времени в разделе '''Ключ-АСТРОМ_instrumented'''.

== 8.1. Инструментация уже работает ==
Если у вас возникла проблема с Ключ-АСТРОМ SwiftUI instrumentor, и он не был восстановлен автоматически, выполните шаги, описанные ниже.

# Остановите	процесс '''DTSwiftInstrumentor''', если он все еще	существует.
# Если вы	видите изменения, сделанные SwiftUI	instrumentor в исходном коде	вашего проекта, выполните следующую	команду в корне проекта:

* '''DTSwiftInstrumentor	restore .''' если вы установили инструмент	через Homebrew
* '''.Ключ-АСТРОМ/DTSwiftInstrumentor	restore .''' если вы установили инструмент	вручную

== 8.2. DTSwiftInstrumentor завершил работу с ошибкой при обработке <filename> ==
Бинарный файл SwiftUI instrumentor дал сбой. Обратитесь в службу поддержки Ключ-АСТРОМ и предоставьте файл журнала затронутой сборки.