概述

在应用的开发过程中，经常需要设计复杂界面，此时涉及到多个相同或不同组件之间的嵌套。如果布局组件嵌套深度过深，或者嵌套组件数过多，会带来额外的开销。如果在布局的方式上进行优化，就可以有效的提升性能，减少时间开销。

RelativeContainer是一种采用相对布局的容器，支持容器内部的子元素设置相对位置关系，适用于处理界面复杂的场景，对多个子元素进行对齐和排列。子元素可以指定兄弟元素或父容器作为锚点，基于锚点进行相对位置布局。在使用锚点时，需注意子元素的相对位置关系，以避免出现错位或遮挡的情况。下图展示了一个 RelativeContainer的概念图，图中的虚线表示位置的依赖关系。

图1 相对布局示意图

子元素并不完全是上图中的依赖关系。比如，Item4可以以Item2为依赖锚点，也可以以RelativeContainer父容器为依赖锚点。

基本概念

• 参考边界：设置当前组件的哪个边界对齐到锚点。

• 锚点：通过锚点设置当前元素基于哪个元素确定位置。

• 对齐方式：通过对齐方式，设置当前元素是基于锚点的上中下对齐，还是基于锚点的左中右对齐。

• 链：将一系列组件以首尾相连的方式对齐，可以形成一条链。通过设置链的模式，可以指定链上元素的排列方式。

• 辅助线：辅助线是在容器内虚拟出的额外水平或垂直锚点，便于统一对齐至某个偏移位置。

• 屏障：屏障是指容器内一组指定组件在特定方向上的共同最远边界，例如，一组组件下方的屏障，是指这些组件底部边缘中最底部的那个边界。

设置依赖关系

设置参考边界

设置当前组件的哪个边界对齐到锚点。容器内子组件的参考边界区分水平方向和垂直方向。

• 在水平方向上，可以按照起始（left）、居中（middle）或尾端（right）的组件边界与锚点对齐。当设置三个边界时，仅起始（left）和居中（middle）的边界设置生效。

• 在垂直方向上，可以设置组件边界与锚点对齐，具体包括顶部（top）、居中（center）和底部（bottom）。当设置三个边界时，仅顶部（top）和居中（center）生效。

设置锚点

锚点设置涉及子元素相对于其父元素或兄弟元素的位置依赖关系。具体而言，子元素可以将其位置锚定到相对布局容器（RelativeContainer）、辅助线（guideline）、屏障（barrier）或其他子元素上。

为了准确定义锚点，RelativeContainer的子元素必须拥有唯一的组件标识（id），用于指定锚点信息。父元素RelativeContainer的标识默认为“__container__”，其他子元素的组件标识（id）则通过id属性设置。

说明

• 未设置组件标识（id）的组件虽可显示，但无法被其他组件引用为锚点。相对布局容器会为其拼接组件标识，但组件标识（id）的规律无法被应用感知。辅助线（guideline）与屏障（barrier）的组件标识（id）需确保唯一，避免与任何组件冲突。若有重复，遵循组件 > guideline > barrier 的优先级。
• 组件间设置锚点时应避免形成依赖循环（组件之间设置链除外），依赖循环将导致子组件缺乏定位基准，最终无法绘制。

• RelativeContainer父组件为锚点，__container__代表父容器的组件标识（id）。

  1. let alignRus: Record<string, Record<string, string | VerticalAlign | HorizontalAlign>> = {
  2. 'top': { 'anchor': '__container__', 'align': VerticalAlign.Top },
  3. 'left': { 'anchor': '__container__', 'align': HorizontalAlign.Start }
  4. }
  5. let alignRue: Record<string, Record<string, string | VerticalAlign | HorizontalAlign>> = {
  6. 'top': { 'anchor': '__container__', 'align': VerticalAlign.Top },
  7. 'right': { 'anchor': '__container__', 'align': HorizontalAlign.End }
  8. }
  9. let marginLeft: Record<string, number> = { 'left': 20 }
  10. let bwc: Record<string, number | string> = { 'width': 2, 'color': '#6699FF' }
  12. @Entry
  13. @Component
  14. struct ParentRefRelativeContainer {
  15. build() {
  16. RelativeContainer() {
  17. Row() {
  18. Text('row1')
  19. }
  20. .justifyContent(FlexAlign.Center)
  21. .width(100)
  22. .height(100)
  23. .backgroundColor('#a3cf62')
  24. .alignRules(alignRus)
  25. .id('row1')
  27. Row() {
  28. Text('row2')
  29. }
  30. .justifyContent(FlexAlign.Center)
  31. .width(100)
  32. .height(100)
  33. .backgroundColor('#00ae9d')
  34. .alignRules(alignRue)
  35. .id('row2')
  36. }.width(300).height(300)
  37. .margin(marginLeft)
  38. .border(bwc)
  39. }
  40. }

  RelativeContainerParentComponentId.ets

• 以兄弟元素为锚点。

  1. let alignRus001: Record<string, Record<string, string | VerticalAlign | HorizontalAlign>> = {
  2. 'top': { 'anchor': '__container__', 'align': VerticalAlign.Top },
  3. 'left': { 'anchor': '__container__', 'align': HorizontalAlign.Start }
  4. }
  5. let relConB: Record<string, Record<string, string | VerticalAlign | HorizontalAlign>> = {
  6. 'top': { 'anchor': 'row1', 'align': VerticalAlign.Bottom },
  7. 'left': { 'anchor': 'row1', 'align': HorizontalAlign.Start }
  8. }
  9. let marginLeft001: Record<string, number> = { 'left': 20 }
  10. let bwc001: Record<string, number | string> = { 'width': 2, 'color': '#6699FF' }
  12. @Entry
  13. @Component
  14. struct SiblingRefRelativeContainer {
  15. build() {
  16. RelativeContainer() {
  17. Row() {
  18. Text('row1')
  19. }
  20. .justifyContent(FlexAlign.Center)
  21. .width(100)
  22. .height(100)
  23. .backgroundColor('#00ae9d')
  24. .alignRules(alignRus001)
  25. .id('row1')
  27. Row() {
  28. Text('row2')
  29. }
  30. .justifyContent(FlexAlign.Center)
  31. .width(100)
  32. .height(100)
  33. .backgroundColor('#a3cf62')
  34. .alignRules(relConB)
  35. .id('row2')
  36. }.width(300).height(300)
  37. .margin(marginLeft001)
  38. .border(bwc001)
  39. }
  40. }

  RelativeContainerSiblingComponentId.ets

• 子组件锚点可以任意选择，但需注意不要相互依赖。

  1. @Entry
  2. @Component
  3. struct ChildRefRelativeContainer {
  4. build() {
  5. Row() {
  6. RelativeContainer() {
  7. Row() {
  8. Text('row1')
  9. }
  10. .justifyContent(FlexAlign.Center)
  11. .width(100)
  12. .height(100)
  13. .backgroundColor('#a3cf62')
  14. .alignRules({
  15. top: { anchor: '__container__', align: VerticalAlign.Top },
  16. left: { anchor: '__container__', align: HorizontalAlign.Start }
  17. })
  18. .id('row1')
  20. Row() {
  21. Text('row2')
  22. }
  23. .justifyContent(FlexAlign.Center)
  24. .width(100)
  25. .backgroundColor('#00ae9d')
  26. .alignRules({
  27. top: { anchor: '__container__', align: VerticalAlign.Top },
  28. right: { anchor: '__container__', align: HorizontalAlign.End },
  29. bottom: { anchor: 'row1', align: VerticalAlign.Center },
  30. })
  31. .id('row2')
  33. Row() {
  34. Text('row3')
  35. }
  36. .justifyContent(FlexAlign.Center)
  37. .height(100)
  38. .backgroundColor('#0a59f7')
  39. .alignRules({
  40. top: { anchor: 'row1', align: VerticalAlign.Bottom },
  41. left: { anchor: 'row1', align: HorizontalAlign.Start },
  42. right: { anchor: 'row2', align: HorizontalAlign.Start }
  43. })
  44. .id('row3')
  46. Row() {
  47. Text('row4')
  48. }.justifyContent(FlexAlign.Center)
  49. .backgroundColor('#2ca9e0')
  50. .alignRules({
  51. top: { anchor: 'row3', align: VerticalAlign.Bottom },
  52. left: { anchor: 'row1', align: HorizontalAlign.Center },
  53. right: { anchor: 'row2', align: HorizontalAlign.End },
  54. bottom: { anchor: '__container__', align: VerticalAlign.Bottom }
  55. })
  56. .id('row4')
  57. }
  58. .width(300).height(300)
  59. .margin({ left: 50 })
  60. .border({ width: 2, color: '#6699FF' })
  61. }
  62. .height('100%')
  63. }
  64. }

  RelativeContainerChildComponentId.ets

设置相对于锚点的对齐位置

设置了锚点之后，可以通过alignRules属性的align设置相对于锚点的对齐位置。

在水平方向上，对齐位置可以设置为HorizontalAlign.Start、HorizontalAlign.Center、HorizontalAlign.End。

在垂直方向上，对齐位置可以设置为VerticalAlign.Top、VerticalAlign.Center、VerticalAlign.Bottom。

子组件位置偏移

子组件经过相对位置对齐后，可能尚未达到目标位置。开发者可根据需要设置额外偏移（offset）。当使用offset调整位置的组件作为锚点时，对齐位置为设置offset之前的位置。从API Version 11开始，新增了Bias对象，建议API Version 11及以后的版本使用bias来设置额外偏移。使用bias的示例可以参考示例4（设置偏移）。

1. @Entry
2. @Component
3. struct ChildComponentOffsetExample {
4. build() {
5. Row() {
6. RelativeContainer() {
7. Row() {
8. Text('row1')
9. }
10. .justifyContent(FlexAlign.Center)
11. .width(100)
12. .height(100)
13. .backgroundColor('#a3cf62')
14. .alignRules({
15. top: { anchor: '__container__', align: VerticalAlign.Top },
16. left: { anchor: '__container__', align: HorizontalAlign.Start }
17. })
18. .id('row1')
20. Row() {
21. Text('row2')
22. }
23. .justifyContent(FlexAlign.Center)
24. .width(100)
25. .backgroundColor('#00ae9d')
26. .alignRules({
27. top: { anchor: '__container__', align: VerticalAlign.Top },
28. right: { anchor: '__container__', align: HorizontalAlign.End },
29. bottom: { anchor: 'row1', align: VerticalAlign.Center },
30. })
31. .offset({
32. x: -40,
33. y: -20
34. })
35. .id('row2')
37. Row() {
38. Text('row3')
39. }
40. .justifyContent(FlexAlign.Center)
41. .height(100)
42. .backgroundColor('#0a59f7')
43. .alignRules({
44. top: { anchor: 'row1', align: VerticalAlign.Bottom },
45. left: { anchor: 'row1', align: HorizontalAlign.End },
46. right: { anchor: 'row2', align: HorizontalAlign.Start }
47. })
48. .offset({
49. x: -10,
50. y: -20
51. })
52. .id('row3')
54. Row() {
55. Text('row4')
56. }
57. .justifyContent(FlexAlign.Center)
58. .backgroundColor('#2ca9e0')
59. .alignRules({
60. top: { anchor: 'row3', align: VerticalAlign.Bottom },
61. bottom: { anchor: '__container__', align: VerticalAlign.Bottom },
62. left: { anchor: '__container__', align: HorizontalAlign.Start },
63. right: { anchor: 'row1', align: HorizontalAlign.End }
64. })
65. .offset({
66. x: -10,
67. y: -30
68. })
69. .id('row4')
71. Row() {
72. Text('row5')
73. }
74. .justifyContent(FlexAlign.Center)
75. .backgroundColor('#30c9f7')
76. .alignRules({
77. top: { anchor: 'row3', align: VerticalAlign.Bottom },
78. bottom: { anchor: '__container__', align: VerticalAlign.Bottom },
79. left: { anchor: 'row2', align: HorizontalAlign.Start },
80. right: { anchor: 'row2', align: HorizontalAlign.End }
81. })
82. .offset({
83. x: 10,
84. y: 20
85. })
86. .id('row5')
88. Row() {
89. Text('row6')
90. }
91. .justifyContent(FlexAlign.Center)
92. .backgroundColor('#ff33ffb5')
93. .alignRules({
94. top: { anchor: 'row3', align: VerticalAlign.Bottom },
95. bottom: { anchor: 'row4', align: VerticalAlign.Bottom },
96. left: { anchor: 'row3', align: HorizontalAlign.Start },
97. right: { anchor: 'row3', align: HorizontalAlign.End }
98. })
99. .offset({
100. x: -15,
101. y: 10
102. })
103. .backgroundImagePosition(Alignment.Bottom)
104. .backgroundImageSize(ImageSize.Cover)
105. .id('row6')
106. }
107. .width(300).height(300)
108. .margin({ left: 50 })
109. .border({ width: 2, color: '#6699FF' })
110. }
111. .height('100%')
112. }
113. }

RelativeContainerChildComponentOffset.ets

多种组件的对齐布局

Row、Column、Flex、Stack等多种布局组件，可按照RelativeContainer组件规则进行对齐排布。

1. @Entry
2. @Component
3. struct RelativeContainerExample {
4. build() {
5. Row() {
7. RelativeContainer() {
8. Row()
9. .width(100)
10. .height(100)
11. .backgroundColor('#a3cf62')
12. .alignRules({
13. top: { anchor: '__container__', align: VerticalAlign.Top },
14. left: { anchor: '__container__', align: HorizontalAlign.Start }
15. })
16. .id('row1')
18. Column()
19. .width('50%')
20. .height(30)
21. .backgroundColor('#00ae9d')
22. .alignRules({
23. top: { anchor: '__container__', align: VerticalAlign.Top },
24. left: { anchor: '__container__', align: HorizontalAlign.Center }
25. })
26. .id('row2')
28. Flex({ direction: FlexDirection.Row }) {
29. Text('1').width('20%').height(50).backgroundColor('#0a59f7')
30. Text('2').width('20%').height(50).backgroundColor('#2ca9e0')
31. Text('3').width('20%').height(50).backgroundColor('#0a59f7')
32. Text('4').width('20%').height(50).backgroundColor('#2ca9e0')
33. }
34. .padding(10)
35. .backgroundColor('#30c9f7')
36. .alignRules({
37. top: { anchor: 'row2', align: VerticalAlign.Bottom },
38. left: { anchor: '__container__', align: HorizontalAlign.Start },
39. bottom: { anchor: '__container__', align: VerticalAlign.Center },
40. right: { anchor: 'row2', align: HorizontalAlign.Center }
41. })
42. .id('row3')
44. Stack({ alignContent: Alignment.Bottom }) {
45. Text('First child, show in bottom')
46. .width('90%')
47. .height('100%')
48. .backgroundColor('#a3cf62')
49. .align(Alignment.Top)
50. Text('Second child, show in top').width('70%').height('60%').backgroundColor('#00ae9d').align(Alignment.Top)
51. }
52. .margin({ top: 5 })
53. .alignRules({
54. top: { anchor: 'row3', align: VerticalAlign.Bottom },
55. left: { anchor: '__container__', align: HorizontalAlign.Start },
56. bottom: { anchor: '__container__', align: VerticalAlign.Bottom },
57. right: { anchor: 'row3', align: HorizontalAlign.End }
58. })
59. .id('row4')
61. }
62. .width(300).height(300)
63. .margin({ left: 50 })
64. .border({ width: 2, color: '#6699FF' })
65. }
66. .height('100%')
67. }
68. }

RelativeContainerDifferentComponentId.ets

以上内容均参考于相对布局 (RelativeContainer)-构建布局-组件布局-UI开发 (ArkTS声明式开发范式)-ArkUI（方舟UI框架）-应用框架 - 华为HarmonyOS开发者

实战演示