跳转到内容
月离文档

scriptui-编程模型

ScriptUI 编程模型

ScriptUI 定义了表示平台特定窗口的 Window 对象，以及表示用户界面控件的各种控件元素，例如 Button 和 StaticText。这些对象共享一组通用的属性和方法，允许您查询类型、移动元素、设置标题、标题或内容等。许多元素类型还具有该类元素独有的属性。

创建窗口

ScriptUI 定义了以下类型的窗口：

  • 模态对话框：显示时保持焦点，不允许在其他应用程序窗口中进行活动，直到关闭。
  • 浮动面板：也称为非模态对话框，允许在其他应用程序窗口中进行活动。（Adobe Photoshop® 不支持通过脚本创建面板窗口。）
  • 主窗口：适合用作应用程序的主窗口。（主窗口通常不由 Adobe 应用程序的脚本开发人员创建。Photoshop 不支持通过脚本创建主窗口。）

要创建新窗口，请使用 Window 构造函数。构造函数接受窗口的所需类型。类型为 "dialog" 表示模态对话框，或 "palette" 表示非模态对话框或浮动面板。您可以提供可选参数来指定初始窗口标题和边界；或者您可以分别设置位置和大小。

以下示例创建了一个名为 dlg 的空对话框，该变量在后续示例中使用：

// 在屏幕左上角附近创建一个空对话框窗口
var dlg = new Window( "dialog", "Alert Box Builder" );
dlg.frameLocation = [ 100, 100 ];

最初，新窗口是隐藏的。show 方法使它们可见并响应用户交互；例如：

dlg.show();

容器元素

所有窗口都是容器——也就是说，它们在其边界内包含其他元素。在窗口内，您可以创建其他类型的容器元素：面板 (Panel) 和组 (Group)。这些可以包含控件元素，也可以包含其他面板和组容器。但是，窗口不能添加到任何容器中。

  • 组 (Group)：最简单的容器，用于在视觉上组织相关的控件。您通常会定义一个组，并用相关元素填充它，例如一个编辑文本框及其描述性的静态文本标签。
  • 面板 (Panel)：框架对象，通常也用于在视觉上组织相关的控件。它具有一个 text 属性来指定标题，并且可以具有边框以在视觉上将元素集合与对话框的其他元素分开。
  • 选项卡面板 (TabbedPanel)：一个仅包含选项卡 (Tab) 元素的框架。每个选项卡都是一个框架，选择选项卡中具有可本地化的标题，其中包含一组控件。当选项卡处于活动状态时，Tab 对象是 TabbedPanel.selection 属性的值。

您可以创建一个 Panel 并用多个 Group 填充它，每个组都有自己的元素。您可以创建嵌套容器，为不同的容器设置不同的布局属性，以便在不进行显式放置的情况下定义相对复杂的布局。

您可以使用 add 方法将元素添加到任何容器中（请参阅 将元素添加到容器）。添加到容器的元素被视为该容器的子元素。对容器的某些操作会应用于其子元素；例如，当您隐藏容器时，其子元素也会被隐藏。

窗口布局

当脚本创建一个 Window 并向其添加各种用户界面元素时，元素的位置和大小以及元素之间的间距称为窗口的布局。每个用户界面元素都有定义其位置和尺寸的属性：location、size 和 bounds。这些属性最初是未定义的，使用 自动布局 的脚本应为主窗口及其包含的元素保留这些属性未定义，以便自动布局机制设置它们的值。

您的脚本可以访问这些值，并且（如果不使用自动布局）可以按如下方式设置它们：

  • 窗口的 location 由包含左上角（原点）坐标（x 和 y）的 Point 对象定义，坐标在屏幕坐标系中指定。窗口或其他容器内元素的位置定义为容器坐标系中指定的原点。也就是说，x 和 y 值是相对于容器的原点的。
    • 以下示例显示了将现有窗口的内容区域放置在屏幕坐标 [10, 50] 处的等效方法： 
      win.location = [ 10, 50 ];
      win.location = { x: 10, y: 50 };
      win.location = "x:10, y:50";
  • 元素区域的 size 由包含 width 和 height（以像素为单位）的 Dimension 对象定义。
    • 以下示例显示了将现有窗口的宽度和高度更改为 200 和 100 的等效方法： 
      win.size = [ 200, 100 ];
      win.size = { width: 200, height: 100 };
      win.size = "width:200, height:100";
    • 此示例显示了如何将窗口的高度更改为 100，同时保持其位置和宽度不变： 
      win.size.height = 100;
  • 元素的 bounds 由包含原点点（x，y）和大小（width，height）的 Bounds 对象定义。要一步定义窗口和控件的大小和位置，请使用 bounds 属性。
    • bounds 属性的值可以是具有适当内容的字符串、内联 JavaScript Bounds 对象或四元素数组。以下示例显示了在屏幕左上角附近放置一个 380 x 390 像素窗口的等效方法： 
      var dlg = new Window( "dialog", "Alert Box Builder", [ 100, 100, 480, 490] );
      dlg.bounds = [ 100, 100, 480, 490 ];
      dlg.bounds = { x: 100, y: 100, width: 380, height: 390 };
      dlg.bounds = { left: 100, top: 100, right: 480, bottom: 490 };
      dlg.bounds = "left:100, top:100, right:480, bottom:490";

窗口的尺寸定义了窗口的内容区域的大小，或脚本可以直接控制的那部分窗口。实际窗口大小通常更大，因为主机平台的窗口系统通常会添加标题栏和边框。Window 的 bounds 属性仅指其内容区域。要确定围绕窗口内容区域的框架的边界，请使用 Window.frameBounds 属性。

将元素添加到容器

要将元素添加到 window、panel 或 group，请使用容器的 add 方法。此方法接受要创建的元素类型和一些可选参数（取决于元素类型）。它创建并返回指定类型的对象。

除了窗口之外，ScriptUI 还定义了以下用户界面元素和控件：

  • 面板（框架）和组，用于收集和组织其他控件类型
  • 带有文本或图标的按钮、单选按钮、复选框按钮
  • 静态文本或图像、编辑文本
  • 进度条、滚动条、滑块
  • 列表，包括列表框、下拉（也称为弹出）列表和树视图。列表中的每个项目都是 item 类型的控件，父列表的 items 属性包含子项目的数组。树视图还可以具有可折叠的 node 类型项目，其中包含子项目。您可以使用父级的 add 方法添加列表项。

您可以在可选的 bounds 参数中指定任何新元素的初始大小和位置，相对于父容器的工作区域。不同类型的元素具有不同的附加参数。例如，对于显示文本的元素，您可以指定初始文本。有关详细信息，请参阅 ExtendScript Toolkit 的对象模型查看器中的 ScriptUI 类字典。

可选参数的顺序必须保持不变。对于您不想设置的参数，请使用值 undefined。例如，如果您想使用自动布局来确定边界，但仍设置面板和按钮的标题和文本，以下代码创建具有初始 text 值但没有 bounds 值的 Panel 和 Button 元素：

dlg.btnPnl = dlg.add("panel", undefined, "Build it");
dlg.btnPnl.testBtn = dlg.btnPnl.add("button", undefined, "Test");

新元素最初设置为可见，但除非其父对象显示，否则不会显示。

创建属性

某些元素类型具有只能在创建元素时指定的属性。这些不是元素的常规属性，因为在元素的生命周期内无法更改它们，并且它们只需要一次。对于这些元素类型，您可以向 add 方法提供可选的创建属性参数。此参数是一个对象，具有一个或多个控制元素外观的属性，或特殊功能，例如编辑文本元素是否可编辑或只读。有关详细信息，请参阅 控件对象构造函数。

您还可以使用资源规范格式为新对象指定创建属性；有关详细信息，请参阅 资源规范。

所有用户界面元素都有一个可选的创建属性，称为 name，用于为该元素分配一个名称以进行标识。例如，以下代码创建了一个名为 ok 的新 Button 元素：

dlg.btnPnl.buildBtn = dlg.btnPnl.add("button", undefined, "Build", {name: "ok"});

访问子元素

添加到容器的每个元素的引用都会附加到容器的 children 属性中。您可以通过此数组访问子元素，使用基于 0 的索引。对于不是容器的控件，children 集合为空。

在此示例中，msgPnl 面板是 dlg 中创建的第一个元素，因此脚本可以通过父级的 children 属性的索引 0 访问面板对象以设置标题的文本：

var dlg = new Window( "dialog", "Alert Box Builder" );
dlg.msgPnl = dlg.add( "panel" );
dlg.children[ 0 ].text = "Messages";

如果您使用创建属性为新创建的元素分配名称，则可以通过其名称访问该子元素，无论是在其父级的 children 数组中，还是直接作为其父级的属性。例如，前面示例中的 Button 被命名为 ok，因此可以按如下方式引用：

dlg.btnPnl.children[ "ok" ].text = "Build";
dlg.btnPnl.ok.text = "Build";

您还可以通过父窗口的 findElement() 方法访问命名元素：

var myOkButton = dlg.findElement( "ok" );

对于列表控件（类型为 list 和 dropdown），您可以通过 items 数组访问子列表项对象。

移除元素

要从 Window、Panel 或 Group 中移除元素，请使用容器的 remove 方法。此方法接受表示要移除的元素的对象，或元素的名称，或容器 children 集合中元素的索引（请参阅 访问子元素）。

指定的元素如果当前可见，则从视图中移除，并且不再可以从容器或窗口访问。脚本对表示该元素的对象的任何进一步引用的结果是未定义的。

要从列表中移除列表项，请以相同的方式使用父列表控件的 remove 方法。它将项目从父级的 items 列表中移除，从视图中隐藏，并删除项目对象。