MigLayout的使用简记

发布时间：2021-06-22 06:39
最后更新：2021-06-22 06:39
所属分类：
JVM Java

MigLayout是一款用于Swing和SWT、JavaFx的老牌布局管理器。虽然MigLayout已经出现了很长时间了，但是它在进行UI布局的时候，使用方法比较简单，布局说明非常清晰，代码量也不高，是使用Java开发GUI应用时比较推荐的一个布局管理器。

MigLayout是一个采用表格方式布局排列的布局管理器，也可以认为它采用的是Grid形式布局，这个布局的特性与CSS 3中的Flex布局的特性相近。在设计MigLayout的布局的时候，可以首先在设计稿上勾画横纵的表格，明确各个组件占用空间的关系，然后再根据MigLayout提供的布局约束描述命令对组件容器进行布局约束定义。

要在项目中使用MigLayout，需要根据当前项目所使用的GUI技术来选择使用不同的包。

例如使用Maven进行项目构建，可以选择以下依赖项。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<!--项目使用Swing-->
<dependency>
    <groupId>com.miglayout</groupId>
    <artifactId>miglayout-swing</artifactId>
    <version>11.0</version>
</dependency>
<!--项目使用JavaFx-->
<dependency>
    <groupId>com.miglayout</groupId>
    <artifactId>miglayout-javafx</artifactId>
    <version>11.0</version>
</dependency>
<!--项目使用SWT-->
<dependency>
    <groupId>com.miglayout</groupId>
    <artifactId>miglayout-swt</artifactId>
    <version>11.0</version>
</dependency>

对应的，如果使用Gradle进行项目构建，只需要将以上依赖定义中的GAV坐标提取出来即可。

布局参数

定义布局就必须使用尺寸和单位，MigLayout设计了以下这些尺寸单位供布局定义使用。

  • ""，空字符串作为单位时，MigLayout将使用平台默认的单位和像素来计量。
  • px，使用屏幕的像素计量，例如10px。
  • %，使用相对于容器的百分比尺寸，例如50%表示在中间。
  • lp，使用平台计算得到的逻辑像素，例如10lp。
  • pt，点，一般为$\frac{1}{72} inch$，例如10pt。
  • mm，毫米，这个单位会受到屏幕DPI的影响，例如10mm。
  • cm，厘米，这个单位会受到屏幕DPI的影响，例如10cm。
  • in，英尺，这个单位会收到屏幕DPI的影响，例如10in。
  • sp，相对屏幕尺寸的百分比，会根据屏幕的像素数进行计算。这个单位在使用的时候是书写在数字前面的，例如sp 70。
  • al，视觉边界对齐。取值0到1，0al表示左对齐，0.5al表示居中，1al则表示右对齐。
  • null，空值，表示值的缺失与不设定，可缩写为n。

在设定布局参数的时候，除了可以使用数字与上面这些单位进行搭配以外，还可以使用以下这些关键字来声明一些固定的尺寸，这些尺寸将会由MigLayout自动完成计算。

  • related，声明两个组件或者行列的尺寸是相关的，可以简写为rel或者r。
  • unrelated，声明两个组件或者行列的尺寸是不相关的，可以简写为unrel或者u。
  • paragraph，使用自动确定的段间距，可以简写为para或者p。
  • indented，使用自动确定的缩进，可以简写为ind或者i。
  • minimum，使用行列中出现的最大的最小尺寸值，可以简写为min。
  • preferred，使用行列中出现的最大的期望尺寸值，可以简写为pref或者p。
  • maximum，使用行列中出现的最大的最大尺寸值，可以简写为max。

布局管理器的创建

MigLayout有两种创建布局管理器实例的方法，一种是使用无参构造函数，一种是使用声明默认整体布局的有参构造函数。MigLayout的有参构造函数主要有以下几个。

  • MigLayout(LC)，使用LC实例声明MigLayout的布局约束。
  • MigLayout(LC, AC)，使用LC实例声明MigLayout的布局约束，AC实例声明列布局约束。
  • MigLayout(LC, AC, AC)，使用LC实例声明MigLayout的布局约束，第一个AC实例声明列布局约束，第二个AC实例声明行布局约束。
  • MigLayout(String)，使用字符串描述MigLayout的布局约束。
  • MigLayout(String, String)，使用第一个字符串描述MigLayout的布局约束，第二个字符串描述列布局约束。
  • MigLayout(String, String, String)，使用第一个字符串描述MigLayout的布局约束，第二个字符串描述列布局约束，第三个字符串描述行布局约束。

从以上列表可以看出，MigLayout的构造函数实际上是分为三类的，分别描述整体布局约束、列布局约束和行布局约束。不过虽然MigLayout支持使用LC和AC两个类来使用强类型约束的形式声明布局约束，但是在大部分情况下，还是推荐优先使用字符串来声明布局约束，因为字符串虽然类型约束很弱，但是描述性和可读性都很强，所需要书写的代码也比较少。

其实LC和AC这两个类十分好记，LC是Layout Constraint（布局约束）的缩写，AC是Axis Constraint（轴向约束）的缩写。在MigLayout中还有一个CC类，它是Component Constraint（组件约束）的缩写。

整体布局约束

整体布局约束影响的是整个容器的布局，如果使用无参构造函数实例化MigLayout，将会直接使用在一行内顺序排布的布局方式，而容器中组件的布局也完全由组件自己声明的布局来决定。整体布局中可以使用以下文字描述来对布局约束进行定义。

在所有的字符串描述中，多个布局约束描述命令之间使用,隔开，例如wrap 3,fillx。而使用LC类的时候，则只需要选择最终能够返回LC实例的方法即可，例如new LC().wrapAfter(3).fillX()。

不仅整体布局约束中的约束描述命令是使用,隔开的，轴向布局约束和组件布局约束中的约束描述命令都是使用,隔开的。书写时只选择需要的布局约束进行声明即可。
约束描述命令 设定布局功能
wrap n 设定自动换行策略，n表示在第几列之后进行换行。
wrap 相当于wrap 0，会使容器内的组件按照轴向布局约束设置排列。
gap x y 设定单元格之间的间隙。
gapx x 设定单元格之间横向的间隙。
gapy y 设定单元格之间纵向的间隙。
nogrid 设定布局管理器不使用基于Grid的布局。
novisualpadding 设定不使用可见留白。
fill 组合fillx和filly的功能。
fillx 设定布局管理器总是尝试获取最大的横向空间。
filly 设定布局管理器总是尝试获取最大的纵向空间。
insets all 同时设定布局四周的留白空间，可以简写为ins。
insets top left bottom right 逐一设定布局四周的留白空间。
flowy 设置布局管理器沿纵向排列组件。
alignx x 设置组件在父组件中的横向对齐方式，可以缩写为ax。
aligny y 设置组件在父组件中的纵向对齐方式，可以缩写为ay。
align x y 组合设置alignx和aligny，可以缩写为al。
lefttoright 设定从左向右布局，可以缩写为ltr。
righttoleft 设定从右向左布局，可以缩写为rtl。
toptobottom 设定从上向下布局，可以缩写为ttb。
bottomtotop 设定从下向上布局，可以缩写为btt。
hidemode n 设置组件不可见时的处理方式。
nocache 如果组件的大小与容器的边界关联，那么必须使用此项关闭Panel的缓存。
width BoundSize 同时设定布局的宽度，可以缩写为w，参数使用BoundSize描述。
height BoundSize 同时设定布局的高度，可以缩写为h，参数使用BoundSize描述。
wmax n 设定布局的最大宽度。
wmin n 设定布局的最小宽度。
hmax n 设定布局的最大高度。
hmin n 设定布局的最小高度。

组件不可见的处理方式

命令hidemode可以接受以下这几个值作为参数。

可取值 布局处理方式
0 默认值，所有不可见的组件依旧会像它们可见时一样占据空间。
1 所有不可见的组件的尺寸将被设置为0, 0，但保留其所在单元格周围的间隙。
2 所有不可见的组件的尺寸将被设置为0, 0，并且其所在单元格周围的间隙也会被清零。
3 所有不可见的组件不会参与布局，并且不会占据单元格。

对齐命令的参数

命令align、alignx和aligny三个命令所接受的参数值主要是以下这几个。

参数值 缩写 含义
top t 顶部对齐
left l 左对齐
bottom b 底部对齐
right r 右对齐
leading lead 头部对齐
trailing trail 尾部对齐
baseline base 基线对齐

BoundSize描述

BoundSize是一组用来描述布局尺寸的参数组合，其中由三个值组成：最小尺寸、期望尺寸和最大尺寸。这是因为在布局尺寸在发生变化的时候，我们通常都需要使用这三个值来对布局和组件的变化进行限定。所以在基本上所有需要使用具体尺寸值的位置，都是使用BoundSize来声明的。BoundSize使用最小值:期望值:最大值的格式来声明，例如30lp:50lp:80lp。除了可以使用具体数值以外，BoundSize还可以使用null、rel等需要MigLayout自行计算决定的关键字参数。

但是对于BoundSize来说，经常会有以下常用的设置技巧存在，这些也都是对于日常布局的需要而存在的。

  • 仅设置单个值，例如10。这表示仅设置期望值，相当于null:10:null。
  • 设置两个值，例如10:20。这表示设置最小值和期望值，相当于10:20:null。
  • 使用!，例如20!。这表示最小值、期望值和最大值都使用相同的设置，相当于20:20:20。

如果需要BoundSize在声明Gap时让Gap能够尽可能的占据所有剩余的空间，可以在BoundSize上附加push关键字，例如gap 10!:push或者gap 5:10:20:push。

轴向布局约束

轴向布局约束是用来定义容器内部每行单元格的的默认布局属性的。轴向布局约束采用[]来定义一行内每个单元格的布局属性，两个[]之间的表达式定义党员个之间的Gap的属性，所以轴向布局约束的格式就是[constraint,constraint]gap size[constraint,constraint]。例如[10!]10[10:20]就定义了一行只有两个单元格的布局，这个布局第一个单元格宽度为10，第二个单元格的宽度是20，两个单元格之间的间距是10。其中Gap Size可以使用所有BoundSize表达式来描述。

如果不需要显式定义间距，直接使用MigLayout的默认间距，那么相邻的][就可以被|代替。例如[10][10][10]就可以简写为[10|10|10]。

轴向布局约束也有自己的一套约束描述命令，这些约束命令主要是使用在单元格的约束定义上。

约束描述命令 设定布局功能
sizegroup name 给指定的单元格设定尺寸组名称，拥有相同尺寸组名称的单元格将共享相同的尺寸设置。可以简写为sg
fill 设定单元格中的组件的属性设置为grow，使组件将尽可能的占据所有可用横向空间，不会影响单元格空间。
nogrid 不使用单元格布局，而是使用流式布局代替。
grow n 设定尺寸增长的权重，默认权重值是100，已经设定的权重之间，尺寸增长都按照权重的比例进行。
growprio n 设定尺寸的增长优先级，可以在尺寸发生变化时，优先使优先级高的行或者列达到最大尺寸。不影响单元格中的组件。
shrink n 与grow相反，设置尺寸缩小时的权重。
shrinkprio n 与growprio相反，设置尺寸缩小时的优先级。可以缩写为shp。
align a 设置组件在单元格内的对齐方式。可以缩写为al。
gap n 单独设置单元格前后的间隙大小。
gapbefore n 单独设置单元格前的间隙大小。
gapafter n 单独设置单元格后的间隙大小。

组件排布

MigLayout是一个行列布局管理器，所以在默认情况下，MigLayout总是沿着X轴按照组件的添加顺序逐一排列组件。例如以下示例。

1
2
3
4
5

panel.setLayout(new MigLayout());
panel.add(new JLabel("Option 1"));
panel.add(new JTextField());
panel.add(new JLabel("Option 2"));
panel.add(new JTextField());

对于每个组件的布局属性是通过.add()方法的第二个参数“布局约束”来实现的，比如将组件换到另一行排列。所以上面这个示例可以像下面这样分成两行排列。

1
2
3
4
5

panel.setLayout(new MigLayout());
panel.add(new JLabel("Option 1"));
panel.add(new JTextField(), "wrap"); // 布局将在这个组件之后换行
panel.add(new JLabel("Option 2"));
panel.add(new JTextField());

组件布局约束

组件布局约束也是通过一系列的约束描述命令来完成的，虽然可以使用MigLayout提供的CC类来进行强类型形式的定义，但是为了更加简便的描述布局，字符串的形式还是更加简单明了一些。

约束描述命令 设定布局功能
wrap n 设定当前组件是本行最后一个组件，下一个组件将换行放置，n表示当前单元格之后需要保留的间隙大小。
newline n 设定在当前组件之前进行换行，当前组件将被放置在新的一行里。n表示上一行末尾需要保留的间隙大小。
push n 使组件的大小按照n定义的权重比例进行增长，可以单独使用pushx和pushy来定义横向和纵向。
skip n 跳过指定数量的单元格再放置当前组件。
span x y 在横向和纵向方向上合并指定数量的单元格。
spanx x 合并指定数量的横向单元格。
spany y 合并指定数量的纵向单元格。
split n 将当前单元格分割成指定数量的单元格，之后添加的组件将先被放置在分割出来的单元格里。
cell x y sx sy 设定组件将被放置到的单元格，其中sx和sy表示指定单元格的合并情况。
flowx、flowy 设定单元格中的组件排布方向。
width BoundSize 设定组件的宽，可以简写为w。
height BoundSize 设定组件的高，不影响单元格中的组件。可以简写为h。
wmin n、wmax n 设定组件的最小宽度和最大宽度。
hmin n、hmax n 设定组件的最小高度和最大高度。
grow x y 设定组件在指定方向上的尺寸增长权重。
growx x 设定组件在横向上的尺寸增长权重。
growy y 设定组件在纵向上的尺寸增长权重。
growprio n 设定组件尺寸的增长优先级。可以缩写为gp。
growpriox n 设定组件横向尺寸的增长的优先级。可以缩写为gpx。
growprioy n 设定组件纵向尺寸的增长的优先级。可以缩写为gpy。
shrink n 设定组件在尺寸缩小权重。
shrinkprio x y 设定组件尺寸缩小时的优先级。可以缩写为shp。
shrinkpriox n 设定组件横向尺寸缩小时的优先级。可以缩写为shpx。
shrinkprioy n 设定组件纵向尺寸缩写时的优先级。可以缩写为shpy。
sizegroup name 为组件设定一个尺寸组的名称，拥有相同名称尺寸组的组件将具有相同的BoundSize。可以简写为sg。
sizegroupx name 为组件设定一个只保存横向尺寸的尺寸组名称。可以简写为sgx。
sizegroupy name 为组件设定一个只保存纵向尺寸的尺寸组名称。可以简写为sgy。
endgroup name 为组件设定一个终止组名称，拥有相同终止组名称的组件，将会使其右侧和底边保持对齐。可以简写为eg。
endgroupx name 为组件设定一个横向的终止组名称。可以简写为egx。
endgroupy name 为组件设定一个纵向的终止组名称，可以简写为egy。
gap l r t b 为组件设定其所在单元格的外周间隙。只设定一个值时，表示四周都使用相同的BoundSize。另外可以使用gapleft、gaptop、gapbottom、gapright、gapbefore和gapafter来设定具体方向上的间隙大小。
gapx l r 为组件所在的单元格设置横向的外周间隙。只设定一个值时，表示左右两侧都使用相同的BoundSize。
gapy t b 与gapx类似，但设置纵向间隙。
id [grp.] id 为组件设置一个ID，这个ID可以用于不同组件之间的相互访问。
pos x y 将组件在容器中使用绝对定位放置。采用绝对定位的组件将不会被放入单元格内。
pos x y x2 y2 将组件在容器中采用绝对定位放置，并且使用x2、y2设定组件的大小边界。
x n、x2 n、y n、y2 n 设定组件的绝对定位边界。
dock s 将组件泊放在容器的边界上，这个定位能力与BorderLayout类似。在泊放方向不是center的时候，dock命令可以被省略。泊放方向可取值有west、south、east、north和center，并且后续的泊放命令将会使之前的泊放被截断，并占据更多的空间。
pad t l b r 在单元格内部，组件的四周设置留白，如果只设置一个值则代表四个方向使用相同的值。
align x y 设置组件在单元格内的对齐，如果只设置一个值则代表在横总两个方向上都使用相同的对齐设置。可以简写为al。
alignx al 设置组件在单元格内的横向对齐，可以简写为ax。
aligny al 设置组件在单元格内的纵向对齐，可以简写为ay。
external 设置禁止组件更改布局的尺寸，布局的尺寸由GUI控制。利用id可以关联的获取组件尺寸。
hidemode n 设置组件被隐藏的时候，处理布局变化的方式，参数取值与整体布局约束相同。
tag n 为组件打一个标签。

组件的标签

标签可以用于标记和解释组件的用途，并且还可以用来定义组件的排序，但是需要注意的是，这个排序是由系统决定的。在MigLayout中可以使用的标签有一下这些。

  • ok，表示组件是“确认”按钮。
  • cancel，表示组件是“取消”按钮。
  • help，表示组件是“帮助”按钮，这个按钮通常会被放置在右侧。
  • help2，表示组件是“帮助”按钮，这个按钮通常会被放置在左侧。
  • yes，表示组件是“是”按钮。
  • no，表示组件是“否”按钮。
  • apply，表示组件是“应用”按钮。
  • next，表示组件是“下一个”按钮。
  • back，表示组件是“后退”按钮。
  • finish，表示组件是“结束”按钮。
  • left，表示按钮组件应该被始终放置在最左边。
  • right，表示按钮组件应该始终被放置在最右边。
索引标签
JVM
Java
GUI
Swing
MigLayout