NativeBook: объединение опыта разработки для iOS с помощью Storybook.js

Введение Внедрение, поддержка, документирование и развитие общего набора компонентов пользовательского интерфейса является сложной задачей в крупномасштабном приложении. Веб-разработчики создали мощное решение этой проблемы — Storybook.js ( ). А как насчет нативной разработки ? Можем ли мы добиться чего-то подобного? (Внимание, спойлер: ) https://storybook.js.org для iOS да! Но сначала давайте рассмотрим исходную концепцию Storybook.js. Storybook.js Storybook.js — это инструмент с открытым исходным кодом, используемый веб-разработчиками для изолированного создания и тестирования компонентов пользовательского интерфейса для веб-приложений. Думайте об этом как о игровой площадке, где разработчики могут создавать и демонстрировать отдельные части веб-сайта (например, кнопки, формы и панели навигации) отдельно от остальной части веб-сайта. Storybook.js служит живой документацией компонентов и предоставляет визуальные эффекты, позволяющие увидеть, как компоненты выглядят и ведут себя в различных состояниях и сценариях, а также примеры кода. Элегантность Storybook.js заключается в том, что компоненты пользовательского интерфейса используются в одной и той же среде; будь то рабочий веб-сайт или сайт Storybook, мы по-прежнему запускаем их в веб-браузере. Это гарантирует, что компоненты будут выглядеть согласованно в нашей документации/игровой площадке и в рабочей среде, предотвращая их рассинхронизацию. Веб-страницы также являются отличным средством хранения документации, обеспечивая удобство чтения, удобство совместного использования, мгновенную загрузку и универсальную доступность на любом устройстве и в любой операционной системе. Однако с ситуация другая. приложениями для iOS Тем временем на iOS В iOS набор инструментов и методов, связанных с разработкой компонентов пользовательского интерфейса, весьма фрагментирован. Давайте посмотрим на них с точки зрения Storybook.js. Разработчик интерфейсов Интерфейсный конструктор предоставляет интерфейс с возможностью перетаскивания, что позволяет легко разрабатывать пользовательские интерфейсы без написания кода. Обычно он используется для размещения существующих компонентов пользовательского интерфейса для целых экранов, а не для разработки отдельных компонентов пользовательского интерфейса. Он не очень хорошо подходит для демонстрации различных состояний компонентов пользовательского интерфейса и обработки сложных пользовательских интерфейсов в целом, часто требуя реализации многих аспектов в коде. В целом, многие, включая Apple, считают это тупиком. Предварительный просмотр SwiftUI SwiftUI Previews — это инструмент, созданный Apple для разработки и тестирования представлений SwiftUI в Xcode. Предварительные просмотры SwiftUI также можно использовать для UIView. См. https://sarunw.com/posts/xcode-previews-with-uiview. Плюсы: Отлично подходит для изолированной разработки Поддержка горячей перезагрузки Используйте настоящий симулятор iOS под капотом Отображение активных компонентов рядом с фрагментом кода Удобно для тестирования динамического типа и темного режима. Минусы: Требовать, чтобы Xcode был установлен с правильно настроенной средой разработки. Время сборки может быть длительным Работают ненадежно и довольно часто выходят из строя Ресурсоемкий, работает медленно даже на высокопроизводительных машинах. Когда это работает, предварительный просмотр SwiftUI, вероятно, наиболее близок к Storybook.js, за исключением аспекта «документации». Генерация документации на основе HTML Следующее, что нам предстоит сделать, — это генерация документации на основе исходного кода, комментариев и аннотаций. Наиболее яркими примерами являются: DocC — https://developer.apple.com/documentation/docc. Джаззи - https://github.com/realm/jazzy Этот тип инструментов можно использовать для создания ссылок на API компонентов в форме веб-страницы. Снимковое тестирование Снимковые тесты — отличный способ изолированной разработки, тестирования различных визуальных состояний компонента, гарантирующих, что что-то не изменится неожиданно. Две наиболее популярные библиотеки, реализующие тестирование снимков на iOS: iOSSnapshotTestCase — https://github.com/uber/ios-snapshot-test-case SnapshotTesting — https://github.com/pointfreeco/swift-snapshot-testing Приложение индивидуального каталога Еще одним очевидным выбором для Storybook.js является создание собственного собственного приложения-каталога. Плюсы: Использует ту же среду, что и в рабочей среде: симулятор iOS или устройство. Отображает реальные компоненты на экране Позволяет тестировать доступность, интернационализацию и темный режим. Минусы: Это приложение; это не мгновенный опыт, и его создание и запуск сопряжены с дополнительными хлопотами. Опыт документирования полностью отсутствует. Некоторые примеры: https://github.com/aj-bartocci/Storybook-SwiftUI https://github.com/hpennington/SwiftBook https://github.com/eure/Storybook-ios Одна классная, хотя и экстравагантная идея — встроить собственное приложение-каталог в веб-сайт Storybook.js с помощью сервиса Appetize.io, который позволяет транслировать содержимое устройства iOS на веб-страницу — . https://medium.com/@vasikarla .raj/storybook-for-native-d772654c7133 Еще одна идея Это факт, что в собственной мобильной разработке отсутствует секретный ингредиент, необходимый для работы, подобной Storyboard.js: единая среда для запуска документации, игровых площадок и производства, и все это на самой доступной платформе — веб-сайте. Но что, если мы объединим приложение-каталог, тесты снимков и генерацию документации на основе HTML в единую систему? Представьте себе, что вы написали фрагмент кода всего один раз, а затем можете сделать следующее: Отображение представления, созданного на основе фрагмента, в собственном приложении-каталоге. Встраивание представления в предварительный просмотр SwiftUI Запустите проверку снимка фрагмента Отобразите этот фрагмент кода и полученный снимок в созданной документации на основе HTML. Хорошие новости! Я построил доказательство концепции такой системы: https://github.com/psharanda/NativeBook Давайте посмотрим и соберем! NativeBook в настоящее время фокусируется на компонентах на основе UIView. Компоненты SwiftUI также можно интегрировать аналогичным образом, хотя они не рассматриваются в этой статье. Реализация NativeBook Истории История — краеугольный камень нашей системы. По сути, это именованный фрагмент кода, который демонстрирует «интересное» состояние компонента пользовательского интерфейса. Его можно представить в виде простой структуры: struct Story { let name: String let makeView: () -> UIView? } Следующий объект — , который содержит список историй для компонента: ComponentStories protocol ComponentStories { var componentName: String { get } var stories: [Story] { get } } Итак, как мы собираемся объявить фрагмент? Для упрощения анализа и удобства функция может иметь специальное соглашение об именах, которое начинается с . В общем, каждый фрагмент кода для истории: story_ Создает представление Настраивает его (что может включать в себя установку ограничений ширины/высоты) Возвращает представление Вот пример фрагмента: @objc static func story_RoundedCornerButton() -> UIView { let button = UIButton() var config = UIButton.Configuration.filled() config.title = "Rounded" config.cornerStyle = .medium button.configuration = config return button } Мы можем улучшить процесс написания историй и сократить количество шаблонов, используя динамическую природу Objective-C. Идея состоит в том, чтобы иметь базовый класс, способный извлекать все селекторы классов, начинающиеся с , и создавать из них список историй. store_ class DynamicComponentStories: NSObject, ComponentStories { var componentName: String { return NSStringFromClass(type(of: self)) .split(separator: ".").last! .replacingOccurrences(of: "Stories", with: "") } private(set) lazy var stories: [Story] = { var methodCount: UInt32 = 0 guard let methodList = class_copyMethodList(object_getClass(type(of: self)), &methodCount) else { return [] } var uniqueSelectors = Set () var selectors = [Selector]() for i in 0 ..< Int(methodCount) { let selector = method_getName(methodList[i]) let name = NSStringFromSelector(selector) if name.starts(with: "story_") { if !uniqueSelectors.contains(name) { uniqueSelectors.insert(name) selectors.append(selector) } } } free(methodList) let cls = type(of: self) return selectors.map { selector in Story(name: NSStringFromSelector(selector).replacingOccurrences(of: "story_", with: "")) { cls.perform(selector).takeUnretainedValue() as? UIView } } }() } Например, класс, в котором размещаются истории для UILabel, может быть структурирован следующим образом: class UILabelStories: DynamicComponentStories { @objc static func story_BasicLabel() -> UIView { … } @objc static func story_FixedWidthLabel() -> UIView { … } } Приложение-каталог Приложение-каталог в своей простейшей форме обычно состоит из двух экранов. Главный экран: на этом экране отображается список компонентов и связанные с ними истории. class StorybookViewController: UITableViewController { let componentsStories: [ComponentStories] init(componentsStories: [ComponentStories]) { self.componentsStories = componentsStories super.init(style: .plain) title = "UIKit: NativeBook" } override func numberOfSections(in _: UITableView) -> Int { return componentsStories.count } override func tableView(_: UITableView, numberOfRowsInSection section: Int) -> Int { return componentsStories[section].stories.count } override func tableView(_: UITableView, titleForHeaderInSection section: Int) -> String? { return componentsStories[section].componentName } override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell { let cell = tableView.dequeueReusableCell(withIdentifier: "CellId") ?? UITableViewCell() cell.textLabel?.text = componentsStories[indexPath.section].stories[indexPath.row].name return cell } override func tableView(_: UITableView, didSelectRowAt indexPath: IndexPath) { let storyViewController = StoryViewController(story: componentsStories[indexPath.section].stories[indexPath.row]) navigationController?.pushViewController(storyViewController, animated: true) } } Экран сведений: на этом экране мы отображаем компонент в центре, не ограничивая его ширину или высоту, поскольку определение этих атрибутов зависит от фрагмента. class StoryViewController: UIViewController { let story: Story init(story: Story) { self.story = story super.init(nibName: nil, bundle: nil) title = story.name } override func viewDidLoad() { super.viewDidLoad() view.backgroundColor = .secondarySystemBackground guard let storyView = story.makeView() else { return } view.addSubview(storyView) storyView.translatesAutoresizingMaskIntoConstraints = false NSLayoutConstraint.activate([ storyView.centerXAnchor.constraint(equalTo: view.centerXAnchor), storyView.centerYAnchor.constraint(equalTo: view.centerYAnchor), ]) } } Весь поток каталога можно инициализировать следующим образом: let vc = StorybookViewController(componentsStories: [ UILabelStories(), UIButtonStories(), UITextFieldStories(), ]) let nc = UINavigationController(rootViewController: vc) window.rootViewController = nc Предварительный просмотр SwiftUI Мы можем взять идею PreviewContainer и ее реализацию с . https://sarunw.com/posts/xcode-previews-with-uiview/ struct PreviewContainer : UIViewRepresentable { let view: T init(_ viewBuilder: @escaping () -> T) { view = viewBuilder() } func makeUIView(context: Context) -> T { return view } func updateUIView(_ view: T, context: Context) { view.setContentHuggingPriority(.defaultHigh, for: .horizontal) view.setContentHuggingPriority(.defaultHigh, for: .vertical) } } И напишите наши превью так же просто, как это struct UIButton_Previews: PreviewProvider { static var previews: some View { ForEach(UIButtonStories().stories, id: \.name) { story in PreviewContainer { story.makeView()! } .previewDisplayName(story.name) } } } Снимковые тесты В нашем примере мы будем использовать библиотеку . iOSSnapshotTestCase В iOS 17 были введены некоторые ценные дополнения к API для переопределения признаков через . Это свойство чрезвычайно полезно для поддержки доступности при тестировании моментальных снимков. Для наших тестов снимков мы собираемся протестировать одно и то же представление в различных условиях, применяя RTL, темный режим и некоторые категории динамического типа. UIView UIView.traitOverrides Важно отметить, что для тестирования нам нужно использовать метод и убедиться, что тестируемые представления добавлены в ключ приложения . traitOverrides drawViewHierarchy(in:afterScreenUpdates:) UIWindow class NativeBookSnapshotTestCase: FBSnapshotTestCase { override func setUp() { super.setUp() usesDrawViewHierarchyInRect = true } func runTests(for componentStories: ComponentStories) { for story in componentStories.stories { if let view = story.makeView() { NativeBookVerifyView(view, storyName: story.name) } } } private func NativeBookVerifyView(_ view: UIView, storyName: String) { let window = UIApplication.shared.connectedScenes .compactMap { ($0 as? UIWindowScene)?.keyWindow }.last! window.addSubview(view) view.translatesAutoresizingMaskIntoConstraints = false NSLayoutConstraint.activate([ view.centerXAnchor.constraint(equalTo: window.centerXAnchor), view.centerYAnchor.constraint(equalTo: window.centerYAnchor), ]) // testing a view for different dynamic type modes let contentSizeCategories: [UIContentSizeCategory: String] = [ .extraSmall: "xs", .medium: "m", .large: "default", .extraLarge: "xl", .extraExtraExtraLarge: "xxxl", ] for (category, categoryName) in contentSizeCategories { view.traitOverrides.preferredContentSizeCategory = category window.layoutIfNeeded() FBSnapshotVerifyView(view, identifier: storyName + "__" + categoryName) } // testing dark mode support view.traitOverrides.preferredContentSizeCategory = .large view.traitOverrides.userInterfaceStyle = .dark window.layoutIfNeeded() FBSnapshotVerifyView(view, identifier: storyName + "__dark") // testing RTL support view.traitOverrides.layoutDirection = .rightToLeft view.semanticContentAttribute = .forceRightToLeft view.traitOverrides.userInterfaceStyle = .light window.layoutIfNeeded() FBSnapshotVerifyView(view, identifier: storyName + "__rtl") view.removeFromSuperview() } } Действительно, при наличии этих приготовлений создание тестового примера становится довольно простым: final class UIButtonTests: NativeBookSnapshotTestCase { func test() { // recordMode = true runTests(for: UIButtonStories()) } } Генератор документации Для этой задачи мы будем использовать другой стек: шаблоны Node.js, TypeScript и EJS. Гораздо проще работать со страницами на основе HTML, используя встроенные в них инструменты. Первое, что нам нужно, это какой-то файл конфигурации, в котором мы можем связать наши фрагменты кода и тестовые снимки. Для этой цели хорошо подойдет простой . файл JSON { "components": [ { "name": "UILabel", "storiesFilePath": "NativeBook/StorySets/UILabelStories.swift", "snapshotsFolderPath": "Ref/ReferenceImages_64/NativeBookTests.UILabelTests" }, … ] } Создав простое приложение Node.js, давайте определим модель. interface Story { name: string; codeSnippet: string; } interface Component { name: string; stories: Story[]; snapshotsFolderPath: string; } Интересная задача — как извлечь фрагменты кода из файла Swift. Этого можно добиться довольно просто, используя регулярное выражение. function storiesFromFile(filePath: string): Story[] { const sourceCode = fs.readFileSync(repoRoot + filePath, "utf-8"); const codeSnippetRegex = /func\s+story_(? [A-Za-z0-9_]+)\s*->\s*UIView\s*{(? [\s\S]*?)return/g; const result: Story[] = []; let match; while ((match = codeSnippetRegex.exec(sourceCode)) !== null && match.groups) { result.push({ name: match.groups["name"], codeSnippet: formatMultilineString(match.groups["codeSnippet"]), }); } return result; } Генерацию HTML можно выполнить с помощью EJS, мощного механизма шаблонов, который позволяет нам использовать JavaScript внутри шаблона: function renderIndex(components: Component[]) { fs.writeFileSync( siteDir + "/index.html", ejs.render( fs.readFileSync(__dirname + "/templates/index.html.ejs", "utf-8"), { components: components, } ) ); } function renderComponent(component: Component) { fs.writeFileSync( siteDir + `/${component.name}.html`, ejs.render( fs.readFileSync(__dirname + "/templates/component.html.ejs", "utf-8"), { component: component, } ) ); } Теперь объединим все в основной функции: (function () { // load config const nativeBookConfigContents = fs.readFileSync( repoRoot + "native_book_config.json", "utf-8" ); const config = JSON.parse(nativeBookConfigContents); // gather information for a component const components: Component[] = []; for (const componentJson of config["components"]) { components.push({ name: componentJson["name"], stories: storiesFromFile(componentJson["storiesFilePath"]), snapshotsFolderPath: componentJson["snapshotsFolderPath"], }); } // prepare site folder if (fs.existsSync(siteDir)) { fs.rmSync(siteDir, { recursive: true }); } fs.mkdirSync(siteDir, { recursive: true }); // render html site renderIndex(components); for (const component of components) { renderComponent(component); } })(); Сайт документации Демо-версия доступна по адресу . https://psharanda.github.io/NativeBook Чтобы создать документацию в репозитории NativeBook, вам необходимо выполнить следующие команды: cd native_book_gen npm install npm run native-book-gen Или просто запустите: sh generate_native_book.sh Документация появится в папке docs Что дальше? Надеюсь, вам понравилось путешествие. в своем нынешнем состоянии является подтверждением концепции, но с некоторыми дополнениями и правильной интеграцией в рабочий процесс разработчика он может начать приносить большую пользу. NativeBook Мы также можем представить себе следующее улучшение: Добавление поддержки Android: мы можем поддерживать обе платформы и иметь согласованные каталоги, тесты моментальных снимков и документацию, в которой вы можете легко переключаться между платформами. Встраивание проектов Figma в документацию Объединение с документацией, созданной такими инструментами, как DocC или Jazzy, для получения подробного справочника по API в дополнение к снимкам и фрагментам кода. Добавление правильной поддержки представлений SwiftUI. Автоматическое создание кода предварительного просмотра SwiftUI