ios

3. WKWebView 공식문서 공부 2편

코코넛딩 2023. 9. 12. 10:03

공식문서를 구글 번역기와 챗지피티를 사용해서 번역한 것입니다. 틀린 것이 있으면 말씀해주세요.

 

1. 웹 컨텐츠 로딩

  • 웹 컨텐츠의 종류
    • 로컬
    • HTML
    • network-based URL
    • data
    • file
  • 반환 값은 진행률을 알려주는 객체 WKNavigation
func load(_ request: URLRequest) -> WKNavigation?
  • 웹 콘텐츠를 로드하고 해당 콘텐츠로 이동하는데 사용되는 메서드입니다.
  • 로컬이나 network-based URL의 페이지를 로드한다.
    • URL
      • 웹페이지를 찾기 위한 주소
      • scheme://
      • http://
  • 매개변수
    • request
      • request에 attribution를 추가하여 앱 액티비티 데이터에 대한 로드 요청의 소스를 제공하세요.
      • attribution
        • 네트워크 요청을 시작하는 body 데이터
        • enum Attribution
          • case developer : 개발자가 시작한 네트워크 요청
          • case user : 사용자는 앱이 네트워크를 요청하도록 명시적으로 지시한다.
    • URLRequest
    • 로드하려는 웹 컨텐츠의 URL 및 기타 관련 정보를 포함한다.
  • 반환 값
    • WKNavigation
      • 웹 요청의 로딩 상황을 추적하는데 사용되는 새로운 Navigation object에 대한 설명

 

var isLoading: Bool { get }
  • 여전히 콘텐츠를 로딩 중이면 true
  • 아니면 false
var estimatedProgress: Double { get }
  • 탐색의 어떤 부분이 로드되었는지에 대한 추정치
  • 0.0 ~ 1.0
  • 탐색 로드가 완료된후 새 탐색이 시작될 때까지 추정된 Progress값은 1.0으로 유지된다. 

 

func reload() -> WKNavigation?
  • 웹페이지를 리로드 한다.
  • 반환 값
    • 리로드 작업을 나타내는 새로운 navigation object

 

@IBAction
func reload(_ sender: Any?)
  • 버튼으로 웹뷰를 리로드할 때 사용
  •  @IBAction
    • 이 어노테이션은 UIControl(버튼, input, slider)과 코드 간 상호 작용을 설정하는 데 사용됩니다.
    • 이 메서드가 UI 요소와 연결되어 있으며 이 메서드가 웹 콘텐츠를 리로드하는 동작을 트리거하는 모든 컨트롤의 액션으로 설정하라는 것입니다.

 

func reloadFromOrigin() -> WKNavigation?
  • 웹페이지를 새로 고치고 캐시를 확인하여 콘텐츠가 최신인지 확인할 수 있다.
  •  @IBAction 버전도 있다.

 

func stopLoading()
  • 최신 페이지에 모든 리소스를 로딩하는 것을 멈춘다.
  •  @IBAction 버전도 있다.

 

func startDownload(
    using request: URLRequest,
    completionHandler: @escaping (WKDownload) -> Void
)
  • URLRequest에 지정된 URL에서 리소스를 다운로드하기 시작한다.
  • request
    • 다운로드할 리소스의 URL과 다운로드에 관련된 다양한 설정이 포함된 URLRequest 객체
  • completionHandler
    • 다운로드가 완료되면 호출되는 콜백함수
    • 이 클로저에 WKDownload 객체가 전달된다.
      • WKDownload 객체를 사용하여 다운로드된 리소스를 처리하거나 표시할 수 있습니다.
      • 다운로드 객체의 진행 상황 업데이트를 수신하려면 completion Handler 내에서 delegate를 설정해야한다.
// 다운로드를 시작하고 다운로드 객체를 생성한 후, 델리게이트를 설정합니다.
startDownload(using: request) { download in
    // 다운로드 객체의 델리게이트를 설정합니다.
    download.delegate = self
}

// URLSessionDownloadDelegate 프로토콜을 준수하는 클래스에서 다음 메서드를 구현합니다.
extension YourViewController: URLSessionDownloadDelegate {
    func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask, didFinishDownloadingTo location: URL) {
        // 다운로드가 완료되면 호출되는 메서드입니다.
        // 다운로드된 파일의 위치(location)를 사용하여 파일을 처리하거나 저장할 수 있습니다.
    }
    
    func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask, didWriteData bytesWritten: Int64, totalBytesWritten: Int64, totalBytesExpectedToWrite: Int64) {
        // 다운로드 중에 호출되며, 다운로드 진행 상황 업데이트를 수신할 수 있습니다.
        let progress = Float(totalBytesWritten) / Float(totalBytesExpectedToWrite)
        // 진행 상황을 처리하거나 UI에 표시할 수 있습니다.
    }
}

 

 

var serverTrust: SecTrust? { get }
  • 웹 페이지에서 신뢰를 평가하기 위해 사용되는 Trust Management Object를 나타낸다.
  • 주로 HTTPS 연결에서 서버 인증서의 신뢰성을 평가하는 데 사용된다.
  • 보안 소켓 레이어(SSL, TLS)를 사용하여 웹 패이지와의 통신을 보호할 때 웹 브라우저나 다른 클라이언트 앱은 서버로 부터 받은 SSL/TLS 인증서의 유효성을 검사해야한다. 이때 serverTrust 객체가 사용된다.

 

var hasOnlySecureContent: Bool { get }
  • 웹 뷰가 안전하게 암호화된 연결을 통해 페이지의 모든 리소스를 로드했는지 여부를 나타내는 부울 값이다.

 

@NSCopying
var underPageBackgroundColor: UIColor! { get set }
  • 페이지의 경계를 넘어서 사용자가 스크롤했을때 보여줄 색깔
  • 웹뷰는 <html> 및 <body> 요소의 배경색과 웹 보기의 배경색을 사용하여 페이지 콘텐츠에서 이 속성의 기본값을 파생합니다.
  • 기본 색상을 재정의하려면 이 속성을 새 색상으로 설정하세요.

 

var pageZoom: CGFloat { get set }
  • 페이지의 컨텐츠를 웹뷰의 경계에 대한 비율로 확대 또는 축소하는데 사용된다.
  • 1.0 -> 실제크기로 표시한다.
  • 이 속성의 값을 변경하는 것은 모든 페이지 콘텐프에 CSS 확대/축소 속성을 설정하는 것과 같습니다.

 

@MainActor
func find(
    _ string: String,
    configuration: WKFindConfiguration = .init(),
    completionHandler: @escaping (WKFindResult) -> Void
)
  • 웹뷰 콘텐츠에서 문자열을 찾는다.
  • 매개변수
    • string
      • 찾을 문자열
    • configuration
      • 검색 매개변수입니다.
      • 검색이 대소문자를 구분하는지, 앞으로 뒤로 이동할지, 페이지 끝에 도달하면 줄 바꿈할지 여부를 지정하려면 이 객체를 사용해라
    • result 
      • 검색에 대한 결과를 포함하는 객체

 

var allowsBackForwardNavigationGestures: Bool { get set }
  • 가로 스와이프 동작이 페이지 뒤, 앞으로 탐색을 유발하는지 여부를 나타내는 불린 값
  • 기본 값은 false

 

var backForwardList: WKBackForwardList { get }
  • 웹뷰에서 방문한 웹페이지의 탐색 기록을 나타내는 객체이다.
  • 탐색 기록에는 이전 페이지, 현재 페이지, 앞으로 갈 수 있는 페이지 등이 포함된다.
  • 메서드 사용 예시
    • 뒤로/앞으로 이동
    • 탐색 기록 조회하고 해당 페이지의 url, title 가져오기
    • 웹뷰의 탐색 상태를 관리하고 페이지 간 전환을 제어할 수 있다.

 

@IBAction
func goBack(_ sender: Any?)

func goBack() -> WKNavigation?
  • 웹 페이지 에서 이전 페이지로 이동하는데 사용된다.
  • back-forward 리스트에서 이전 페이지로 이동한다.
  • 이동 할 수 있는 경우에만 작동하고 할 수 없으면 아무 동작도 하지 않는다.
  • 매개 변수
    • sender
      • 메세지를 보낸 객체(버튼: 버튼을 눌렀을 때)

 

@IBAction
func goForward(_ sender: Any?)

func goForward() -> WKNavigation?
  • back-forward list에서 앞으로 이동하게 한다.
func go(to item: WKBackForwardListItem) -> WKNavigation?
  • back--forward list에서 항목을 탐색하여 현재 항목으로 설정합니다.
  • 매개 변수
    • item
      • 탐색할 항목 
      • 항목은 back-forword list에 있어야한다.
  • 반환 
    • 요청된 항목에 대한 새로운 탐색입니다.
    • 해당 항목이 현재 항목이거나 웹 뷰의 back-forward 목록에 포함되지 않은 경우는 nil이다.

 

var canGoBack: Bool { get }

var canGoForward: Bool { get }
  • back-forward list에 유효한 back, forward 항목이 있는지 여부를 나타내는 불린 값이다.

 

var allowsLinkPreview: Bool { get set }
  • 링크를 누르면 링크 대상의 미리보기가 표시되는지 여부를 결정하는 불린 값
  • iOS에서는 3D Touch를 지원하는 장치에서 이 속성을 사용할 수 있습니다.
  • iOS10이상에서는 기본값이 true, 이전 버전의 iOS에서는 기본값이 false

 

var interactionState: Any? { get set }
  • 나중에 해당 상태를 다른 웹 뷰로 복원할 수 있도록 현재 상호작용 상태를 캡쳐하는데 사용하는 객체

 

JavaScript 실행

func evaluateJavaScript(
    _ javaScriptString: String,
    completionHandler: ((Any?, Error?) -> Void)? = nil
)
  • JavaScript의 string을 평가한다.
  • 매개 변수
    • javaScriptString
      • 평가할 JavaScript string
    • completionHandler
      • 스크림트의 평가가 끝났을때 실행되는 핸들러 블록
      • 앱의 메인 쓰레드에서 항상 실행된다.
      • 이 메서드는 스크립트 평가가 성공적으로 완료되거나 실패하는지 여부에 따라 블록을 호출합니다.
      • 블록에는 반환 값이 없으며 다음 매개 변수를 사용합니다.
        • object 
          • 스크립트 평가 결과
          • nil : 오류가 발생한 경우
        • error
          • nil : 성공시
          • error 객체

 

 

@MainActor
func evaluateJavaScript(
    _ javaScript: String,
    in frame: WKFrameInfo? = nil,
    in contentWorld: WKContentWorld,
    completionHandler: ((Result<Any, Error>) -> Void)? = nil
)
  • 지정된 프레임 및 contents world의 context에서 JavaScript string을 평가합니다.
  • 매개 변수
    • javaScript
      • 평가할 javaScript의 문자열입니다.
    • frame
      • JavaScript 코드를 평가할 프레임입니다.
      • 메인 프레임을 대상으로 하려면 nil을 지정
      • 스크립트 평가가 시작될 때 이 프레임이 더 이상 유효하지 않으면 WKError.Code.javaScriptInvalidFrameTarget 오류를 반환합니다.
    • content world
      • JavaScript 코드를 평가할 네임스페이스이다.
      • 이 매개변수는 문서의 DOM구조와 같은 기본 웹콘텐츠에 대한 변경 사항에는 적용되지 않는다.
        • DOM
          • XML이나 HTML 문서에 접근하기 위한 일종의 인터페이스이다.
      • WKContentWorld
        • JavaScript 코드의 실행 범위를 정의하고 다른 스크립트 간의 충돌을 방지하는데 사용하는 객체
        • 웹 페이지와 앱간의 스크립트 실행 환경을 분리하고 구분하는데 도움을 주는 개념이다.
        • 웹 페이지와 앱이 서로 다른 nameSpace에서 스크립트를 실행하며 각각의 환경에 속하는 변수, 함수, 클래스 등이 서로 격리된 상태로 존재하게 된다.
        • 이를 통해 그 환경 간의 충돌을 방지하고 보안과 안정성을 향상시킬 수 있습니다.
        • 같은 WKContentWorld 객체를 두개의 WKWebView에 사용하더라도 각 WKWebView는 독립된 환경을 갖는다.
        • 따라서 한 웹 뷰의 스크립트 환경에서 정의한 변수나 객체는 다른 웹뷰에서 접근할 수 없다.

 

@MainActor
func callAsyncJavaScript(
    _ functionBody: String,
    arguments: [String : Any] = [:],
    in frame: WKFrameInfo? = nil,
    in contentWorld: WKContentWorld,
    completionHandler: ((Result<Any, Error>) -> Void)? = nil
)
  • functionBody(지정된 문자열)을 비동기 JavaScript 함수로 실행합니다.
    • 동기(Synchronous)
      • 서버에서 요청을 보냈을 때 응답이 돌아와야 다음 동작을 수행할 수 있다.
      • A작업이 모두 진행될때까지 B작업은 대기해야한다.
    • 비동기(Asynchronous)
      • 요쳥을 보냈을때 응답상태와 상관없이 다음 동작을 수행할 수있다. 
      • A작업이 시작되면 동시에 B작업이 실행된다. A작업은 결과값이 나오는 대로 출력된다.
  • @MainActor
    • swift 5.5
    • Actor내 구현이 실행중인 모든 작업은 항상 메인 큐(메인 쓰레드)에서 수행하게 된다.
    • 원리
      • 비동기 코드가 새로운 async/await 패턴을 따르도록 만들어야한다.
      • await는 실행 흐름이 비동기 작업의 완료를 기다리는 것을 의미, 그동안 다른 작업을 처리하지 않는다.
      • await를 사용하면 해당 비동기 작업이 완료될 때까지 현재 스레드의 실행이 일시 중지된다.
      • 다른 작업을 처리하려면 별도의 비동기 함수를 호출하거나 다른 스레드에서 작업을 수행해야한다.
      • 액터는 캡슐화와 보호를 제공하며 외부에서 직접 데이터나 메서드에 엑세스할 수 없습니다.
      • 이것은 데이터 무결성을 유지하고 경쟁 조건을 방지하는데 도움이 됩니다.
  • 매개 변수
    • functionBody
      • function body로 사용할 javaScript 문자열이다.
      • functionBody는 익명 JavaScript 함수로 처리된다.
      • functionBody에는 함수 본문만 넣어야한다. 호출부 제외한다.
    • arguments
      • JavaScript 함수 호출에 전달할 인수를 딕셔너리 형태로 지정합니다.
      • 딕셔너리의 각 키는 fuctionBody에서 사용된 인수 이름과 일치하며, 그 키의 값은 코드 평가 중에 사용됩니다.
      • 지원되는 값 유형은 NSNumber, NSString, NSDate, NSArray, NSDictionary, NSNull 이다.
      • 배열또는 딕셔너리 내의 모든 항목도 지원되는 유형 중 하나여야 한다.
    • frame
      • javaScript 코드를 평가할 대상 프레임이다.
      • nil을 지정하면 기본적으로 현재 웹 페이지의 메인 프레임에서 실행된다.
      • frame이 코드 실행될 때 더이상 유효하지 않으면 WKError.Code.javaScriptInvalidFrameTarget오류를 반환 합니다.    
    • completionHandler
      • 스크립트 평가가 완료되면 호출되는 핸들러 블록입니다
      • 스크립트 평가가 성공하든 실패하든 핸들러 블록이 호출됩니다.
      • 이 블록은 반환 값을 가지지 않고 result 매개 변수를 사용한다.
      • result
        • 스크립트 평가의 결과 또는 발생한 문제에 대한 정보를 포함하는 오류객체
        • 함수 본문이 명시적인 값을 반환하지 않으면 성공한 경우 WebKit은 핸들러에 nil을 전달한다.
        • 함수가 명시적으로 null을 반환하면 WebKit은 그 값을 NSNull 객체로 반환한다.

 

func takeSnapshot(
    with snapshotConfiguration: WKSnapshotConfiguration?,
    completionHandler: @escaping (UIImage?, Error?) -> Void
)
  • WKWebView의 내용으로 부터 플랫폼 네이티브 이미지를 비동기적으로 생성하는데 사용됩니다.
  • 이 함수를 호출하면 WKWebView의 현재 내용을 기반으로 플랫폼 별 이미지가 생성되며, 이 이미지를 클로저 내의 UIImage 매개 변수를 통해 받을 수 있습니다.
  • 스냅샷 생성이 실패한 경우 오류 정보를 Error 매개 변수를 통해 확인할 수 있습니다.
  • 매개 변수
    • snapshotConfiguration
      • 스냅샷을 생성하는 데 사용되는 설정입니다.
      • 매개 변수를 nil로 설정하면 기본 설정이 사용됩니다.
    • completionHandler
      • 스냅샷이 생성이 완료되면 호출되는 클로저
      • UIImage?
        • 생성된 이미지가 전달됩니다.
        • 이미지 객체나 nil이 전달된다.
      • Error??
        • 오류
        • 오류 없으면 nil

 

@MainActor
func createPDF(
    configuration: WKPDFConfiguration = .init(),
    completionHandler: @escaping (Result<Data, Error>) -> Void
)
  • 웹뷰의 콘텐츠에서 PDF data를 비동기적으로 만든다.
  • 매개 변수 
    • configuration
      • PDF data로 캡쳐할 웹 뷰 부분을 지정하는 객체
    • completionHandler
      • 데이터가 준비되면 호출할 완료 핸들러
        • pdfDocumentData
          • 웹뷰의 콘텐츠를 렌더링하는데 사용할 PDF data가 포함된 데이터 객체입니다.
        • error
          • error 객체
          • error 없으면 nil