Constraintlayout

API 參考資料
androidx.constraintlayout.widget

透過相對定位的方式靈活調整小工具定位和大小。

這個資料表會列出 androidx.constraintlayout 群組中的所有構件。

構件	穩定版	候選版	Beta 版	Alpha 版
constraintlayout	2.1.4	-	-	2.2.0-alpha07
constraintlayout-compose	1.0.1	-	-	1.1.0-alpha07
constraintlayout-core	1.0.4	-	-	1.1.0-alpha07

宣告依附元件

如要在 ConstraintLayout 中新增依附元件，您必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

Groovy

dependencies {
    implementation "androidx.constraintlayout:constraintlayout:2.2.0-alpha07"
    // To use constraintlayout in compose
    implementation "androidx.constraintlayout:constraintlayout-compose:1.1.0-alpha07"
}

Kotlin

dependencies {
    implementation("androidx.constraintlayout:constraintlayout:2.2.0-alpha07")
    // To use constraintlayout in compose
    implementation("androidx.constraintlayout:constraintlayout-compose:1.1.0-alpha07")
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。建立新的問題之前，請先查看這個程式庫中的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 文件。

ConstraintLayout-compose 和 ConstraintLayout-Core 1.1

1.1.0-alpha07 版

2023 年 2 月 8 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.1.0-alpha07 和 androidx.constraintlayout:constraintlayout-core:1.1.0-alpha07。查看 1.1.0-alpha07 版的修訂項。

新功能

新增 API，以使用 DSL 在 Compose 中啟用格線輔助功能 (I1143b)

修正錯誤

修正了 Flow 的 Wrap.Chain 無法正確套用至指定 maxElement 參數的問題 (e1f2ed3)。
修正了在透過 MotionLayout(motionScene: MotionScene, progress: Float, transitionName: String) 變更 Transition 時，start ConstraintSet 無法更新的問題 (17ffff1)。
修正了在透過 ConstraintSet(extendConstraintSet: ConstraintSet, description: ConstraintSetScope.() -> Unit) 繼承限制時，ConstraintSet 無法反映部分變更的問題 (740804b)。

1.1.0-alpha06 版

2023 年 1 月 25 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.1.0-alpha06 和 androidx.constraintlayout:constraintlayout-core:1.1.0-alpha06。查看 1.1.0-alpha06 版的修訂項。

新功能

新增 Apis，以 JSON 表示法在 Compose 中啟用格線協助程式，這可將可組合項放置在 2D 格線中 (I968ad)。

API 變更

支援在 MotionLayout 中新增弧形向上和弧形向上模式，以及 Arc.Above 和 Arc.Below 方向的獨立弧形模式 (I184a9)
現在可以將基準錨定標記限制為頂端/底部錨定標記，反之亦然。(I54628)
MotionLayoutScope#motionProperties (包括衍生工具) 已重新命名為 MotionLayoutScope#customProperties。這與設定自訂屬性時一致。(Ib34c9)
現在可以在 ConstraintSet 和 MotionScene 中建立多個參照：val (box, text, button) = createRefsFor("box", "text","button")。使用 constrain(box, button, text) 將限制條件套用至多個元素。在 ConstrainScope 中，您現在可以使用 Dp.asDimension 以直覺化的方式設定固定維度：width = 10.dp.asDimension。(I021ec、Ia0960)
MotionScene() 和 Transition() 方法現在為非可組合函式。這些函式 (包括 ConstraintSet) 中的物件現在應能夠適當地相互比較。ConstraintLayout 中的 animateChanges = true 現在只能用於一個 ConstraintSet 參照，前提是其任何屬性在重組時已變更。(I7d22e)

修正錯誤

修正問題：協助程式發生變更時，ConstraintLayout 一律會觸發不必要的多餘重組。(Id83ad、b/222093277)
修正搭配 ConstraintLayout 和 MotionLayout 使用內建函式時的行為。(I487ae、b/220527863)
修正無法在內容變更時重新評估的問題。(Ibfe8a、b/219091179)

1.1.0-alpha05 版

2022 年 12 月 7 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.1.0-alpha05 和 androidx.constraintlayout:constraintlayout-core:1.1.0-alpha05。查看 1.1.0-alpha05 版的修訂項。

新功能

支援 DSL 中的自訂 KeyAttributes (b94e748)
ConstrainScope 中的途徑偏誤屬性 (32625d0)
支援鏈結中的自訂參數 (72a2e9e)
在 Compose 中為 MotionLayout 新增巨集基準測試 (36f43bc)
如要進一步瞭解先前在 Compose 版本中的變更內容，請參閱維基網頁

API 變更

翻轉 addConstraintSet 和 addTransition 參數 (152facc)

修正錯誤

修正水平鏈結 (ed5f56e)

1.1.0-alpha01 版

2022 年 5 月 20 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.1.0-alpha01。

請注意，MotionLayout API 處於實驗階段，必須選擇加入才能運作。

詳情請參閱 GitHub 上的撰寫 1.1.0-alpha01 的新功能一文。

2.2 版

2.2.0-alpha07 版

2023 年 2 月 8 日

發布了 androidx.constraintlayout:constraintlayout:2.2.0-alpha07。查看 2.2.0-alpha07 版的修訂項。

修正錯誤

修正 ConstraintLayout 網頁內容遺漏的問題 (I82e25)。

2.2.0-alpha05 版

2022 年 12 月 7 日

發布了 androidx.constraintlayout:constraintlayout:2.2.0-alpha05。查看 2.2.0-alpha05 版的修訂項。

如要進一步瞭解先前版本變更內容，請參閱 GitHub 維基網頁

修正錯誤

修正 View Carousel 中的外洩問題 (eb67b82)

2.2.0-alpha01 版

2022 年 5 月 20 日

發布了 androidx.constraintlayout:constraintlayout:2.2.0-alpha01。

包含新版 Grid 協助工具的預覽畫面。

詳情請參閱 GitHub 上的 2.2.0-alpha01 新功能一文。

ConstraintLayout-compose 1.0

ConstraintLayout-compose 1.0 在 Jetpack Compose 中提供 ConstraintLayout 功能。

1.0.1 版

2022 年 5 月 20 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.0.1。

請注意，MotionLayout API 處於實驗階段，必須選擇加入才能運作。

詳情請參閱 GitHub 上的撰寫 1.0.1 版的新功能一文

1.0.0 版

2022 年 1 月 13 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.0.0。

請注意，MotionLayout API 目前處於實驗階段，必須啟用才能運作。

詳情請參閱 GitHub 的 1.0 版新功能 (Compose) 一文。

1.0.0-rc02 版

2021 年 11 月 16 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.0.0-rc02。

詳情請參閱 GitHub 的 1.0 版新功能 (Compose) 一文。

1.0.0-rc01 版

2021 年 9 月 27 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.0.0-rc01。

這個版本為第二個 Beta 版。系統會將此版本視為功能完整的版本，可為 Compose 提供 ConstraintLayout 和 MotionLayout。

詳情請參閱 GitHub 的 1.0 版新功能 (Compose) 一文。

1.0.0-beta02 版

2021 年 7 月30 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.0.0-beta02。

這個版本為第二個 Beta 版。系統會將此版本視為功能完整的版本，可為 Compose 提供 ConstraintLayout 和 MotionLayout。

詳情請參閱 GitHub 的 1.0 版新功能 (Compose) 一文。

1.0.0-beta01 版

2021 年 7 月 22 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.0.0-beta01。

這個版本為第一個 Beta 版，系統會將此版本視為功能完整的版本，可為 Compose 提供 ConstraintLayout 和 MotionLayout。

詳情請參閱 GitHub 的 1.0 版新功能 (Compose) 一文。

1.0.0-alpha07 版

2021 年 5 月 18 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.0.0-alpha07。

更新為相容於 Compose 1.0.0-beta07 版。

1.0.0-alpha06 版

2021 年 5 月 4 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.0.0-alpha06。

Compose 最佳化：Constraintlayout 內嵌組件 (#193)
盡量減少在 Compose 中的重新評估 (#210)

1.0.0-alpha05 版

2021 年 3 月 15 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.0.0-alpha05。

包含最佳化引擎的修正項目 (b/182657720)
將 optimizationLevel 參數新增至 ConstraintLayout 組件

1.0.0-alpha04 版

2021 年 3 月 11 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.0.0-alpha04。

更新為採用最新 constraintlayout-core 引擎

1.0.0-alpha03 版

2021 年 2 月 24 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.0.0-alpha03。

Jetpack Compose beta01 版更新

1.0.0-alpha02 版

2021 年 2 月 10 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.0.0-alpha02。

Jetpack Compose alpha12 版更新

1.0.0-alpha01 版

2021 年 2 月 2 日

發布了 androidx.constraintlayout:constraintlayout-compose:1.0.0-alpha01。

程式庫的第一個版本，提供內嵌和外部 DSL 來表達限制。

2.1 版

ConstraintLayout 2.1.0 在 MotionLayout 中提供更豐富的功能和全新的輔助工具 (輪轉介面等)

2.1.4 版

2022 年 5 月 20 日

發布了 androidx.constraintlayout:constraintlayout:2.1.4。

詳情請參閱 GitHub 上的 2.1.4 版新功能一文。

2.1.3 版

2022 年 1 月 13 日

發布了 androidx.constraintlayout:constraintlayout:2.1.3。

詳情請參閱 GitHub 的 2.1 版新功能一文。

2.1.2 版

2021 年 11 月 16 日

發布了 androidx.constraintlayout:constraintlayout:2.1.2。

詳情請參閱 GitHub 的 2.1 版新功能一文。

2.1.1 版

2021 年 9 月 27 日

發布了 androidx.constraintlayout:constraintlayout:2.1.1。

這是 2.1.1 的最終版本。

詳情請參閱 GitHub 的 2.1 版新功能一文。

2.1.0 版

2021 年 7 月30 日

發布了 androidx.constraintlayout:constraintlayout:2.1.0。

這是 2.1.0 的最終版本。

詳情請參閱 GitHub 的 2.1 版新功能一文。

2.1.0-rc01 版

2021 年 7 月 22 日

發布了 androidx.constraintlayout:constraintlayout:2.1.0-rc01。

這是 2.1.0 版本的候選版本，針對上次的 Beta 版提供小幅改善和修正。詳情請參閱 GitHub 的 2.1 版新功能一文。

2.1.0-beta02 版

2021 年 5 月 4 日

發布了 androidx.constraintlayout:constraintlayout:2.1.0-beta02。

MotionLayout 中的幾項新功能：

OnSwipe 強化效果，包括 Spring (剛硬、抑制、集結等) 與永不完成
jumpToState 函式
在 ViewTransition downUp 模式中輕觸「向下」時，會播放至 100，輕觸「向上」則會還原為 0

修正多項問題，值得注意的有：

修正 MotionLayout 中垂直捲動的問題 (#173)
改善巢狀 MotionLayout 的效能 (#189)
在 MotionLayout 中運用 NestedScrollView 快速轉場 (#189)
在 MotionLayout 中移除 ConstraintSet (#189)
在 MotionLayout 中支援 downUp ViewTransitions (#190)
修正重複使用可繪項目時 ImageFilter 中的內容 (#192)
在 MotionLayout 新增 Spring 支援 (#199)
CircularFlow 效能改善 (#200)
修正衍生限制/限制覆寫 (#212)

2.1.0-beta01 版

2021 年 3 月 11 日

發布了 androidx.constraintlayout:constraintlayout:2.1.0-beta01。

ConstraintLayout

由於發生相容性問題，因此 android:layout_width 和 android:layout_height 變更回非選用項目。

MotionLayout

針對「轉場」支援以程式輔助方式插入及移除 onSWipe 和 onClick
實驗性支援透過畫面旋轉進行「轉場」
針對轉場支援持續時間引數
針對屬於布林值或參考資料的 customAttributes 提供更完善的支援

輔助工具

新增一種方式以透過動畫或跳躍直接前往輪轉介面的特定項目
全新 CircularFlow 輔助工具

如要瞭解這個版本的更多資訊，請參閱這裡和已關閉的錯誤。

2.1.0-alpha2 版

2020 年 12 月 17 日

發布了 androidx.constraintlayout:constraintlayout:2.1.0-alpha2。

這是第二個 Alpha 版，新增了幾項功能：

ConstraintLayout

android:layout_width 和 android:layout_height 現在為選用項目，預設行為是 wrap_content
新增 layout_constraintWidth 和 layout_constraintHeight 屬性，用於表示尺寸限制
支援使用負數邊界設定限制
支援頂端基準和底端基準限制
支援基準邊界限制
SharedValues 可讓您將外部值插入 ConstraintLayout 中

MotionLayout

支援過衝內插器 (預判、過衝)
強化版 MotionHelper 支援
將 ConstraintSet 的動畫式更新新增至 MotionLayout updateStateAnimate(id,cset,duration)；
共用以價值為準 ViewTransition
scheduleTransitonTo 可讓您安排某個轉場在目前轉場完成後執行。

輔助工具

輪轉介面現已支援無限 (圍繞) 模式
ReactiveGuide：SharedValue 變更時會自動安置自身位置的指南
MotionAction：將主要畫面格插入至正往指定方向移動的參照檢視畫面
MotionLabel - 使單行文字動畫化的檢視畫面

如要瞭解這個版本的更多資訊，請參閱這裡。

2.1.0-alpha1 版

2020 年 11 月 19 日

發布了 androidx.constraintlayout:constraintlayout:2.1.0-alpha1。

2.1 版的第一個 Alpha 版。開始支援下列項目：

輪轉介面動作輔助工具，用於建立自訂輪轉介面檢視畫面
MotionLayout 場景支援納入與限制覆寫
MotionLayout 針對旋轉功能新增更多支援 (輸入和輸出)
MotionLayout 新增 ViewTransfers，允許針對 constraintsets 的變化進行單一檢視畫面轉場

如要瞭解這個版本的更多資訊，請參閱這裡。

2.0 版

ConstraintLayout 2.0 針對版面配置新增功能 (虛擬版面配置等)，並針對簡化檢視畫面動畫提供新的類別 MotionLayout。

2.0.4 版

2020 年 10 月 29 日

發布了 androidx.constraintlayout:constraintlayout:2.0.4。

修正錯誤

這個版本修正了在執行階段移除子項檢視畫面時可能發生的 NPE。建議更新至這個版本。

如要查看已關閉的問題清單，請按這裡。

2.0.3 版

2020 年 10 月 27 日

發布了 androidx.constraintlayout:constraintlayout:2.0.3。

修正錯誤

這個版本修正了一些問題。建議更新至這個版本。

Windows 插邊處理
在某些情況中的尺寸比例處理
某些由右至左版面配置當機問題

如要查看已關閉的問題清單，請按這裡。

2.0.2 版

2020 年 10 月 6 日

發布了 androidx.constraintlayout:constraintlayout:2.0.2。

修正錯誤

這個版本可提高效能並修正了一些問題。建議更新至這個版本。

某些情況下，在 ConstraintLayout 中處理檢視 Gone 顯示設定的方式有誤
某些情況下，在 ConstraintLayout 中處理封裝鏈的方式有誤
針對「流程」虛擬版面配置輔助工具修正 API 15 上的加載例外
limitBoundsTo 在 MotionLayout 中損毀
某些情況下，MotionLayout 中的跳至結尾功能損毀 (鏈結轉場)

如要查看已關閉的問題清單，請按這裡。

2.0.1 版

2020 年 8 月 25 日

發布了 androidx.constraintlayout:constraintlayout:2.0.1。

此為小幅更新，啟用在 Android Studio 中使用 MotionEditor 的功能。

2.0.0 版

2020 年 8 月 21 日

發布了 androidx.constraintlayout:constraintlayout:2.0.0。

修正錯誤

如要查看已關閉的問題清單，請按這裡。

重要修正項目如下：

MotionLayout 轉場延遲和 TransitionListener 修正
ConstraintLayout 流程與障礙修正

2.0.0-rc1 版

2020 年 7 月 29 日

發布了 androidx.constraintlayout:constraintlayout:2.0.0-rc1。

修正錯誤

如要查看已關閉的問題清單，請按這裡。

重要修正項目如下：

修正流程
RecyclerView 修正 (建議更新到 recyclerview 1.2.0 alpha 5 以上版本)
MotionLayout TransitionListener 修正
MotionLayout 記憶體外洩修正

2.0.0-beta8 版

2020 年 7 月 7 日

發布了 androidx.constraintlayout:constraintlayout:2.0.0-beta8。

修正錯誤

如要查看已關閉的問題清單，請按這裡。

重要修正項目如下：

預留位置行為
資料層顯示設定
流程、障礙修正
TransitionListener 修正

2.0.0-beta7 版

2020 年 6 月 12 日

發布了 androidx.constraintlayout:constraintlayout:2.0.0-beta7。

修正錯誤

如要查看已關閉的問題清單，請按這裡。

重要修正項目如下：

MotionLayout 中的巢狀捲動檢視畫面問題
MotionLayout 轉場事件監聽器問題
MotionLayout 中的記憶體流失問題
RecyclerView 問題
群組顯示設定
邊框間距問題

2.0.0-beta6 版

2020 年 5 月 13 日

發布了 androidx.constraintlayout:constraintlayout:2.0.0-beta6。

修正錯誤

如要查看已關閉的問題清單，請按這裡。重要修正包括 MotionLayout 中的群組顯示設定處理和衍生限制問題。

2.0.0-beta5 版

2020 年 5 月 7 日

發布了 androidx.constraintlayout:constraintlayout:2.0.0-beta5。

修正錯誤

如要查看已關閉的問題清單，請按這裡

2.0.0-beta4 版

2019 年 12 月 16 日

發布了 androidx.constraintlayout:constraintlayout:2.0.0-beta4。

新功能

MotionLayout

轉場中的新屬性：

layoutDuringTransition：讓您設定 MotionLayout 如何回應子項在轉場期間的 requestLayouts 呼叫。可能的值為 {ignoreRequest, honorRequest}
pathMotionArc：元素移動時採用的路徑會使用弧形。可能的值為 {startVertical | startHorizontal | flip | none }

預設轉場現在可以省略起始和結束 ConstraintSets 而進行定義。如果沒有符合目前開始/結束狀態的其他現有轉場，系統就會採用預設轉場。

修正錯誤

如要查看已關閉的問題清單，請按這裡