diff --git a/topics/appendix/tools/ide_tooling/internal_actions/internal_ui_inspector.md b/topics/appendix/tools/ide_tooling/internal_actions/internal_ui_inspector.md index 79d374d9bf8..3022ea6bf56 100644 --- a/topics/appendix/tools/ide_tooling/internal_actions/internal_ui_inspector.md +++ b/topics/appendix/tools/ide_tooling/internal_actions/internal_ui_inspector.md @@ -25,7 +25,7 @@ The _UI Inspector_ displays the icon details: ![Internal Icon Info](internal_ui_inspector_icon_info.png) -## `added-at` Property +## `added-at` Property {id="added-at-property"} Sometimes, inspecting complex component's properties is not enough to understand how the component was created and configured. _UI Inspector_ gives the possibility of finding the code where the selected component was added, which makes it much easier to understand which APIs can be used to build custom components with similar complexity. diff --git a/topics/ui/components/tool_window.md b/topics/ui/components/tool_window.md index fe5b1e95a51..9421cb6eeb8 100644 --- a/topics/ui/components/tool_window.md +++ b/topics/ui/components/tool_window.md @@ -1,55 +1,54 @@ -# Tool Window +# 工具窗口 -UI guidelines on using tool windows. +工具窗口的指南 -A tool window is a pane inside the main IDE window. For information about tool windows, see [IntelliJ IDEA Web Help](https://www.jetbrains.com/help/idea/tool-windows.html). For information about implementing tool windows, see [](tool_windows.md). +工具窗口是在IDE主窗口内的一个面板。有关工具窗口的信息，请参考[IntelliJ IDEA Web Help](https://www.jetbrains.com/help/idea/tool-windows.html)。有关实现工具窗口的信息，请参考[](tool_windows.md)。 ![](tool_window_example.png){width=960} -## When to use +## 什么时候使用 +您可以在编辑器或其它工具窗口旁边使用工具窗口，这样可以展示用户需要的大量信息。比如查看文件结构、运行及调试应用、查看git提交日志等。 -Use the tool window to show a large amount of information that the user needs while working side-by-side with the editor or other tool windows. For example, viewing the project structure, running and debugging an application, and viewing git log. +如果这些信息足够少，您应该将它显示在编辑器内、主工具栏、状态栏或者弹出窗口中。比如在编辑器侧边栏显示文件的变化，在主工具栏中显示面包屑导航，在状态栏中显示当前分支和文件详细信息，在弹出窗口中显示快捷文档等。 -If the amount of information is small, show it in the editor, main toolbar, status bar or popup. For example, show version control changes on the editor gutter, breadcrumbs in the main toolbar, current branch and file details in the status bar, quick doc in a popup. +如果用户不需要这些主窗口中的信息来完成操作，您应该把它们现实在弹出窗口或者对话框中。比如随处搜索弹窗和设置对话框。 -If the user does not need the information from the main window to complete an operation, show the content in the popup or dialog window. For example, Search Everywhere popup, Settings dialog. - -## Tool window structure +## 工具窗口结构 ![](tool_window_structure.png){width=483} -## How to use +## 如何使用 -Give the tool window a name: +为工具窗口命名： -* The name should be [short and descriptive](writing_short.md), preferably not longer than two words. -* Use title-case capitalization. +* 名称应该[言简意赅](writing_short.md)，最好不超过两个词（这里指英文的两个词，中文请酌情考虑）。 +* 使用标题大小写。 -Show the tool window name in the tool window button and header. If there are tabs in the tool window header, add a colon after the tool window name. Otherwise, do not add it. +请在工具窗口按钮（Tool window button）和页眉（Header）处显示窗口名称。如果窗口内分了标签页，请在窗口名称后面添加一个冒号，反之则不用。 ![](pull_requests.png){width=308} -Add an icon for the tool window. The icon is 13px x 13px, grey and monochromatic. See how to create icons in the [icons guidelines](icons_style.md). +请为工具窗口添加一个灰色纯色图标，大小为13px × 13px。创建图标请参考[](icons_style.md)。 -**Exception:** Problems and Event Log icons change color and show the current status. +**例外：**Problems和Event Log会改变颜色来展现当前状态。 -Select the tool window orientation depending on the content. Vertical tool windows work better for trees, for example, Project, Structure, or Maven tool windows. Horizontal tool windows work better for tables, wide content or master-detail panels, for example, Git Log, Terminal, or Problems. +请根据具体内容选择工具窗口的布局方向。垂直布局的窗口更适合树，例如项目、结构或Maven工具窗口。水平布局的窗口更适合表格、宽内容或详细信息，例如Git日志、终端以及问题。 -Do **not** show the tool window button if the tool window is not relevant to the current project configuration. For example, do not show the Maven tool window for a project without Maven configuration files. +请**不要**展示与当前项目无关的工具窗口。比如，不要在没有Maven配置文件的项目中展示Maven工具窗口。 -If a tool window has no content yet, show its button by default only if the window contains basic functionality that is likely to be used for all projects, for example, Version Control or Problems. Otherwise, do not show the tool window button by default. +如果一个工具窗口没有内容，则仅当其包含几乎对所有项目都有用的基础功能时，才应该显示它的按钮，比如版本控制和问题窗口；否则应该默认不显示。 -Add a toolbar for [frequently used actions and filters](toolbar.md#what-items-to-add-on-toolbar). Use a horizontal toolbar for vertical tool windows and a vertical toolbar for horizontal tool windows. For more details, see the [toolbar guidelines](toolbar.md). +为[经常使用的功能和筛选程序](toolbar.md#what-items-to-add-on-toolbar)添加一个工具栏。Use a horizontal toolbar for vertical tool windows and a vertical toolbar for horizontal tool windows. 另请参考[](toolbar.md)。 -Put tool window viewing mode settings under the gear icon in the header. If there is no toolbar, put other options under the gear icon as well. For example, see the gear icon in the Project tool window. +请将工具窗口的设置放在页眉的齿轮图标中。如果没有工具栏，则应将其它选项也放进齿轮图标中。比如项目窗口中的齿轮图标。 -Add tabs if all the information does not fit in one tab or refers to similar instances, like run sessions, history for files, find results. The tabs for entities should be closable. +当所有信息并不适合放在一个标签页中，或者不指代类似的东西时，请添加标签页，比如运行、文件历史、查找结果。这些标签页应该是可以关闭的。 ![](git.png){width=308 style=block} -*Separate tabs are added for each file history.* +*为每个文件的历史添加单独的标签页* ![](find.png){width=448 style=block} -*Separate tabs are added for different search queries.* +*为每个搜索添加各自的标签页* diff --git a/topics/ui/principles/layout.md b/topics/ui/principles/layout.md index e8e02d0a94c..19dc847485d 100644 --- a/topics/ui/principles/layout.md +++ b/topics/ui/principles/layout.md @@ -1,234 +1,231 @@ -# Layout +# 布局 -UI guidelines on laying out the controls in dialogs. +关于对话框中控件布局的UI指南 -Arrange UI controls in dialogs according to the rules below to help people locate the necessary settings faster and understand how they are related.
+根据如下提及的规则来管理对话框中的控件布局，以便使用者能快速定位必要的设置项，并理解相互之间的关系。
-Independent controls: +独立控件： -- [Labeled input controls](#labeled-input-controls): fields, combo boxes, text areas, etc. -- [Checkboxes and radio buttons](#checkboxes-and-radio-buttons) -- [Buttons and links](#buttons-and-links) -- [Lists, trees, tables](#lists-trees-and-tables) +- [带标签的输入控件](#labeled-input-controls)：框，组合框，文本域等 +- [单选、复选按钮](#checkboxes-and-radio-buttons) +- [按钮和链接](#buttons-and-links) +- [列表，树，表格](#lists-trees-and-tables) -[Dependent controls ](#dependent-controls)— controls that depend on a parent control.

+[从属控件](#dependent-controls) — 依赖于父容器的控件

-Organize controls into easily readable groups with [vertical and horizontal insets](layout.md#organize-with-insets). +请配合[垂直、水平间距](#organize-with-insets)将控件放入易辨别的分类中。 [//]: # (TODO: See [Dialog window](dialog_window.md) for buttons and other controls at the bottom of a dialog.) -## Independent controls +## 独立控件 -### Labeled input controls +### 带标签的输入控件 {id="labeled-input-controls"} -Labeled input controls are: [input field](input_field.md), [combo box](combo_box.md), [drop-down list](drop_down.md), [text area](text_area.md), and spinner. +带标签的输入控件包括：[输入框](input_field.md)，[组合框](combo_box.md)，[下拉列表](drop_down.md)，[文本域](text_area.md)以及微调按钮。 -By default, put input controls with labels of similar length on different lines and align their input boxes on the left side. +一般情况下，请将带标签的输入控件放在不同的行上，标签内容长度应差不多一样长，并且控件输入框左端对齐。 ![](1_01_input_similar_labels.png){width=391} -Do **not** align input boxes on the left side if one label is twice as long as the other one or even longer. +如果一个标签是其它标签的两倍长或者更长，请**不要**将输入框对齐到左端。 ![](1_02_input_different_labels_incorrect.png){width=391} ![](1_02_input_different_labels_correct.png){width=391} -If several related input controls have labels of up to 10 characters and their input boxes are short, organize them in two columns. Do **not** use more than two columns. +如果几个相关的输入控件都只拥有最多10个字符，且输入框都比较短，请将他们组织成两列。请**不要**超过两列。 ![](1_03_short_inputs.png){width=391} -If an input box is long, and the horizontal space is limited, place the label above the box. Otherwise, always put the label and the box on the same line. +如果输入框很长，但水平空间有限，请将其标签置于上方。反之，请始终把标签和输入框置于同一行。 ![](1_04_input_top_label.png){width=412} -#### Separated by other controls +#### 被其它控件隔开 -If there are two input controls with labels of similar length that are separated from each other by a single control, align their input boxes on the left side. +如果两个输入控件的标签差不多长，又被另一个控件分隔开，请将它们的输入框左端对齐。 ![](1_05_separated_by_one.png){width=452} -Align only the input boxes of the neighboring input controls. If there are several input controls on a page, and they are separated from each other by two or more other UI elements, do **not** align their input boxes. +仅需要对其相邻的控件。如果同一页上的几个控件被两个或更多其它UI元素隔开，请**不要**对齐它们。 ![](1_06_separated_by_two.png){width=452} -If input groups are separated by a group of other UI controls, align only the boxes located within one group. +如果几组输入控件被其它控件组隔开，仅需要对齐同一组中的控件。 ![](1_07_separated_groups.png){width=616} -#### Labels and right borders +#### 标签和右边界 -Always left-align labels. +请始终将标签左对齐 -> This alignment is inconsistent with macOS guidelines, but the aim is to maintain consistency in all JetBrains IDEs on all supported platforms. +> 这条对齐规则与MacOS指南并不一致，但其目的在于维持所有JetBrains IDE在受支持的平台上的一致性。 > {style="note"} ![](1_08_label_alignment.png){width=464} -Align the right borders of input boxes that have a similar length. For alignment, use [built-in icons](built_in_button.md). Do **not** use buttons. +请将长度相当的输入框右端对齐。为了整齐，请使用[内联图标](built_in_button.md)。请**不要**使用按钮。 ![](1_09_built_in_button.png){width=302} -### Checkboxes and radio buttons +### 单选、复选按钮 {id="checkboxes-and-radio-buttons"} -By default, put independent checkboxes and radio button groups on different lines. +一般情况下，请将相互独立的单选、复选按钮放置在不同的行上。 ![](2_01_checkbox_radio_column.png){width=358} -If there is a group of 2–3 checkboxes with short labels (1–3 words), place them on the same line. -The same rule applies to radio buttons. -With this alignment, controls form a short sentence, making it easier to understand their meaning compared to when they are split into several lines. +如果一组复选框只有2-3个选项，每个选项的标签只有1-3个词，请将他们置于同一行；单选按钮同理。 +在这种布局下，控件形成一个短句，会比它们分散在不同行时更易读。 ![](2_02_checkbox_radio_line.png){width=358} -When there is an input control on one line and a group of checkboxes or radio buttons on the next line, and their labels are of similar length -(one is no more than 5 characters longer than the other), align the input box with the checkbox/radio button. +当一行有一个输入控件，下一行有一组复选或单选按钮，并且它们的标签长度相当（一个标签的长度不超过5个字符），请将输入框与复选/单选按钮对齐。 -If one label is much longer than the other, do **not** align these UI elements. +如果一个标签比另一个长很多，请**不要**对齐这些元素。 ![](2_03_align_group_labels.png){width=461} -If a checkbox group does not have a label, align it with other independent controls by the left side. +如果一组复选框没有标签，请将其与另一个无关的控件左对齐。 ![](2_03_align_without_group_labels.png){width=417} -4 and more checkboxes can be arranged in columns: +4个或者更多的复选框可以排成列： -* Arrange checkboxes with labels of up to 30 characters in 2 columns. +* 将总标签词数少于30的复选框组排成两列。 ![](2_04_checkbox_2_columns.png){width=417} -* Arrange checkboxes with labels of up to 15 characters in 3 columns. +* 将总标签词数少于15的复选框组排成三列。 ![](2_05_checkbox_3_columns.png){width=417} -Do **not** arrange radio buttons from one group in several columns. Splitting a group of radio buttons into two or more columns makes it unclear that all these radio buttons belong to the same setting. +请**不要**同一组的单选按钮排列成几列。将一组单选按钮拆分为两列或多列后，会让人分不清这些按钮是否属于同一设置。 ![](2_06_radio_columns_incorrect.png){width=417} -### Buttons and links +### 按钮和链接 {id="buttons-and-links"} -Align an independent button or link to the left with other controls. +将独立的按钮和链接与其它控件向左对齐。 ![](3_01_button_column.png){width=361} ![](3_01_link_column.png){width=361} -If there are 2–3 buttons or links with labels of up to 30 characters each, place them on one line. +如果有2-3个按钮或链接，每个按钮和链接的标签不超过30个字符，请将它们放在一行中。 ![](3_02_button_line.png){width=361} -Do **not** arrange buttons or links in several columns. Such a layout takes more time to parse visually. +请**不要**将按钮和链接放在多个列中，这样的布局需要更多的时间来直观地理解。 ![](3_03_button_columns.png){width=361} -### Lists, trees and tables +### 列表，树，表格 {id="lists-trees-and-tables"} -Choose a control width such that most of the common values are visible. Take the whole width of the dialog if necessary. +调整控件宽度，使得大多数常用值都可见。如有必要，请利用整个对话框的宽度。 ![](4_01_table_full_width.png){width=638} -If the dialog containing the control is noticeably wider than the control itself, reduce the length of the control. +如果包含控件的对话框明显比控件本身宽，请缩短控件的长度。 -Do **not** put other independent controls to the right of a list, tree, or table. -They would look like dependent controls in the master-detail layout. +请**不要**将其它独立控件放在列表、树或表的右侧，这样会看起来像master-detail布局中的从属控件。 ![](4_02_table_fixed_width.png){width=638} -If there are several lists, trees, or tables in a dialog, make them of the same width. +如果对话框中有多个列表、树或表格，请使它们一样宽。 ![](4_03_aligned_lists.png){width=452} -## Dependent controls +## 从属控件 {id="dependent-controls"} -

Align controls according to the rules below to show that they are related.

+

根据以下规则对齐控件，以表示它们是相关的。

-Place 2–3 related UI controls on the same line if each control takes up to 30 characters. This way the user needs to read just one line, and it is quicker to see that the controls depend on each other. +如果每个控件最多占用30个字符，则请将2-3个相关的UI控件放在同一行上。这样，用户只用看一行就能很快意识到它们是相关的。 ![](5_01_dependent_one_line.png){width=497} -

In all other cases, place interrelated controls on different lines:

+

其它情况下，请将相关的控件放在不同的行上：

-Main control: **labeled input control**. +主控件：**带标签的输入控件** -* Align other dependent elements with the left border of the input box. +* 请将其他非独立元素对齐到输入框的左边。 ![](5_03_dependent_on_field_checkbox.png){width=281} ![](5_03_dependent_on_field_button.png){width=281} -* If an input's label is long or the input box is very short, align by the label and add a horizontal inset. +* 如果输入框的标签很长或输入框很短，请按标签对齐并插入水平间距。 ![](5_04_dependent_on_field_long_label.png){width=489} -Main control: **checkbox** or **radio button**. Align dependent controls by the label. +主控件：**复选按钮**或**单选按钮**。从属控件请按标签对齐。 ![](5_02_dependent_on_checkbox.png){width=342} -When the main control or one of the dependent controls takes the whole width of a panel, left align all elements. +当主控件或一个从属控件占据面板的整个宽度时，请将所有元素左对齐。 ![](5_05_whole_width_text_area.png){width=475 style=block} -*The text area is the main control, the button is the dependent control.* +*文本域是主控件，按钮是从属控件* ![](5_06_whole_width_checkbox.png){width=475 style=block} -*The checkbox is the main control, the table is the dependent control.* +*复选框是主控件，表格是从属控件* -When the main control takes the whole width of a panel, and there is one small dependent control (for example, a drop-down list), place this dependent control to the top-right corner, above the main control. +当主控件占据面板的整个宽度，且有一个小的从属控件（例如下拉列表）时，请将此从属控件放在主控件的右上角。 ![](5_07_whole_width_top_right_corner.png){width=475} [//]: # (TODO: See [Master-detail layout](masterdetail_layout.md) for more information on how to lay out controls if they depend on lists or trees.) -See the [Inline help text](inline_help_text.md#placement) and [Tooltip](tooltip.md#question-mark-icon-for-help-tooltips) articles for details on how to arrange help information in dialogs. +关于如何在对话框中排列帮助信息，请参阅[](inline_help_text.md#placement)和[](tooltip.md#question-mark-icon-for-help-tooltips)。 -If controls do **not** depend on each other, left-align them all. Otherwise, the user might think that controls are linked. +如果控件彼此**不**依赖，请将它们左对齐。否则，用户可能会认为控件之间有联系。 ![](5_09_incorrect_alignment.png){width=517 style=block} -*The spinners do not depend on the top checkbox.* +*微调按钮不依赖于顶部的复选框* -## Organize with insets +## 使用间距 {id="organize-with-insets"} -Use vertical insets to break a list of controls into easily readable groups. Compare: +使用垂直间距将控件列表分为易读的组。对比： -Incorrect +错误 ![](6_02_group_insets_incorrect.png){width=396 style=block} -*The list of controls is hard to scan quickly because the controls "stick" together.* +*控件很难快速辨认，因为控件都“粘”在一起* -Correct +正确 ![](6_02_group_insets_correct.png){width=396 style=block} -*Scanning a list of controls becomes easier when vertical insets are added between the groups of controls.* +*在控件组之间添加垂直间距时，辨认控件会更加容易* -Treat insets with extra care and make sure that elements within a group are actually related. An unnecessary inset may create a false impression that the controls are grouped. This complicates the UI and might cause confusion. +处理间距时要留意，并确保分组中的元素确实是相关的。不必要的间距可能造成控件已分组的错觉。这会使界面复杂化，也可能导致混淆。 -Incorrect +错误 ![](6_04_inset_incorrect.png){width=396 style=block} -*The first checkbox depends on the combo box which is shown with the horizontal inset. However, the checkboxes appear grouped because they are closer.* +*第一个复选框从属于与水平间距一起显示的组合框。然而，两个复选框似乎是同一组，因为它们更接近。* -Correct +正确 ![](6_04_inset_correct.png){width=396 style=block} -*The first checkbox is closer to its main control, and it is easier to see that the combo box and checkbox are related.* +*第一个复选框更靠近其主控件，这样更容易看出组合框和复选框是相关的。* -Horizontal insets also matter for grouping controls. +水平间距对于控件分组也很重要。 -Incorrect +错误 ![](6_05_hor_inset_incorrect.png){width=396 style=block} -*The checkboxes and the "Length" fields look independent because the horizontal inset between them is bigger than the vertical inset below the second checkbox.* +*复选框和“Length”字段看起来是无关的，因为它们之间的水平间距大于第二个复选框下方的垂直间距。* -Better +好一些 ![](6_05_hor_inset_better.png){width=396 style=block} -*With smaller horizontal and bigger vertical insets, the checkboxes and the "Length" fields look related. However, it could be made better if the repeating word "Separator" appears only once.* +*使用较小的水平间距和较大的垂直间距，复选框和“Length”字段看起来就相关了。如果重复的单词“Separator”只出现一次就更好了。* -Correct +正确 ![](6_05_hor_inset_correct.png){width=396 style=block} -*Correct grouping and no duplicates help understand the UI quicker.* +*正确的分组和不重复有助于更快地理解界面。* -See [Groups of controls](groups_of_controls.md) for how to organize a bigger group of controls. +关于如何组织更大的控件组，请参考[](groups_of_controls.md)。 diff --git a/topics/ui/principles/validation_errors.md b/topics/ui/principles/validation_errors.md index f69e9ac81af..3c4207a9778 100644 --- a/topics/ui/principles/validation_errors.md +++ b/topics/ui/principles/validation_errors.md @@ -1,109 +1,109 @@ -# Validation Errors +# 验证输入 UI guidelines on displaying and writing texts of validation errors. -Validation is the process of checking the values specified by the user, and displaying the errors that are found. +验证是检查用户指定的值并提示错误的过程。 -An error can appear in a **tooltip**: +错误可以在**工具提示**中显示 ![](example_tooltip.png){width=235} -Or **inline**, above the confirmation buttons: +或**内联显示**在确认按钮之上： ![](example_inline.png){width=358} -## Principles +## 原则

-Always try not to let the user enter invalid data. To achieve this: +永远不要让用户输入非法的数据。为了达到这点，你可以：

-Use controls that are constrained to valid values. For example, use a combo box or a slider instead of the input field. +使用限制为有效值的控件。例如，使用组合框或滑块而不是输入框。 -Limit the characters users can enter. For example, if only numbers are supported in a field, and this is obvious to the user, ignore input of letters instead of showing an error: +限制用户可以输入的字符。例如，如果一个字段仅支持数字，并且这对用户来说是显而易见的，请忽略输入的字母，而不是显示错误： ![](port_correct.png){width=188} -If it’s not obvious that only numbers can be entered, allow entering any sign and perform validation. +如果只能输入数字并不显然，则应允许输入任何符号并执行验证。 ![](font_error.png){width=301} -Provide a default value if possible. Even if the user decides to change the default value, it gives a clue on the expected input format. +请尽量提供默认值。这样，即使用户决定更改默认值，它也会提示预期的输入格式。 -Write instructions and examples on how to fill a form using [context help](context_help.md). +请使用[](context_help.md)编写填写表单的说明和示例。 -If it’s not possible to limit input, try to show an error as soon as possible so that the user can quickly return and fix it. +如果无法限制输入，请尽快显示错误，以便用户可以快速修复。 -## Validation types and usage +## 验证方式和用法 - - - + + + - - - + + - - - + + - - - + + + - - - + + + - - - + + + - - - + + +
What to validate Validation type Format 验证的内容 验证方式 提示方式

1

 Non-allowed characters or too big/long values + 不允许的字符或太大、太长的值 Immediately on input Tooltip 输入时立刻验证 工具提示

2

 Non-allowed values in dialogs. -

For example, an existing file name, a value that does not match the pattern, or a value that’s too small

+ 		对话框中不允许的值 +

例如，现有的文件名或值与模式不匹配，或值太小

 On sending the form or on focus loss Tooltip 提交表格或失去焦点时 工具提示

3

 Empty required fields in dialogs Disable the confirmation button or check on sending the form Tooltip 对话框中的必填字段为空 禁用确认按钮或在发送表单时检查 工具提示

4

 Non-allowed or empty values in the main window On Enter or focus loss Tooltip 主窗口中不允许的值或空值 获得焦点或失去焦点时 工具提示

5

 Remote connection On sending the form Tooltip or inline 远程连接 提交表格时 工具提示或内联

6

 Complex values in multi-page dialogs On reopening the form or when the values are used Tooltip, inline or notification 多页对话框中的复杂值 重新打开表单或使用值时 工具提示，内联或消息
-### 1. Non-allowed characters or too big values +### 1. 不允许的字符或太大、太长的值 {id="1-non-allowed-characters-or-too-big-values"} -If a non-allowed character is entered, or the maximum input size or value is exceeded, validate it immediately on input. +如果输入了不允许的字符，或者输入大小或值超过了最大值，请在输入时立即验证它。 -#### How it works {id="how-it-works_1"} +#### 如何工作 {id="how-it-works_1"} -The field is highlighted with red, and the error appears in the tooltip. +该字段以红色高亮显示，并在工具提示显示错误中。 ![](create_class.png){width=373} -If the maximum value is exceeded, specify what values are allowed (e.g. a range for numeric values, or the number of symbols): +如果超过最大值，请指出允许的值（例如，数值范围或符号数量）： ![](port_error.png){width=461} -Hide the error when the incorrect symbol is deleted. +在删除不正确的符号后隐藏错误。 -#### Implementation {id="implementation_1"} +#### 实现方式 {id="implementation_1"} @@ -167,44 +167,44 @@ myPort.getDocument().addDocumentListener(new DocumentAdapter() { }); ``` -See also: [](disposers.md#choosing-a-disposable-parent). +另请参阅：[](disposers.md#choosing-a-disposable-parent). -### 2. Non-allowed values in dialogs +### 2. 对话框中不允许的值{id="2-non-allowed-values-in-dialogs"} -A non-allowed value is a value that can be checked only when fully entered. For example, an existing file name, value that does not match the pattern or a value that’s too small/short. +不允许的值是只有在完全输入后才能检查的值。例如，现有的文件名或值与模式不匹配，或值太小、太短。 -If a non-allowed value is entered, validate it on focus loss or on sending the form, depending on what happens faster. +如果输入了不允许的值，请根据不同方式的快慢，选择在失去焦点或发送表单时对其进行验证。 -Do **not** validate non-allowed values on input, it will interrupt the user. +请**不要**在输入时验证，这会打断用户。 -Do **not** validate empty fields on focus loss. Users should be able to fill the form in a random order, so do not interrupt them. +请**不要**在失去焦点时验证空字段。用户应该能够按随机顺序填写表格，因此请勿打断他们。 -#### How it works {id="how-it-works_2"} +#### 如何工作 {id="how-it-works_2"} -On sending the form, the field is highlighted in red and the error tooltip appears. +提交表单时，字段以红色高亮显示，并显示错误提示。 ![](exesting_name.png){width=257} -If validated on focus loss, highlight the field in light-red. Do not return focus to the field with the error automatically. +如果在失去焦点时验证，请以浅红色高亮显示。不要自动将焦点返回到出现错误的字段。 ![](focus_loss.png){width=169} -The error tooltip appears when the invalid field gets the focus or on hovering over the field. +当无效字段获得焦点或将鼠标悬停在该字段上时，应显示错误提示。 -When the user changes the value, the tooltip disappears and error highlighting is replaced with the regular focus: +当用户更改值时，错误提示应消失，高亮会替换为常规焦点： ![](fix_error.png){width=480} -When the focus is returned to the field with an error, use validation on input. Otherwise, it can be unclear for the user how to initiate validation. +当焦点返回到有错误的字段时，请对输入进行验证。否则，用户可能不知道如何进行验证。 -#### Implementation {id="implementation_2"} +#### 实现方式 {id="implementation_2"} -In [`Configurable`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/options/Configurable.java) panels, throw [`ConfigurationException`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/options/ConfigurationException.java) from `apply()` in case of errors. +当发生错误时，请从[`Configurable`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/options/Configurable.java)面板的`apply()`中抛出[`ConfigurationException`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/options/ConfigurationException.java)。 -Non-configurable panels: +非配置项的面板： @@ -217,7 +217,7 @@ textField() -Add `andStartOnFocusLost()` call on [`ComponentValidator`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/ComponentValidator.java) before installing it on a component: +在将[`ComponentValidator`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/ComponentValidator.java)安装到组件之前，请先调用`andStartOnFocusLost()`： ```java new ComponentValidator(parentDisposable) @@ -229,43 +229,42 @@ new ComponentValidator(parentDisposable) -### 3. Empty required fields in dialogs +### 3. 对话框中的必填字段为空{id="3-empty-required-fields-in-dialogs"} -#### Simple form +#### 简易表单 -If a form is simple, move the focus to the first required field and disable the confirmation button until all required fields have been filled. It is clear from the form behavior that input is required, showing validation messages is redundant. +如果表单简单，请将焦点移至第一个必填字段并禁用确认按钮，直到填写完所有必填字段。从表单行为中可以显然看出，输入是必需的，因此显示验证消息是多余的。 ![](simple_dialog.png){width=373} -#### Complex form +#### 复杂表单 -If a form is complex, always enable the confirmation button. Otherwise, it can be hard to understand what should be done to complete the form. +如果表单很复杂，请始终启用确认按钮。否则，可能很难理解应该怎样完成表单。 -Complex forms are: +复杂表单包括： -* Forms with more than 3 input fields or combo boxes. -* Forms with at least one control (checkbox, table, and so on) apart from an input field and a combo box. +* 具有3个以上输入字段或组合框的表单。 +* 除了输入字段和组合框之外，至少包含一个控件（复选框、表格等）的表单。 -**Never** validate empty required fields on input or focus loss. Users should be able to fill the form in a random order, so do not interrupt them. +**永远不要**在输入或失去焦点时验证空的必填字段。用户应该能够按随机顺序填写表格，因此请勿打断他们。 -#### How to use +#### 如何使用 -Validation is performed when the user clicks the confirmation button (for example, the "Add" button). +在用户单击确认按钮（例如，“Add”按钮）时执行验证。 -Highlight all invalid fields, move the focus to the first invalid field and show the tooltip. +高亮所有无效字段，将焦点移至第一个无效字段并显示工具提示。 ![](complex_dialog.png){width=912} -Hide the tooltip and the red highlighting when the user starts editing the invalid value or entering symbols into the empty required field. +当用户开始编辑无效值或在空的必填字段中输入符号时，隐藏工具提示和红色高亮。 -Show the error tooltip for the next field when it gets the focus, hover, or the user clicks the "Add" button one more time. +当用户进入或悬停在下一个字段，或用户再次单击“Add”按钮时，显示下一个字段的错误提示。 -#### Implementation {id="implementation_3"} +#### 实现方式 {id="implementation_3"} -By default, [`DialogWrapper`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java) disables OK button until -all fields that participate in validation become valid. +[`DialogWrapper`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java)默认会禁用确定按钮，直到所有无效字段均有效。 -Explicitly enable OK button for each input field: +为每个输入框显式启用确定按钮： @@ -285,161 +284,161 @@ new ValidationInfo("The host cannot be reached", myHostField) -### 4. Non-allowed or empty values in the main window +### 4. 主窗口中不允许的值或空值 {id="4-non-allowed-or-empty-values-in-the-main-window"} -If a non-allowed or an empty value is entered into a field that’s within the Properties view, for example, in UI Designers like the Android Studio Layout Editor, validate it on pressing Enter or focus loss. +如果在属性视图中的字段中输入了不允许的值或空值，比如在Android Studio布局编辑器等界面设计器中，请在回车或失去焦点时对其进行验证。 -#### How it works +#### 如何工作 -On Enter, the field is highlighted with red and the error tooltip appears. +回车时，高亮该字段并显示错误提示。 ![](main_window.png){width=379} -If validated on focus loss, the field is highlighted with light-red. The focus is not returned to the field automatically. +如果在失去焦点时验证，则该区域应以浅红色高亮。焦点不应自动返回到该字段。 -Hide the field highlighting and the tooltip when the user fixes the invalid value. +当用户处理无效值时，取消高亮并隐藏工具提示。 -### 5. Remote connection +### 5. 远程连接 {id="5-remote-connection"} -If validation is slow or attempts are limited, for example, due to connection to a remote server, validate values on sending the form. +如果验证速度较慢或尝试次数有限（例如连接到远程服务器时），请在发送表单时验证值。 -If it’s not possible to detect the fields with errors, show the error message inline under the fields: +如果无法检测到有错误的字段，请在下方内联显示错误消息： ![](example_inline.png){width=358} -An inline error only appears on clicking the confirmation button. The dialog is resized to fit the error message. Do **not** leave an empty space for the error in advance. +内联错误仅在单击确认按钮时显示。对话框的大小将调整至适应错误消息。请**不要**提前为错误留出空白处。 -Hide the error messages once any field related to the error is edited. Set the dialog to its original size when the error disappears. +编辑与错误相关的任何字段后，应隐藏错误消息并将对话框设置为其原始大小。 -#### Implementation {id="implementation_4"} +#### 实现方式 {id="implementation_4"} -[`ValidationInfo`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/ui/ValidationInfo.java) for messages in inline area is created with `null` component: +[`ValidationInfo`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/ui/ValidationInfo.java)内联消息由`null`组件创建： ```java new ValidationInfo( "The host cannot be reached. Check the address and credentials."); ``` -### 6. Complex values in multi-page dialogs +### 6. 多页对话框中的复杂值 {id="6-complex-values-in-multi-page-dialogs"} -If a value is complex, for example, a list of values, a regexp, or a value copied from another place, and it appears in a multi-page dialog, such as Settings, Project Structure or Run Configurations, show a dialog informing the user about an error on clicking the confirmation button. +如果一个值很复杂，比如值列表、正则表达式或从其他位置复制的值，并且它出现在多页对话框（如设置、项目结构或运行配置）中，则应显示一个对话框，告知用户在单击确认按钮时出现错误。 -For example, in a complex Resource patterns field +例如，在复杂的Resource patterns字段中 ![](comlex_field.png){width=694} -show the following dialog on pressing the confirmation button: +在按下确认按钮时应显示以下对话框： ![](confirmation_dialog.png){width=409} -It should be possible to close the Settings dialog and save the entered data if the user wants to fix the values later or needs additional data outside of the modal Settings dialog. +如果用户想稍后修复值或需要在模态设置对话框之外的其他数据，应能够关闭设置对话框并保存输入的数据。 -If an invalid field is not empty, highlight it on reopening the Settings dialog or report the error when the entered data is used. +如果无效字段不为空，请在重新打开设置对话框时高亮该字段，或者在使用输入的数据时显示错误。 -## Tooltip +## 工具提示

-An error tooltip appears in two cases: +错误提示在两种情况下出现：

-If the field with an error gets focus: +当有错误的字段获得焦点时： ![](example_tooltip.png){width=235} -If the field loses focus, hide the tooltip and highlight the field with light-red: +该字段失去焦点后，应隐藏提示并以浅红色高亮： ![](incorrect_symbol_non_focused.png){width=206} -On hover over the field or the element with an error: +当鼠标悬停在有错误的字段或元素上时： ![](incorrect_symbol_hover.png){width=235} ![](validation_table_hover.png){width=429} -Show the tooltip above the field and move it 40px right, so that the controls above it are not overlapped. -If there is important info above the field, the tooltip can be shown on the right. +在字段上方显示提示，并将其向右移动40px，确保不会与其上方的控件重叠。 +如果字段上方有重要信息，则提示可以显示在右侧。 -## Error message text +## 错误信息文本 -An error message describes the problem and provides the way to solve it if it’s not clear from the problem description. +错误消息应描述问题；如果问题描述不清楚，则应提供解决问题的方法。 ![](message_short.png){width=319 style=block} -*It’s clear how to fix the error from the error description.* +*从错误描述中可以清楚地了解如何修复* ![](message_long.png){width=456 style=block} -*The way to solve the problem is provided.* +*提供了解决问题的方法* -Describe the problem in terms of target users’ actions or goals, not in terms of the program’s architecture. +根据目标用户的行为或目的来描述问题，而不是从程序的架构来描述问题。 - - + + - +
Incorrect Invalid Git Executable. Error running "git.exe". File not found: "git.exe". 错误 Invalid Git Executable. Error running "git.exe". File not found: "git.exe".
Correct 正确 Cannot run "git.exe". The file is not found.
-Provide specific names, locations, and values of the objects involved: +提供所涉及对象的具体名称、位置和值： - + - +
Incorrect 错误
Correct 正确
-For a period at the end of an error message, see [Punctuation](punctuation.md#period). +有关错误消息末尾的句点，请参阅[标点符号](punctuation.md#period)。 -Make the error message short and descriptive. See [Writing short and clear](writing_short.md). +错误消息应言简意赅，请参阅[](writing_short.md)。 -Examples of common errors and corresponding error messages: +常见错误和相应错误消息的示例： - - + + - - + + - - + + - - + - - + + - - + +
Error type Error message 错误 错误消息
Empty required field Specify the port number 必需字段为空 请指定端口号
Incorrect symbol "/" is not an allowed symbol 错误的符号 不能包含“/”
Incorrect value

The port number should be between XXX and XXXX

-

The file name should be at least 4 symbols

-

The name is already in use

-

The username or password is incorrect

+ 		错误的值

端口号应在XXX和XXXX之间

+

文件名应至少有4个字符

+

该名称已被使用

+

用户名或密码不正确
Incorrect format The email format should be xxx@xxx.com 格式错误 邮箱的格式应为xxx@xxx.com
Missing file The file is not found 文件不存在 文件不存在
-Use encouraging tone: +使用鼓励的语气： - - + + @@ -457,21 +456,29 @@ Use encouraging tone: + + + + + + + +
Do not use Use 不要使用 使用
Error, failure Must Should be
非法，无效 错误
必须 应该
-## Warning +## 警告 ![](validation_warning.png){width=336} -A warning informs the user that something is configured incorrectly, but does not prevent them from applying the changes. +警告会通知用户某些配置不正确，但不会阻止他们应用更改。 -A warning can appear on input, focus loss, or on reopening a filled form. For example, make the empty field Target name show a warning on reopening: +在输入、失去焦点或重新打开已填写的表单时，可能会出现警告。例如，空字段Target name在重新打开时会显示警告： ![](warning_dialog.png){width=580} -The warning can be shown: +警告可以在这些地方显示： -In a tooltip for a specific field. Follow the rules for [the error tooltip](tooltip.md). +在某个特定字段的工具提示中。请遵循[错误提示](tooltip.md)的规则。 @@ -491,48 +498,48 @@ new ValidationInfo("Target name is not specified", myNameField) -On the form under the controls. Show the message with the yellow warning icon. +在控件下方。请同时显示一个黄色的警告图标。 ![](warning_inline.png){width=303} -On the "Problems" page in complex multipage dialogs. Show warnings and fix options: +对于复杂的多页对话框，可以显示在“问题”（Problems）页上。请一同显示警告和修复建议： ![](problems.png){width=418 style=block} -*Problems page in the Project Structure dialog.* +*项目结构对话框中的问题页面* -Mark all navigation elements for areas that contain warnings with yellow icons. +用黄色图标标记包含警告的所有导航栏元素。 -Update the problem counter when a problem is detected. When all problems have been fixed, do not show the "Problems" tab. +在检测到问题时更新问题计数器。修复所有问题后，请不要显示问题选项。 -On a particular page, highlight the element that contains a warning in yellow or add a warning icon next to it. +在特定页面上，用黄色高亮包含警告的元素，或在它旁边添加警告图标。 -## UI elements with validation errors +## 存在验证错误的UI元素 -### Input field +### 输入框 ![](example_tooltip.png){width=235} -Add a red light bulb on the right side of the input field if an action to fix the error is available: +如果有修复建议可用，请在输入框的右侧添加一个红色灯泡： ![](input_field_bulb.png){width=729} -### Combo box +### 组合框 ![](combo_box.png){width=235} -### Tables and lists +### 表格和列表 ![](table_error.png){width=429} -When the field in a table loses focus, show an error icon. An error tooltip appears on mouse hover or when the line gets focus: +当表中的字段失去焦点时，应显示错误图标。鼠标悬停或特定行获得焦点时，应显示错误提示： ![](validation_table_hover.png){width=429} -Use a warning icon for warnings: +警告应使用警告图标： ![](table_warning.png){width=429} -#### Implementation +#### 实现方法 @@ -590,53 +597,53 @@ firstColumn.setCellRenderer(new DefaultTableCellRenderer() { -### Trees and lists +### 树和列表 -Add an error or warning icon on the right side of the invalid line. +在无效行的右侧添加错误或警告图标。 ![](list.png){width=647} -### Multi-page dialog +### 多页对话框 -If validation in a multipage form can be performed only by clicking the confirmation button, then: +如果多页表单中的验证只能在单击确认按钮后执行，则： -* Use red highlighting for navigation elements such as tabs, menu and list items for areas that contain errors so that the user can quickly locate the error. -* Open the first page with an error or stay on the opened page if it has errors on clicking the confirmation button. +* 对包含错误的导航元素（如选项卡、菜单和列表项）使用红色高亮，以便用户可以快速找到错误。 +* 打开有错误的第一页，或者停留在打开的页面上。 ![](multipage1.png){width=1014} -## Avoid mistakes +## 避免错误 -Do not show an error in a message box. Users are pulled out of the context, they need to close the dialog and locate the invalid field. +请不要在消息框中显示错误。用户被迫脱离上下文，他们需要关闭对话框并重新找到无效字段。 ![](message_box.png){width=472} -Do not allow to click "OK" button if a form contains empty required fields. For this, the Cancel button should be used, and the OK button should be disabled. Otherwise, if users accidentally leave the field empty, they can expect that the value was entered correctly. +如果表单包含空的必填字段，则不应允许单击“确定”按钮。为此，应启用取消按钮，并禁用确定按钮。否则，如果用户不小心将字段留空，他们会认为输入的值是正确的。 ![](wildcard.png){width=521} -Do not show an error message inside the empty required field. It looks like a prefilled field, not like an error message. +请不要在空的必填字段中显示错误消息。这会看起来像一个预填充的字段，而不是一条错误消息。 ![](goto_line.png){width=438} -Do not underline the field label. It looks like a spell error and poorly visible. +请不要为字段标签添加下划线。这会看起来像一个拼写错误，而且不清楚。 ![](underline.png){width=278} -Do not shake a form and show an error with a delay. A shaking form is distracting and time-consuming. +请不要摇晃表单并延迟显示错误。晃动的表单会分散注意力，消耗更多时间。 ![](new_class.png){width=445} -Do not show an error immediately after opening a form. It distracts the user from filling the form. +打开表单后请不要立即显示错误。这会分散用户填写表单的注意力。 ![](add_tfs.png){width=350} -Do not allow submitting the form with the error. -When the form is opened again, the value is reset, so users don’t know if they entered incorrect data. +请不要允许提交包含错误的表单。 +再次打开表单时，该值将被重置，这样用户不知道他们的输入是否正确。 ![](save.png){width=471} -## Insets and colors +## 间距及颜色 ![](tooltip_insets.png){width=534} diff --git a/topics/user_interface_components/dialog_wrapper.md b/topics/user_interface_components/dialog_wrapper.md index ecaae754517..49ad82a2808 100644 --- a/topics/user_interface_components/dialog_wrapper.md +++ b/topics/user_interface_components/dialog_wrapper.md @@ -43,34 +43,33 @@ * 重写 `getDimensionServiceKey()` 方法返回用于持久化对话框大小的标识符。 * 重写 `getHelpId()` 方法返回与对话框关联的上下文帮助主题（参见 [上下文帮助](ide_infrastructure.md#context-help)）。 -#### Dialog Content +#### 对话框内容 -Use [Kotlin UI DSL](kotlin_ui_dsl_version_2.md) to provide the dialog's contents (see [samples](#kotlin)). -Alternatively or when using Java, the `DialogWrapper` class can be used together with [GUI Designer forms](https://www.jetbrains.com/help/idea/gui-designer-basics.html). -In this case, bind a GUI Designer form to the class extending `DialogWrapper`, bind the top-level panel of the form to a field and return that field from the `createCenterPanel()` method. +使用[Kotlin UI DSL](kotlin_ui_dsl_version_2.md)提供对话框的内容（参见[样例](#kotlin)）。 +其它时候或使用Java时，可以使用`DialogWrapper`，并参考[GUI Designer forms](https://www.jetbrains.com/help/idea/gui-designer-basics.html)。 +这种情况下，可以将GUI设计表绑定到一个`DialogWrapper`的子类，并将其顶级面板绑定到`createCenterPanel()`方法返回的字段上。 > 请查看 [UI Guidelines](layout.md) 主题，获取关于如何在对话框中布置 UI 控件的建议。 > > Existing dialogs can be inspected at runtime using [UI Inspector](internal_ui_inspector.md), for example, to locate the underlying implementation of UI components. > -#### Displaying the Dialog +#### 显示对话框 要显示对话框，请调用 `show()` 方法，然后使用 `getExitCode()` 方法来检查对话框如何关闭（参见 `DialogWrapper#OK_EXIT_CODE, CANCEL_EXIT_CODE, CLOSE_EXIT_CODE`）。 可以使用 `showAndGet()` 方法来结合这两个调用。 -#### Customizing Buttons +#### 自定义按钮 -To customize the buttons displayed in the dialog (replacing the standard OK/Cancel/Help set of buttons), override either the `createActions()` or `createLeftActions()` methods. -Both of these methods return an array of Swing Action objects. -If a button closes the dialog, use [`DialogWrapperExitAction`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java) as the base class for the action. +重写`createActions()`或者`createLeftActions()`方法来自定义按钮（替换掉标准的OK/Cancel/Help按钮）。 +这两个方法都返回Swing Action对象数组。 +如果一个按钮会关闭对话框，请使用[`DialogWrapperExitAction`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java)作为该action的基类。 -Use `action.putValue(DialogWrapper.DEFAULT_ACTION, true)` to set the default button and -`action.putValue(DialogWrapper.FOCUSED_ACTION, true)` to set the focused button. +请使用`action.putValue(DialogWrapper.DEFAULT_ACTION, true)`设置默认按钮，使用`action.putValue(DialogWrapper.FOCUSED_ACTION, true)`设置聚焦的按钮。 ### 输入验证 {id=input-validation} -See also [](validation_errors.md) topic in UI Guidelines. +另请参考UI指南中的[](validation_errors.md)。 要验证输入到对话框中的数据，请重写 `doValidate()` 方法。 该方法将由定时器自动调用。 diff --git a/topics/user_interface_components/kotlin_ui_dsl_version_2.md b/topics/user_interface_components/kotlin_ui_dsl_version_2.md index 95a1d76b8e2..5aae698bb2c 100644 --- a/topics/user_interface_components/kotlin_ui_dsl_version_2.md +++ b/topics/user_interface_components/kotlin_ui_dsl_version_2.md @@ -3,52 +3,52 @@ # Kotlin UI DSL Version 2 -Kotlin DSL for creating UI forms with input components bound to a state object. +Kotlin DSL，用于创建将输入绑定到状态对象的表单界面。 -**UI Guidelines:** [](layout.md) +**UI指南** [](layout.md) -> This page describes API available in IntelliJ Platform releases **2021.3 and later** only. +> 该页面仅描述**2021.3及更新**版本的IntelliJ平台API > -> See [](kotlin_ui_dsl.md) for targeting earlier releases. +> 对于更早的版本，请参阅[](kotlin_ui_dsl.md) > -Kotlin UI DSL Version 2 allows creating UI forms with input components bound to state objects. -The forms are built by using a declarative Kotlin syntax and follow the official IntelliJ Platform UI conventions described in the [](ui_guidelines_welcome.topic). -The library is written in [Kotlin](using_kotlin.md) and makes it easy to develop user interfaces like [dialogs](dialog_wrapper.md) and [settings pages](settings.md). +Kotlin UI DSL版本2允许创建将输入组件绑定到状态对象的表单界面。 +这些表单是使用声明式Kotlin语法构建的，并遵循[](ui_guidelines_welcome.topic)中描述的官方IntelliJ平台UI约定。 +该库是用[Kotlin](using_kotlin.md)编写的，可以轻松开发[对话框](dialog_wrapper.md)和[设置](settings.md)等用户界面。 -The Kotlin UI DSL is not intended to build general UIs, like [tool windows](tool_window.md) controls that trigger some actions and do not contain any input components bound to state objects. -For this purpose, use [custom Swing components](user_interface_components.md) from the IntelliJ Platform or the standard ones. +Kotlin UI DSL并不用于构建所有界面，例如[](tool_window.md)，这些控件会产生某些行为，并且不包含绑定到状态对象的任何输入组件。 +为此，请使用IntelliJ平台中的[Swing组件](user_interface_components.md)或标准Swing组件。 -The _Kotlin UI DSL Version 2_ functions are located in the [`com.intellij.ui.dsl.builder`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder) package. +_Kotlin UI DSL Version 2_ 功能在[`com.intellij.ui.dsl.builder`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder)包中。 -## UI DSL Examples +## UI DSL示例 -It is highly recommended to take a look at the UI DSL demo available via Tools | Internal Actions | UI | UI DSL Showcase (see [Internal Actions](internal_actions_intro.md) if not available in your IDE instance). +强烈建议您查看UI DSL示例，该示例可通过Tools | Internal Actions | UI | UI DSL Showcase。（如果在您的IDE中不可用，请参阅[](internal_actions_intro.md)） -It describes some UI DSL basics and contains explanations, tips, a list of all available components, and many examples with links to the source code. +它描述了一些UI DSL的基础知识，并包含解释、提示、可用组件的列表以及许多带有源代码链接的示例。 -> All sections below refer to the relevant tab available in this demo: +> 所有如下形式的段落均指向该示例中提供的相关选项卡： > -> **UI DSL Showcase Tab**: _Tab Name_ (Link to sources of demonstration tab) +> **UI DSL展示标签页：** _标签页名称_（标签页的源码链接） > -> To understand how a component visible in the IDE is created in code, see the component's [`added-at` property in the UI Inspector](internal_ui_inspector.md#added-at-property). -> Note that it is not limited only to components created with Kotlin UI DSL, but helps to understand the creation of any visible Swing component. +> 为弄清IDE中的可见组件是如何在代码中创建出来的，请参阅[UI查看器中的`added-at`属性](internal_ui_inspector.md#added-at-property) +> 请注意，它不仅限于使用Kotlin UI DSL创建的组件，还有助于理解任何可见Swing组件的创建。 > -## UI DSL Basics +## UI DSL基础 -**UI DSL Showcase Tab**: Basics (Sources: [`DemoBasics`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoBasics.kt)) +**UI DSL展示标签页：** Basics（源码：[`DemoBasics`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoBasics.kt)） -See the following simple example of UI DSL: +请看这个简单的UI DSL例子： ```kotlin panel { @@ -58,29 +58,29 @@ panel { } ``` -Building content of any form starts from `panel {` which returns [`DialogPanel`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/DialogPanel.kt) filled with components described inside the panel block. -A panel consists of any number of rows marked with `row` tag created vertically from top to bottom. +所有内容的构建均从`panel {`开始，并返回一个[`DialogPanel`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/DialogPanel.kt)，其中填充了代码中描述的组件。 +一个面板可以包含任意数量的行，每一行标记了`row`，从上往下排列。 -Every row consists of cells where the last cell in a row occupies the remaining width. -Inside one row, cells are added from left to right in the same order calls to factory methods or `cell()` appear in each row. -Cells can contain one component or a sub-panel. +每一行都由单元格组成，最后一个单元格会占全部剩余空间。 +每一行内单元格从左往右排列，顺序与调用工厂方法或`cell()`的顺序相同。 +单元格内可以有一个组件或子面板。 -If there are unoccupied cells at the end of a row, they are merged into one cell with the last non-empty cell. +如果一行的最后有未被占用的单元格，它们会被合并到最后一个被占用的单元格中。 ## `Panel` -[`Panel`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder/Panel.kt) is the start interface for building content. -It can consist of several rows and different UI groups. +[`Panel`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder/Panel.kt)是构建内容的开始。 +它由多行以及不同的UI组构成。 ### `Panel.row` -Adds row with the label if present. +添加一行，标签可选。 ### `Panel.indent` -**UI DSL Showcase Tab**: Gaps (Sources: [`DemoGaps`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGaps.kt)) +**UI DSL展示标签页：** Gaps（源码：[`DemoGaps`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGaps.kt)） -Adds standard left indent: +添加标准的左缩进： ```kotlin row { @@ -95,24 +95,26 @@ indent { ### `Panel.separator` -**UI DSL Showcase Tab**: Groups (Sources: [`DemoGroups`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGroups.kt)) +**UI DSL展示标签页：** Groups（源码：[`DemoGroups`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGroups.kt)） -Adds horizontal line separator with an optional title. +添加一个水平分界线，标题可选。 ### `Panel.panel` -Creates a sub-panel that occupies the whole width and uses its own grid inside. +创建一个子面板，该子面板占据整个宽度，并在内部使用自己的网格。 ### `Panel.rowsRange` Creates a grouped rows range to perform operations on them like `enabled`, `enabledIf` etc. All rows use the parent grid. +创建分组行区域，可以对它们进行像`enabled`、`enabledIf`一类的操作。 +所有行都使用父网格。 ### `Panel.group` -**UI DSL Showcase Tab**: Groups (Sources: [`DemoGroups`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGroups.kt)) +**UI DSL展示标签页：** Groups（源码：[`DemoGroups`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGroups.kt)） -Adds a panel with an independent grid, optional title, and some vertical space above and below the group. +添加一个面板，该面板具有独立的网格、可选标题以及上方和下方的一些垂直间距。 ```kotlin group("Title") { @@ -124,13 +126,13 @@ group("Title") { ### `Panel.groupRowsRange` -Similar to `Panel.group()` method but uses the same grid as the parent. +类似于`Panel.group()`，使用与父面板一样的网格。 ### `Panel.collapsibleGroup` -**UI DSL Showcase Tab**: Groups (Sources: [`DemoGroups`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGroups.kt)) +**UI DSL展示标签页：** Groups（源码：[`DemoGroups`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGroups.kt)） -Adds a collapsible panel with independent grid, title, and some vertical space above and below the group. +添加一个可折叠面板，该面板具有独立的网格、标题以及上方和下方的一些垂直间距。 ```kotlin collapsibleGroup("Title") { @@ -142,10 +144,10 @@ collapsibleGroup("Title") { ### `Panel.buttonsGroup` -**UI DSL Showcase Tab**: Groups (Sources: [`DemoGroups`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGroups.kt)) +**UI DSL展示标签页：** Groups（源码：[`DemoGroups`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGroups.kt)） -Unions `Row.radioButton` in one group. -Must also be used for `Row.checkBox` if these are grouped with a title. +将`Row.radioButton`组合到同一组中。 +如果一组`Row.checkBox`有标题，也请使用该组件。 ```kotlin var value = true @@ -161,24 +163,22 @@ buttonsGroup("Panel.buttonsGroup:") { ### `Panel.onApply`/`onReset`/`onIsModified` -Registers callbacks that will be called from `DialogPanel.apply()`/`reset()`/`isModified()` methods. +注册回调方法，这些回调会在`DialogPanel.apply()`/`reset()`/`isModified()`中调用。 ## `Row` -Every row is represented by the [`Row`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder/Row.kt) interface. -It contains all available factory methods for creating components (like `button()`, `label()`, `textField()`, etc.) and methods for row configuration. +每一行都实现了[`Row`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder/Row.kt)接口，其中包含了用于创建组件的工厂方法（例如`button()`，`label()`，`textField()`等），以及配置该行的方法。 ### `Row.layout` -**UI DSL Showcase Tab**: Row Layout (Sources: [`DemoRowLayout`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoRowLayout.kt)) +**UI DSL展示标签页：** Row Layout（源码：[`DemoRowLayout`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoRowLayout.kt)） -There are three possible layouts: -- `INDEPENDENT`: all cells of the row (including label if present) independent of the parent grid. - That means this row has its own grid. -- `LABEL_ALIGNED`: label is aligned with the parent grid, other components independent of the parent grid. -- `PARENT_GRID`: all components, including label (if present), are in the parent grid. +有三种布局： +- `INDEPENDENT`：该行的所有单元格（包括可能存在的标签）都独立于父网格，即拥有它自己的网格。 +- `LABEL_ALIGNED`: 标签对齐到父网格，其它组件独立于父网格。 +- `PARENT_GRID`: 所有组件（包括可能存在的标签）均位于父网格中。 -The default value is `LABEL_ALIGNED` when a label is provided for the row, `INDEPENDENT` otherwise. +提供了标签时，默认值为`LABEL_ALIGNED`，否则为`INDEPENDENT`。 ```kotlin row("Label:") { @@ -189,8 +189,8 @@ row("Long label:") { } ``` -Here both labels are aligned together because rows have `LABEL_ALIGNED` by default. -If an independent layout is needed, then `INDEPENDENT` layout should be used: +这个实例中标签都对齐了，因为行的默认布局为`LABEL_ALIGNED`。 +像这样使用`INDEPENDENT`布局： ```kotlin row("Long label:") { @@ -200,22 +200,22 @@ row("Long label:") { ### `Row.resizableRow` -The row becomes resizable and occupies all vertical free space. -For several resizable rows, extra free space is divided between rows equally. +该行将可调整大小，并占用所有可用的垂直间距。 +对于多个可调整大小的行，剩余的可用空间将在各行之间平均分配。 ### `Row.rowComment` -**UI DSL Showcase Tab**: Comments (Sources: [`DemoComments`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoComments.kt)) +**UI DSL展示标签页：** Comments（源码：[`DemoComments`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoComments.kt)） -Adds comment after the row with an appropriate color and font. -Visibility and enabled state of the row affects row comment as well. +向行尾添加适当颜色和字体的注释。 +行的可见性和启用状态也会影响行注释。 ### `Row.cell` -Adds `component`. -Use it only for custom specific components, all standard components like `label()`, `button()`, `checkbox()` etc. are covered by dedicated [`Row`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder/Row.kt) factory methods. +添加`component`。 +仅在添加自定义控件时调用，标准的控件（比如`label()`，`button()`，`checkbox()`等）可以使用[`Row`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder/Row.kt)中专门的工厂方法。 -For example, there is no method for password field so that the following code can be used: +例如，没有添加密码字段的方法，因此可以使用以下代码： ```kotlin val passwordField = JPasswordField() @@ -226,29 +226,28 @@ row { ### `Row.scrollCell(component)` -Adds `component` wrapped with [`JBScrollPane`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBScrollPane.java). +添加`component`，并使用[`JBScrollPane`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBScrollPane.java)包装它。 ### `Row.topGap`/`bottomGap` -Adds a gap above/below the current row. -It is visible together with the row. -By default, `NONE` is used. -Between unrelated settings, `SMALL` can be used. -`MEDIUM` is used between groups and usually set automatically by `group()` method and similar ones. +在当前行的上方/下方添加间隙，它与行一同显示。 +默认值为`NONE`。 +在无关的设置之间，可以使用`SMALL`。 +`MEDIUM`在组之间使用，通常由`group()`方法和类似的方法自动设置。 ### `Row.visible`/`enabled` -**UI DSL Showcase Tab**: Enabled/Visible (Sources: [`DemoAvailability`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoAvailability.kt)) +**UI DSL展示标签页：** Enabled/Visible（源码：[`DemoAvailability`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoAvailability.kt)） -Sets visibility/enabled state of the row, including row comment (see `Row.rowComment`) and all children recursively. -The row is invisible/disabled if there is an invisible/disabled parent. +递归设置行的可见性/启用状态，包括行注释（参见`Row.rowComment`）和所有子项。 +如果其父项是不可见/禁用的，则该行也是不可见/禁用的。 ### `Row.visibleIf`/`enabledIf` -**UI DSL Showcase Tab**: Enabled/Visible (Sources: [`DemoAvailability`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoAvailability.kt)) +**UI DSL展示标签页：** Enabled/Visible（源码：[`DemoAvailability`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoAvailability.kt)） -Binds row visibility/enabled state to the provided predicate. -Below is an example of a checkbox whose enabled state depends on another checkbox: +将行可见性/启用状态绑定到提供的谓词。 +下面是一个复选框的示例，其启用状态取决于另一个复选框： ```kotlin lateinit var checkBox: Cell @@ -262,27 +261,24 @@ row { ### `Row.panel` -**UI DSL Showcase Tab**: Groups (Sources: [`DemoGroups`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGroups.kt)) +**UI DSL展示标签页：** Groups（源码：[`DemoGroups`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGroups.kt)） -Creates a sub-panel inside the cell of the row. -The panel contains its own set of rows and cells. -For example, it is possible to create several columns by creating a row with several panels inside. +在行的单元格内创建一个子面板。该面板包含其自己的行和单元格。例如，可以通过创建一个包含多个面板的行来创建多个列。 ## `Cell` -Every component in the UI DSL builder is wrapped into [`Cell`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder/Cell.kt) class. -Standard components should not be created directly but with factory methods from [`Row`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder/Row.kt) class like `checkBox()`, `button()` and others because of additional functionality, e.g., `textField()` is configured with the column's width, radio buttons are placed into radio buttons groups. +所有UI DSL构建器中的组件都被包装成了[`Cell`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder/Cell.kt)类。 +由于一些组件的附加功能，标准组件不能直接创建，只能通过[`Row`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder/Row.kt)里面的工厂方法（`checkBox()`，`button()`等）来创建，比如`textField()`需要与列宽一起配置，单选按钮需要放置进单选按钮组。 ### `Cell.component` -`JComponent` that occupies the cell. +占据该单元格的`JComponent`。 -### `Cell.horizontalAlign`/`verticalAlign` -{#cell-horizontalVerticalAlign} +### `Cell.horizontalAlign`/`verticalAlign` {#cell-horizontalVerticalAlign} -> Deprecated in 2022.3, use [](#cell-align) instead. +> 从2022.3起弃用，请使用[](#cell-align)。 -Sets horizontal/vertical alignment of content inside the cell. +设置单元格内内容的水平/垂直对齐方式。 ```kotlin row("Row:") { @@ -291,17 +287,16 @@ row("Row:") { } ``` -### `Cell.align` -{#cell-align} +### `Cell.align` {#cell-align} _2022.3_ -Updates horizontal and/or vertical alignment of the component inside the cell. -Default alignment is `AlignX.LEFT` and `AlignY.CENTER`. +更新单元格内组件的水平和/或垂直对齐方式。 +默认为`AlignX.LEFT`和`AlignY.CENTER`。 -To stretch the content on whole cell, use `AlignX.FILL`/`AlignY.FILL`/`Align.FILL`. -For setting both horizontal and vertical alignment, use `Align` constants or overloaded plug operator -like `align(AlignX.LEFT + AlignY.TOP)`. +要使内容充满整个单元格，请使用`AlignX.FILL`/`AlignY.FILL`/`Align.FILL`。 +对于设置水平和垂直对齐方式，请使用`Align`常量或重载plug operator +，比如`align(AlignX.LEFT + AlignY.TOP)`。 ```kotlin row("Row:") { @@ -312,12 +307,12 @@ row("Row:") { ### `Cell.resizableColumn` -**UI DSL Showcase Tab**: Tips (Sources: [`DemoTips`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoTips.kt)) +**UI DSL展示标签页：** Tips（源码：[`DemoTips`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoTips.kt)） -Marks column of the cell as resizable: the column occupies all extra horizontal space in the panel and changes size together with the panel. -It's possible to have several resizable columns, which means extra space is shared between them. -There is no need to set resizable for cells in different rows, but in the same column: it has no additional effect. -Note that the size and placement of components in columns are managed by [](#cell-align) ([](#cell-horizontalVerticalAlign) for pre-2022.3). +将单元格的列标记为可调整大小：该列占据面板中所有剩余的水平空间，并随面板一起改变大小。 +可以有多个可调整大小的列，它们将共享剩余的空间。 +除了将在同一列的组件设为可调整大小之外，对不同行的组件设置此属性没有任何作用。 +注意，列中组件的大小和位置由[](#cell-align)管理。（2022.3之前的版本是[](#cell-horizontalVerticalAlign)） ```kotlin row("Row") { @@ -329,12 +324,12 @@ row("Row") { ### `Cell.gap` -**UI DSL Showcase Tab**: Gaps (Sources: [`DemoGaps`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGaps.kt)) +**UI DSL展示标签页：** Gaps（源码：[`DemoGaps`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoGaps.kt)） -Separates the next cell in the current row with `rightGap`. -`RightGap.SMALL` gap is set after row label automatically by `Panel.row()` methods. +使用`rightGap`分隔当前行中的下一个单元格。 +`Panel.row()`方法会自动在行标签后设置`RightGap.SMALL`间隙。 -Below are some cases where `RightGap.SMALL` should be used: +以下是一些应使用`RightGap.SMALL`的情况 ```kotlin row { @@ -351,16 +346,15 @@ row("Width:") { ### `Cell.visible`/`enabled` -**UI DSL Showcase Tab**: Enabled/Visible (Sources: [`DemoAvailability`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoAvailability.kt)) +**UI DSL展示标签页：** Enabled/Visible（源码：[`DemoAvailability`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoAvailability.kt)） -Sets visibility/enabled state of the cell and all children recursively. -The cell is invisible/disabled if there is an invisible/disabled parent. +递归设置单元格及其所有子元素的可见性/启用状态。如果存在不可见/禁用的父级，则单元格将不可见/禁用。 ### `Cell.visibleIf`/`enabledIf` -**UI DSL Showcase Tab**: Enabled/Visible (Sources: [`DemoAvailability`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoAvailability.kt)) +**UI DSL展示标签页：** Enabled/Visible（源码：[`DemoAvailability`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoAvailability.kt)） -Binds cell visibility/enabled state to the provided predicate. +将单元格的可见性/启用状态与提供的谓词绑定。 ```kotlin row { @@ -373,12 +367,12 @@ row { ### `Cell.comment` -**UI DSL Showcase Tab**: Comments (Sources: [`DemoComments`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoComments.kt)) +**UI DSL展示标签页：** Comments（源码：[`DemoComments`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoComments.kt)） -Adds comment under the cell aligned by left edge with an appropriate color and font size (macOS uses smaller font). -Comment can contain HTML tags except ``, which is added automatically. -The comment occupies the available width before the following comment (if present) or the whole remaining width. -Visibility and enabled state of the cell affect comment as well. +在单元格左边缘下方添加注释，使用适当的颜色和字体大小（macOS应使用较小字体）。 +注释可包含除``外的HTML标签（该标签会自动添加）。 +如果存在后续注释，注释会占据后续注释前的可用宽度，否则占据剩余全部宽度。 +单元格的可见性和启用状态同样影响注释。 ```kotlin row("Label:") { @@ -389,11 +383,12 @@ row("Label:") { ### `Cell.label` -**UI DSL Showcase Tab**: Components Labels (Sources: [`DemoComponentLabels`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoComponentLabels.kt)) +**UI DSL展示标签页：** Components Labels（源码：[`DemoComponentLabels`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoComponentLabels.kt)） -Adds label at the specified position. +在指定位置添加标签。 `LabelPosition.TOP` labels occupy available width before the next top label (if present) or the whole remaining width. -Visibility and enabled state of the cell affect the label as well. +`LabelPosition.TOP`类型的标签会占据下一个顶部标签前的可用宽度（如果存在），否则占据全部剩余宽度。 +单元格的可见性和启用状态同样影响标签。 ```kotlin row { @@ -404,36 +399,33 @@ row { ### `Cell.onApply`/`onReset`/`onIsModified` -Registers callbacks that will be called for the component from `DialogPanel.apply()`/`reset()`/`isModified()` methods. +注册通过`DialogPanel.apply()`/`reset()`/`isModified()`方法调用组件时的回调函数。 -## Placeholder +## 占位符 {id="placeholder"} -Used as a reserved cell in the layout. -It can be created by `Row.placeholder()` method and populated by content later via component property or reset to `null`. +用作布局中的预留单元格。 +可通过`Row.placeholder()`方法创建，后续可通过组件属性填充内容或重置为`null`。 -## Bindings +## 绑定 -It is possible to bind component values to properties with the following methods. +可通过以下方法将组件值绑定到属性： ### `Cell.graphProperty` -> Removed in 2023.3, use `validationRequestor(property::afterPropagation)` instead. +> 已在 2023.3 版本移除，请改用 `validationRequestor(property::afterPropagation)`。 -Binds `component` value changing to property. -The property is updated when the value is changed and is not related to `DialogPanel.apply()`. -The method is rarely used directly. -There are many extensions for specific components described in [](#cellbind). +将`component`的值的变更绑定到属性。 +属性会在值更改时更新，且与`DialogPanel.apply()`无关。 +此方法很少直接使用，对具体的组件有许多扩展方法（详见[](#cellbind)）。 ### `Cell.bind` -**UI DSL Showcase Tab**: Binding (Sources: [`DemoBinding`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoBinding.kt)) +**UI DSL展示标签页：** Binding（源码：[`DemoBinding`](%gh-ic%/platform/platform-impl/internal/src/com/intellij/internal/ui/uiDslShowcase/DemoBinding.kt)） -Binds `component` value provided by `componentGet` and `componentSet` methods to the specified binding property. -The property is applied only when `DialogPanel.apply()` is invoked. -Methods `DialogPanel.isModified()` and `DialogPanel.reset()` are also supported automatically for bound properties. +通过`componentGet`和`componentSet`方法将`component`绑定到指定属性。 +该属性仅在调用`DialogPanel.apply()`时生效，`DialogPanel.isModified()`和`DialogPanel.reset()`方法也会自动支持绑定的属性。 -The `bind()` method is rarely used directly. -There are many extensions for specific components, see the following example: +`bind()`方法很少直接使用，具体的组件有许多扩展方法，示例如下： ```kotlin row { @@ -469,41 +461,40 @@ buttonsGroup(title = "radioButton:") { }.bind(model::radioButtonColor) ``` -## Version 1 and 2 Comparison +## 版本1与版本2对比 -In UI DSL version 2, some crucial problems from version 1 have been fixed, so porting is highly desirable. -See [](#migration-from-version-1) on how to port existing UI DSL code from version 1 to version 2 API. -Version 1 is deprecated and will be removed in future platform releases. +在UI DSL版本2中，已修复了版本1存在的重要问题，因此强烈建议进行迁移。 +关于如何将现有UI DSL代码从版本1迁移到版本2 API，请参见[](#migration-from-version-1)。 +版本1已弃用，将在未来平台版本中移除。 -The following significant changes were made: +主要变更如下： -- Reduced API, which allows conceiving API easier and faster. - Example: there were 5 overloaded methods `Cell.checkBox()` in version 1, now only one method remains. - Functionality for binding properties is extracted into `Cell.bindSelected()` methods. -- UI DSL became stricter, so the available API in every context is much smaller. - Example: code like `row { row {` is forbidden now. -- Structured API is mostly based on interfaces, because it's easier to learn API by grouped methods. - Only a small part of the API is implemented as extensions. -- KDoc is widely used. -- MIG layout is fully removed from the new UI DSL and replaced by `GridLayout`. - Because MIG layout is an external library, it's hard to fix bugs there (e.g., there are layout problems when components become invisible) and extend its functionality. - Fixed focus ring cropping problems: when components are placed near the panel border focus ring could be cropped if panel insets do not specify enough space. -- Implemented [Placeholder](#placeholder) that allows replacing components at runtime after content is shown. +- 精简API：降低学习成本，提升开发效率。 + 例如：版本1中`Cell.checkBox()`有5个重载方法，现仅保留1个方法。属性绑定功能被提取到`Cell.bindSelected()`方法中。 +- 更严格的约束：每个上下文中可用的API范围显著缩小。 + 例如：`row { row {`这类嵌套写法现已被禁止。 +- 结构化API：主要基于接口实现，便于通过分组方法学习API。 + 仅有少量API通过扩展函数实现。 +- 广泛使用KDoc注释体系。 +- 完全移除了MIG布局，由`GridLayout`替代。 + 由于MIG是第三方库，修复布局问题（如组件不可见时的显示异常）和扩展功能较为困难。 + 修复了边缘焦点环裁剪问题：当组件靠近面板边界时，面板边距不足会导致焦点环被裁剪。 +- 新增[](#placeholder)功能，支持运行时动态替换已显示内容。 -### Migration from Version 1 +### 从版本1迁移 {id="migration-from-version-1"} -The new API is very similar to the old one and covers almost all functionality now, so moving to the new version can be done quickly. +新版API与旧版高度兼容且功能覆盖全面，可快速完成迁移。 -Version 1 is placed in `com.intellij.ui.layout` package. +版本1包名：`com.intellij.ui.layout` -Version 2 is placed in `com.intellij.ui.dsl.builder` package. +版本2包名：`com.intellij.ui.dsl.builder` - + -1. Having a screenshot or live version of the initial components layout can help -2. Remove imports of old UI DSL starting with `com.intellij.ui.layout` -3. Go to the place where the panel is created and import new UI DSL `com.intellij.ui.dsl.builder` suggested by IntelliJ IDEA -4. Update non-compilable code, using the following table +1. 保留界面布局的截图或运行实例作为参考 +2. 移除所有`com.intellij.ui.layout`开头的旧版导入 +3. 在面板创建处使用IDEA的自动导入建议，选择新版`com.intellij.ui.dsl.builder` +4. 参照下表逐步修复编译错误 @@ -514,8 +505,8 @@ Version 2 is placed in `com.intellij.ui.dsl.builder` package. | `fullRow {` | `row {` | | `titledRow(…) {` | `group(…) {` | | `hideableRow` | `collapsibleGroup` | -| `cell` used as sub-grid | `row { panel { … } }` | -| `component(…)` or its invocation via `()` | `cell(…)` | +| 使用`cell`作为子网格 | `row { panel { … } }` | +| `component(…)`或`()`调用 | `cell(…)` | | `enableIf` | `enabledIf` | | `checkBox(text, bindOptions)` | `checkBox(text).bindSelected(bindOptions)` | | `radioButton(text, bindOptions)` | `radioButton(text).bindSelected(bindOptions)` | @@ -527,9 +518,9 @@ Version 2 is placed in `com.intellij.ui.dsl.builder` package. | `.growPolicy(GrowPolicy.COLUMNS_SHORT)` | `.columns(SHORT_TEXT)` | | `.growPolicy(GrowPolicy.MEDIUM_TEXT)` | `.columns(COLUMNS_MEDIUM)` | | `label(…, bold = true)` | `label(…).bold()` | -| `withLeftGap()` | For previous left cell use `Cell.gap(SMALL)` | -| `withLeftGap(gapLeft)` | Please do not use custom gaps if possible | -| `withLargeLeftGap()` | Not needed, this gap is set by default | +| `withLeftGap()` | 对前一个左单元格使用`Cell.gap(SMALL)` | +| `withLeftGap(gapLeft)` | 尽可能避免使用自定义间隙 | +| `withLargeLeftGap()` | 不再需要（默认设置大间隙） | | `withValidationOnInput` | `validationOnInput` | | `withValidationOnApply` | `validationOnApply` | | `withErrorOnApplyIf` | `errorOnApply` | diff --git a/topics/user_interface_components/tool_windows.md b/topics/user_interface_components/tool_windows.md index fd07ced532e..9ee9e4583bf 100644 --- a/topics/user_interface_components/tool_windows.md +++ b/topics/user_interface_components/tool_windows.md @@ -1,124 +1,124 @@ -# Tool Windows +# 工具窗口 -Displaying additional information and controls in child windows of the IDE. +在IDE的子窗口中展示额外的信息和控件 -**Product Help:** [Tool windows](https://www.jetbrains.com/help/idea/tool-windows.html) +**帮助：**[Tool windows](https://www.jetbrains.com/help/idea/tool-windows.html) -**UI Guidelines:** [](tool_window.md) +**UI指南：**[](tool_window.md) -_Tool windows_ are child windows of the IDE used to display information. -These windows generally have their own toolbars (referred to as _tool window bars_) along the outer edges of the main window containing one or more _tool window buttons_, which activate panels displayed on the left, bottom, and right sides of the main IDE window. +_工具窗口_ 是IDE用来展示信息的子窗口。 +这些窗口通常在主窗口的边缘有自己的工具栏（称为 _窗口工具栏_，_Tool window bars_），其中包含一个或多个 _工具窗口按钮_ (_Tool window buttons_)，这些按钮会激活窗口，而窗口会显示在主窗口的左边、底边或右边。 -Each side contains two tool window groups, the primary and the secondary one, and only one tool window from each group can be active at a time. +每一边都有两个工具窗口分组，第一组(primary)和第二组(secondary)，每一组在同一时间内只能显示一个工具窗口。 -Each tool window can show multiple tabs (or "contents", as they are called in the API). -For example, the Run tool window displays a tab for each active run configuration, and the Version Control related tool windows display a fixed set of tabs depending on the version control system used in the project. +每个窗口都能显示多个标签页（在API中被称为“contents”）。 +例如，运行窗口为每一个正在运行的配置显示一个标签页，而版本控制相关的窗口则根据项目使用的版本控制系统显示一组固定的标签页。 -There are two main scenarios for the use of tool windows in a plugin. -Using [declarative setup](#declarative-setup), a tool window button is always visible, and the user can activate it and interact with the plugin functionality at any time. -Alternatively, using [programmatic setup](#programmatic-setup), the tool window is created to show the results of a specific operation, and can then be closed after the operation is completed. +在插件中使用工具窗口有两种方法。 +使用[声明式配置](#declarative-setup)，这样工具窗口按钮则永远可见，用户可以随时激活它并使用插件的功能。 +另一种方式是[编程式配置](#programmatic-setup)，这样工具窗口可以显示某个特定操作的结果，并能在操作完成后关闭。 -### Declarative Setup +### 声明式配置 {id="declarative-setup"} -The tool window is registered in [plugin.xml](plugin_configuration_file.md) using the `com.intellij.toolWindow` extension point. -The extension point attributes specify all the data which is necessary to display the tool window button: +使用扩展点`com.intellij.toolWindow`在[plugin.xml](plugin_configuration_file.md)中注册工具窗口。 +该扩展点的属性指定了显示工具窗口按钮的必要数据： -* The `id` attribute (required) of the tool window which corresponds to the text displayed on the tool window button. -To provide a localized text, specify matching `toolwindow.stripe.[id]` message key (escape spaces with `_`) in the [resource bundle](plugin_configuration_file.md#idea-plugin__resource-bundle) (code insight supported in 2020.3 and later). +* 与展示在按钮上的文字相关的工具窗口的`id`（必需） +可以通过在[resource bundle](plugin_configuration_file.md#idea-plugin__resource-bundle)中指定相应的翻译键`toolwindow.stripe.[id]`（将空格替换为`_`）来进行本地化（代码洞察在2020.3及之后的版本中可用）。 -* The `icon` to display on the tool window button (13x13 pixels, grey and monochromatic; see [](tool_window.md) in UI Guidelines and [](icons.md)) +* 显示在按钮上的`icon`（13×13像素，灰色纯色，参见UI指南中的[](tool_window.md)和[](icons.md)） -* The `anchor`, meaning the side of the screen on which the tool window is displayed ("left" (default), "right" or "bottom") +* `anchor`属性，指定窗口停靠位置（“left”（默认），“right”或“bottom”） -* The `secondary` attribute, specifying whether the tool window is displayed in the primary or the secondary group +* `secondary`属性，指定窗口展示在第一组还是第二组 -* The `factoryClass` attribute (required), a class implementing [`ToolWindowFactory`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowFactory.kt). +* `factoryClass`属性（必需），由[`ToolWindowFactory`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowFactory.kt)扩展来的工厂类。 -When the user clicks on the tool window button, the `createToolWindowContent()` method of the factory class is called, and initializes the UI of the tool window. -This procedure ensures that unused tool windows don't cause any overhead in startup time or memory usage: if a user does not interact with the tool window, no plugin code will be loaded or executed. +当用户按下工具窗口按钮时，工厂类的`createToolWindowContent()`方法被调用，并初始化窗口界面。 +这确保了没有用的工具窗口不会产生启动时间和内存上的开销；如果用户不与该窗口交互，则相关的代码不会被加载或调用。 -#### Conditional Display +#### 选择性显示 -If the tool window of a plugin should not be displayed for all projects: +如果该工具窗口不适用于所有项目： -Implement `ToolwindowFactory.isApplicableAsync(Project)`. +实现`ToolwindowFactory.isApplicableAsync(Project)`。 -Implement `ToolwindowFactory.isApplicable(Project)`. +实现`ToolwindowFactory.isApplicable(Project)`。 -Specify the `conditionClass` attribute in plugin.xml with a class implementing [`Condition`](%gh-ic%/platform/util/src/com/intellij/openapi/util/Condition.java) (can be the same class as the `ToolWindowFactory` implementation). +在plugin.xml中将属性`conditionClass`绑定到实现了[`Condition`](%gh-ic%/platform/util/src/com/intellij/openapi/util/Condition.java)的类上（可以与`ToolWindowFactory`的实现是同一个类）。 -Note, the condition is evaluated only once when the project is loaded. -To show and hide a tool window dynamically while the user is working with the project, use [programmatic setup](#programmatic-setup) for tool window registration. +注意，该条件只会在项目加载时判断一次。 +如果要在用户工作时动态地显示、隐藏工具窗口，请使用[编程式配置](#programmatic-setup)来注册窗口。 -### Programmatic Setup +### 编程式配置 {id="programmatic-setup"} -For toolwindows shown only after invoking specific actions, use [`ToolWindowManager.registerToolWindow(String,RegisterToolWindowTaskBuilder)`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.kt). +对于仅在特定操作后才展示的工具窗口，请使用[`ToolWindowManager.registerToolWindow(String,RegisterToolWindowTaskBuilder)`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.kt)。 -Always use [`ToolWindowManager.invokeLater()`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.kt) instead of "plain" `Application.invokeLater()` when scheduling EDT tasks related to tool windows (see [](threading_model.md)). +在计划与工具窗口相关的EDT事件时，请始终使用[`ToolWindowManager.invokeLater()`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.kt)，而不是“普通的”`Application.invokeLater()`。 -## Contents (Tabs) +## Contents（标签页） -Displaying the contents of many tool windows requires access to [indexes](indexing_and_psi_stubs.md). -Because of that, tool windows are normally disabled while building indexes unless the `ToolWindowFactory` is marked [dumb aware](indexing_and_psi_stubs.md#DumbAwareAPI). +显示多个工具窗口的内容时需要使用[文件索引](indexing_and_psi_stubs.md)。 +因此，除非`ToolWindowFactory`工厂类被标记为[dumb aware](indexing_and_psi_stubs.md#DumbAwareAPI)，工具窗口在构建索引时会被禁用。 -As mentioned previously, tool windows can contain multiple contents (tabs). -To manage the contents of a tool window, call [`ToolWindow.getContentManager()`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/wm/ToolWindow.java). -To add a content (tab), first create it by calling [`ContentManager.getFactory().createContent()`](%gh-ic%/platform/ide-core/src/com/intellij/ui/content/ContentManager.java), and then to add it to the tool window using [`ContentManager.addContent()`](%gh-ic%/platform/ide-core/src/com/intellij/ui/content/ContentManager.java). -Use `Content.setDisposer()` to register associated `Disposable` (see [](disposers.md)). +正如先前提到的，工具窗口可以包含多个标签页。 +调用[`ToolWindow.getContentManager()`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/wm/ToolWindow.java)来管理工具窗口的内容。 +要添加标签页，首先调用[`ContentManager.getFactory().createContent()`](%gh-ic%/platform/ide-core/src/com/intellij/ui/content/ContentManager.java)创建它，再调用[`ContentManager.addContent()`](%gh-ic%/platform/ide-core/src/com/intellij/ui/content/ContentManager.java)将其添加到工具窗口中。 +调用`Content.setDisposer()`注册相关的`Disposable`（参考[](disposers.md)）。 -See [`SimpleToolWindowPanel`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/SimpleToolWindowPanel.java) as a convenient base class, supporting [Toolbars](basic_action_system.md#buildingToolbarPopupMenu) and both vertical/horizontal layout. +[`SimpleToolWindowPanel`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/SimpleToolWindowPanel.java)是一个方便的基类，支持[工具栏](basic_action_system.md#buildingToolbarPopupMenu)和垂直或水平布局。 -### Closing Tabs +### 关闭标签页 -A plugin can control whether the user is allowed to close tabs either globally or on a per-content basis. -The former is done by passing the `canCloseContents` parameter to the `registerToolWindow()` function, or by specifying `canCloseContents="true"` in plugin.xml. -The default value is `false`; calling `setClosable(true)` on `ContentManager` content will be ignored unless `canCloseContents` is explicitly set. +插件可以决定用户能否全部或部分关闭标签页。 +前者可以通过向`registerToolWindow()`中传递`canCloseContents`参数，或在plugin.xml中指定`canCloseContents="true"`做到。 +默认值为`false`；通过`ContentManager`调用`setClosable(true)`会被忽略，除非`canCloseContents`被显式地设置。 -If closing tabs is enabled in general, a plugin can disable closing of specific tabs by calling [`Content.setCloseable(false)`](%gh-ic%/platform/ide-core/src/com/intellij/ui/content/Content.java). +如果允许关闭标签页，插件可以通过[`Content.setCloseable(false)`](%gh-ic%/platform/ide-core/src/com/intellij/ui/content/Content.java)来阻止某个特定标签页被关闭。 -## Tool Window FAQ +## 工具窗口FAQ -### Accessing Tool Window +### 访问工具窗口 -Use [`ToolWindowManager.getToolWindow()`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.kt) specifying the `id` used for [registration](#declarative-setup). +调用[`ToolWindowManager.getToolWindow()`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.kt)，并指定[注册](#declarative-setup)时的`id`。 -### Tool Window Notification +### 工具窗口消息 -[`ToolWindowManager.notifyByBalloon()`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.kt) allows showing a notification for the given tool window. +可以通过[`ToolWindowManager.notifyByBalloon()`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.kt)为给定的窗口显示消息。 -### Events +### 事件 -Project-level topic [`ToolWindowManagerListener`](%gh-ic%/platform/platform-impl/src/com/intellij/openapi/wm/ex/ToolWindowManagerListener.java) allows listening to tool window registration/show events (see [](plugin_listeners.md)). +项目级别的[`ToolWindowManagerListener`](%gh-ic%/platform/platform-impl/src/com/intellij/openapi/wm/ex/ToolWindowManagerListener.java)允许你监听工具窗口的注册、显示事件（参考[](plugin_listeners.md)）。 -## Sample Plugin +## 示例插件 -To clarify how to develop plugins that create tool windows, consider the **toolWindow** sample plugin available in the [code samples](%gh-sdk-samples-master%/tool_window). +为了弄清如何创建工具窗口，请参考[示例](%gh-sdk-samples-master%/tool_window)中的**工具窗口**样例。 -See [](code_samples.md) on how to set up and run the plugin. +关于如何配置并运行示例插件，请参考[](code_samples.md)。 -This plugin creates the Sample Calendar tool window that displays the system date, time and time zone. -When opened, this tool window is similar to the following screen: +该插件创建了一个Sample Calendar工具窗口，可以显示系统日期、时间以及时区。 +打开后，看起来应该是这样的： ![Sample Calendar](sample_calendar.png){width="403"} diff --git a/topics/user_interface_components/user_interface_components.md b/topics/user_interface_components/user_interface_components.md index f30b74de090..74eda9b4f99 100644 --- a/topics/user_interface_components/user_interface_components.md +++ b/topics/user_interface_components/user_interface_components.md @@ -1,40 +1,39 @@ -# User Interface Components +# UI组件 -Introduction to UI Components provided by IntelliJ Platform. +介绍由IntelliJ平台提供的UI组件 -**UI Guidelines:** [Overview](ui_guidelines_welcome.topic) +**UI指南：**[](ui_guidelines_welcome.topic) -The IntelliJ Platform includes a large number of custom [Swing](https://en.wikipedia.org/wiki/Swing_(Java)) components. -Using those components in your plugins will ensure that your plugin looks and works consistently with the UI of the rest of the IDE, and can often reduce the code size compared to using the default Swing components. -Use inspection Plugin DevKit | Code | Undesirable class usage to highlight replacement components provided by the platform. +IntelliJ平台提供大量自定义的[Swing](https://en.wikipedia.org/wiki/Swing_(Java))组件，使用这些组件可以确保您的插件和IDE的其他UI拥有一致的外观和工作方式，并且相较于默认的Swing组件，通常能减少代码量。 +启用检查项Plugin DevKit | Code | Undesirable class usage以高亮显示平台提供的替代组件建议。 -> Use [UI Inspector](internal_ui_inspector.md) to locate the underlying Swing component implementation or to inspect an existing UI at runtime. +> 使用[](internal_ui_inspector.md)查看背后的Swing组件实现，或者在运行时检查一个存在的UI。 > {title="Inspecting existing UI"} -> UI forms like [](dialog_wrapper.md) or [](settings.md) should use [Kotlin UI DSL](kotlin_ui_dsl_version_2.md) (IntelliJ Platform 2021.3+). +> 外观类似[](dialog_wrapper.md)或[](settings.md)的UI应该使用[Kotlin UI DSL](kotlin_ui_dsl_version_2.md) (IntelliJ平台2021.3+)。 > -> Using _UI Designer_ plugin with Kotlin is [not supported](https://youtrack.jetbrains.com/issue/KTIJ-791). +> 和Kotlin一起使用 _UI Designer_ 插件是[不受支持](https://youtrack.jetbrains.com/issue/KTIJ-791)的。 > {style="note"} -Please refer to [](writing_short.md) in UI Guidelines on writing UI-related texts. +关于编写UI相关的文本，请参考UI指南中的[](writing_short.md)。 -See [](UI_kit.md) when using [Figma](https://www.figma.com) to design UI. +使用[Figma](https://www.figma.com)设计UI时，请参考[](UI_kit.md)。 -The following components are particularly noteworthy: +以下内容值得留意： -* Menus and toolbars are built using [](basic_action_system.md) +* 使用[](basic_action_system.md)构建菜单和工具栏 * [](tool_windows.md) * [](dialog_wrapper.md) * [](popups.md) @@ -47,6 +46,6 @@ The following components are particularly noteworthy: * Drag & Drop Helpers (TBD) * [](misc_swing_components.md) -See also [](ui_faq.md). +另请查看[](ui_faq.md)。