DOCSEARCHbyAlgolia
Submit Docs

JXCategoryView Documentation

repository·master·Indexed 27 days ago

https://github.com/pujiaxin33/jxcategoryview

An Objective-C library for iOS 9.0+ providing highly customizable category and segmented view components. It supports various visual effects, indicators, and navigation patterns found in mainstream applications. The library includes JXCategoryTitleView for title management and integrates with JXPagingView to synchronize category tabs with paging content via JXPagerView and JXPagerViewDelegate.

Tokens
7.9K
Snippets
14
Records
54
Agent score
91%

What's inside JXCategoryView

  1. Overview of JXCategoryView

    master

    JXCategoryView is a powerful and highly customizable category view component for iOS. It supports various scrolling and paging view patterns commonly seen in mainstream apps like Tencent News, Toutiao, QQ Music, and others. It can be used to implement segmented controls, segment views, paging views, and page controls.

    Key advantages include:

    • Customizable Indicators: Uses protocols to encapsulate indicator logic, allowing for easy custom effects.
    • Rich Effects: Provides a comprehensive range of highly customizable visual effects.
    • Subclass-based Cell Management: Uses subclassing to manage cell styles, making logic clearer and extensions simpler.
    • Encapsulated List Containers: Highly encapsulated list containers that support the full lifecycle of the list components.

  2. Review JXCategoryView visual effects and indicators

    master

    JXCategoryView supports a wide variety of visual styles for both indicators and cells:

    Indicator Styles

    • LineView: Standard line, extended line, and offset line (e.g., iQIYI style).
    • RainbowLineView: Multi-color rainbow style.
    • DotLineView: Dotted line effect.
    • BallView: Sticky red dot (QQ style).
    • TriangleView: Triangle indicators at the top or bottom.
    • BackgroundView: Elliptical (with or without shadow), rectangular, or gradient backgrounds.
    • ImageView: Custom images (e.g., boat, football) with scrolling effects.

    Note: JXCategoryIndicatorLineView, JXCategoryIndicatorImageView, JXCategoryIndicatorBallView, and JXCategoryIndicatorTriangleView all support switching between top and bottom positions.

    Cell Styles

    • Animations: Color gradients, size zooming (with top/bottom anchor support), and click animations.
    • Content: Images (top, left, bottom, right), mixed text and images, numbers, red dots, multi-line text, and attributed strings.
    • Layout: Cell background color gradients and separator lines.

  3. Review advanced usage and special effects

    master

    JXCategoryView can be used in complex UI scenarios:

    • Segmented Control: Mimic segmented controls or use within a Navigation Bar.
    • Nested Views: Nesting category views within other controllers.
    • Paging/Personal Profiles: Integration with paging views for scrolling headers and content.
    • Vertical Lists: Support for vertical list scrolling (e.g., Tencent Video style).
    • Vertical Zoom: Scaling effects similar to NetEase or Maimai homepages.
    • Data Loading: Handling data refreshes and list loading within the container.
    • Dynamic Navigation: Hiding the navigation bar during scroll up/down.

  5. Use JXCategoryTitleView

    master

    To implement a category title view, initialize JXCategoryTitleView, set its delegate, and configure its titles and indicators.

    1. Initialize: Create the view with a frame and assign a delegate.
    2. Configure Titles: Set the titles array and optional properties like titleColorGradientEnabled.
    3. Add Indicators: Create an indicator view (e.g., JXCategoryIndicatorLineView), configure its properties, and add it to the indicators array.
    4. Handle Events: Implement JXCategoryViewDelegate to respond to selection or scrolling events.
    // 1. Initialize
self.categoryView = [[JXCategoryTitleView alloc] initWithFrame:CGRectMake(0, 0, WindowsSize.width, 50)];
self.categoryView.delegate = self;
[self.view addSubview:self.categoryView];

// 2. Configure properties
self.categoryView.titles = @[@"螃蟹", @"麻辣小龙虾", @"苹果"...];
self.categoryView.titleColorGradientEnabled = YES;

// 3. Add indicator
JXCategoryIndicatorLineView *lineView = [[JXCategoryIndicatorLineView alloc] init];
lineView.indicatorColor = [UIColor redColor];
lineView.indicatorWidth = JXCategoryViewAutomaticDimension;
self.categoryView.indicators = @[lineView];

// 4. Implement JXCategoryViewDelegate (Example methods)
- (void)categoryView:(JXCategoryBaseView *)categoryView didSelectedItemAtIndex:(NSInteger)index;
- (void)categoryView:(JXCategoryBaseView *)categoryView didClickSelectedItemAtIndex:(NSInteger)index;
- (void)categoryView:(JXCategoryBaseView *)categoryView didScrollSelectedItemAtIndex:(NSInteger)index;
- (void)categoryView:(JXCategoryBaseView *)categoryView scrollingFromLeftIndex:(NSInteger)leftIndex toRightIndex:(NSInteger)rightIndex ratio:(CGFloat)ratio;

  6. Manage List View Controller Lifecycle

    master

    In version 1.5.0 and later, JXCategoryListContainerView manages its own JXCategoryListContainerViewController to handle the lifecycle of all list view controllers.

    CRITICAL: Do NOT call addChildViewController: manually when implementing initListForIndex: in the JXCategoryListContainerViewDelegate. Doing so will cause a crash because the container view controller has already performed the addChild operation.

    Additionally, if your list is a UIViewController, you can remove any custom naviController properties you previously passed in. The container view controller automatically detects UIViewController types and manages the hierarchy, allowing the list VC to use self.navigationController directly.

    - (id<JXCategoryListContentViewDelegate>)listContainerView:(JXCategoryListContainerView *)listContainerView initListForIndex:(NSInteger)index {
    LoadDataListContainerListViewController *listVC = [[LoadDataListContainerListViewController alloc] init];
    // ⚠️ DO NOT call [self addChildViewController:listVC];
    listVC.title = self.titles[index];
    return listVC;
}

  7. Handle custom navigation bar back items with swipe gestures

    master

    If you are using a custom back item in your navigation bar while implementing the swipe-back logic described above, you must also set the gesture recognizer's delegate and allow simultaneous recognition to prevent the gesture from being blocked.

    // Set the delegate for the interactive pop gesture recognizer
self.navigationController.interactivePopGestureRecognizer.delegate = self;

// Implement the delegate method to allow simultaneous recognition
- (BOOL)gestureRecognizer:(UIGestureRecognizer *)gestureRecognizer shouldRecognizeSimultaneouslyWithGestureRecognizer:(UIGestureRecognizer *)otherGestureRecognizer {
    return YES;
}

  8. Simplify Delegate and Property Synchronization

    master

    Starting from version 1.5.0, JXCategoryBaseView automatically handles synchronization with its listContainer. You no longer need to manually forward delegate calls or update properties on both objects.

    Remove Manual Delegate Forwarding

    Delete manual calls to didClickSelectedItemAtIndex: and scrollingFromLeftIndex:toRightIndex:ratio: inside your JXCategoryViewDelegate implementation.

    Set defaultSelectedIndex on Category View Only

    Do not set defaultSelectedIndex on both the category view and the list container. Setting it on categoryView is sufficient; it will automatically sync to the listContainer.

    Call reloadData on Category View Only

    Instead of calling reloadData on both objects, call it only on categoryView. It will automatically trigger reloadData on the listContainer.

  9. Install JXPagingView via CocoaPods

    master

    JXPagingView provides separate pods for Swift and Objective-C. Ensure you select the correct one for your project and run pod repo update before pod install.

    # Swift version (requires Swift 5.0+)
target '<Your Target Name>' do
    pod 'JXPagingView/Paging'
end

# Objective-C version
target '<Your Target Name>' do
    pod 'JXPagingView/Pager'
end

  11. Customize Cell Styles

    master

    When customizing cells, follow these patterns depending on your needs:

    • Full Customization: If you want to completely control the cell content, you must subclass all three components: the View, the Cell, and the CellModel (e.g., subclass JXCategoryIndicatorView, JXCategoryIndicatorCell, and JXCategoryIndicatorCellModel).
    • Minor Adjustments: If you only need to tweak existing controls or add a new control to an existing style, inherit from the target View, Cell, and CellModel (e.g., inheriting from the JXCategoryTitleImageView series).

  12. Migration Guide: Upgrading JXPagerView

    master

    Version 0.0.9

    Return types for the following methods changed from CGFloat to NSUInteger (or Int in Swift). Update your implementations to avoid crashes:

    • - (NSUInteger)heightForPinSectionHeaderInPagerView:(JXPagerView *)pagerView
    • - (NSUInteger)tableHeaderViewHeightInPagerView:(JXPagerView *)pagerView

    Version 1.0.0

    listViewsInPagerView: was removed. Use these two methods instead:

    • - (NSInteger)numberOfListsInPagerView:(JXPagerView *)pagerView;
    • - (id<JXPagerViewListViewDelegate>)pagerView:(JXPagerView *)pagerView initListAtIndex:(NSInteger)index;

    Version 2.0.0

    • JXPagerListContainerView was refactored; lists are now UIViewController subclasses with full lifecycle support (e.g., viewWillAppear).
    • collectionView property was replaced by scrollView.
    • Update CategoryView binding to: self.categoryView.listContainer = (id<JXCategoryViewListContainer>)self.pagerView.listContainerView;.
    • Use the new initializer to specify container type: - (instancetype)initWithDelegate:(id<JXPagerViewDelegate>)delegate listContainerType:(JXPagerListContainerType)type.