Skip to content

README_zh-TW.md

Latest commit

 

History

History
300 lines (207 loc) · 8.39 KB

README_zh-TW.md

File metadata and controls

300 lines (207 loc) · 8.39 KB

SFSymbolsGenerator

🌐 Language / 語言選擇

Swift 版本 支援平台 GitHub release (with filter)

使用 Swift 簡化 SF Symbols 列舉產生！

這是一個基於 Swift 的命令列工具，專門用來產生具有型別安全性的 Swift 列舉，並為 SF Symbols 提供適當的可用性標註。專案採用整潔架構原則建構。

✨ 特色功能

  • 🎯 型別安全產生：建立具有編譯時期安全性的 Swift 列舉
  • 📱 可用性標註：自動產生適當平台支援的 @available 屬性
  • 🔄 雙版本支援：支援穩定版和測試版 SF Symbols
  • 🏗️ 整潔架構：遵循 SOLID 原則的良好程式碼結構
  • ⚡ 效能最佳化：快速的符號處理和程式碼產生
  • 🛠️ 關鍵字處理：正確處理 Swift 保留關鍵字
  • 📝 完整文件：詳盡的內嵌文件和註解

📋 系統需求

  • macOS：14.0 或以上版本
  • Xcode：15.0 或以上版本
  • Swift：5.8 或以上版本
  • SF Symbols App：5.0 或以上版本（穩定版）/ 7.0 或以上版本（測試版）

🏗️ 專案架構

本專案遵循整潔架構原則，具有清晰的關注點分離：

Sources/
├── Application/                   # 應用層
│   ├── Commands/                  # CLI 命令實作
│   └── SFSymbolsGenerator.swift
├── Domain/                        # 領域層
│   ├── Models/                    # 領域模型和擴展
│   └── Services/                  # 核心業務邏輯服務
├── Infrastructure/                # 基礎設施層
│   ├── FileSystem/                # 檔案操作
│   └── Errors/                    # 錯誤處理
└── Foundation/                    # 基礎層
    └── Types/                     # 型別別名和基本型別

架構優勢

  • 可維護性：清晰的分層讓程式碼易於理解和修改
  • 可測試性：每一層都可以獨立測試
  • 可擴展性：容易新增功能而不影響現有程式碼
  • 可重用性：元件可以在不同情境中重複使用

📦 安裝方式

Homebrew 安裝（推薦）

brew tap leoho0722/tap
brew install sf-symbols-generator

從發布版本安裝

  1. 從 GitHub Releases 下載最新的二進位檔案
  2. 解壓縮並將二進位檔案放置到您希望的位置
  3. 設為可執行：chmod +x sf-symbols-generator

從原始碼建置

git clone https://github.com/leoho0722/SFSymbolsGenerator.git
cd SFSymbolsGenerator
swift build -c release
# 二進位檔案將位於 .build/release/sf-symbols-generator

🚀 使用方法

命令結構

sf-symbols-generator generate <filepath> [--name <n>] [--enum-name <enum-name>] [--use-beta]
sf-symbols-generator version

產生命令

# 基本用法
sf-symbols-generator generate /path/to/output

# 自訂檔案名稱
sf-symbols-generator generate /path/to/output --name CustomSymbols

# 使用測試版本
sf-symbols-generator generate /path/to/output --use-beta

# 完整範例
sf-symbols-generator generate ~/Desktop --name MySymbols --use-beta

命令選項

選項 說明 預設值 必填
filepath 產生 Swift 檔案的目錄路徑 - ✅
--name 指定輸出檔案名稱 SFSymbols+Enum ❌
--enum-name 指定輸出列舉名稱 SFSymbols ❌
--use-beta 是否使用 SF Symbols 測試版本 false ❌

📝 產生的輸出

工具會產生具有以下結構的 Swift 列舉檔案：

// SFSymbols.swift
// Generated by SFSymbolsGenerator
// Do not edit this file manually.

import Foundation

public enum SFSymbols: String, CaseIterable {
    /// SF Symbols's name：arrow.left
    @available(iOS 13.0, macOS 10.15, *)
    case arrowLeft = "arrow.left"
    
    /// SF Symbols's name：star.fill
    @available(iOS 14.0, macOS 11.0, *)
    case starFill = "star.fill"
    
    public static var allCases: [SFSymbols] {
        var allCases: [SFSymbols] = []
        if #available(iOS 13.0, macOS 10.15, *) {
            allCases.append(.arrowLeft)
        }
        if #available(iOS 14.0, macOS 11.0, *) {
            allCases.append(.starFill)
        }
        return allCases
    }
}

🛠️ 開發資訊

建置專案

swift build

執行測試

swift test

專案結構詳細說明

  • 應用層（Application Layer）：包含主要的 CLI 介面和命令處理
  • 領域層（Domain Layer）：符號處理和程式碼產生的核心業務邏輯
  • 基礎設施層（Infrastructure Layer）：檔案 I/O 操作和錯誤處理基礎設施
  • 基礎層（Foundation Layer）：基本型別、別名和工具定義

🤝 參與貢獻

歡迎貢獻！請隨時提交 Pull Request。對於重大變更，請先開啟一個 issue 來討論您想要變更的內容。

開發指南

  1. 遵循 Swift 編碼慣例
  2. 維持整潔架構原則
  3. 為新功能新增測試
  4. 視需要更新文件

🎯 使用案例

在 iOS/macOS 專案中使用

import UIKit

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        
        // 使用產生的列舉
        let imageView = UIImageView()
        imageView.image = UIImage(systemName: SFSymbols.starFill.rawValue)
        
        // 檢查可用性
        if SFSymbols.allCases.contains(.arrowLeft) {
            print("Arrow left symbol is available")
        }
    }
}

在 SwiftUI 中使用

import SwiftUI

struct ContentView: View {

    var body: some View {
        VStack {
            Image(systemName: SFSymbols.starFill.rawValue)
                .font(.largeTitle)
            
            Text("Available symbols: \\(SFSymbols.allCases.count)")
        }
    }
}

🔧 進階功能

錯誤處理

工具提供詳細的錯誤訊息，包括：

  • SF Symbols 應用程式未安裝
  • 檔案權限問題
  • 資料格式錯誤
  • 程式碼產生失敗

符號名稱轉換

工具會自動處理：

  • 點號轉換為駝峰命名（arrow.left → arrowLeft）
  • Swift 關鍵字處理（return → `return`）
  • 數字開頭的符號（1.circle → _1Circle）

可用性標註

根據 SF Symbols 的發布時程自動產生：

  • iOS 13.0+：2019 年發布的符號
  • iOS 14.0+：2020 年發布的符號
  • iOS 15.0+：2021 年發布的符號
  • 以此類推...

🐛 疑難排解

常見問題

Q: 提示找不到 SF Symbols 應用程式

A: 請確保已從 Apple Developer 網站下載並安裝 SF Symbols 應用程式。

Q: 產生的檔案為空

A: 檢查 SF Symbols 應用程式版本是否正確，並確保有符號資料可用。

Q: 權限被拒絕

A: 確保輸出目錄具有寫入權限，或使用 sudo 執行命令。

回報問題

如果遇到問題，請在 GitHub 上建立 issue，並提供：

  1. 錯誤訊息
  2. 執行的命令
  3. 系統環境（macOS 版本、SF Symbols 版本）
  4. 預期和實際行為

📄 授權條款

本專案採用 MIT 授權條款 - 詳見 LICENSE 檔案。

🙏 致謝

📚 相關文件

更詳細的文件請參考：

🔗 相關連結

由 Leo Ho 用 ❤️ 製作