约束布局与高级排版

// 伪代码：ConstraintLayout 的 onMeasure 核心流程
override fun onMeasure(widthSpec: Int, heightSpec: Int) {
    // 1. 将每个子 View 的约束信息转换为 ConstraintWidget 上的锚点连接
    for (child in children) {
        val widget = getWidget(child)           // 获取子 View 对应的 ConstraintWidget
        applyConstraints(widget, child.layoutParams) // 读取 LayoutParams，建立约束关系
    }
 
    // 2. 将所有 ConstraintWidget 的约束写入线性方程组
    linearSystem.reset()                        // 重置方程组（增量模式下可做部分重置）
    rootWidget.addToSolver(linearSystem)         // 递归地将根 Widget 及其子 Widget 的约束加入求解器
 
    // 3. 调用 Cassowary/Simplex 求解
    linearSystem.minimize()                      // 执行单纯形法迭代，求出所有变量的值
 
    // 4. 将求解结果回写到 ConstraintWidget 的坐标字段
    rootWidget.updateFromSolver(linearSystem)    // 每个 Widget 从求解器读取 left, top, width, height
 
    // 5. 根据 Widget 坐标设置最终测量尺寸
    setMeasuredDimension(
        resolveSize(rootWidget.width, widthSpec),  // 结合 MeasureSpec 确定最终宽
        resolveSize(rootWidget.height, heightSpec)  // 结合 MeasureSpec 确定最终高
    )
}

<!-- 经典列表项：头像 + 标题 + 副标题，全部在同一层 ConstraintLayout 中 -->
<androidx.constraintlayout.widget.ConstraintLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:padding="16dp">
 
    <!-- 头像：垂直居中于父容器，Start 贴父容器 Start -->
    <ImageView
        android:id="@+id/ivAvatar"
        android:layout_width="48dp"
        android:layout_height="48dp"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintBottom_toBottomOf="parent" />
    <!-- 
        水平方向：Start → parent.Start（贴左） 
        垂直方向：Top → parent.Top + Bottom → parent.Bottom（上下约束均存在 → 垂直居中）
    -->
 
    <!-- 标题：顶部对齐头像顶部，Start 在头像右侧 -->
    <TextView
        android:id="@+id/tvTitle"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:layout_marginStart="12dp"
        android:text="张三"
        app:layout_constraintStart_toEndOf="@id/ivAvatar"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toTopOf="@id/ivAvatar" />
    <!--
        水平方向：Start → ivAvatar.End（头像右侧，间距 12dp）
                  End → parent.End（撑满剩余空间，因为宽度是 0dp/match_constraint）
        垂直方向：Top → ivAvatar.Top（顶部对齐头像）
    -->
 
    <!-- 副标题：顶部紧贴标题底部，水平范围与标题一致 -->
    <TextView
        android:id="@+id/tvSubtitle"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:layout_marginTop="4dp"
        android:text="最近消息内容..."
        app:layout_constraintStart_toStartOf="@id/tvTitle"
        app:layout_constraintEnd_toEndOf="@id/tvTitle"
        app:layout_constraintTop_toBottomOf="@id/tvTitle" />
    <!--
        水平方向：Start → tvTitle.Start + End → tvTitle.End（与标题完全左右对齐）
        垂直方向：Top → tvTitle.Bottom（紧贴标题下方，间距 4dp）
    -->
 
</androidx.constraintlayout.widget.ConstraintLayout>

<!-- 四条 Parent 约束同时施加：水平两条 + 垂直两条 -->
<!-- 结果：控件精确地出现在 ConstraintLayout 的正中心 -->
<TextView
    android:id="@+id/tvCenter"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="正中央"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintBottom_toBottomOf="parent" />

<!-- 贴靠左上角，并留出 16dp 的安全边距 -->
<ImageView
    android:id="@+id/ivLogo"
    android:layout_width="48dp"
    android:layout_height="48dp"
    android:layout_marginStart="16dp"
    android:layout_marginTop="16dp"
    android:src="@drawable/ic_logo"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent" />
<!-- 仅有 Start 和 Top 约束，控件贴靠左上角 -->
<!-- marginStart=16dp 使其与左边界保持 16dp -->
<!-- marginTop=16dp 使其与上边界保持 16dp -->

<!-- 头像：贴靠父容器左边缘与顶部 -->
<ImageView
    android:id="@+id/ivAvatar"
    android:layout_width="40dp"
    android:layout_height="40dp"
    android:layout_marginStart="16dp"
    android:layout_marginTop="12dp"
    android:src="@drawable/avatar"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent" />
<!-- Start→parent 表示贴左，Top→parent 表示贴上 -->
 
<!-- 昵称：左边紧跟在头像右边，垂直方向与头像顶部对齐 -->
<TextView
    android:id="@+id/tvName"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_marginStart="12dp"
    android:text="用户昵称"
    app:layout_constraintStart_toEndOf="@id/ivAvatar"
    app:layout_constraintTop_toTopOf="@id/ivAvatar" />
<!-- Start→ivAvatar.End 表示"我在头像的右边" -->
<!-- Top→ivAvatar.Top 表示"我的顶部与头像的顶部对齐" -->
<!-- marginStart=12dp 是昵称与头像之间的水平间距 -->
 
<!-- 时间戳：贴靠父容器右边缘，垂直基线与昵称对齐 -->
<TextView
    android:id="@+id/tvTime"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_marginEnd="16dp"
    android:text="3分钟前"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintBaseline_toBaselineOf="@id/tvName" />
<!-- End→parent 表示"贴靠右边缘" -->
<!-- Baseline→tvName.Baseline 使两段文字的基线完美对齐 -->
<!-- 这比 Top 对齐更精确，因为不同字号的文字 Top 对齐会视觉不齐 -->

<!-- 在 A 和 B 之间水平居中放置 C -->
<View
    android:id="@+id/viewC"
    android:layout_width="60dp"
    android:layout_height="60dp"
    app:layout_constraintStart_toEndOf="@id/viewA"
    app:layout_constraintEnd_toStartOf="@id/viewB"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintBottom_toBottomOf="parent" />
<!-- Start→A.End + End→B.Start 在水平方向形成双向拉力 -->
<!-- 求解结果：C 被放置在 A 和 B 之间的正中央 -->

<!-- 场景：登录按钮在水平方向偏左 30% 处，垂直方向偏下 70% 处 -->
<Button
    android:id="@+id/btnLogin"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="登录"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintHorizontal_bias="0.3"
    app:layout_constraintVertical_bias="0.7" />
<!-- 四条 Parent 约束建立了双向拉力 -->
<!-- horizontal_bias=0.3：水平空闲空间的 30% 分配给左侧，70% 给右侧 -->
<!-- vertical_bias=0.7：垂直空闲空间的 70% 分配给上方，30% 给下方 -->
<!-- 最终效果：按钮出现在左下方区域 -->

// 获取控件的约束布局参数
val params = btnLogin.layoutParams as ConstraintLayout.LayoutParams
// 将水平偏移比例从当前值修改为 0.8（偏右）
params.horizontalBias = 0.8f
// 将垂直偏移比例修改为 0.2（偏上）
params.verticalBias = 0.2f
// 重新应用参数，触发布局刷新
btnLogin.layoutParams = params
// 调用 requestLayout() 其实在 setLayoutParams 内部已自动触发
// 但如果你直接修改 params 字段而不调用 setter，则需要手动 requestLayout()

<!-- 场景：商品标签 A（固定显示）→ 促销标签 B（可能隐藏）→ 价格 C -->
 
<!-- A：促销图标，固定在左侧 -->
<ImageView
    android:id="@+id/ivTag"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_marginStart="16dp"
    android:src="@drawable/ic_tag"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent" />
 
<!-- B：促销文案，可能被后台控制隐藏 -->
<TextView
    android:id="@+id/tvPromo"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_marginStart="8dp"
    android:text="限时折扣"
    android:visibility="gone"
    app:layout_constraintStart_toEndOf="@id/ivTag"
    app:layout_constraintBaseline_toBaselineOf="@id/ivTag" />
<!-- 正常情况下距 ivTag 右边 8dp -->
<!-- 当前 visibility="gone"，此控件被视为零尺寸点 -->
 
<!-- C：价格文字 -->
<TextView
    android:id="@+id/tvPrice"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_marginStart="8dp"
    android:text="¥99.00"
    app:layout_goneMarginStart="16dp"
    app:layout_constraintStart_toEndOf="@id/tvPromo"
    app:layout_constraintBaseline_toBaselineOf="@id/ivTag" />
<!-- tvPrice 的 Start 锚定到 tvPromo 的 End -->
<!-- 当 tvPromo 可见时：marginStart = 8dp 生效，正常间距 -->
<!-- 当 tvPromo GONE 时：goneMarginStart = 16dp 生效 -->
<!-- 这个 16dp 补偿了 tvPromo 消失后的空间，让间距看起来合理 -->

【状态 1：tvPromo 可见】
┌──────────────────────────────────────────┐
│  [ivTag]  ←8dp→  [限时折扣]  ←8dp→  [¥99] │
│                   tvPromo               │
└──────────────────────────────────────────┘
 
【状态 2：tvPromo GONE】
┌──────────────────────────────────────────┐
│  [ivTag]  ←——— 16dp(goneMargin) ———→  [¥99] │
│           tvPromo 缩为零宽点            │
└──────────────────────────────────────────┘

// 业务逻辑：根据后台接口判断是否显示促销标签
fun updatePromoVisibility(hasPromo: Boolean) {
    // 切换 tvPromo 的可见性
    binding.tvPromo.visibility = if (hasPromo) View.VISIBLE else View.GONE
    // 无需额外修改 tvPrice 的 margin！
    // ConstraintLayout 会自动检测 tvPromo 的 GONE 状态
    // 并将 tvPrice 的 marginStart 从 8dp 切换为 goneMarginStart 的 16dp
    // 这种自动化切换大大减少了手动布局调整的代码
}

<!-- ❌ 错误写法：在 ConstraintLayout 中使用 match_parent -->
<TextView
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="Hello" />
<!-- 
  问题：
  1. 缺少水平约束，控件位置由默认值(0,0)决定，与约束系统脱节
  2. match_parent 语义跳过了约束求解，margin/bias 可能失效
  3. Lint 会发出警告
-->
 
<!-- ✅ 正确写法：使用 0dp + 左右约束 -->
<TextView
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    android:text="Hello" />
<!--
  效果：
  1. 0dp 告诉系统"我的宽度由约束来决定"
  2. Start→parent.Start + End→parent.End 建立了完整的水平约束
  3. 求解器计算出宽度 = 父容器宽度 - startMargin - endMargin
  4. bias、margin、chain 等特性全部正常工作
-->

<!-- 场景：TextView 夹在两个按钮之间 -->
<Button
    android:id="@+id/btnLeft"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Left"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent" />
 
<TextView
    android:id="@+id/tvContent"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="这是一段可能非常非常非常长的文本内容..."
    android:ellipsize="end"
    android:maxLines="1"
    app:layout_constrainedWidth="true"
    app:layout_constraintStart_toEndOf="@id/btnLeft"
    app:layout_constraintEnd_toStartOf="@id/btnRight"
    app:layout_constraintTop_toTopOf="parent" />
<!-- 
  layout_constrainedWidth="true" 关键属性：
  - 当文本短时，宽度 = 文本自身宽度（wrap_content 正常行为）
  - 当文本长时，宽度 = 两个按钮之间的可用空间（约束上限生效）
  - 配合 ellipsize="end" 实现文本截断省略号效果
-->
 
<Button
    android:id="@+id/btnRight"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Right"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toTopOf="parent" />

<!-- 示例 1：spread 模式（默认） - 填满约束空间 -->
<View
    android:id="@+id/banner"
    android:layout_width="0dp"
    android:layout_height="200dp"
    android:background="#E3F2FD"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    android:layout_marginStart="16dp"
    android:layout_marginEnd="16dp" />
<!--
  宽度 = 父容器宽度 - 16dp(左margin) - 16dp(右margin)
  layout_constraintWidth_default 默认就是 spread，无需显式声明
  效果类似传统的 match_parent + marginHorizontal
-->
 
<!-- 示例 2：percent 模式 - 占父容器 80% 宽度 -->
<View
    android:id="@+id/card"
    android:layout_width="0dp"
    android:layout_height="120dp"
    android:background="#FFF3E0"
    app:layout_constraintWidth_default="percent"
    app:layout_constraintWidth_percent="0.8"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toBottomOf="@id/banner"
    android:layout_marginTop="16dp" />
<!--
  宽度 = 父容器宽度 × 0.8
  即使有 Start/End 约束到 parent，百分比优先于约束空间计算
  控件会居中显示（因为 bias 默认 0.5）
-->
 
<!-- 示例 3：wrap 模式 - 内容驱动但不超出约束 -->
<TextView
    android:id="@+id/label"
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    android:text="动态文本"
    app:layout_constraintWidth_default="wrap"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toBottomOf="@id/card"
    android:layout_marginTop="8dp" />
<!--
  当文本短时：宽度 = 文本宽度（wrap 行为）
  当文本超长时：宽度 = 父容器宽度（约束上限生效）
  等效于 wrap_content + constrainedWidth="true"
-->

<!-- 尺寸范围控制示例 -->
<TextView
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintWidth_min="100dp"
    app:layout_constraintWidth_max="300dp" />
<!--
  宽度由约束计算，但被钳制(clamp)在 [100dp, 300dp] 范围内
  - 若约束空间 < 100dp → 宽度 = 100dp（可能溢出）
  - 若约束空间在 100~300dp → 宽度 = 约束空间
  - 若约束空间 > 300dp → 宽度 = 300dp（居中由 bias 控制）
-->

<!-- 场景 1：视频播放器 - 宽度填满，高度按 16:9 自动计算 -->
<com.google.android.exoplayer2.ui.PlayerView
    android:id="@+id/playerView"
    android:layout_width="0dp"
    android:layout_height="0dp"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintDimensionRatio="H,16:9" />
<!--
  宽高都为 0dp，需要前缀指定被动维度
  "H,16:9" → H 是被动维度（被比例算出来的）
  → 先算宽度：0dp + Start/End 约束 = 填满父容器宽度
  → 再算高度：宽度 × (9/16)
  → 最终效果：宽度撑满屏幕，高度自动保持 16:9 比例
-->
 
<!-- 场景 2：圆形头像 - 1:1 正方形 + 圆角裁剪 -->
<de.hdodenhof.circleimageview.CircleImageView
    android:id="@+id/avatar"
    android:layout_width="0dp"
    android:layout_height="0dp"
    app:layout_constraintWidth_percent="0.2"
    app:layout_constraintDimensionRatio="1:1"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toBottomOf="@id/playerView"
    android:layout_marginTop="16dp" />
<!--
  宽度 = 父容器的 20%（通过 percent 控制）
  高度 = 宽度 × 1 = 与宽度相同（正方形）
  只有宽度设了 percent，高度的 0dp 由 ratio 驱动
  无需前缀，因为系统能自动推断：宽度有 percent 约束，高度靠 ratio
-->
 
<!-- 场景 3：固定高度，宽度按比例计算 -->
<ImageView
    android:id="@+id/thumbnail"
    android:layout_width="0dp"
    android:layout_height="80dp"
    android:scaleType="centerCrop"
    app:layout_constraintDimensionRatio="4:3"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toBottomOf="@id/avatar"
    android:layout_marginTop="16dp" />
<!--
  高度已知 = 80dp
  宽度 = 0dp，由 ratio 计算：80 × (4/3) ≈ 106.7dp
  "4:3" 中 4 是宽的比例，3 是高的比例
  无需前缀，因为只有宽度是 0dp，系统知道宽度是被动维度
-->

<!-- 综合实战：视频卡片布局 -->
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:padding="12dp">
 
    <!-- 视频封面：宽度填满，高度按 16:9 自动计算 -->
    <ImageView
        android:id="@+id/ivCover"
        android:layout_width="0dp"
        android:layout_height="0dp"
        android:scaleType="centerCrop"
        android:background="#ECEFF1"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintDimensionRatio="H,16:9" />
    <!--
      宽高都为 0dp，前缀 "H" 指定高度为被动维度
      宽度由 Start+End 约束 → 填满父容器（减去 padding）
      高度 = 宽度 × 9/16 → 自动保持 16:9
    -->
 
    <!-- 头像：占父容器 10% 宽度，正方形 -->
    <ImageView
        android:id="@+id/ivAvatar"
        android:layout_width="0dp"
        android:layout_height="0dp"
        android:background="#C8E6C9"
        app:layout_constraintWidth_percent="0.1"
        app:layout_constraintDimensionRatio="1:1"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toBottomOf="@id/ivCover"
        android:layout_marginTop="8dp" />
    <!--
      宽度 = 父容器 × 10%
      高度 = 宽度 × 1 = 正方形
    -->
 
    <!-- 标题：占据头像右侧到父容器右边的空间 -->
    <TextView
        android:id="@+id/tvTitle"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:text="ConstraintLayout 尺寸控制完全指南"
        android:textSize="14sp"
        android:textStyle="bold"
        android:maxLines="2"
        android:ellipsize="end"
        app:layout_constraintStart_toEndOf="@id/ivAvatar"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toTopOf="@id/ivAvatar"
        android:layout_marginStart="8dp" />
    <!--
      宽度 0dp + Start(头像右侧) + End(父容器右边) → 自动填满剩余空间
      高度 wrap_content → 根据文本行数自适应
    -->
 
    <!-- 副标题：跟随标题下方 -->
    <TextView
        android:id="@+id/tvSubtitle"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:text="2.4万次观看 · 3天前"
        android:textSize="12sp"
        android:textColor="#757575"
        app:layout_constraintStart_toStartOf="@id/tvTitle"
        app:layout_constraintEnd_toEndOf="@id/tvTitle"
        app:layout_constraintTop_toBottomOf="@id/tvTitle"
        android:layout_marginTop="2dp" />
    <!--
      Start/End 对齐标题 → 宽度与标题一致
      0dp 在此确保文字区域不会溢出
    -->
 
</androidx.constraintlayout.widget.ConstraintLayout>

<!-- 控件 A：链头（Chain Head） -->
<!-- start 锚定到 parent，end 锚定到 B 的 start，形成前向约束 -->
<TextView
    android:id="@+id/tvA"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="A"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toStartOf="@id/tvB" />
 
<!-- 控件 B：链中间节点 -->
<!-- start 反向锚定到 A 的 end，end 前向锚定到 C 的 start -->
<TextView
    android:id="@+id/tvB"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="B"
    app:layout_constraintStart_toEndOf="@id/tvA"
    app:layout_constraintEnd_toStartOf="@id/tvC" />
 
<!-- 控件 C：链尾 -->
<!-- start 反向锚定到 B 的 end，end 锚定到 parent，闭合整条链 -->
<TextView
    android:id="@+id/tvC"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="C"
    app:layout_constraintStart_toEndOf="@id/tvB"
    app:layout_constraintEnd_toEndOf="parent" />

<!-- 在链头 tvA 上声明 chainStyle 为 spread -->
<!-- 该属性控制整条链的分布模式 -->
<TextView
    android:id="@+id/tvA"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="A"
    app:layout_constraintHorizontal_chainStyle="spread"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toStartOf="@id/tvB" />

<!-- 在链头声明 spread_inside -->
<!-- 首尾控件紧贴 parent 边缘，中间均匀分布 -->
<TextView
    android:id="@+id/tvA"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="A"
    app:layout_constraintHorizontal_chainStyle="spread_inside"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toStartOf="@id/tvB" />
 
<!-- tvB：中间节点，与两侧等距 -->
<TextView
    android:id="@+id/tvB"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="B"
    app:layout_constraintStart_toEndOf="@id/tvA"
    app:layout_constraintEnd_toStartOf="@id/tvC" />
 
<!-- tvC：链尾，紧贴 parent 右边缘 -->
<TextView
    android:id="@+id/tvC"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="C"
    app:layout_constraintStart_toEndOf="@id/tvB"
    app:layout_constraintEnd_toEndOf="parent" />

<!-- 链头设置 packed 模式，并通过 bias 控制整体偏移 -->
<TextView
    android:id="@+id/tvA"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="A"
    app:layout_constraintHorizontal_chainStyle="packed"
    app:layout_constraintHorizontal_bias="0.3"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toStartOf="@id/tvB" />
 
<!-- tvB：紧跟 tvA，无额外间距 -->
<TextView
    android:id="@+id/tvB"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="B"
    app:layout_constraintStart_toEndOf="@id/tvA"
    app:layout_constraintEnd_toStartOf="@id/tvC" />
 
<!-- tvC：紧跟 tvB，整个 ABC 组作为整体偏左 30% -->
<TextView
    android:id="@+id/tvC"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="C"
    app:layout_constraintStart_toEndOf="@id/tvB"
    app:layout_constraintEnd_toEndOf="parent" />

<!-- 左栏：固定 80dp 宽度 -->
<!-- 作为链头，默认 spread 模式 -->
<View
    android:id="@+id/left"
    android:layout_width="80dp"
    android:layout_height="0dp"
    android:background="#C8E6C9"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toStartOf="@id/center" />
 
<!-- 中栏：0dp 触发 match_constraint -->
<!-- weight=1 表示独占全部剩余水平空间 -->
<View
    android:id="@+id/center"
    android:layout_width="0dp"
    android:layout_height="0dp"
    android:background="#BBDEFB"
    app:layout_constraintHorizontal_weight="1"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintStart_toEndOf="@id/left"
    app:layout_constraintEnd_toStartOf="@id/right" />
 
<!-- 右栏：固定 80dp 宽度 -->
<!-- 链尾，end 锚定 parent 闭合链 -->
<View
    android:id="@+id/right"
    android:layout_width="80dp"
    android:layout_height="0dp"
    android:background="#FFE0B2"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintStart_toEndOf="@id/center"
    app:layout_constraintEnd_toEndOf="parent" />

<!-- 三个按钮等宽排列：每个 weight=1，宽度均为 0dp -->
<!-- 按钮 A：链头 -->
<Button
    android:id="@+id/btnA"
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    android:text="取消"
    app:layout_constraintHorizontal_weight="1"
    app:layout_constraintHorizontal_chainStyle="spread"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toStartOf="@id/btnB" />
 
<!-- 按钮 B：中间节点 -->
<Button
    android:id="@+id/btnB"
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    android:text="稍后"
    app:layout_constraintHorizontal_weight="1"
    app:layout_constraintStart_toEndOf="@id/btnA"
    app:layout_constraintEnd_toStartOf="@id/btnC" />
 
<!-- 按钮 C：链尾 -->
<Button
    android:id="@+id/btnC"
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    android:text="确认"
    app:layout_constraintHorizontal_weight="2"
    app:layout_constraintStart_toEndOf="@id/btnB"
    app:layout_constraintEnd_toEndOf="parent" />

<!-- 2x2 九宫格示例（简化为 4 格） -->
<!-- 第一行水平链：A <-> B -->
<!-- 第一列垂直链：A <-> C -->
<!-- A 同时属于行链和列链 -->
<View
    android:id="@+id/cellA"
    android:layout_width="0dp"
    android:layout_height="0dp"
    app:layout_constraintHorizontal_weight="1"
    app:layout_constraintVertical_weight="1"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toStartOf="@id/cellB"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintBottom_toTopOf="@id/cellC" />
 
<!-- B：第一行右侧，第二列顶部 -->
<View
    android:id="@+id/cellB"
    android:layout_width="0dp"
    android:layout_height="0dp"
    app:layout_constraintHorizontal_weight="1"
    app:layout_constraintVertical_weight="1"
    app:layout_constraintStart_toEndOf="@id/cellA"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintBottom_toTopOf="@id/cellD" />
 
<!-- C：第二行左侧，第一列底部 -->
<View
    android:id="@+id/cellC"
    android:layout_width="0dp"
    android:layout_height="0dp"
    app:layout_constraintHorizontal_weight="1"
    app:layout_constraintVertical_weight="1"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toStartOf="@id/cellD"
    app:layout_constraintTop_toBottomOf="@id/cellA"
    app:layout_constraintBottom_toBottomOf="parent" />
 
<!-- D：第二行右侧，第二列底部 -->
<View
    android:id="@+id/cellD"
    android:layout_width="0dp"
    android:layout_height="0dp"
    app:layout_constraintHorizontal_weight="1"
    app:layout_constraintVertical_weight="1"
    app:layout_constraintStart_toEndOf="@id/cellC"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toBottomOf="@id/cellB"
    app:layout_constraintBottom_toBottomOf="parent" />

<!-- 水平引导线：位于父布局顶部 30% 处 -->
<!-- orientation="horizontal" 表示这是一条水平线（上下分割） -->
<!-- 水平线拥有 top/bottom 锚点，其他控件可以约束到它的上方或下方 -->
<androidx.constraintlayout.widget.Guideline
    android:id="@+id/guideline_horizontal"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:orientation="horizontal"
    app:layout_constraintGuide_percent="0.3" />
 
<!-- 垂直引导线：距离左侧固定 120dp -->
<!-- orientation="vertical" 表示这是一条垂直线（左右分割） -->
<!-- 垂直线拥有 start/end 锚点，其他控件可以约束到它的左侧或右侧 -->
<androidx.constraintlayout.widget.Guideline
    android:id="@+id/guideline_vertical"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:orientation="vertical"
    app:layout_constraintGuide_begin="120dp" />
 
<!-- 表单标签：右侧紧贴垂直引导线 -->
<!-- 标签的 end 约束到 Guideline，形成"标签右对齐到 120dp 处"的效果 -->
<TextView
    android:id="@+id/label_name"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="姓名："
    app:layout_constraintEnd_toStartOf="@id/guideline_vertical"
    app:layout_constraintTop_toTopOf="parent" />
 
<!-- 输入框：左侧紧贴垂直引导线 -->
<!-- 输入框的 start 约束到 Guideline，形成"输入区从 120dp 处开始"的效果 -->
<EditText
    android:id="@+id/input_name"
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    app:layout_constraintStart_toEndOf="@id/guideline_vertical"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toTopOf="parent" />

// 获取 Guideline 引用
val guideline = findViewById<Guideline>(R.id.guideline_vertical)
 
// 获取 Guideline 的 LayoutParams，它是 ConstraintLayout.LayoutParams 类型
val params = guideline.layoutParams as ConstraintLayout.LayoutParams
 
// 方式一：设置百分比位置为 40%
// guidePercent 字段直接对应 XML 中的 layout_constraintGuide_percent
params.guidePercent = 0.4f
 
// 方式二：设置距离起始边 200px（注意这里是 px 不是 dp）
// 实际使用中建议用 TypedValue.applyDimension() 转换 dp 到 px
params.guideBegin = 200
 
// 将修改后的 params 回写，触发重新布局
guideline.layoutParams = params

<!-- 标签 1：姓名 -->
<TextView
    android:id="@+id/label_name"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="姓名"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent" />
 
<!-- 标签 2：电子邮箱地址（可能比"姓名"宽得多） -->
<TextView
    android:id="@+id/label_email"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="电子邮箱地址"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toBottomOf="@id/label_name" />
 
<!-- Barrier：监视两个标签的 end 边缘，取最远值 -->
<!-- barrierDirection="end" 表示 Barrier 位于被引用控件的右侧（RTL 下为左侧） -->
<!-- constraint_referenced_ids 用逗号分隔列出所有被监视控件的 id（不带 @+id/ 前缀） -->
<androidx.constraintlayout.widget.Barrier
    android:id="@+id/barrier_label_end"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:barrierDirection="end"
    app:constraint_referenced_ids="label_name,label_email" />
 
<!-- 输入框 1：start 约束到 Barrier -->
<!-- 无论"姓名"和"电子邮箱地址"谁更宽，输入框都从最宽标签的右侧开始 -->
<EditText
    android:id="@+id/input_name"
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    android:layout_marginStart="8dp"
    app:layout_constraintStart_toEndOf="@id/barrier_label_end"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toTopOf="@id/label_name" />
 
<!-- 输入框 2：同样约束到 Barrier，保证与输入框 1 左对齐 -->
<EditText
    android:id="@+id/input_email"
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    android:layout_marginStart="8dp"
    app:layout_constraintStart_toEndOf="@id/barrier_label_end"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toTopOf="@id/label_email" />

<!-- barrierAllowsGoneWidgets="false" 表示忽略 GONE 控件的边界 -->
<!-- 这在某些动态显隐场景中非常有用：当某个标签被隐藏时，Barrier 不应该被它"拉"过去 -->
<androidx.constraintlayout.widget.Barrier
    android:id="@+id/barrier"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:barrierDirection="end"
    app:barrierAllowsGoneWidgets="false"
    app:constraint_referenced_ids="label_name,label_email" />

// 获取 Barrier 引用
val barrier = findViewById<Barrier>(R.id.barrier_label_end)
 
// 动态修改被引用的控件 id 列表
// referencedIds 是一个 IntArray，接收 View 的资源 id
// 例如运行时新增了一个标签 label_phone，将其也纳入 Barrier 监视
barrier.referencedIds = intArrayOf(
    R.id.label_name,        // 原有：姓名标签
    R.id.label_email,       // 原有：邮箱标签
    R.id.label_phone        // 新增：电话标签
)
 
// 修改后无需手动调用 requestLayout()
// Barrier 内部会在 referencedIds setter 中自动触发父布局的重新测量

<!-- 内容区域的控件 -->
<TextView android:id="@+id/tv_title" ... />
<TextView android:id="@+id/tv_subtitle" ... />
<ImageView android:id="@+id/iv_cover" ... />
<Button android:id="@+id/btn_action" ... />
 
<!-- Group：将上述四个控件编为一组 -->
<!-- constraint_referenced_ids 列出所有需要批量控制的控件 id -->
<!-- 设置 Group 的 visibility 等于同时设置这四个控件的 visibility -->
<androidx.constraintlayout.widget.Group
    android:id="@+id/group_content"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:visibility="visible"
    app:constraint_referenced_ids="tv_title,tv_subtitle,iv_cover,btn_action" />
 
<!-- 加载指示器：当 Group 隐藏时显示 -->
<ProgressBar
    android:id="@+id/progress_loading"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:visibility="gone"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintBottom_toBottomOf="parent" />

// 获取 Group 和 ProgressBar 的引用
val groupContent = findViewById<Group>(R.id.group_content)
val progressLoading = findViewById<ProgressBar>(R.id.progress_loading)
 
// 模拟加载开始：隐藏内容组，显示加载指示器
fun showLoading() {
    // 设置 Group 为 GONE，内部会遍历所有 referenced ids 并逐一设为 GONE
    groupContent.visibility = View.GONE
    // 显示加载指示器
    progressLoading.visibility = View.VISIBLE
}
 
// 模拟加载完成：显示内容组，隐藏加载指示器
fun showContent() {
    // 设置 Group 为 VISIBLE，内部会遍历所有 referenced ids 并逐一设为 VISIBLE
    groupContent.visibility = View.VISIBLE
    // 隐藏加载指示器
    progressLoading.visibility = View.GONE
}

// 获取 Group 引用
val group = findViewById<Group>(R.id.group_content)
 
// 动态添加新的控件到 Group 的管理列表中
// 注意：referencedIds 是整体替换，不是追加
group.referencedIds = intArrayOf(
    R.id.tv_title,      // 保留原有
    R.id.tv_subtitle,   // 保留原有
    R.id.iv_cover,      // 保留原有
    R.id.btn_action,    // 保留原有
    R.id.tv_footer      // 新增：页脚文本
)
// 设置后立即生效：Group 当前的 visibility 会被应用到 tv_footer 上

<!-- 在布局右上角预留一个 Placeholder -->
<!-- Placeholder 自身会按照这些约束确定位置 -->
<!-- 稍后被"吸引"过来的 View 将占据这个位置 -->
<androidx.constraintlayout.widget.Placeholder
    android:id="@+id/placeholder_feature"
    android:layout_width="80dp"
    android:layout_height="80dp"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toTopOf="parent"
    android:layout_marginEnd="16dp"
    android:layout_marginTop="16dp" />
 
<!-- 一个图标按钮，初始位于左下角 -->
<ImageButton
    android:id="@+id/btn_star"
    android:layout_width="48dp"
    android:layout_height="48dp"
    android:src="@drawable/ic_star"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintBottom_toBottomOf="parent"
    android:layout_marginStart="16dp"
    android:layout_marginBottom="16dp" />

// 获取 Placeholder 引用
val placeholder = findViewById<Placeholder>(R.id.placeholder_feature)
 
// 将 btn_star "吸引"到 Placeholder 的位置
// 调用后 btn_star 会从左下角"移动"到右上角（Placeholder 所在位置）
// 注意：这里只是立即改变布局参数，如果需要动画效果需配合 TransitionManager
placeholder.setContentId(R.id.btn_star)
 
// 如果需要动画过渡效果，可以在 setContentId 之前调用：
// TransitionManager.beginDelayedTransition(constraintLayout)
// 这样 btn_star 会平滑地从左下角动画移到右上角

// 获取父布局和 Placeholder 引用
val constraintLayout = findViewById<ConstraintLayout>(R.id.root)
val placeholder = findViewById<Placeholder>(R.id.placeholder_feature)
 
// 先告诉 TransitionManager "我要开始变化了，请录制当前状态"
// beginDelayedTransition 会在下一帧自动计算差异并执行动画
TransitionManager.beginDelayedTransition(constraintLayout)
 
// 切换 Placeholder 的内容
// TransitionManager 会检测到 btn_star 的位置变化，自动生成平移动画
placeholder.setContentId(R.id.btn_star)

// 创建一个空的 ConstraintSet 实例
val set = ConstraintSet()
 
// 从已经渲染好的 ConstraintLayout 中克隆所有约束信息
// 这会遍历 constraintLayout 的所有子 View，读取它们的 LayoutParams
// 并将约束数据复制到 set 内部的 SparseArray<Constraint> 中
set.clone(constraintLayout)
 
// 现在 set 就是当前布局的一份"快照"
// 对 set 的修改不会立即影响界面，直到你调用 applyTo()

// 从一个 XML 布局资源文件中克隆约束
// 框架会内部 inflate 这个 XML，读取其中的约束信息，然后丢弃 View 树
// 因此这个 XML 中的控件不需要设置 text、src 等显示属性
// 只需要保证 ID 与当前布局中的控件一一对应
val expandedSet = ConstraintSet()
expandedSet.clone(context, R.layout.activity_main_expanded)
 
// 同理，克隆"折叠态"的约束
val collapsedSet = ConstraintSet()
collapsedSet.clone(context, R.layout.activity_main_collapsed)

val set = ConstraintSet()
 
// 先克隆当前布局作为基础（避免从零开始配置每一个控件）
set.clone(constraintLayout)
 
// 然后修改特定控件的约束
// connect() 的四个参数：源控件ID、源锚点、目标控件ID、目标锚点
// 这里将 btnSubmit 的 START 边连接到 parent 的 START 边
set.connect(
    R.id.btnSubmit,              // 要修改约束的控件 ID
    ConstraintSet.START,         // 源控件的锚点（左边缘）
    ConstraintSet.PARENT_ID,     // 目标控件（parent）
    ConstraintSet.START,         // 目标锚点
    16.dp                        // 间距（margin），单位为像素
)
 
// 设置控件的宽度为 match_constraint（0dp）
set.constrainWidth(R.id.btnSubmit, ConstraintSet.MATCH_CONSTRAINT)
 
// 设置控件可见性
set.setVisibility(R.id.btnSubmit, View.VISIBLE)
 
// 设置水平偏移比例（Bias）
set.setHorizontalBias(R.id.btnSubmit, 0.3f)

// ========== 最简单的用法：一行代码实现自动过渡 ==========
 
// 第一步：通知 TransitionManager 开始监听布局变化
// 传入目标 ViewGroup（这里是 ConstraintLayout）
// 框架会立即捕获所有子 View 的当前状态（Before Snapshot）
TransitionManager.beginDelayedTransition(constraintLayout)
 
// 第二步：应用新的约束集合
// applyTo() 会修改 LayoutParams 并触发 requestLayout()
// 但由于上一步已经设置了延迟过渡监听
// 框架会在新布局计算完成后自动捕获 After Snapshot
// 然后对比差异，生成并执行平滑动画
expandedSet.applyTo(constraintLayout)
 
// 就这样！不需要手动创建任何 Animator
// 框架会自动为位置、尺寸、可见性等变化创建动画

// ========== 自定义过渡效果示例 ==========
 
// 创建一个 TransitionSet，内部并行执行多种过渡
val transition = TransitionSet().apply {
    // 设置为并行执行（所有动画同时开始）
    ordering = TransitionSet.ORDERING_TOGETHER
 
    // 添加 ChangeBounds：处理位置和尺寸变化
    addTransition(ChangeBounds().apply {
        // 设置动画时长为 300ms
        duration = 300L
        // 使用 FastOutSlowIn 插值器（Material Design 标准曲线）
        interpolator = FastOutSlowInInterpolator()
    })
 
    // 添加 Fade：处理可见性变化
    addTransition(Fade().apply {
        duration = 200L
    })
 
    // 添加 ChangeTransform：处理旋转、缩放变化
    addTransition(ChangeTransform().apply {
        duration = 300L
    })
}
 
// 使用自定义 Transition 开始延迟过渡
TransitionManager.beginDelayedTransition(constraintLayout, transition)
 
// 应用新约束
targetSet.applyTo(constraintLayout)

val transition = ChangeBounds().apply {
    duration = 400L
 
    // 方式一：白名单模式 —— 只对指定控件生效
    // 只有 btnSubmit 和 tvTitle 会有过渡动画，其余控件瞬间切换
    addTarget(R.id.btnSubmit)
    addTarget(R.id.tvTitle)
 
    // 方式二：黑名单模式 —— 排除指定控件
    // 除了 ivBackground 以外的所有控件都会有过渡动画
    // excludeTarget(R.id.ivBackground, true)
 
    // 还可以按 View 类型过滤
    // 比如排除所有 ImageView，只让非图片控件做动画
    // excludeTarget(ImageView::class.java, true)
}

class CardActivity : AppCompatActivity() {
 
    // 定义两个 ConstraintSet 分别代表折叠态和展开态
    private val collapsedSet = ConstraintSet()
    private val expandedSet = ConstraintSet()
 
    // 用一个布尔值跟踪当前状态
    private var isExpanded = false
 
    // 持有根布局引用
    private lateinit var rootLayout: ConstraintLayout
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 加载默认布局（折叠态）
        setContentView(R.layout.activity_card_collapsed)
 
        // 获取根布局引用
        rootLayout = findViewById(R.id.rootLayout)
 
        // 从当前已渲染的布局中克隆折叠态约束
        // 此时布局已经完成 inflate，所有约束都已就绪
        collapsedSet.clone(rootLayout)
 
        // 从另一个 XML 资源中克隆展开态约束
        // 该 XML 文件中的控件 ID 必须与当前布局一一对应
        // 但约束关系、尺寸、margin 等可以完全不同
        expandedSet.clone(this, R.layout.activity_card_expanded)
 
        // 设置切换按钮的点击事件
        findViewById<Button>(R.id.btnToggle).setOnClickListener {
            toggleCardState()
        }
    }
 
    private fun toggleCardState() {
        // 翻转状态标志
        isExpanded = !isExpanded
 
        // 构建自定义过渡动画
        val transition = TransitionSet().apply {
            ordering = TransitionSet.ORDERING_TOGETHER
            // ChangeBounds 处理控件的移动和大小变化
            addTransition(ChangeBounds().apply {
                duration = 350L
                interpolator = FastOutSlowInInterpolator()
            })
            // Fade 处理内容区域的显示/隐藏
            addTransition(Fade().apply {
                duration = 250L
                // 只对详情文本和额外按钮生效
                addTarget(R.id.tvDetails)
                addTarget(R.id.btnExtra)
            })
        }
 
        // 关键一步：在修改布局之前通知 TransitionManager
        TransitionManager.beginDelayedTransition(rootLayout, transition)
 
        // 根据当前状态应用对应的约束集合
        if (isExpanded) {
            expandedSet.applyTo(rootLayout)
        } else {
            collapsedSet.applyTo(rootLayout)
        }
    }
}

<!-- res/xml/scene_card_expand.xml -->
<!-- MotionScene 是整个动画描述的根元素 -->
<MotionScene xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
 
    <!-- Transition 定义一个完整的过渡 -->
    <!-- constraintSetStart：起始状态的 ConstraintSet ID -->
    <!-- constraintSetEnd：目标状态的 ConstraintSet ID -->
    <!-- duration：动画总时长（毫秒） -->
    <Transition
        app:constraintSetStart="@id/collapsed"
        app:constraintSetEnd="@id/expanded"
        app:duration="500">
 
        <!-- OnClick 触发器：点击 btnToggle 时执行过渡 -->
        <!-- clickAction="toggle" 表示点击时在 start/end 之间来回切换 -->
        <OnClick
            app:targetId="@id/btnToggle"
            app:clickAction="toggle" />
 
        <!-- KeyFrameSet 在这里定义，稍后详细讲解 -->
        <KeyFrameSet>
            <!-- 关键帧定义... -->
        </KeyFrameSet>
 
    </Transition>
 
    <!-- 起始状态：折叠态 -->
    <ConstraintSet android:id="@+id/collapsed">
        <Constraint android:id="@id/ivAvatar"
            android:layout_width="48dp"
            android:layout_height="48dp"
            app:layout_constraintStart_toStartOf="parent"
            app:layout_constraintTop_toTopOf="parent"
            android:layout_marginStart="16dp"
            android:layout_marginTop="16dp" />
        <!-- 其他控件的约束... -->
    </ConstraintSet>
 
    <!-- 目标状态：展开态 -->
    <ConstraintSet android:id="@+id/expanded">
        <Constraint android:id="@id/ivAvatar"
            android:layout_width="120dp"
            android:layout_height="120dp"
            app:layout_constraintStart_toStartOf="parent"
            app:layout_constraintEnd_toEndOf="parent"
            app:layout_constraintTop_toTopOf="parent"
            android:layout_marginTop="32dp" />
        <!-- 其他控件的约束... -->
    </ConstraintSet>
 
</MotionScene>

<!-- res/layout/activity_card.xml -->
<!-- 将根布局声明为 MotionLayout（ConstraintLayout 的子类） -->
<androidx.constraintlayout.motion.widget.MotionLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/motionLayout"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:layoutDescription="@xml/scene_card_expand">
    <!-- layoutDescription 指向 MotionScene 文件 -->
    <!-- 这是 MotionLayout 与普通 ConstraintLayout 唯一的区别 -->
 
    <!-- 子控件正常声明，ID 必须与 MotionScene 中的 Constraint ID 匹配 -->
    <ImageView android:id="@+id/ivAvatar" ... />
    <TextView android:id="@+id/tvName" ... />
    <Button android:id="@+id/btnToggle" ... />
 
</androidx.constraintlayout.motion.widget.MotionLayout>

<KeyFrameSet>
    <!-- KeyPosition：在动画进度 50% 时，控制 ivAvatar 的位置 -->
    <!-- framePosition：时间轴位置，0-100 对应动画的 0%-100% -->
    <!-- motionTarget：作用于哪个控件 -->
    <!-- keyPositionType：坐标系类型 -->
    <!--   parentRelative = 相对于父容器的坐标（0,0 在父容器左上角） -->
    <!--   deltaRelative  = 相对于起止两点差值的坐标 -->
    <!--   pathRelative   = 相对于起止直线路径的坐标 -->
    <!-- percentX / percentY：在选定坐标系下的坐标值 -->
    <KeyPosition
        app:motionTarget="@id/ivAvatar"
        app:framePosition="50"
        app:keyPositionType="parentRelative"
        app:percentX="0.8"
        app:percentY="0.2" />
    <!-- 
        解读：当动画播放到 50% 时，ivAvatar 应该位于
        父容器宽度 80%、高度 20% 的位置。
        框架会自动将 0%→50%→100% 三个位置点用平滑曲线连接。
    -->
</KeyFrameSet>

<KeyFrameSet>
    <!-- 在动画 30% 位置，让 ivAvatar 旋转 -15 度并放大到 1.3 倍 -->
    <KeyAttribute
        app:motionTarget="@id/ivAvatar"
        app:framePosition="30"
        android:rotation="-15"
        android:scaleX="1.3"
        android:scaleY="1.3" />
 
    <!-- 在动画 60% 位置，让 ivAvatar 半透明 -->
    <KeyAttribute
        app:motionTarget="@id/ivAvatar"
        app:framePosition="60"
        android:alpha="0.5" />
 
    <!-- 在动画 80% 位置，恢复为不透明且无旋转 -->
    <!-- 到 100%（end 状态）时会使用 ConstraintSet end 中定义的值 -->
    <KeyAttribute
        app:motionTarget="@id/ivAvatar"
        app:framePosition="80"
        android:alpha="1.0"
        android:rotation="0" />
</KeyFrameSet>

<KeyFrameSet>
    <!-- KeyCycle：让 ivAvatar 在移动过程中产生正弦波式的上下振荡 -->
    <!-- wavePeriod：振荡的完整周期数（在 framePosition 点附近） -->
    <!-- waveOffset：振荡的基准偏移值 -->
    <!-- waveShape：波形类型 sin/cos/sawtooth/square/bounce/reverseSawtooth -->
    <KeyCycle
        app:motionTarget="@id/ivAvatar"
        app:framePosition="50"
        android:translationY="20dp"
        app:wavePeriod="3"
        app:waveShape="sin" />
    <!--
        解读：在动画 50% 附近，ivAvatar 的 translationY
        会以 20dp 为振幅、3 个完整周期的正弦波振荡。
        视觉效果就像控件一边移动一边上下"弹跳"。
    -->
</KeyFrameSet>

// 获取 MotionLayout 引用
val motionLayout = findViewById<MotionLayout>(R.id.motionLayout)
 
// 手动设置动画进度（0.0f = start 状态，1.0f = end 状态）
// 这在与 Slider、ScrollView 联动时非常有用
motionLayout.progress = 0.5f  // 直接跳到 50% 位置
 
// 手动触发从 start 到 end 的过渡动画
motionLayout.transitionToEnd()
 
// 手动触发从 end 到 start 的回退动画
motionLayout.transitionToStart()
 
// 监听过渡动画的各个阶段
motionLayout.setTransitionListener(object : MotionLayout.TransitionListener {
    // 过渡动画开始时回调
    override fun onTransitionStarted(layout: MotionLayout, startId: Int, endId: Int) {
        // startId 和 endId 是 ConstraintSet 的资源 ID
        Log.d("Motion", "动画开始：从 $startId 到 $endId")
    }
 
    // 过渡进度变化时回调（每帧都会调用）
    // progress 范围 0.0f ~ 1.0f
    override fun onTransitionChange(layout: MotionLayout, startId: Int, endId: Int, progress: Float) {
        // 可以在这里联动其他 UI 元素
        // 比如根据 progress 同步更新一个进度条或颜色渐变
        toolbar.alpha = progress  // 让 toolbar 的透明度与动画进度同步
    }
 
    // 过渡动画结束时回调
    override fun onTransitionCompleted(layout: MotionLayout, currentId: Int) {
        // currentId 是动画结束后的 ConstraintSet ID
        Log.d("Motion", "动画完成，当前状态：$currentId")
    }
 
    // 过渡动画触发状态变化时回调
    override fun onTransitionTrigger(layout: MotionLayout, triggerId: Int, positive: Boolean, progress: Float) {
        // 用于处理 KeyTrigger 触发的事件
    }
})

<!-- 在 MotionScene 的 Transition 中添加 OnSwipe 触发器 -->
<Transition
    app:constraintSetStart="@id/collapsed"
    app:constraintSetEnd="@id/expanded"
    app:duration="300">
 
    <!-- OnSwipe：通过滑动手势驱动动画 -->
    <!-- touchAnchorId：手势追踪的控件（手指在这个控件上滑动） -->
    <!-- touchAnchorSide：从控件的哪个边缘开始追踪 -->
    <!-- dragDirection：滑动方向（dragUp = 向上滑动） -->
    <OnSwipe
        app:touchAnchorId="@id/cardContent"
        app:touchAnchorSide="top"
        app:dragDirection="dragUp" />
</Transition>

// RelativeLayout 嵌套测量次数示意
// 层级 depth = d，每个 RelativeLayout 都做 2 次 measure pass
 
// depth=1: 子 View 被测量 2^1 = 2 次
// depth=2: 子 View 被测量 2^2 = 4 次
// depth=3: 子 View 被测量 2^3 = 8 次
// ...
// depth=d: 子 View 被测量 2^d 次

// ==================== RelativeLayout → ConstraintLayout 属性映射 ====================
 
// --- 相对于父容器 (Parent) 的定位 ---
 
// RelativeLayout: android:layout_alignParentStart="true"
// ConstraintLayout: 将 View 的 start 边约束到父容器的 start 边
// app:layout_constraintStart_toStartOf="parent"
 
// RelativeLayout: android:layout_alignParentEnd="true"
// ConstraintLayout: 将 View 的 end 边约束到父容器的 end 边
// app:layout_constraintEnd_toEndOf="parent"
 
// RelativeLayout: android:layout_alignParentTop="true"
// ConstraintLayout: 将 View 的 top 边约束到父容器的 top 边
// app:layout_constraintTop_toTopOf="parent"
 
// RelativeLayout: android:layout_alignParentBottom="true"
// ConstraintLayout: 将 View 的 bottom 边约束到父容器的 bottom 边
// app:layout_constraintBottom_toBottomOf="parent"
 
// RelativeLayout: android:layout_centerInParent="true"
// ConstraintLayout: 四边都约束到 parent → 自动居中
// app:layout_constraintStart_toStartOf="parent"
// app:layout_constraintEnd_toEndOf="parent"
// app:layout_constraintTop_toTopOf="parent"
// app:layout_constraintBottom_toBottomOf="parent"
 
// RelativeLayout: android:layout_centerHorizontal="true"
// ConstraintLayout: 水平方向两边约束到 parent
// app:layout_constraintStart_toStartOf="parent"
// app:layout_constraintEnd_toEndOf="parent"
 
// RelativeLayout: android:layout_centerVertical="true"
// ConstraintLayout: 垂直方向两边约束到 parent
// app:layout_constraintTop_toTopOf="parent"
// app:layout_constraintBottom_toBottomOf="parent"
 
 
// --- 相对于同级控件 (Sibling) 的定位 ---
 
// RelativeLayout: android:layout_toEndOf="@id/viewA"
// ConstraintLayout: 当前 View 的 start 边 → viewA 的 end 边
// app:layout_constraintStart_toEndOf="@id/viewA"
 
// RelativeLayout: android:layout_toStartOf="@id/viewA"
// ConstraintLayout: 当前 View 的 end 边 → viewA 的 start 边
// app:layout_constraintEnd_toStartOf="@id/viewA"
 
// RelativeLayout: android:layout_below="@id/viewA"
// ConstraintLayout: 当前 View 的 top 边 → viewA 的 bottom 边
// app:layout_constraintTop_toBottomOf="@id/viewA"
 
// RelativeLayout: android:layout_above="@id/viewA"
// ConstraintLayout: 当前 View 的 bottom 边 → viewA 的 top 边
// app:layout_constraintBottom_toTopOf="@id/viewA"
 
 
// --- 对齐 (Alignment) ---
 
// RelativeLayout: android:layout_alignStart="@id/viewA"
// ConstraintLayout: start 对 start 对齐
// app:layout_constraintStart_toStartOf="@id/viewA"
 
// RelativeLayout: android:layout_alignEnd="@id/viewA"
// ConstraintLayout: end 对 end 对齐
// app:layout_constraintEnd_toEndOf="@id/viewA"
 
// RelativeLayout: android:layout_alignTop="@id/viewA"
// ConstraintLayout: top 对 top 对齐
// app:layout_constraintTop_toTopOf="@id/viewA"
 
// RelativeLayout: android:layout_alignBottom="@id/viewA"
// ConstraintLayout: bottom 对 bottom 对齐
// app:layout_constraintBottom_toBottomOf="@id/viewA"
 
// RelativeLayout: android:layout_alignBaseline="@id/viewA"
// ConstraintLayout: 文字基线对齐
// app:layout_constraintBaseline_toBaselineOf="@id/viewA"

<?xml version="1.0" encoding="utf-8"?>
<!-- 整个表单只需要一个 ConstraintLayout 作为根容器 -->
<!-- 所有控件都是它的直接子 View，没有任何嵌套 -->
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/formRoot"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:padding="16dp">
 
    <!-- ======================== 辅助定位元素 ======================== -->
 
    <!-- 垂直引导线：将表单分为"标签列"和"输入列" -->
    <!-- 位于父容器宽度 28% 处，所有标签右对齐于此线，所有输入框左对齐于此线 -->
    <androidx.constraintlayout.widget.Guideline
        android:id="@+id/guidelineLabelEnd"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:orientation="vertical"
        app:layout_constraintGuide_percent="0.28" />
 
    <!-- 屏障：位于所有输入框的底部之下，用于动态定位提交按钮 -->
    <!-- 无论哪一行最长/最高，屏障都会自动取最大 bottom 值 -->
    <androidx.constraintlayout.widget.Barrier
        android:id="@+id/barrierFormBottom"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        app:barrierDirection="bottom"
        app:constraint_referenced_ids="inputName,inputEmail,inputPhone,inputBio" />
 
    <!-- ======================== 第 1 行：用户名 ======================== -->
 
    <!-- 用户名标签：右边缘对齐到 Guideline -->
    <TextView
        android:id="@+id/labelName"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:text="用户名"
        android:textSize="14sp"
        android:gravity="end"
        android:paddingEnd="12dp"
        app:layout_constraintEnd_toStartOf="@id/guidelineLabelEnd"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="@id/inputName"
        app:layout_constraintBottom_toBottomOf="@id/inputName" />
    <!-- 标签在垂直方向上与对应输入框的 top/bottom 对齐 → 自动垂直居中 -->
 
    <!-- 用户名输入框：左边缘从 Guideline 开始，宽度填满剩余空间(0dp) -->
    <EditText
        android:id="@+id/inputName"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:hint="请输入用户名"
        android:inputType="textPersonName"
        android:maxLines="1"
        app:layout_constraintStart_toEndOf="@id/guidelineLabelEnd"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toTopOf="parent" />
    <!-- 第一行顶部直接约束到 parent 顶部 -->
 
    <!-- 用户名错误提示：初始隐藏(gone)，通过 goneMarginTop 保留间距 -->
    <TextView
        android:id="@+id/errorName"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:text="用户名不能为空"
        android:textColor="#D32F2F"
        android:textSize="12sp"
        android:visibility="gone"
        app:layout_constraintStart_toEndOf="@id/guidelineLabelEnd"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toBottomOf="@id/inputName" />
    <!-- 错误提示 gone 时不占空间，下一行通过 goneMarginTop 适配 -->
 
    <!-- ======================== 第 2 行：邮箱 ======================== -->
 
    <!-- 邮箱标签 -->
    <TextView
        android:id="@+id/labelEmail"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:text="邮箱"
        android:textSize="14sp"
        android:gravity="end"
        android:paddingEnd="12dp"
        app:layout_constraintEnd_toStartOf="@id/guidelineLabelEnd"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="@id/inputEmail"
        app:layout_constraintBottom_toBottomOf="@id/inputEmail" />
 
    <!-- 邮箱输入框 -->
    <!-- 顶部约束到 errorName 的 bottom，但 errorName 为 gone 时 -->
    <!-- goneMarginTop=8dp 确保与 inputName 仍保持合理间距 -->
    <EditText
        android:id="@+id/inputEmail"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:hint="请输入邮箱地址"
        android:inputType="textEmailAddress"
        android:maxLines="1"
        android:layout_marginTop="8dp"
        app:layout_goneMarginTop="8dp"
        app:layout_constraintStart_toEndOf="@id/guidelineLabelEnd"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toBottomOf="@id/errorName" />
 
    <!-- ======================== 第 3 行：手机号 ======================== -->
 
    <TextView
        android:id="@+id/labelPhone"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:text="手机号"
        android:textSize="14sp"
        android:gravity="end"
        android:paddingEnd="12dp"
        app:layout_constraintEnd_toStartOf="@id/guidelineLabelEnd"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="@id/inputPhone"
        app:layout_constraintBottom_toBottomOf="@id/inputPhone" />
 
    <EditText
        android:id="@+id/inputPhone"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:hint="请输入手机号码"
        android:inputType="phone"
        android:maxLines="1"
        android:layout_marginTop="8dp"
        app:layout_constraintStart_toEndOf="@id/guidelineLabelEnd"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toBottomOf="@id/inputEmail" />
 
    <!-- ======================== 第 4 行：个人简介（多行） ======================== -->
 
    <TextView
        android:id="@+id/labelBio"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:text="简介"
        android:textSize="14sp"
        android:gravity="end"
        android:paddingEnd="12dp"
        app:layout_constraintEnd_toStartOf="@id/guidelineLabelEnd"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="@id/inputBio" />
    <!-- 多行输入时标签只与 inputBio 的 top 对齐，不做垂直居中 -->
 
    <EditText
        android:id="@+id/inputBio"
        android:layout_width="0dp"
        android:layout_height="0dp"
        android:hint="介绍一下自己..."
        android:inputType="textMultiLine"
        android:gravity="top|start"
        android:minHeight="100dp"
        android:layout_marginTop="8dp"
        app:layout_constraintHeight_min="100dp"
        app:layout_constraintHeight_max="200dp"
        app:layout_constraintStart_toEndOf="@id/guidelineLabelEnd"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toBottomOf="@id/inputPhone" />
    <!-- 高度使用 0dp + min/max 约束，允许内容自适应但有上下限 -->
 
    <!-- ======================== 提交按钮 ======================== -->
 
    <!-- 按钮顶部约束到 Barrier（所有输入框最底部），无论哪行最高都不会重叠 -->
    <Button
        android:id="@+id/btnSubmit"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:text="提交"
        android:layout_marginTop="24dp"
        app:layout_constraintStart_toEndOf="@id/guidelineLabelEnd"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toBottomOf="@id/barrierFormBottom" />
 
</androidx.constraintlayout.widget.ConstraintLayout>