JIRAUI定制全攻略

# JIRA UI 定制全攻略 ## 1. JIRA UI 定制概述 JIRA 拥有简洁而强大的用户界面，从 3.13.x 到 4.1.x 版本，其界面有了诸多变化，始终能让用户满意并吸引插件开发者。不过，在某些情况下，我们需要对其界面进行修改，添加或移除一些元素。通常，修改网页应用的用户界面，我们首先会想到修改 JSP、VM 等文件，但对于 JIRA 而言，很多界面更改无需触碰其核心代码，借助一些与 UI 相关的插件模块就能实现。 ## 2. 改变基本外观和感觉 ### 2.1 可配置的方面 要改变 JIRA 的外观，主要可从以下四个方面进行配置： |配置项|说明| | ---- | ---- | |Logo|这是大家都想更改的部分| |Colors|JIRA 原本以蓝色为主题，可轻松更改颜色以符合个人或公司喜好| |Gadget colors|可为每个小工具设置不同颜色，可通过简单配置更改预定义的颜色列表| |Date and Time formats|只要是 Java 的 SimpleDateFormat 支持的有效格式，就能轻松修改 JIRA 中的日期和时间格式| ### 2.2 操作步骤 以下是更改 JIRA 基本外观和感觉的具体步骤： 1. 以管理员身份登录 JIRA。 2. 导航至“Administration | Global Settings | Look and Feel”。 3. 点击“Edit Configuration”。 4. 进行相应更改： - Logo：将新 logo 打包到 JIRA WAR 中，或放置在 JIRA 安装目录下的 images 文件夹或其他有效目录中。以相对路径引用新 logo 的 URL，例如“/images/logo/mynewlogo.png”。根据需要输入新 logo 的宽度或高度。 - Colors：若要更改配色方案，指定感兴趣颜色的十六进制表示（HEX 值）。 - Gadget colors：同样指定感兴趣颜色的十六进制表示（HEX 值），以便小工具用户能从新的颜色集合中选择。 - Date and Time formats：输入新的日期和时间格式，需为 Java 的 SimpleDateFormat 支持的有效格式。 5. 点击“Update”。可重复此过程，直至达到理想效果。在编辑配置时，点击“Reset Defaults”可恢复默认设置。 ### 2.3 效果展示 通过这些简单更改，JIRA UI 会有很大不同。例如，查看问题页面可能会呈现出与以往不同的样子，这虽小却很强大。 ## 3. 在 UI 中添加新的网页部分 ### 3.1 网页片段的概念 网页片段是 JIRA 网页界面特定位置的链接或链接部分，它可以是 JIRA 顶部导航栏的菜单、新的问题操作集合，或者管理 UI 部分的新区域。在 JIRA 中添加新网页片段有两种插件模块，即 Web Section 插件模块和 Web Item 插件模块。Web Section 是在 JIRA 用户界面特定位置一起显示的链接集合，可能是问题操作栏上的一组按钮或用线分隔的一组链接。 ### 3.2 操作步骤 以下是向 JIRA 添加新网页部分的步骤： 1. 确定新部分应添加的位置。JIRA 用户界面有很多已确定的位置，可在其中任何位置添加新网页部分。完整的可用位置列表可在“http://confluence.atlassian.com/display/JIRA/Web+Fragments”找到。 2. 在 atlassian - plugin.xml 中添加新的 web - section 模块： ```xml <web-section key="jtricks-admin-section" name="JTricks Section" location="system.admin" i18n-name-key="webfragments.admin.jtricks. section" weight="900"> <label>J Tricks</label> <description>J Tricks Section Descitption</description> <tooltip>J Tricks - Little JIRA Tricks</tooltip> </web-section> ``` 3. 每个插件模块都有唯一的键。web - section 元素的另外两个重要属性是 location 和 weight。location 定义了该部分应在 UI 中出现的位置，weight 定义了其出现的顺序。例如，上述示例中 location 为“system.admin”，将在管理屏幕下创建一个新的网页部分，就像现有的“Project”“Global Settings”等部分一样。 4. web - section 模块还有一组子元素： - condition 或 conditions 元素：可用于定义一个或多个条件。 - context - provider 元素：可用于添加新的上下文提供程序，以定义网页部分的 Velocity 上下文。 - label：将显示给用户的内容。 - param 元素：可用于定义键/值参数，若想从 UI 使用额外的自定义值时很有用。 - resource 元素：可用于包含 JavaScript 或 CSS 等资源文件。 - tooltip 元素：为该部分提供工具提示。其中，label 是唯一必需的元素。 - 像 label 和 tooltip 等元素可以有可选的键值参数，示例如下： ```xml <label key="some.valid.key"> <param name="param0">$somevariable</param> </label> ``` 这里，label 接受键/值参数，值从 Velocity 变量动态填充。param 将作为 {0} 传递给文本，并替换标签中的相应位置。参数允许使用 Java 的 MessageFormat 语法将值插入标签中，具体细节可参考“http://download.oracle.com/javase/7/docs/api/java/text/MessageFormat.html”。参数名必须以“param”开头，将按字母顺序映射到格式字符串中的替换项，即“param0”对应 {0}，“param1”对应 {1}，以此类推。 5. 部署插件。 ### 3.3 工作原理 插件部署后，可在 JIRA 的管理屏幕中看到新部分。通过更改 location 属性，可将该部分添加到不同位置。例如，将 location 改为“opsbar - operations”，新部分将出现在查看问题页面上。不过需注意，网页部分的标签并非总是可见，因为在某些情况下，该部分仅用于对链接进行分组。 ## 4. 在 UI 中添加新的网页项 ### 4.1 网页项的概念 网页项是可添加到 JIRA UI 不同位置的新链接，通常位于网页部分之下。链接可以简单地指向一个 URL，也可用于调用一个操作。 ### 4.2 操作步骤 以下是向 JIRA 添加新网页项的步骤： 1. 确定新链接应添加的网页部分。 2. 若要将链接添加到之前创建的网页部分，section 元素的值应为“system.admin/jtricks - admin - section”。若位置是非分段的，可直接将链接添加到该位置；对于分段位置，应使用位置键后跟斜杠（“/”）和网页部分的键。 3. 在 atlassian - plugin.xml 中添加新的 web - item 模块： ```xml <web-item key="jtricks-admin-link" name="JTricks Link" section="system.admin/jtricks-admin-section" i18n-name- key="webfragments.admin.jtricks.item" weight="10"> <label>J Tricks Website</label> <link linkId="jtricks.admin.link">http://www.j-tricks.com</link> </web-item> ``` Web 项模块也有唯一的键。web - item 的另外两个重要属性是 section 和 weight。section 定义了链接所在的网页部分，weight 定义了链接出现的顺序。 web 项还具有网页部分的所有元素，如 condition/conditions、context - provider、description、param、resource 和 tooltip。此外，web 项还有一个 link 元素，用于定义网页项应链接到的位置。链接可以是一个操作、直接链接等，还可使用 Velocity 参数动态创建，示例如下： ```xml <link linkId="create_link" absolute="false">/secure/ CreateIssue!default.jspa</link> <link linkId="google_link">http://www.google.com</link> <link linkId="profile_link" absolute="false">/secure/ViewProfile. jspa?name=$user.name</link> ``` 在第三个示例中，“user”是 Velocity 上下文中可用的变量。若需要在链接旁边添加图标，可使用 icon 元素： ```xml <icon height="16" width="16"> <link>/images/avatar.gif</link> </icon> ``` 4. 部署插件。 ### 4.3 工作原理 插件部署后，可在之前创建的网页部分中看到新的网页项。通过更改 section 属性，可将该项添加到不同位置。 ## 5. 为网页片段添加条件 ### 5.1 添加条件的必要性 添加网页片段相对容易，但很多时候我们希望根据一组条件来限制网页项的显示。例如，“Edit Issue”链接应仅对具有问题编辑权限的人显示，管理员链接应仅在用户是 JIRA 管理员时显示。 ### 5.2 操作步骤 可向网页部分或网页项添加一个或多个条件。对于网页项，使用 conditions 元素，它包含一个或多个 condition 元素以及一个 type 属性，type 属性可以是逻辑 AND 或 OR。 例如，以下条件指定用户在看到具有此条件的网页片段之前，应在项目中具有 admin 权限或 use 权限： ```xml <conditions type="OR"> <condition class="com.atlassian.jira.plugin.webfragment.conditions. JiraGlobalPermissionCondition"> <param name="permission">admin</param> </condition> <condition class="com.atlassian.jira.plugin.webfragment.conditions. JiraGlobalPermissionCondition"> <param name="permission">use</param> </condition> </conditions> ``` permission 的可能值包括“admin”“use”“sysadmin”“project”“browse”“create”“edit”等众多选项。 下面以一个简单示例说明如何编写条件并根据条件显示网页项。在此示例中，只有当用户登录并属于“jira - developer”组时，才会在顶部导航栏显示一个网页项。具体步骤如下： 1. 编写条件类。该类应继承 AbstractJiraCondition 类，并重写以下抽象方法： ```java public abstract boolean shouldDisplay(User user, JiraHelper jiraHelper); ``` 2. 在本示例中，只需检查用户是否不为 null 且属于“jira - developers”组，类的实现如下： ```java public class DeveloperCondition ```