網路上搜 UIWebView 的整理文章,多半是同一份沒有註解的純代碼拷貝。本文重新為每個 API 補上說明,並把最冷門的介面標示出來,讓它真正能當字典用。
這個枚舉定義了「使用者在網頁中做了什麼」,主要用途是在代理方法中區分載入來源。
typedef NS_ENUM(NSInteger, UIWebViewNavigationType) {
UIWebViewNavigationTypeLinkClicked, // 點擊連結
UIWebViewNavigationTypeFormSubmitted, // 提交表單
UIWebViewNavigationTypeBackForward, // 點擊上一頁/下一頁
UIWebViewNavigationTypeReload, // 點擊重新載入
UIWebViewNavigationTypeFormResubmitted, // 重複提交表單
UIWebViewNavigationTypeOther // 其他行為
};
typedef NS_ENUM(NSInteger, UIWebPaginationMode) {
UIWebPaginationModeUnpaginated, // 不分頁
UIWebPaginationModeLeftToRight, // 由左至右
UIWebPaginationModeTopToBottom, // 由上至下
UIWebPaginationModeBottomToTop, // 由下至上
UIWebPaginationModeRightToLeft // 由右至左
};
typedef NS_ENUM(NSInteger, UIWebPaginationBreakingMode) {
UIWebPaginationBreakingModePage, // 預設值,CSS 依頁(page-break)斷裂
UIWebPaginationBreakingModeColumn // 改用 column-break 規則斷裂
};
這兩個 iOS 7 才加入的 API,讓 UIWebView 能把長網頁像電子書一樣切成分頁,配合 pageLength 與 gapBetweenPages 就能做出翻頁閱讀的效果。
@interface UIWebView : UIView <NSCoding, UIScrollViewDelegate> @property (nonatomic, assign) id <UIWebViewDelegate> delegate; @property (nonatomic, readonly, retain) UIScrollView *scrollView; // iOS 5 起可取得內層 scrollView @end
// 1. 最常用:直接給定網路請求
- (void)loadRequest:(NSURLRequest *)request;
// 2. 載入本地 HTML 字串,baseURL 決定相對路徑的解析基準
- (void)loadHTMLString:(NSString *)string baseURL:(NSURL *)baseURL;
// 3. 載入已轉為 NSData 的位元組內容,需指定 MIME 類型與文字編碼
- (void)loadData:(NSData *)data
MIMEType:(NSString *)MIMEType
textEncodingName:(NSString *)textEncodingName
baseURL:(NSURL *)baseURL;
@property (nonatomic, readonly, retain) NSURLRequest *request; // 當前請求 - (void)reload; // 重新載入 - (void)stopLoading; // 停止載入 - (void)goBack; // 回到上一頁 - (void)goForward; // 前往下一頁 @property (nonatomic, readonly, getter=canGoBack) BOOL canGoBack; @property (nonatomic, readonly, getter=canGoForward) BOOL canGoForward; @property (nonatomic, readonly, getter=isLoading) BOOL loading;
這個方法是 UIWebView 與網頁溝通的核心橋樑,必須等頁面載入完成後呼叫才有效:
- (NSString *)stringByEvaluatingJavaScriptFromString:(NSString *)script; // 取得頁面標題 NSString *title = [webView stringByEvaluatingJavaScriptFromString:@"document.title"];
@property (nonatomic) BOOL scalesPageToFit; // 內容是否伸縮以適應目前尺寸
// 讓電話號碼、網址、Email、日期等文字自動變成可點擊連結 @property (nonatomic) UIDataDetectorTypes dataDetectorTypes NS_AVAILABLE_IOS(3_0); // 已棄用,功能由 dataDetectorTypes 取代 @property (nonatomic) BOOL detectsPhoneNumbers NS_DEPRECATED_IOS(2_0, 3_0); // 是否以內嵌方式播放 HTML5 影片,而非切換全螢幕播放器 // 生效條件有兩項:此屬性為 YES,且 video 標籤帶有 webkit-playsinline // iPhone Safari 預設 NO,iPad Safari 預設 YES @property (nonatomic) BOOL allowsInlineMediaPlayback NS_AVAILABLE_IOS(4_0); // 影片是否可自動播放;iPhone 與 iPad 預設皆為 YES @property (nonatomic) BOOL mediaPlaybackRequiresUserAction NS_AVAILABLE_IOS(4_0); // 是否允許 AirPlay;兩者預設皆為 YES @property (nonatomic) BOOL mediaPlaybackAllowsAirPlay NS_AVAILABLE_IOS(5_0);
// 為 YES 時會等內容全部載入記憶體後才渲染,可避免逐步閃動;預設 NO @property (nonatomic) BOOL suppressesIncrementalRendering NS_AVAILABLE_IOS(6_0); // 為 YES 時使用者必須明確點擊輸入框才會彈出鍵盤; // 為 NO 時元素獲得焦點即自動彈出鍵盤並關聯該元素 @property (nonatomic) BOOL keyboardDisplayRequiresUserAction NS_AVAILABLE_IOS(6_0);
@property (nonatomic) UIWebPaginationMode paginationMode; // 分頁方向 @property (nonatomic) UIWebPaginationBreakingMode paginationBreakingMode; // 斷頁規則 @property (nonatomic) CGFloat pageLength; // 每頁長度 @property (nonatomic) CGFloat gapBetweenPages; // 頁間距 @property (nonatomic, readonly) NSUInteger pageCount; // 總頁數
// 每個請求發生前都會先經過這裡,可攔截不當連結 // 回傳 YES 允許載入,回傳 NO 中止載入 - (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType; - (void)webViewDidStartLoad:(UIWebView *)webView; // 開始載入 - (void)webViewDidFinishLoad:(UIWebView *)webView; // 載入完成 - (void)webView:(UIWebView *)webView didFailLoadWithError:(NSError *)error; // 載入失敗
實務上,shouldStartLoadWithRequest: 是攔截 scheme 跳轉、攔截廣告、以及做原生與網頁雙向溝通的關鍵入口;didFailLoadWithError: 則要記得排除 NSURLErrorCancelled(-999),這在正常的中斷流程中也會觸發。
UIWebView 自 iOS 12 起已被蘋果標記為棄用並在後續版本中移除,新專案應改用 WKWebView。這份整理仍適用於維護既有程式碼的情境。