studio-web

latest

false

重要 :

请注意，此内容已使用机器翻译进行了部分本地化。新发布内容的本地化可能需要 1-2 周的时间才能完成。

Studio Web 用户指南

适用平台：

上次更新日期 2025年4月17日

自定义 HTML

自定义 HTML 控件面向高级用户，并提供 HTML、 CSS 和 JavaScript 编程语言的灵活性，以便其根据业务需求制作自定义交互式控件。该控件包括用于 HTML、 CSS 和 JavaScript 代码的专用编辑器，并具有通过 URL 合并外部托管的 CSS 和 JavaScript 文件的优点。

常规

“打开代码编辑器” - 打开一个三面板编辑器，用于添加 HTML、 CSS 和 JavaScript 代码。
“可访问标签” - 控件的说明。屏幕阅读器使用此属性来增强辅助功能。
隐藏 - 如果为 true，则在 Runtime 隐藏该控件。
已禁用- 如果为 True，则使控件在 Runtime 处于非活动状态。系统会加载 HTML、 CSS 和 JavaScript 内容，但对用户操作（例如单击）无响应。

Events

无事件。

样式

“控件对齐”- 默认情况下，继承父级对齐方式。可以设置与父级对齐方式不同的对齐方式。要默认返回到父级对齐方式，请取消选择覆盖的选项。

注意：对齐方式取决于为父元素选择的布局（垂直与水平）。
“边框” - 控件的边框。可以配置边框粗细和半径。
“边距”- 设置控件的边距。默认情况下，边距设置为 4 像素。“上/下”和“左/右”边距属性结合使用。可以使用“边距”部分右侧的“链接”按钮分离这些属性。
“大小”- 控件的宽度和高度。默认情况下，大小设置为 auto。要设置最小值或最大值，请单击三点图标 (...)。

自定义 HTML 的代码编辑器

自定义 HTML 控件的代码编辑器提供了三个面板，用于以 HTML、 CSS 和 JavaScript 编程语言输入代码。每个编辑器都支持 IntelliSense，即自动代码补全和语法高亮显示。

面板中的代码编译到项目中，并在 Apps Studio 中呈现以供预览。要观察控件的功能，请预览应用程序。

重要提示：

每个编辑器的最大内容大小为 5MB。当内容超过此大小时，您将无法再保存更改。
IntelliSense 不适用于在 HTML 编辑器中编写的 CSS 和 JavaScript 代码。

添加外部资源

如果已定义样式或脚本，则可以在控件中引用它们，而无需在相应的 CSS 或 JavaScript 面板中编写代码。

要引用现有的.css或.js文件，请执行以下操作：

在自定义 HTML 控件的代码编辑器中，切换到“外部资源”选项卡。
在 CSS 部分下，添加外部 CSS 文件。该文件必须托管在可通过网络访问的 URL 中，以确保运行应用程序的兼容性和可用性。
在“JavaScript” 部分下，添加一个外部脚本文件。该文件必须托管在可通过网络访问的 URL 中，以确保运行应用程序的兼容性和可用性。
添加完所有外部资源后，单击“保存” 。

Tab 键的辅助功能快捷方式

默认情况下，Tab 键会在当前编辑器中添加一个制表符空格。要自定义 Tab 键的行为，请使用以下快捷方式：

操作系统	快捷方式	行为
Windows	CTRL+M	指示使用 Tab 键在面板之间导航，并将焦点切换到编辑器的可见按钮上。再次按 CTRL+M 可返回到默认的 Tab 行为。
MacOS	CTRL+Shift+M	指示使用 Tab 键在面板之间导航，并将焦点切换到编辑器的可见按钮上。再次按 CTRL+Shift+M 可返回到默认的 Tab 行为。

HTML 编辑器

在此面板中，您可以输入控件的结构，该结构通常包含在 HTML 代码块的<body></body>标签内。

例如，要在应用程序中为交互式饼图添加容器元素，您可以使用以下 HTML 代码片段：

 <canvas id="myChart" class="chart-container" style="width:100%;max-width:600px"></canvas><canvas id="myChart" class="chart-container" style="width:100%;max-width:600px"></canvas>

其中：

id="myChart"引用在 HTML 元素中生成交互式饼图的 JavaScript“myChart”元素。有关详细信息，请参阅 JavaScript 编辑器。
class="chart-container"引用“图表容器” CSS 类，该类在 HTML 元素中添加饼图样式。有关详细信息，请参阅 CSS 编辑器。

CSS 编辑器

在此面板中，您可以输入控件及其中的元素的样式。

例如，要向饼图添加颜色和边框，您可以使用以下 CSS 代码片段：

 .chart-container {
    background-color: #f3f7e9;
    border: 1px solid #cccccc;
}.chart-container {
    background-color: #f3f7e9;
    border: 1px solid #cccccc;
}

JavaScript 编辑器

在此面板中，您可以创建控件的交互式部分，例如及时的内容更新、地图或 2D/3D 动画图形。

例如，要创建 Apple 产品在全球范围内的销售情况饼图，并将其设计为显示所选扇区的值，您需要执行以下操作：

添加以下 JavaScript 外部资源:

 https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.4/Chart.jshttps://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.4/Chart.js

使用以下 JavaScript 代码片段：

 const ctx = document.getElementById('myChart').getContext('2d');
const myChart = new Chart(ctx, {
  type: 'pie',
  data: {
    labels: ['iPhone', 'iPad', 'MacBook', 'Apple Watch', 'AirPods'],
    datasets: [{
      label: 'Sales',
      data: [120000, 80000, 50000, 40000, 30000],
      backgroundColor: [
        '#5CB85C', // Green
        '#F0AD4E', // Orange
        '#D9534F', // Red
        '#5BC0DE', // Light blue
        '#999',    // Gray
      ],
      borderColor: '#fff',
      borderWidth: 2,
    }],
  },
  options: {
    plugins: {
      legend: {
        position: 'top',
      },
      title: {
        display: true,
        text: 'Apple Products Sales',
      },
    },
  },
});const ctx = document.getElementById('myChart').getContext('2d');
const myChart = new Chart(ctx, {
  type: 'pie',
  data: {
    labels: ['iPhone', 'iPad', 'MacBook', 'Apple Watch', 'AirPods'],
    datasets: [{
      label: 'Sales',
      data: [120000, 80000, 50000, 40000, 30000],
      backgroundColor: [
        '#5CB85C', // Green
        '#F0AD4E', // Orange
        '#D9534F', // Red
        '#5BC0DE', // Light blue
        '#999',    // Gray
      ],
      borderColor: '#fff',
      borderWidth: 2,
    }],
  },
  options: {
    plugins: {
      legend: {
        position: 'top',
      },
      title: {
        display: true,
        text: 'Apple Products Sales',
      },
    },
  },
});

在自定义 HTML 中使用变量

要在自定义 HTML 控件与其他控件或集成之间建立通信，我们建议使用setVariable() 、 getVariable()和onVariableChange()内置函数。

getVariable()

在 JavaScript 编辑器中，使用此函数获取现有变量的值。

例如，要将变量的值传递给internalValue ，您可以使用以下 JavaScript 代码片段：

 async function init() {
  let internalValue = await App.getVariable('<app_variable_name>');
}
init();async function init() {
  let internalValue = await App.getVariable('<app_variable_name>');
}
init();

备注：

getVariable()函数是异步函数，需要您使用await 。
如果在函数内调用getVariable() ，请将该函数async 。在提供的示例中，我们创建了init()函数并立即调用它。
如果在顶层调用getVariable() ，请将其嵌入到async函数中。

要处理诸如无效变量名称之类的错误，请使用 Try-Catch 语句。例如：

 async function init() {
  try {
    const value = await App.getVariable("test");
  } catch (e) {
    console.log("Error in evaluating app variable:", e);
  }
}
init();async function init() {
  try {
    const value = await App.getVariable("test");
  } catch (e) {
    console.log("Error in evaluating app variable:", e);
  }
}
init();

setVariable()

在 JavaScript 编辑器中，使用此函数为现有变量设置值。第一个参数是变量名称，第二个参数是要设置的值。

 async function setValue() {
  await App.setVariable('<app_variable_name>', <app_variable_value>);
}
setValue();async function setValue() {
  await App.setVariable('<app_variable_name>', <app_variable_value>);
}
setValue();

备注：

要等待设置操作完成后再执行其他代码，请使用await 。

要处理诸如无效的变量名称或变量与设置值之间的类型不匹配之类的错误，请使用 Try-Catch 语句。例如：

 try {
  App.setVariable('<app_variable_name>', <app_variable_value>);
} catch (e) {
  console.log("Error in setting app variable:", e);
}try {
  App.setVariable('<app_variable_name>', <app_variable_value>);
} catch (e) {
  console.log("Error in setting app variable:", e);
}

onVariableChange()

在 JavaScript 编辑器中，使用此函数侦听现有变量值的更改并访问最新的变量值。

 App.onVariableChange('<app_variable_name>', value => {
  console.log("Latest value: ", value);
});App.onVariableChange('<app_variable_name>', value => {
  console.log("Latest value: ", value);
});

在以下示例中，我们将onVariableChange()返回的函数赋值给deregister变量。然后，如果您想停止侦听变量更改，可以调用deregister()函数：

 const deregister = App.onVariableChange('<app_variable_name>', value => {
  console.log("Latest value: ", value);
});

// To stop listening for value changes, the deregister function can be invoked like below
deregister();const deregister = App.onVariableChange('<app_variable_name>', value => {
  console.log("Latest value: ", value);
});

// To stop listening for value changes, the deregister function can be invoked like below
deregister();

备注：

侦听器在自定义 HTML 控件完全呈现后启动。如果在初始化自定义 HTML 控件之前变量值发生更改，则不会捕获更新的值。

要获取最新的变量值，请在调用getVariable()之前调用onVariableChange() 。
HTML 控件及其中的函数在运行时显示控件后进行初始化。

变量类型

应用程序变量类型	变量函数的响应示例
Text (String)	"Hello world"
UInt64 (Int)	100
Decimal number	50.25
True/False (Boolean)	True
DateOnly	2024-01-02 (格式: YYYY-MM-DD)
DateTimeOffset	2024-01-06T09:54:41.9170000Z (等效 JS 格式: 日期对象 ISO 字符串)
Apps 文件 -文件选取器控件的值	JS 文件对象
Apps 文件 - 从 URL 创建的值例如： `new AppsFile("https://image.jpg")`new AppsFile("https://image.jpg")	文件对象： `{FileSize: 0, Name: "", URL: "https://image.jpg", __infoType: "$metadata"}`{FileSize: 0, Name: "", URL: "https://image.jpg", __infoType: "$metadata"}
GUID	"5637F7DB-391D-4C8B-805D-0A918531CA3E"
List(Of string)	["Banana", "Kiwi", "Apple", "Lemon"]
ListSource(Of <Entity>)	`{ data: [{Name: "John", Age: "28", ...},{Name: "Kane", Age: "48", ...}], totalRecords: 2 }`{ data: [{Name: "John", Age: "28", ...},{Name: "Kane", Age: "48", ...}], totalRecords: 2 }
<Entity> (Single entity row)	`{ Name: "John", Age: "28", ... }`{ Name: "John", Age: "28", ... }
ListSource(Of <Choiceset>)	`{ data: [{DisplayName: "Male", Id: "00F3372D-3920-EC11-AE72-0003FFBA1E91", Name: "Male", ...}, {DisplayName: "Female", Id: "01F3372D-3920-EC11-AE72-0003FFBA1E91", Name: "Female", ...}], totalRecords: 2 }`{ data: [{DisplayName: "Male", Id: "00F3372D-3920-EC11-AE72-0003FFBA1E91", Name: "Male", ...}, {DisplayName: "Female", Id: "01F3372D-3920-EC11-AE72-0003FFBA1E91", Name: "Female", ...}], totalRecords: 2 }
Datatable	`[{From: 'Ahmedabad', To: 'Azua', ...},{From: 'banglore', To: 'Dominican Republic',...},...]`[{From: 'Ahmedabad', To: 'Azua', ...},{From: 'banglore', To: 'Dominican Republic',...},...]

自定义 HTML 的最佳实践

由于具有客户端访问权限，因此请勿在自定义 HTML 控件中包含敏感数据。
不要在 HTML 编辑器中使用<html>和<head>标签，因为代码会自动附加到<body>标签中。
在“外部资源”选项卡中添加外部资源（例如Bootstrap、jQuery 或其他 JavaScript SDK）的 CDN URL。
如要停止侦听变量更改，请使用deregister()函数。
避免大型数据循环，以防止减慢应用程序的速度，并保持控件的响应能力。
尽可能减少 DOM 元素的使用：仅在必要时创建 DOM 元素，并在它们过时时将其删除。
对大型数据集使用无限滚动或虚拟滚动，而不是标准滚动。
创建并维护干净、优化且无冗余的代码。

功能限制

要将控件连接到 Apps，您必须使用变量函数： getVariable() 、 setVariable() 、 onVariableChange() 。
不会动态调整 HTML 控件的尺寸以显示弹出窗口或下拉菜单。您必须手动设置 HTML 控件的大小以适应这些菜单。
您无法在设计时与 HTML 控件交互。
setVariable() 、 getVariable()和onVariableChange()函数仅在运行时运行。
更改变量名称或删除变量不会自动反映在代码编辑器中。您需要使用当前变量手动更新代码。
将图像数据从 HTML 控件传输到存储桶或使用数据 URL 的实体时，文件大小不应超过 1 MB。超过此大小的文件可能会导致性能问题。
该控件只能通过使用变量与其他 UiPath^TM 组件（例如流程、队列或存储桶）通信。
使用 LESS 或 S CSS 的预处理 CSS 代码与 HTML 控件不兼容。
出于安全考虑，以下 API 在使用时会静默失败：
- 使用download属性进行下载。
- 使用Window.alert() 、 Window.confirm() 、 Window.print() 、 Window.prompt()打开模态框。
- 指针和方向锁定。
- 导航顶级浏览器上下文。
- 使用requestFullscreen()进入全屏。
- 使用MediaDevices.getDisplayMedia()进行屏幕捕获。
- 使用MediaDevices.getUserMedia()访问摄像头或麦克风。
- 请求付款。
- 使用navigator.geolocation()访问位置。
- 使用navigator.share()共享数据。

调试自定义 HTML 控件的代码

添加和筛选自定义 HTML 控件的控制台日志

在 JavaScript 编辑器中添加console.log() 。
按 F12 键打开浏览器控制台，然后选择“控制台”选项卡。
在控制台设置中，选中“仅限选定上下文”复选框。
从控制台页面顶部的 JavaScript 上下文下拉列表中，选择所需 HTML 控件的html-control-base.html选项。

所选控件中的日志将显示在控制台中。

有关更多详细信息，请观看视频：

添加断点

在 JavaScript 编辑器中添加console.log() 。
按 F12 键打开浏览器控制台，然后选择“控制台”选项卡。
在日志右侧，单击虚拟机消息。

调试器将打开。通过单击所需的行号来选择断点。

有关更多详细信息，请观看视频：

VB 属性

VB 属性	数据类型	描述
`AccessibleLabel`	字符串	对控件的说明，由屏幕阅读器等辅助功能技术使用。
`Hidden`	布尔值	确定自定义 HTML控件的可见性。如果为 True，则在 Runtime 隐藏该控件。
`Disabled`	布尔值	确定是否禁用“自定义 HTML ”控件。如果为 True，则禁用在 Runtime 与控件进行交互。已加载 HTML、CSS 和 JavaScript 内容，但对用户操作无响应。