theme详解[二]

# 3. 实操与代码解析 🛠️💻

# 3.1 代码结构解析

本节我们聚焦 theme.json 的三大核心：layouts、placement、widgets，帮助你理解 Ambari 配置页面自定义 UI 的渲染原理。

# 3.1.1 `layouts` 结构

layouts 决定了每个配置页面的布局方式，主要包括 tab 页、分区（sections）、以及更细粒度的 subsections。比如：

{
  "name": "default",
  "layouts": [
    {
      "name": "default",
      "tabs": [
        {
          "name": "ranger_admin_settings",
          "display-name": "Ranger Admin",
          "layout": {
            "tab-columns": "2",
            "tab-rows": "2",
            "sections": [
              {
                "name": "section-ranger-admin",
                "display-name": "Ranger Admin",
                "section-columns": "2",
                "section-rows": "3",
                "subsections": [
                  {
                    "name": "subsection-ranger-db-row1-col1",
                    "row-index": "0",
                    "column-index": "0"
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

提示

tabs 字段是数组，意味着你可以自定义多个 tab 页（比如基础、数据库、认证等），不仅限于 ADVANCED。

tab 多页布局示意

tab-columns 和 tab-rows 用于定义页面网格系统，控制控件分布的行列。
sections 代表页面的大分区，每个 section 负责一个配置功能块，可以包含多个子项。

section 分区示意

row-index 和 column-index 明确 section 在页面中的具体位置
subsections 则更细粒度地定义每个 section 里的行列结构，对应实际表单控件的落点。

subsection 行列结构示意

# 3.1.2 `placement` 字段解析

placement 用于将配置项精准绑定到页面布局的具体位置。每个配置项需声明其落在 subsection 的哪个单元格：

"placement": {
"configuration-layout": "default",
"configs": [
{
"config": "admin-properties/DB_FLAVOR",
"subsection-name": "subsection-ranger-db-row1-col1"
}
]
}

1
2
3
4
5
6
7
8
9

config：指定具体配置项（如 admin-properties/DB_FLAVOR）。
subsection-name：定义该配置项落在哪个布局区域。

笔记

这种分离式绑定方式让布局和业务解耦，灵活适配各种大规模配置页面场景。

# 写法补充

config 的写法即“配置文件类型/属性名”模式：

<config-type>/<property-name>

config-type：如 ranger-env、admin-properties 等，对应实际 Ambari 配置文件。
property-name：具体属性，例如 db_user、DB_FLAVOR。

# 示例细解

placement config 示例


{
  "config": "admin-properties/DB_FLAVOR",
  "subsection-name": "subsection-ranger-db-row1-col1"
},{
"config": "ranger-env/create_db_dbuser",
"subsection-name": "subsection-ranger-db-row2"
}

1
2
3
4
5
6
7
8
9

admin-properties/DB_FLAVOR 会渲染到数据库相关区域。
ranger-env/create_db_dbuser 显示于其它配置区块，并可用于控制其他配置项的显示逻辑（如 visible）。

提示

subsection-name 决定 UI 位置，config 决定数据源，两者相互解耦更易扩展。

# 3.1.3 `widgets` 字段解析

widgets 决定了每个配置项的控件类型（如下拉框、文本框、开关等），极大提升了页面交互体验。

"widgets": [
{
"config": "admin-properties/DB_FLAVOR",
"widget": {
"type": "combo"
}},
{
"config": "admin-properties/db_user",
"widget": {
"type": "text-field"
}
}
]

1
2
3
4
5
6
7
8
9
10
11
12
13

type 控件类型（combo：下拉选择，text-field：文本输入）

页面效果如 HBase 服务配置页：

widgets 控件类型示意

# 3.2 实操演示

下面以实际场景展示如何新建并应用 theme.json 主题，实现 Ambari 服务自定义 UI。

# 3.2.1 准备工作

配置 metainfo.xml 在 metainfo.xml 中引入主题：

<metainfo>
  <themes>
    <theme>
      <fileName>theme_version_2.json</fileName>
      <default>true</default>
    </theme>
  </themes>
</metainfo>

1
2
3
4
5
6
7
8

指定 theme_version_2.json 为默认主题文件。

创建 theme.json 文件 路径通常为 resources/stacks/BIGTOP/3.2.0/services/你的服务/themes/theme_version_2.json。

典型模板结构：

{
  "name": "default",
  "description": "Default theme for XXX service",
  "configuration": {
    "layouts": [
      {
        "name": "default",
        "tabs": [
          {
            "name": "ranger_admin_settings",
            "display-name": "XXXXX",
            "layout": {
              "tab-columns": "2",
              "tab-rows": "2",
              "sections": [
                {
                  "name": "section-ranger-admin",
                  "display-name": "XXXXXX",
                  "row-index": "0",
                  "column-index": "0",
                  "row-span": "3",
                  "column-span": "2",
                  "subsections": [
                    {
                      "name": "subsection-xx-db-row1-col1",
                      "row-index": "0",
                      "column-index": "0"
                    }
                  ]
                }
              ]
            }
          }
        ]
      }
    ],
    "placement": {
      "configuration-layout": "default",
      "configs": [
        {
          "config": "admin-properties/DB_FLAVOR",
          "subsection-name": "subsection-ranger-db-row1-col1"
        }
      ]
    },
    "widgets": [
      {
        "config": "admin-properties/DB_FLAVOR",
        "widget": {
          "type": "combo"
        }
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

提示

建议采用统一命名规则（如 subsection-业务-行-列），便于团队协作和后续维护。

# 3.2.2 应用主题

编辑好 theme.json 后，放到目标目录或重新打包后，重启 Ambari 服务：

ambari-server restart

重启后登录界面，即可体验新主题布局与控件交互效果。

# 4. 最佳实践与技巧 💡

利用 depends-on 实现动态 UI：通过 depends-on 动态联动字段，让页面只在需要时展示相关配置项，减少配置干扰。
分层布局让 UI 更清晰：合理拆分 layouts > sections > subsections，让配置项归类更自然，用户体验更佳。
合适选用 widgets 类型：不同属性类型选配合适控件（如 toggle/checkbox/combo），提升表单友好度，降低误操作风险。
充分用好 property_value_attributes：比如定义只读、UI 专用、默认隐藏等行为，实现页面与后端松耦合，方便后期迭代。

#theme.json #metainfo.xml #Ambari定制 #配置可视化 #交互体验

← theme详解[一] theme详解[三]→