UIWebView

UIWebView

You use the UIWebView class to embed web content in your application. To do so, you simply create a UIWebView object, attach it to a window, and send it a request to load web content. You can also use this class to move back and forward in the history of webpages, and you can even set some web content properties programmatically.

Use the loadRequest: method to begin loading web content, the stopLoading method to stop loading, and the loading property to find out if a web view is in the process of loading.

If you allow the user to move back and forward through the webpage history, then you can use the goBack and goForward methods as actions for buttons. Use the canGoBack and canGoForward properties to disable the buttons when the user can’t move in a direction.

By default, a web view automatically converts telephone numbers that appear in web content to Phone links. When a Phone link is tapped, the Phone application launches and dials the number. Set the detectsPhoneNumbers property to NO to turn off this default behavior.

You can also use the scalesPageToFit property to programmatically set the scale of web content the first time it is displayed in a web view. Thereafter, the user can change the scale using gestures.

Set the delegate property to an object conforming to the UIWebViewDelegateprotocol if you want to track the loading of web content.

IMPORTANT

You should not embed UIWebView or UITableView objects in UIScrollView objects. If you do so, unexpected behavior can result because touch events for the two objects can be mixed up and wrongly handled.

You can easily debug the HTML, CSS, and JavaScript contained inside a UIWebView with Web Inspector. Read Debugging Web Content on iOS to learn how to configure Web Inspector for iOS. Read the rest of Safari Web Content Guide to learn how to create web content that is optimized for Safari on iPhone and iPad.

For information about basic view behaviors, see View Programming Guide for iOS. 

Supported File Formats

In addition to HTML content, UIWebView objects can be used to display other content types. For more information, see Using UIWebView to display select document types.

State Preservation

In iOS 6 and later, if you assign a value to this view’s restorationIdentifier property, it attempts to preserve its URL history, the scaling and scrolling positions for each page, and information about which page is currently being viewed. During restoration, the view restores these values so that the web content appears just as it did before. For more information about how state preservation and restoration works, see App Programming Guide for iOS. 

For more information about appearance and behavior configuration, see Web Views in UIKit User Interface Catalog.

Subclassing Notes

The UIWebView class should not be subclassed.

Setting the Delegate

• delegate

  The receiver’s delegate.

  Declaration

  SWIFT

  unowned(unsafe) var delegate: UIWebViewDelegate?

  OBJECTIVE-C

  @property(nonatomic, assign) id< UIWebViewDelegate > delegate

  Discussion

  The delegate is sent messages when content is loading. See UIWebViewDelegate Protocol Reference for the optional methods this delegate may implement.

  IMPORTANT

  Before releasing an instance of UIWebView for which you have set a delegate, you must first set its delegate property to nil. This can be done, for example, in your dealloc method.

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

•  

   

   

   

Loading Content

• loadData:MIMEType:textEncodingName:baseURL:

  Sets the main page contents, MIME type, content encoding, and base URL.

  Declaration

  SWIFT

      func loadData(_ data: NSData!,
        MIMEType MIMEType: String!,
textEncodingName encodingName: String!,
         baseURL baseURL: NSURL!)

  OBJECTIVE-C

  - (void)loadData:(NSData *)data
        MIMEType:(NSString *)MIMEType
textEncodingName:(NSString *)encodingName
         baseURL:(NSURL *)baseURL


  Parameters

  data	The content for the main page.
  MIMEType	The MIME type of the content.
  encodingName	The IANA encoding name as in utf-8 or utf-16.
  baseURL	The base URL for the content.

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

  See Also

  – loadHTMLString:baseURL:

• loadHTMLString:baseURL:

  Sets the main page content and base URL.

  Declaration

  SWIFT

  func loadHTMLString(_ string: String!,
            baseURL baseURL: NSURL!)

  OBJECTIVE-C

  - (void)loadHTMLString:(NSString *)string
               baseURL:(NSURL *)baseURL


  Parameters

  string	The content for the main page.
  baseURL	The base URL for the content.

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

  See Also

  – loadData:MIMEType:textEncodingName:baseURL:

• loadRequest:

  Connects to a given URL by initiating an asynchronous client request.

  Declaration

  SWIFT

  func loadRequest(_ request: NSURLRequest)

  OBJECTIVE-C

  - (void)loadRequest:(NSURLRequest *)request


  Parameters

  request

  A URL request identifying the location of the content to load.

  Discussion

    To stop this load, use the stopLoading method. To see whether the receiver is done loading the content, use the loading property.

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

  See Also

    request
– stopLoading
  loading
– reload

• request

  The URL request identifying the location of the content to load. (read-only)

  Declaration

  SWIFT

  var request: NSURLRequest? { get }

  OBJECTIVE-C

  @property(nonatomic, readonly, retain) NSURLRequest *request

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

  See Also

  – loadRequest:
– stopLoading
  loading
– reload

• loading

  A Boolean value indicating whether the receiver is done loading content. (read-only)

  Declaration

  SWIFT

  var loading: Bool { get }

  OBJECTIVE-C

  @property(nonatomic, readonly, getter=isLoading) BOOL loading

  Discussion

  If YES, the receiver is still loading content; otherwise, NO.

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

  See Also

    request
– stopLoading
– loadRequest:
– reload

• stopLoading

  Stops the loading of any web content managed by the receiver.

  Declaration

  SWIFT

  func stopLoading()

  OBJECTIVE-C

  - (void)stopLoading

  Discussion

  Stops any content in the process of being loaded by the main frame or any of its children frames. Does nothing if no content is being loaded.

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

  See Also

    request
  loading
– loadRequest:
– reload

• reload

  Reloads the current page.

  Declaration

  SWIFT

  func reload()

  OBJECTIVE-C

  - (void)reload

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

  See Also

    request
  loading
– loadRequest:
– stopLoading

•  

   

   

   

Moving Back and Forward

• canGoBack

  A Boolean value indicating whether the receiver can move backward. (read-only)

  Declaration

  SWIFT

  var canGoBack: Bool { get }

  OBJECTIVE-C

  @property(nonatomic, readonly, getter=canGoBack) BOOL canGoBack

  Discussion

  If YES, able to move backward; otherwise, NO.

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

  See Also

    canGoForward

• canGoForward

  A Boolean value indicating whether the receiver can move forward. (read-only)

  Declaration

  SWIFT

  var canGoForward: Bool { get }

  OBJECTIVE-C

  @property(nonatomic, readonly, getter=canGoForward) BOOLcanGoForward

  Discussion

  If YES, able to move forward; otherwise, NO .

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

  See Also

    canGoBack

• goBack

  Loads the previous location in the back-forward list.

  Declaration

  SWIFT

  func goBack()

  OBJECTIVE-C

  - (void)goBack

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

  See Also

  – goForward

• goForward

  Loads the next location in the back-forward list.

  Declaration

  SWIFT

  func goForward()

  OBJECTIVE-C

  - (void)goForward

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

  See Also

  – goBack

•  

   

   

   

Setting Web Content Properties

• detectsPhoneNumbers (iOS 3.0)

  A Boolean value indicating whether telephone number detection is on.

  Deprecation Statement

    Use dataDetectorTypes instead.

  Declaration

  OBJECTIVE-C

  @property(nonatomic) BOOL detectsPhoneNumbers

  Discussion

  If YES, telephone number detection is on; otherwise, NO. If a webpage contains numbers that can be interpreted as phone numbers, but are not phone numbers, you can turn off telephone number detection by setting this property to NO. The default value is YES on devices that have phone capabilities.

  Special Considerations

    The functionality provided by this property has been superseded by the dataDetectorTypes property.

  Import Statement

   

  Availability

  Available in iOS 2.0 and later.

  Deprecated in iOS 3.0.

• scalesPageToFit

  A Boolean value determining whether the webpage scales to fit the view and the user can change the scale.

  Declaration

  SWIFT

  var scalesPageToFit: Bool

  OBJECTIVE-C

  @property(nonatomic) BOOL scalesPageToFit

  Discussion

  If YES, the webpage is scaled to fit and the user can zoom in and zoom out. If NO, user zooming is disabled. The default value is NO.

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

• scrollView

  The scroll view associated with the web view. (read-only)

  Declaration

  SWIFT

  var scrollView: UIScrollView { get }

  OBJECTIVE-C

  @property(nonatomic, readonly, retain) UIScrollView *scrollView

  Discussion

  Your application can access the scroll view if it wants to customize the scrolling behavior of the web view.

  Import Statement

  import UIKit

  Availability

  Available in iOS 5.0 and later.

• suppressesIncrementalRendering

  A Boolean value indicating whether the web view suppresses content rendering until it is fully loaded into memory.

  Declaration

  SWIFT

  var suppressesIncrementalRendering: Bool

  OBJECTIVE-C

  @property(nonatomic) BOOL suppressesIncrementalRendering

  Discussion

  When set to YES, the web view does not attempt to render incoming content as it arrives. Instead, the view’s current contents remain in place until all of the new content has been received, at which point the new content is rendered. This property does not affect the rendering of content retrieved after a frame finishes loading. 

  The value of this property is NO by default.

  Import Statement

  import UIKit

  Availability

  Available in iOS 6.0 and later.

• keyboardDisplayRequiresUserAction

  A Boolean value indicating whether web content can programmatically display the keyboard.

  Declaration

  SWIFT

  var keyboardDisplayRequiresUserAction: Bool

  OBJECTIVE-C

  @property(nonatomic) BOOL keyboardDisplayRequiresUserAction

  Discussion

  When this property is set to YES, the user must explicitly tap the elements in the web view to display the keyboard (or other relevant input view) for that element. When set to NO, a focus event on an element causes the input view to be displayed and associated with that element automatically. 

  The default value for this property is YES.

  Import Statement

  import UIKit

  Availability

  Available in iOS 6.0 and later.

•  

   

   

   

Running JavaScript

• stringByEvaluatingJavaScriptFromString:

  Returns the result of running a script.

  Declaration

  SWIFT

  func stringByEvaluatingJavaScriptFromString(_ script: String) -> String?

  OBJECTIVE-C

  - (NSString *)stringByEvaluatingJavaScriptFromString:(NSString*)script


  Parameters

  script

  The script to run.

  Return Value

  The result of running script or nil if it fails.

  Discussion

  JavaScript allocations are limited to 10 MB. The web view raises an exception if you exceed this limit on the total memory allocation for JavaScript.

  Import Statement

  import UIKit

  Availability

  Available in iOS 2.0 and later.

•  

   

   

   

Detecting Types of Data

• dataDetectorTypes

  The types of data converted to clickable URLs in the web view’s content.

  Declaration

  SWIFT

  var dataDetectorTypes: UIDataDetectorTypes

  OBJECTIVE-C

  @property(nonatomic) UIDataDetectorTypes dataDetectorTypes

  Discussion

  You can use this property to specify the types of data (phone numbers, http links, email address, and so on) that should be automatically converted to clickable URLs in the web view. When clicked, the web view opens the application responsible for handling the URL type and passes it the URL. 

  Import Statement

  import UIKit

  Availability

  Available in iOS 3.0 and later.

•  

   

   

   

Managing Media Playback

• allowsInlineMediaPlayback

  A Boolean value that determines whether HTML5 videos play inline or use the native full-screen controller.

  Declaration

  SWIFT

  var allowsInlineMediaPlayback: Bool

  OBJECTIVE-C

  @property(nonatomic) BOOL allowsInlineMediaPlayback

  Discussion

  The default value on iPhone is NO.

  In order for video to play inline, not only does this property need to be set on the view, but the video element in the HTML document must also include the webkit-playsinline attribute.

  Import Statement

  import UIKit

  Availability

  Available in iOS 4.0 and later.

• mediaPlaybackRequiresUserAction

  A Boolean value that determines whether HTML5 videos can play automatically or require the user to start playing them.

  Declaration

  SWIFT

  var mediaPlaybackRequiresUserAction: Bool

  OBJECTIVE-C

  @property(nonatomic) BOOL mediaPlaybackRequiresUserAction

  Discussion

  The default value on both iPad and iPhone is YES. To make media play automatically when loaded, set this property to NO and ensure the <audio> or <video> element you want to play has the autoplay attribute set.

  Import Statement

  import UIKit

  Availability

  Available in iOS 4.0 and later.

• mediaPlaybackAllowsAirPlay

  A Boolean value that determines whether Air Play is allowed from this view.

  Declaration

  SWIFT

  var mediaPlaybackAllowsAirPlay: Bool

  OBJECTIVE-C

  @property(nonatomic) BOOL mediaPlaybackAllowsAirPlay

  Discussion

  The default value on both iPad and iPhone is YES.

  Import Statement

  import UIKit

  Availability

  Available in iOS 5.0 and later.

•  

   

   

   

Managing Pages

• gapBetweenPages

  The size of the gap, in points, between pages.

  Declaration

  SWIFT

  var gapBetweenPages: CGFloat

  OBJECTIVE-C

  @property(nonatomic) CGFloat gapBetweenPages

  Discussion

  The default value is 0.

  Import Statement

  import UIKit

  Availability

  Available in iOS 7.0 and later.

• pageCount

  The number of pages produced by the layout of the web view. (read-only)

  Declaration

  SWIFT

  var pageCount: Int { get }

  OBJECTIVE-C

  @property(nonatomic, readonly) NSUInteger pageCount

  Import Statement

  import UIKit

  Availability

  Available in iOS 7.0 and later.

• pageLength

  The size of each page, in points, in the direction that the pages flow.

  Declaration

  SWIFT

  var pageLength: CGFloat

  OBJECTIVE-C

  @property(nonatomic) CGFloat pageLength

  Discussion

      When paginationMode is right to left or left to right, this property represents the width of each page. When paginationMode is top to bottom or bottom to top, this property represents the height of each page.

  The default value is 0, which means the layout uses the size of the viewport to determine the dimensions of the page. Adjusting the value of this property causes a relayout. 

  Import Statement

  import UIKit

  Availability

  Available in iOS 7.0 and later.

• paginationBreakingMode

  The manner in which column- or page-breaking occurs.

  Declaration

  SWIFT

  var paginationBreakingMode: UIWebPaginationBreakingMode

  OBJECTIVE-C

  @property(nonatomic) UIWebPaginationBreakingModepaginationBreakingMode

  Discussion

  This property determines whether certain CSS properties regarding column- and page-breaking are honored or ignored. When this property is set to UIWebPaginationBreakingModeColumn, the content respects the CSS properties related to column-breaking in place of page-breaking.

  See UIWebPaginationBreakingMode for possible values. The default value is UIWebPaginationBreakingModePage.

  Import Statement

  import UIKit

  Availability

  Available in iOS 7.0 and later.

• paginationMode

  The layout of content in the web view.

  Declaration

  SWIFT

  var paginationMode: UIWebPaginationMode

  OBJECTIVE-C

  @property(nonatomic) UIWebPaginationMode paginationMode

  Discussion

      This property determines whether content in the web view is broken up into pages that fill the view one screen at a time, or shown as one long scrolling view. If set to a paginated form, this property toggles a paginated layout on the content, causing the web view to use the values of pageLengthand gapBetweenPages to relayout its content.

  See UIWebPaginationMode for possible values. The default value is UIWebPaginationModeUnpaginated.

  Import Statement

  import UIKit

  Availability

  Available in iOS 7.0 and later.

•  

   

   

   

Data Types

• UIWebViewNavigationType

  Constant indicating the user’s action.

  Declaration

  OBJECTIVE-C

  enum { UIWebViewNavigationTypeLinkClicked, UIWebViewNavigationTypeFormSubmitted, UIWebViewNavigationTypeBackForward, UIWebViewNavigationTypeReload, UIWebViewNavigationTypeFormResubmitted, UIWebViewNavigationTypeOther }; typedef NSUInteger UIWebViewNavigationType;

  Constants

  • UIWebViewNavigationTypeLinkClicked

    User tapped a link.

    Available in iOS 2.0 and later.

  • UIWebViewNavigationTypeFormSubmitted

    User submitted a form.

    Available in iOS 2.0 and later.

  • UIWebViewNavigationTypeBackForward

    User tapped the back or forward button.

    Available in iOS 2.0 and later.

  • UIWebViewNavigationTypeReload

    User tapped the reload button.

    Available in iOS 2.0 and later.

  • UIWebViewNavigationTypeFormResubmitted

    User resubmitted a form.

    Available in iOS 2.0 and later.

  • UIWebViewNavigationTypeOther

    Some other action occurred.

    Available in iOS 2.0 and later.

  Import Statement

   

  Availability

  Available in iOS 2.0 and later.

•  

   

   

   

Constants

• UIWebPaginationBreakingMode

  The manner in which column- or page-breaking occurs.

  Declaration

  OBJECTIVE-C

  typedef NS_ENUM (NSInteger , UIWebPaginationBreakingMode ) { UIWebPaginationBreakingModePage , UIWebPaginationBreakingModeColumn };

  Constants

  • UIWebPaginationBreakingModePage

    Content respects CSS properties related to page-breaking.

    Available in iOS 7.0 and later.

  • UIWebPaginationBreakingModeColumn

    Content respects CSS properties related to column-breaking.

    Available in iOS 7.0 and later.

  Import Statement

   

  Availability

  Available in iOS 7.0 and later.

• UIWebPaginationMode

  The layout of content in the web view, which determines the direction that the pages flow.

  Declaration

  OBJECTIVE-C

  typedef NS_ENUM (NSInteger , UIWebPaginationMode ) { UIWebPaginationModeUnpaginated , UIWebPaginationModeLeftToRight , UIWebPaginationModeTopToBottom , UIWebPaginationModeBottomToTop , UIWebPaginationModeRightToLeft };

  Constants

  • UIWebPaginationModeUnpaginated

    Content appears as one long scrolling view with no distinct pages.

    Available in iOS 7.0 and later.

  • UIWebPaginationModeLeftToRight

    Content is broken up into pages that flow from left to right.

    Available in iOS 7.0 and later.

  • UIWebPaginationModeTopToBottom

    Content is broken up into pages that flow from top to bottom.

    Available in iOS 7.0 and later.

  • UIWebPaginationModeBottomToTop

    Content is broken up into pages that flow from bottom to top.

    Available in iOS 7.0 and later.

  • UIWebPaginationModeRightToLeft

    Content is broken up into pages that flow from right to left.

    Available in iOS 7.0 and later.

  Import Statement

   

  Availability

  Available in iOS 7.0 and later.