1. Что это и зачем нужна

R.swift — это мощная библиотека для языка Swift, которая предоставляет type-safe (типобезопасный) доступ к ресурсам вашего iOS/macOS/tvOS/watchOS приложения. Вместо того чтобы использовать строковые литералы для обращения к изображениям, шрифтам, цветам, локализованным строкам и другим ресурсам, R.swift генерирует для них строго типизированные структуры. Это означает, что компилятор может проверить корректность имени ресурса на этапе компиляции, а не во время выполнения приложения.

Зачем это нужно? В стандартной разработке под Apple вы часто пишете код вроде UIImage(named: "myImage") или NSLocalizedString("hello_key", comment: ""). Если вы опечатаетесь в имени файла или ключе локализации, приложение упадёт с ошибкой только во время выполнения. R.swift решает эту проблему кардинально: после генерации кода вы обращаетесь к ресурсам как к свойствам сгенерированных структур. Например: R.image.myImage или R.string.localizable.helloKey(). Компилятор сразу укажет на несуществующий ресурс, а Xcode предложит автодополнение.

Кроме того, R.swift автоматически обрабатывает каталоги активов (Asset Catalogs), .strings файлы, .storyboard, .xib, .json, .plist, шрифты, цвета и даже файлы данных (Data). Это делает код чище, безопаснее и значительно ускоряет разработку за счёт автодополнения в Xcode. Библиотека активно поддерживается сообществом и используется в тысячах проектов по всему миру.

2. Установка

R.swift устанавливается через Swift Package Manager (SPM) или CocoaPods. Мы рекомендуем SPM, так как это современный стандарт для Swift-проектов.

Установка через Swift Package Manager (SPM)

Добавьте пакет в ваш проект через Xcode:

1. Откройте ваш проект в Xcode.
2. Перейдите в File > Add Packages....
3. Вставьте URL: https://github.com/mac-cain13/R.swift
4. Выберите версию (рекомендуется последняя стабильная) и нажмите Add Package.
5. Убедитесь, что пакет добавлен в вашу основную цель.

Также можно добавить вручную в Package.swift:

// swift-tools-version:5.7
import PackageDescription

let package = Package(
    name: "YourProject",
    dependencies: [
        .package(url: "https://github.com/mac-cain13/R.swift", from: "7.0.0")
    ],
    targets: [
        .target(
            name: "YourTarget",
            dependencies: [
                .product(name: "RswiftLibrary", package: "R.swift")
            ]
        )
    ]
)

Установка через CocoaPods

Если вы используете CocoaPods, добавьте в Podfile:

platform :ios, '13.0'
use_frameworks!

target 'YourApp' do
  pod 'R.swift', '~> 7.0'
end

Затем выполните команду:

pod install

Настройка Build Phase (обязательно!)

После установки необходимо добавить Run Script Phase в Build Phases вашей цели:

1. Перейдите в Build Phases вашей цели.
2. Нажмите + и выберите New Run Script Phase.
3. Перетащите эту фазу так, чтобы она выполнялась до фазы Compile Sources.
4. В поле скрипта вставьте:

"$PODS_ROOT/R.swift/rswift" generate "$SRCROOT/R.generated.swift"

Если вы используете SPM, скрипт будет выглядеть так:

"${BUILD_DIR%/Build/*}/SourcePackages/checkouts/R.swift/rswift" generate "$SRCROOT/R.generated.swift"

После сборки проекта будет сгенерирован файл R.generated.swift. Добавьте его в ваш проект (не забудьте перетащить из Finder или добавить через Add Files to...).

3. Быстрый старт — минимальный рабочий пример

Предположим, у вас есть простое приложение с одним изображением в Asset Catalog (назовём его logo) и одной локализованной строкой в Localizable.strings (ключ welcome_message).

Шаг 1: Добавьте ресурсы в проект.

Шаг 2: Соберите проект (Cmd+B), чтобы сгенерировался файл R.generated.swift.

Шаг 3: Используйте в коде:

import UIKit
import RswiftLibrary // или import R.swift, в зависимости от версии

class ViewController: UIViewController {

    @IBOutlet weak var imageView: UIImageView!
    @IBOutlet weak var label: UILabel!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Type-safe доступ к изображению
        imageView.image = R.image.logo()

        // Type-safe доступ к локализованной строке
        label.text = R.string.localizable.welcomeMessage()
    }
}

Обратите внимание: R.image.logo() возвращает опциональный UIImage?, а R.string.localizable.welcomeMessage() возвращает String. Если бы вы ошиблись в имени, компилятор бы выдал ошибку. Автодополнение работает отлично: начните печатать R.image. и Xcode покажет все доступные изображения.

4. Основные методы/функции/классы

Рассмотрим 8 ключевых возможностей R.swift. Все примеры предполагают, что ресурсы уже добавлены в проект и файл R.generated.swift сгенерирован.

4.1. R.image — доступ к изображениям

Сигнатура: static func imageName() -> UIImage?

Что делает: Возвращает изображение из Asset Catalog по имени. Имя преобразуется в camelCase (например, my_image станет myImage()).

Пример:

// Допустим, в Assets.xcassets есть изображение с именем "onboarding_icon"
if let icon = R.image.onboardingIcon() {
    myImageView.image = icon
} else {
    print("Изображение не найдено")
}

4.2. R.string — доступ к локализованным строкам

Сигнатура: static func keyName() -> String (для строк без плейсхолдеров) или static func keyName(_ args: CVarArg...) -> String (для строк с плейсхолдерами).

Что делает: Обеспечивает type-safe доступ к строкам из Localizable.strings (или других .strings файлов). Поддерживает форматирование с помощью String(format:).

Пример:

// Localizable.strings: "welcome_user" = "Hello, %@!";

let userName = "Alice"
let welcome = R.string.localizable.welcomeUser(userName)
print(welcome) // "Hello, Alice!"

4.3. R.color — доступ к цветам

Сигнатура: static func colorName() -> UIColor? (iOS/tvOS) или NSColor? (macOS).

Что делает: Возвращает цвет из Asset Catalog (Color Set). Цвета должны быть определены в Assets.xcassets.

Пример:

// В Assets.xcassets есть Color Set с именем "primaryButton"
if let primaryColor = R.color.primaryButton() {
    button.backgroundColor = primaryColor
}

4.4. R.font — доступ к шрифтам

Сигнатура: static func fontName(size: CGFloat) -> UIFont?

Что делает: Позволяет получить шрифт, добавленный в проект (например, .ttf или .otf файлы). Шрифт должен быть добавлен в Info.plist (ключ UIAppFonts).

Пример:

// В проекте есть шрифт "OpenSans-Regular.ttf"
if let openSans = R.font.openSansRegular(size: 16.0) {
    label.font = openSans
}

4.5. R.storyboard — доступ к storyboard

Сигнатура: static func storyboardName() -> UIStoryboard

Что делает: Возвращает объект UIStoryboard по имени файла storyboard. Имя файла (без расширения) преобразуется в camelCase.

Пример:

// Файл "Main.storyboard"
let storyboard = R.storyboard.main()
let initialVC = storyboard.instantiateInitialViewController()

4.6. R.nib — доступ к XIB-файлам

Сигнатура: static func nibName() -> UINib

Что делает: Возвращает объект UINib для загрузки view из XIB-файла.

Пример:

// Файл "CustomView.xib"
let nib = R.nib.customView()
let views = nib.instantiate(withOwner: nil, options: nil)
if let customView = views.first as? CustomView {
    // используем customView
}

4.7. R.file — доступ к файлам данных

Сигнатура: static func fileName() -> URL? (возвращает URL) или static func fileName() -> Data? (возвращает Data).

Что делает: Позволяет получить URL или Data для файлов, добавленных в bundle (например, .json, .plist, .txt). Файлы должны быть добавлены в target.

Пример:

// В проекте есть файл "config.json"
if let configURL = R.file.configJson() {
    let data = try? Data(contentsOf: configURL)
    // парсим JSON
}

4.8. R.segue — доступ к идентификаторам Segue

Сигнатура: static func segueName() -> StoryboardSegueIdentifier<SpecificViewController, SpecificViewController>

Что делает: Обеспечивает type-safe выполнение segue. Позволяет указать тип контроллера источника и назначения.

Пример:

// В storyboard есть segue с идентификатором "showDetail"
override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
    // Type-safe проверка
    if let detailSegue = R.segue.mainViewController.showDetail(segue: segue) {
        let detailVC = detailSegue.destination
        detailVC.itemID = 42
    }
}

5. Реальный практический пример (100-200 строк кода)

Рассмотрим создание экрана профиля пользователя, который использует изображение, цвет, локализованные строки, шрифт и загружает данные из JSON-файла. Этот пример демонстрирует, как R.swift делает код чистым и безопасным.

import UIKit
import RswiftLibrary

// MARK: - Модель данных
struct UserProfile: Codable {
    let name: String
    let age: Int
    let bio: String
}

// MARK: - ViewController профиля
class ProfileViewController: UIViewController {

    // MARK: - Outlets
    @IBOutlet weak var avatarImageView: UIImageView!
    @IBOutlet weak var nameLabel: UILabel!
    @IBOutlet weak var ageLabel: UILabel!
    @IBOutlet weak var bioLabel: UILabel!
    @IBOutlet weak var editButton: UIButton!

    // MARK: - Lifecycle
    override func viewDidLoad() {
        super.viewDidLoad()

        setupUI()
        loadUserProfile()
    }

    // MARK: - Setup UI
    private func setupUI() {
        // 1. Устанавливаем цвет фона из Asset Catalog
        view.backgroundColor = R.color.backgroundPrimary()

        // 2. Настраиваем аватар
        avatarImageView.image = R.image.defaultAvatar()
        avatarImageView.layer.cornerRadius = avatarImageView.frame.width / 2
        avatarImageView.clipsToBounds = true

        // 3. Настраиваем шрифты
        nameLabel.font = R.font.montserratBold(size: 22.0)
        ageLabel.font = R.font.montserratRegular(size: 16.0)
        bioLabel.font = R.font.montserratLight(size: 14.0)

        // 4. Настраиваем кнопку
        editButton.setTitle(R.string.localizable.editProfile(), for: .normal)
        editButton.backgroundColor = R.color.accentBlue()
        editButton.layer.cornerRadius = 8.0
    }

    // MARK: - Load Data
    private func loadUserProfile() {
        // 5. Загружаем JSON из файла, используя R.file
        guard let profileURL = R.file.userProfileJson() else {
            showError(message: R.string.localizable.errorFileNotFound())
            return
        }

        do {
            let data = try Data(contentsOf: profileURL)
            let decoder = JSONDecoder()
            let profile = try decoder.decode(UserProfile.self, from: data)

            // 6. Заполняем UI с использованием локализованных строк
            nameLabel.text = profile.name
            ageLabel.text = String(format: R.string.localizable.ageFormat(), profile.age)
            bioLabel.text = profile.bio

        } catch {
            showError(message: R.string.localizable.errorLoadingData())
        }
    }

    // MARK: - Actions
    @IBAction func editButtonTapped(_ sender: UIButton) {
        // 7. Type