Material 3 的 Carousel 控件

/**
 * A class responsible for creating a model used by a carousel to mask and offset views as they move
 * along a scrolling axis.
 */
public abstract class CarouselStrategy {

  abstract KeylineState onFirstChildMeasuredWithMargins(
      @NonNull Carousel carousel, @NonNull View child);

  @FloatRange(from = 0F, to = 1F)
  static float getChildMaskPercentage(float maskedSize, float unmaskedSize, float childMargins) {
    return 1F - ((maskedSize - childMargins) / (unmaskedSize - childMargins));
  }
}

KeylineState onFirstChildMeasuredWithMargins(@NonNull Carousel carousel, @NonNull View child) {
  float availableSpace = carousel.getContainerWidth();

  LayoutParams childLayoutParams = (LayoutParams) child.getLayoutParams();
  float childHorizontalMargins = childLayoutParams.leftMargin + childLayoutParams.rightMargin;

  float smallChildWidthMin = getSmallSizeMin(child.getContext()) + childHorizontalMargins;
  float smallChildWidthMax = getSmallSizeMax(child.getContext()) + childHorizontalMargins;

  float measuredChildWidth = child.getMeasuredWidth();
  float targetLargeChildWidth = min(measuredChildWidth + childHorizontalMargins, availableSpace);
  // Ideally we would like to create a balanced arrangement where a small item is 1/3 the size of
  // the large item and medium items are sized between large and small items. Clamp the small
  // target size within our min-max range and as close to 1/3 of the target large item size as
  // possible.
  float targetSmallChildWidth =
      MathUtils.clamp(
          measuredChildWidth / 3F + childHorizontalMargins,
          getSmallSizeMin(child.getContext()) + childHorizontalMargins,
          getSmallSizeMax(child.getContext()) + childHorizontalMargins);
  float targetMediumChildWidth = (targetLargeChildWidth + targetSmallChildWidth) / 2F;

  // Create arrays representing the possible count of small, medium, and large items. These are
  // not in an asc./dec. order but are in order of priority. A small count array of { 2, 3, 1 }
  // says that ideally an arrangement with 2 small items is found, then 3 is next most desirable,
  // then finally 1.
  int[] smallCounts = SMALL_COUNTS;
  int[] mediumCounts = forceCompactArrangement ? MEDIUM_COUNTS_COMPACT : MEDIUM_COUNTS;
  // Find the minimum space left for large items after filling the carousel with the most
  // permissible medium and small items to determine a plausible minimum large count.
  float minAvailableLargeSpace =
      availableSpace
          - (targetMediumChildWidth * maxValue(mediumCounts))
          - (smallChildWidthMax * maxValue(smallCounts));
  int largeCountMin = (int) max(1, floor(minAvailableLargeSpace / targetLargeChildWidth));
  int largeCountMax = (int) ceil(availableSpace / targetLargeChildWidth);
  int[] largeCounts = new int[largeCountMax - largeCountMin + 1];
  for (int i = 0; i < largeCounts.length; i++) {
    largeCounts[i] = largeCountMax - i;
  }

  Arrangement arrangement =
      findLowestCostArrangement(
          availableSpace,
          targetSmallChildWidth,
          smallChildWidthMin,
          smallChildWidthMax,
          smallCounts,
          targetMediumChildWidth,
          mediumCounts,
          targetLargeChildWidth,
          largeCounts);

  float extraSmallChildWidth = getExtraSmallSize(child.getContext()) + childHorizontalMargins;

  float start = 0F;
  float extraSmallHeadCenterX = start - (extraSmallChildWidth / 2F);

  float largeStartCenterX = start + (arrangement.largeSize / 2F);
  float largeEndCenterX =
      largeStartCenterX + (max(0, arrangement.largeCount - 1) * arrangement.largeSize);
  start = largeEndCenterX + arrangement.largeSize / 2F;

  float mediumCenterX =
      arrangement.mediumCount > 0 ? start + (arrangement.mediumSize / 2F) : largeEndCenterX;
  start = arrangement.mediumCount > 0 ? mediumCenterX + (arrangement.mediumSize / 2F) : start;

  float smallStartCenterX =
      arrangement.smallCount > 0 ? start + (arrangement.smallSize / 2F) : mediumCenterX;

  float extraSmallTailCenterX = carousel.getContainerWidth() + (extraSmallChildWidth / 2F);

  float extraSmallMask =
      getChildMaskPercentage(extraSmallChildWidth, arrangement.largeSize, childHorizontalMargins);
  float smallMask =
      getChildMaskPercentage(
          arrangement.smallSize, arrangement.largeSize, childHorizontalMargins);
  float mediumMask =
      getChildMaskPercentage(
          arrangement.mediumSize, arrangement.largeSize, childHorizontalMargins);
  float largeMask = 0F;

  KeylineState.Builder builder =
      new KeylineState.Builder(arrangement.largeSize)
          .addKeyline(extraSmallHeadCenterX, extraSmallMask, extraSmallChildWidth)
          .addKeylineRange(
              largeStartCenterX, largeMask, arrangement.largeSize, arrangement.largeCount, true);
  if (arrangement.mediumCount > 0) {
    builder.addKeyline(mediumCenterX, mediumMask, arrangement.mediumSize);
  }
  if (arrangement.smallCount > 0) {
    builder.addKeylineRange(
        smallStartCenterX, smallMask, arrangement.smallSize, arrangement.smallCount);
  }
  builder.addKeyline(extraSmallTailCenterX, extraSmallMask, extraSmallChildWidth);
  return builder.build();
}

private static final int[] SMALL_COUNTS = new int[] {1};
private static final int[] MEDIUM_COUNTS = new int[] {1, 0};

float minAvailableLargeSpace =
    availableSpace
        - (targetMediumChildWidth * maxValue(mediumCounts))
        - (smallChildWidthMax * maxValue(smallCounts));
int largeCountMin = (int) max(1, floor(minAvailableLargeSpace / targetLargeChildWidth));
int largeCountMax = (int) ceil(availableSpace / targetLargeChildWidth);
int[] largeCounts = new int[largeCountMax - largeCountMin + 1];
for (int i = 0; i < largeCounts.length; i++) {
  largeCounts[i] = largeCountMax - i;
}

Arrangement.findLowestCostArrangement
↓
Arrangement()
↓
Arrangement.fit
↓
Arrangement.calculateLargeSize

largeSize =
    calculateLargeSize(availableSpace, smallCount, smallSize, mediumCount, largeCount);
mediumSize = (largeSize + smallSize) / 2F;

private float calculateLargeSize(
        float availableSpace, int smallCount, float smallSize, int mediumCount, int largeCount) {
  // Zero out small size if there are no small items
  smallSize = smallCount > 0 ? smallSize : 0F;
  return (availableSpace - (((float) smallCount) + ((float) mediumCount) / 2F) * smallSize)
      / (((float) largeCount) + ((float) mediumCount) / 2F);
}

if (mediumCount > 0 && largeSize != targetLargeSize) {
  float targetAdjustment = (targetLargeSize - largeSize) * largeCount;
  float availableMediumFlex = (mediumSize * MEDIUM_ITEM_FLEX_PERCENTAGE) * mediumCount;
  float distribute = min(abs(targetAdjustment), availableMediumFlex);
  if (targetAdjustment > 0F) {
    // Reduce the size of the medium item and give it back to the large items
    mediumSize -= (distribute / mediumCount);
    largeSize += (distribute / largeCount);
  } else {
    // Increase the size of the medium item and take from the large items
    mediumSize += (distribute / mediumCount);
    largeSize -= (distribute / largeCount);
  }
}

/**
 * A data class that represents a state an item should be in when its center is at a position
 * along the scroll axis.
 */
static final class Keyline {
  final float loc;
  final float locOffset;
  final float mask;
  final float maskedItemSize;
  // ...
}

LayoutManager.layoutChildren
↓
CarouselLayoutManager.updateCurrentKeylineStateForScrollOffset
↓
KeylineStateList.getShiftedState
↓
KeylineStateList.lerp
↓
KeylineState.lerp
↓
Keyline.lerp

/** Interface for any view that can clip itself and all children to a percentage of its size. */
interface Maskable {

  /**
   * Set the percentage by which this {@link View} should mask itself along the x axis.
   *
   * @param percentage 0 when this view is fully unmasked. 1 when this view is fully masked.
   */
  void setMaskXPercentage(@FloatRange(from = 0F, to = 1F) float percentage);

  /**
   * Gets the percentage by which this {@link View} should mask itself along the x axis.
   *
   * @return a float between 0 and 1 where 0 is fully unmasked and 1 is fully masked.
   */
  @FloatRange(from = 0F, to = 1F)
  float getMaskXPercentage();

  /** Gets a {@link RectF} that this {@link View} is masking itself by. */
  @NonNull
  RectF getMaskRectF();

  /**
   * Sets an {@link OnMaskChangedListener}.
   *
   * @param listener a listener to receive callbacks for changes in the mask or null to clear the
   *     listener.
   */
  void setOnMaskChangedListener(@Nullable OnMaskChangedListener listener);
}

private void onMaskChanged() {
  if (getWidth() == 0) {
    return;
  }
  // Translate the percentage into an actual pixel value of how much of this view should be
  // masked away.
  float maskWidth = AnimationUtils.lerp(0f, getWidth() / 2F, 0f, 1f, maskXPercentage);
  maskRect.set(maskWidth, 0F, (getWidth() - maskWidth), getHeight());
  maskableDelegate.onMaskChanged(this, maskRect);
  if (onMaskChangedListener != null) {
    onMaskChangedListener.onMaskChanged(maskRect);
  }
}

private MaskableDelegate createMaskableDelegate() {
  if (VERSION.SDK_INT >= VERSION_CODES.TIRAMISU) {
    return new MaskableDelegateV33(this);
  } else if (VERSION.SDK_INT >= VERSION_CODES.LOLLIPOP_MR1) {
    return new MaskableDelegateV22(this);
  } else {
    return new MaskableDelegateV14();
  }
}