Skip to content

Latest commit

 

History

History
501 lines (361 loc) · 20.1 KB

README_ko.md

File metadata and controls

501 lines (361 loc) · 20.1 KB

codebeat badge Platforms CocoaPods Carthage SPM Twitter: @JuanpeCatalan
License

🌎 번역에 도움을 주신분들:
🇨🇳 by @WhatsXie
🇧🇷 by @brunomunizaf
🇰🇷 by @techinpark

오늘날 거의 대부분의 앱들은 비동기 방식의 API 호출을 사용하는 프로세스를 가지고 있습니다. 프로세스가 작동하는동안 개발자들은 작업이 실행되고 있다는것을 사용자들에게 보여주기 위해서 로딩 뷰를 배치합니다.

SkeletonView는 이러한 필요에 의해 고안되었고, 사용자들에게 무엇인가 로딩이 되고 있다는것을 보여주면서 기다리는 콘텐츠에 대해서도 미리 준비할 수 있게 해주는 우아하게 표현할수 있는 방법입니다

맘껏 누리세요 🙂

🌟 기능

  • 사용이 쉽습니다
  • 모든 UIView에서 사용가능합니다
  • 전체 커스터마이징이 가능합니다
  • 공통으로 이용가능합니다 (iPhone & iPad)
  • Interface Builder 에서 사용 가능합니다.
  • 간단한 스위프트 문법
  • 가볍고 가독성 좋은 코드

🎬 사용가이드

📲 설치 방법

CocoaPods 로 사용하기

당신의 프로젝트 Podfile 파일에 아래와 같이 입력합니다:

pod "SkeletonView"

Carthage로 사용하기

당신의 프로젝트 Cartfile 파일에 아래와 같이 입력합니다:

github "Juanpe/SkeletonView"

Swift Package Manager로 사용하기

당신의 프로젝트에 Swift package를 설정한다면, SkeletonViewPackage.swift 파일에 있는 dependencies에 추가하시면 됩니다.

  dependencies: [
    .package(url: "https://github.com/Juanpe/SkeletonView.git", from: "1.6")
  ]

🐒 어떻게 사용하나요?

SkeletonView 를 이용하기 위해서는 딱 3 단계만 기억하세요:

1. 사용하고자 하는 파일에서 SkeletonViewImport 합니다.

import SkeletonView

2. 자, 그렇다면 UIView 속성에 skeletonables 를 이용하실 수 있습니다. 두가지 옵션이 있습니다

코드로 사용하는 방법:

avatarImageView.isSkeletonable = true

인터페이스빌더 / 스토리보드를 이용하는 방법:

3. 당신이 뷰를 세팅할때, skeleton 옵션을 사용 할 수 있습니다. 총 4 가지 옵션을 지원합니다:

(1) view.showSkeleton()                 // Solid
(2) view.showGradientSkeleton()         // Gradient
(3) view.showAnimatedSkeleton()         // Solid animated
(4) view.showAnimatedGradientSkeleton() // Gradient animated

미리보기

Solid Gradient Solid Animated Gradient Animated

중요!

SkeletonView 는 재귀적으로 되어있습니다, 만약 모든 뷰에 대해서 skeleton을 호출하고 싶다면, 메인 컨테이너 뷰에서 show method를 호출하여야 합니다. 예를 들자면 UIViewControllers가 있습니다.

🌿 Collections

현재, SkeletonViewUITableViewUICollectionView에서 호환됩니다.

UITableView

만약 UITableView에서 skeleton을 호출하고 싶다면, SkeletonTableViewDataSource protocol 을 구현하여야 합니다.

public protocol SkeletonTableViewDataSource: UITableViewDataSource {
    func numSections(in collectionSkeletonView: UITableView) -> Int
    func collectionSkeletonView(_ skeletonView: UITableView, numberOfRowsInSection section: Int) -> Int
    func collectionSkeletonView(_ skeletonView: UITableView, cellIdentifierForRowAt indexPath: IndexPath) -> ReusableCellIdentifier
}

해당 프로토클은 보시다시피 UITableViewDataSource를 상속받아 구현하였으므로, skeleton의 protocol과 대체 가능합니다.

프로토콜의 기본 구현은 다음과 같습니다:

func numSections(in collectionSkeletonView: UITableView) -> Int
// Default: 1
func collectionSkeletonView(_ skeletonView: UITableView, numberOfRowsInSection section: Int) -> Int
// Default:
// 전체 테이블 뷰를 채우는데 필요한 셀 수를 계산합니다 

해당 메소드는 당신이 구현하여야할 cell identifier을 아는 경우에만 사용합니다, 해당 메소드는 기본으로 구현하지 않아도됩니다 :

func collectionSkeletonView(_ skeletonView: UITableView, cellIdentifierForRowAt indexPath: IndexPath) -> ReusableCellIdentifier

Example

func collectionSkeletonView(_ skeletonView: UITableView, cellIdentifierForRowAt indexPath: IndexPath) -> ReusableCellIdentifier {
   return "CellIdentifier"
}

중요! 만약 사이즈가 변하는 셀을 사용한다면 (tableView.rowHeight = UITableViewAutomaticDimension ),estimatedRowHeight를 무조건 정의해주세요.

👩🏼‍🏫 어떻게 특정 요소에 skeleton 을 지정할까요?

아래의 그림은 UITableView 에서 특정한 요소에 skeleton 을 지정하는 방법을 보여주는 이미지 입니다:

위의 이미지에서 보이듯, 테이블 뷰와 셀에 들어가는 UI 요소들에는 적용을 해야하지만, contentView에 skeleton을 적용할 필요는 없습니다.

UICollectionView

UICollectionView 에 적용을 하기 위해서는, SkeletonCollectionViewDataSource protocol 을 구현할 필요가 있습니다.

public protocol SkeletonCollectionViewDataSource: UICollectionViewDataSource {
    func numSections(in collectionSkeletonView: UICollectionView) -> Int
    func collectionSkeletonView(_ skeletonView: UICollectionView, numberOfItemsInSection section: Int) -> Int
    func collectionSkeletonView(_ skeletonView: UICollectionView, cellIdentifierForItemAt indexPath: IndexPath) -> ReusableCellIdentifier
}

UITableView 와 사용방법은 같습니다.

📰 Multiline text

텍스트가 들어있는 요소를 사용한다면, SkeletonView 에서 텍스트의 라인을 그려줍니다. 그리고, 원하는 라인 수를 설정할 수 있습니다. 만약 numberOfLines 을 0으로 설정한다면, 자동으로 필요한 라인수를 계산해서 그려줍니다. 대신 값이 설정되어있다면 설정된 수만큼의 라인이 그려집니다.

🎛 Customize

당신은 멀티라인을 위해 몇가지 옵션을 설정할 수 있습니다.

속성 기본값 미리보기
마지막 라인의 퍼센트 를 지정 할 수 있습니다. 0...100 70%
라인의 Corner radius 를 지정할 수 있습니다. (새로운기능) 0...10 0

라인의 radius를 지정하기 위해서는 코드 를 이용합니다, 아래 처럼 코드를 작성합니다:

descriptionTextView.lastLineFillPercent = 50
descriptionTextView.linesCornerRadius = 5

혹은 IB/Storyboard 를 이용하실 수 있습니다:

🎨 Custom colors

당신은 skeleton의 색상을 지정 할 수 있습니다. 간단하게 원하는 색상을 파라미터로 넘겨주시면 됩니다.

단색 이용방법

view.showSkeleton(usingColor: UIColor.gray) // Solid
// or
view.showSkeleton(usingColor: UIColor(red: 25.0, green: 30.0, blue: 255.0, alpha: 1.0))

그라디언트 이용 방법

let gradient = SkeletonGradient(baseColor: UIColor.midnightBlue)
view.showGradientSkeleton(usingGradient: gradient) // Gradient

게다가, SkeletonView 에서는 20가지의 기본 컬러를 지원합니다 🤙🏼

UIColor.turquoise, UIColor.greenSea, UIColor.sunFlower, UIColor.flatOrange ...

위 이미지는 https://flatuicolors.com 사이트에서 발췌했습니다.

🦋 Appearance

새로운 사항 skeleton 은 기본설정 값이 정해져 있습니다. 만약 커스텀 컬러를 사용할 필요가 없다면, SkeletonView 에 지정 되어있는 기본설정을 사용하시면 됩니다.

기본 설정값:

  • tintColor: UIColor
    • 기본값: .clouds
  • gradient: SkeletonGradient
    • 기본값: SkeletonGradient(baseColor: .clouds)
  • multilineHeight: CGFloat
    • 기본값: 15
  • multilineSpacing: CGFloat
    • 기본값: 10
  • multilineLastLineFillPercent: Int
    • 기본값: 70
  • multilineCornerRadius: Int
    • 기본값: 0

SkeletonAppearance.default 에는 사용 되어지는 기본 값들이 설정되어 있습니다 . 아래의 코드와 같이 사용할 수 있습니다:

SkeletonAppearance.default.multilineHeight = 20
SkeletonAppearance.default.tintColor = .green

🤓 커스텀 애니메이션

SkeletonView 에는 두가지 애니메이션이 내장되어 있습니다, 단색 바운스 애니메이션과 그라디언트 슬라이드 애니메이션 입니다 .

게다가, 직접 애니메이션을 추가하고 싶다면 정말 간단합니다.

Skeleton 에서는 showAnimatedSkeleton 함수를 SkeletonLayerAnimation에 정의하여 맞춤형 애니메이션을 정의할 수 있도록 되어 있습니다.

public typealias SkeletonLayerAnimation = (CALayer) -> CAAnimation

함수는 이렇게 호출 가능합니다:

view.showAnimatedSkeleton { (layer) -> CAAnimation in
  let animation = CAAnimation()
  // Customize here your animation

  return animation
}

SkeletonAnimationBuilder의 사용이 가능합니다. SkeletonLayerAnimation을 만들기 위해 사용됩니다.

이제, 그라디언트를 위한 슬라이딩 애니메이션 을 만들 수 있습니다, 애니메이션을 위한 방향지속시간 을 설정 할 수 있습니다. (기본값 = 1.5초).

// func makeSlidingAnimation(withDirection direction: GradientDirection, duration: CFTimeInterval = 1.5) -> SkeletonLayerAnimation

let animation = SkeletonAnimationBuilder().makeSlidingAnimation(withDirection: .leftToRight)
view.showAnimatedGradientSkeleton(usingGradient: gradient, animation: animation)

GradientDirection 는 enum 으로 정의 되어있습니다., 아래의 케이스를 참조하세요:

방향 미리보기
.leftRight
.rightLeft
.topBottom
.bottomTop
.topLeftBottomRight
.bottomRightTopLeft

😉 꿀팁! 슬라이딩 애니메이션을 만들기 위한 또다른 방법이 있습니다, 아래의 코드를 참조하세요:

let animation = GradientDirection.leftToRight.slidingAnimation()

👨‍👧‍👦 계층 구조

SkeletonView는 재귀적입니다 , 그리고 우리는 skeleton이 효율적으로 작동하기를 원하기 때문에, 가능한 빨리 재귀작업을 중단하기를 원합니다. 이러한 이유때문에 반드시 컨테이너 뷰를 Skeletonable 로 설정해야 합니다, skeletonable 되지 않는 뷰를 만나는 순간 재귀 작업을 중단하기 떄문입니다.

아래의 이미지를 참고하세요 이미지는 한눈에 이해되실겁니다:

ìsSkeletonable= ☠️

설정값 결과

🔬 디버그

새로운소식 어떤것들이 잘 동작 하지 않을때를 위해 디버그 작업을 용이하게 하기 위해서 SkeletonView 에는 몇가지 새로운 것들이 있습니다.

첫번쨰로, UIView 에서 skeleton 정보를 보기위해 다음과 같이 지원하고 있습니다:

var skeletonDescription: String

skeleton은 이렇게 생겼습니다:

그리고, 새로운 디버그 모드를 활성화 시킬 수 있습니다. 간단하게 SKELETON_DEBUG 이라는 환경 변수를 추가해 활성화 하면 됩니다.

그런 이후 skeleton이 나오면 Xcode 콘솔창에서 계층 구조를 볼 수 있습니다.

예제를 확인해보세요.

📚 문서화

조금만 기다려주세요...😅

📋 지원 가능한 OS & SDK 버전

  • iOS 9.0+
  • tvOS 9.0+
  • Swift 4.2

📬 예정된 기능들

  • 멀티라인 에서의 마지막 라인의 채우기 비율 설정
  • 더많은 그라디언트 애니메이션
  • resizable cells 지원
  • CollectionView 호환
  • tvOS 호환
  • recovery state 추가
  • Custom default appearance
  • 디버그 모드
  • Custom collections 호환
  • skeletons 가 보이거나 가려질때 애니메이션 추가
  • MacOS 와 WatchOS 호환

❤️ 기여하기

이 프로젝트는 오픈소스 프로젝트 입니다, 마음편하게 기여해주시면 됩니다 어떻게 하냐구요?

  • 새로운 이슈를 등록합니다.
  • email을 보냅니다.
  • 당신의 수정을 제안합니다, pull request를 포함한 수정을 권장합니다.

전체 기여자목록

SwiftPlate를 통해 프로젝트가 생성되었습니다

📢 소식들

👨🏻‍💻 개발자

  • Juanpe Catalán alt text

Buy me a coffee

👮🏻 라이센스

MIT License

Copyright (c) 2017 Juanpe Catalán

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.