iOS圖片瀏覽器 - XLPhotoBrowser(類似微信多圖片瀏覽效果)

XLPhotoBrowser的GitHub連結
XLPhotoBrowser常見問題彙總

提示:最新使用教程請以GitHub連結為準,此文章不會每個版本都更新,有什麼問題或者bug等可以在GitHub上提交issues

1.XLPhotoBrowser描述

一個簡單實用的圖片瀏覽器,效果類似微信圖片瀏覽器,支援彈出動畫和回縮動畫,支援多圖瀏覽,支援本地和網路圖片瀏覽,支援多種屬性自定義(支援橫豎屏瀏覽)

支援多種圖片瀏覽樣式

• 類似微信圖片瀏覽樣式XLPhotoBrowserStylePageControl , 底部有個pagecontrol顯示圖片索引
• 類似微博圖片瀏覽樣式XLPhotoBrowserStyleIndexLabel , 上面有個UILabel顯示圖片索引
• 簡單樣式XLPhotoBrowserStyleSimple , 上面有UILabel顯示圖片索引,左下部分有個儲存按鈕,可以儲存當前圖片

支援長按手勢彈出多功能選擇框,類似微博微信中的效果

其他效果圖:

2. 安裝方法

2.1 第一種方法: 使用cocoapods自動安裝

pod 'XLPhotoBrowser+CoderXL'

2.2 第二種方法 :

• 2.2.1 下載示例Demo
• 2.2.2 把裡面的XLPhotoBrowser資料夾拖到你的專案中(注意: 裡面用到了一些第三方的類庫,如果你的專案中已經使用了這些庫,視情況刪除)
• 2.2.3 如果你的專案中沒有用到SDWebImage框架,把圖中SDWebImage資料夾也一起拖到你的工程中

注意:

• XLPhotoBrowser 1.2.0版本依賴於SDWebImage框架4.0.0版本,由於SDWebImage4.0版本對API進行了修改,所以不相容SDWebImage4.0以下版本

3. 使用說明

3.1基本使用(提供2種傳遞資料的方法:圖片以陣列形式批量傳遞 和 資料來源方法分開傳遞每一個位置的圖片資料)

方法一:一行程式碼進入圖片瀏覽器 在某些場景,例如只是想瀏覽一組本地/網路圖片,你可以這樣使用:

    // 傳入圖片資料來源,直接進行圖片瀏覽
    // 傳入圖片資料來源陣列self.images 可以是UIImage物件陣列 ,可以是ALAsset物件, 也可以是圖片的NSURL連結 , 或者是可以變成NSURL連結的NSString物件陣列

    [XLPhotoBrowser showPhotoBrowserWithImages:self.images currentImageIndex:0];

方法二：如果上面直接提供圖片陣列的方式不適合,你可以考慮實現資料來源方法,提供資料

• 資料來源方法提供了三個,不同的需求效果需要搭配不同的方法使用.根據每個方法的註釋說明和專案的需求來決定具體要實現哪幾個方法

/**
 進入圖片瀏覽器
 */
- (void)clickImage:(UITapGestureRecognizer *)tap
{
    [XLPhotoBrowser showPhotoBrowserWithCurrentImageIndex:tap.view.tag imageCount:self.images.count datasource:self];
}

#pragma mark    -   XLPhotoBrowserDatasource

/**
 *  返回這個位置的佔點陣圖片 , 也可以是原圖
 *  如果不實現此方法,會預設使用placeholderImage
 *
 *  @param browser 瀏覽器
 *  @param index   位置索引
 *
 *  @return 佔點陣圖片
 */
- (UIImage *)photoBrowser:(XLPhotoBrowser *)browser placeholderImageForIndex:(NSInteger)index
{
    return self.images[index];
}

/**
 *  返回指定位置圖片的UIImageView,用於做圖片瀏覽器彈出放大和消失回縮動畫等
 *  如果沒有實現這個方法,沒有回縮動畫,如果傳過來的view不正確,可能會影響回縮動畫效果
 *
 *  @param browser 瀏覽器
 *  @param index   位置索引
 *
 *  @return 展示圖片的容器檢視,如UIImageView等
 */
- (UIView *)photoBrowser:(XLPhotoBrowser *)browser sourceImageViewForIndex:(NSInteger)index
{
    return self.scrollView.subviews[index];
}

/**
 *  返回指定位置的高清圖片URL
 *  如果你要顯示更高質量的圖片,可以通過這個方法傳遞網路/本地圖片路徑實現效果
 *
 *  @param browser 瀏覽器
 *  @param index   位置索引
 *
 *  @return 返回高清大圖索引
 */
- (NSURL *)photoBrowser:(XLPhotoBrowser *)browser highQualityImageURLForIndex:(NSInteger)index
{
    return [NSURL URLWithString:self.urlStrings[index]];
}

ps:下面的示例程式碼中如非必要,統一用第一種方式傳遞圖片陣列來展示

3.2進階使用說明(自定義多種屬性等)

• 如何進行網路圖片瀏覽
  一行程式碼進入瀏覽,傳遞網路圖片的地址陣列進去即可

    // 1. NSURL陣列
//    NSMutableArray *URLArray = [NSMutableArray array];
//    for (NSString *urlString in self.urlStrings) {
//        NSURL *URL = [NSURL URLWithString:urlString];
//        [URLArray addObject:URL];
//    }
//    [XLPhotoBrowser showPhotoBrowserWithImages:URLArray currentImageIndex:0];

    // 2.可以變成NSURL連結的NSString物件陣列
    [XLPhotoBrowser showPhotoBrowserWithImages:self.urlStrings currentImageIndex:0];

或者用資料來源方式,實現photoBrowser: highQualityImageURLForIndex:方法

- (void)clickImage:(UITapGestureRecognizer *)tap
{
    [XLPhotoBrowser showPhotoBrowserWithCurrentImageIndex:tap.view.tag imageCount:self.images.count datasource:self];
}

#pragma mark    -   XLPhotoBrowserDatasource

// 可以不實現此方法
- (UIImage *)photoBrowser:(XLPhotoBrowser *)browser placeholderImageForIndex:(NSInteger)index
{
    return self.images[index];
}

- (NSURL *)photoBrowser:(XLPhotoBrowser *)browser highQualityImageURLForIndex:(NSInteger)index
{
    return [NSURL URLWithString:self.urlStrings[index]];
}

• 如何新增長按手勢並自定義選擇選單
• 獲取XLPhotoBrowser例項物件,呼叫setActionSheetWithTitle:delegate:cancelButtonTitle:deleteButtonTitle:otherButtonTitles:方法
• 同時在 XLPhotoBrowserDelegate代理方法中監聽到使用者的選擇

/**
 *  瀏覽圖片
 *
 */
- (void)clickImage:(UITapGestureRecognizer *)tap
{
    XLPhotoBrowser *browser = [XLPhotoBrowser showPhotoBrowserWithImages:self.images currentImageIndex:tap.view.tag];
    browser.browserStyle = XLPhotoBrowserStyleIndexLabel; // 微博樣式
    
    // 設定長按手勢彈出的地步ActionSheet資料,不實現此方法則沒有長按手勢
    [browser setActionSheetWithTitle:@"這是一個類似微信/微博的圖片瀏覽器元件" delegate:self cancelButtonTitle:nil deleteButtonTitle:@"刪除" otherButtonTitles:@"傳送給朋友",@"儲存圖片",@"收藏",@"投訴",nil];
}

#pragma mark    -   XLPhotoBrowserDelegate

- (void)photoBrowser:(XLPhotoBrowser *)browser clickActionSheetIndex:(NSInteger)actionSheetindex currentImageIndex:(NSInteger)currentImageIndex
{
    // do something yourself
    switch (actionSheetindex) {
        case 4: // 刪除
        {
            NSLog(@"點選了actionSheet索引是:%zd , 當前展示的圖片索引是:%zd",actionSheetindex,currentImageIndex);
            [self.images removeObjectAtIndex:currentImageIndex];
            [self resetScrollView];
        }
            break;
        case 1: // 儲存
        {
            NSLog(@"點選了actionSheet索引是:%zd , 當前展示的圖片索引是:%zd",actionSheetindex,currentImageIndex);
            [browser saveCurrentShowImage];
        }
            break;
        default:
        {
            NSLog(@"點選了actionSheet索引是:%zd , 當前展示的圖片索引是:%zd",actionSheetindex,currentImageIndex);
        }
            break;
    }
}

• 如何選擇瀏覽器樣式
• 獲取到例項物件以後,設定browserStyle屬性即可

    XLPhotoBrowser *browser = [XLPhotoBrowser showPhotoBrowserWithImages:self.images currentImageIndex:tap.view.tag];
    browser.browserStyle = XLPhotoBrowserStyleIndexLabel; // 微博樣式

• 如何修改pagecontrol為縮放動畫樣式
• 僅在XLPhotoBrowserStylePageControl樣式中有效, 在XLPhotoBrowserStyleIndexLabel樣式無效

    // 自定義pageControl的一些屬性
    browser.pageDotColor = [UIColor purpleColor]; ///< 此屬性針對動畫樣式的pagecontrol無效
    browser.currentPageDotColor = [UIColor greenColor];
    browser.pageControlStyle = XLPhotoBrowserPageControlStyleClassic;///< 修改底部pagecontrol的樣式為系統樣式,預設是彈性動畫的樣式

• 如何實現類似微信那樣點選圖片進入瀏覽器時的圖片放大和退出瀏覽時圖片縮放的過渡動畫
• 實現資料來源方法中的photoBrowser:sourceImageViewForIndex:方法,傳遞圖片的容器檢視,才可以做過渡動畫

#pragma mark    -   XLPhotoBrowserDatasource

- (UIImage *)photoBrowser:(XLPhotoBrowser *)browser placeholderImageForIndex:(NSInteger)index
{
    return self.images[index];
}

- (UIView *)photoBrowser:(XLPhotoBrowser *)browser sourceImageViewForIndex:(NSInteger)index
{
    return self.scrollView.subviews[index];
}

• 如何使用XLPhotoBrowserConfig,
• 如何開啟除錯模式,輸出格式化的提示資訊
• 開啟在XLPhotoBrowserConfig中的這個程式碼即可 //#define XLPhotoBrowserDebug 1
• 還可以在這裡修改很多樣式屬性,如:修改瀏覽器的背景色/圖片間隔等 ,使用方式很簡單,具體的使用就不在這裡贅述

4. 更新日誌

*   1.2.0
    *   1. 支援橫豎屏適配(裝置沒有鎖定方向,且專案配置支援橫屏才可以觸發橫屏瀏覽模式)
    *   2. 更新SDWebImage到4.0.0 , 由於SDWebImage4.0版本對API進行了修改,所以不相容SDWebImage4.0以下版本
    *   3. 修復圖片下載進度條等已知bug
*   1.1.0 
    *   1. 優化框架結構，XLPhotoBrowser內部維護一個優先順序為maxfloat的UIWindow，避免不同的專案會因為視窗問題造成XLPhotoBrowser顯示不正確等問題
    *   2. 修改FSActionSheet原始碼，修復長按彈出ActionSheet顯示在圖片後面等問題
    *   3. 優化圖片放大縮小處理邏輯，修復已知bug

5. 喜歡的話,就給作者一個star ,你可以通過下面的方式聯絡到我

• QQ群 : 579572313 (有什麼問題,歡迎進群討論提問)
• 郵箱 : coder_xl@163.com

6. 常見問題，可以參考這篇帖子XLPhotoBrowser常見問題彙總