HTML拼图

这些拼图可以操作HTML DOM元素。

内容

什么是HTML DOM？

HTML DOM（文档对象模型，见技术文档）是一个HTML页面的程序化接口。基本上，这意味着除了通过直接编辑文本代码，还可以通过执行拼图模块来修改应用。例如，您可以添加新的HTML元素来自定义页面外观、在模型上画图、屏幕截图、下载文件等。

拼图参考

add HTML element(添加HTML元素)

创建一个具有指定类型和标识符（对应于 "id" 属性）的HTML元素，并将其添加到指定的现有HTML元素之前或之后。

remove HTML element(移除HTML元素)

移除一个具有指定标识符的HTML元素。

set property(设置属性)

为具有指定id的HTML元素设置属性。如果HTML元素位于外部HTML文档（其中使用 iframe 嵌入Verge3D应用的 .html 文件）中，则应启用 "in parent doc(在父文档中)" 复选框。也适用于元素ID列表。

属性	描述
alt	指定原始元素无法显示时的替代文本。
checked	指定复选框/单选元素的选中状态。
className	设置元素的 class 属性的值。
download	指定当用户单击超链接时将下载目标。
disabled	指定应禁用指定的元素/元素组。
height	指定元素的高度。
href	指定链接转到的页面的 URL。
id	指定元素的唯一 ID。
innerHTML	设置元素的 HTML 内容。
loop	指定音频/视频在每次完成时将重新开始。
muted	指定音频/视频静音。
rel	指定当前文档和链接文档之间的关系。
scrollLeft	设置元素内容水平滚动的像素数。
scrollTop	设置元素内容垂直滚动的像素数。
src	指定已加载文件的 URL。
style	指定元素的内联 CSS 样式。
target	指定打开链接文档的位置或提交表单的位置的目标。
title	指定有关元素的额外信息。
type	指定元素的类型。
value	指定元素的值。
volume	指定音频/视频元素的音量。
width	指定元素的宽度。

get property(获取属性)

从具有指定 ID 的 HTML 元素中获取属性。如果HTML元素位于外部HTML文档（其中使用 iframe 嵌入Verge3D应用的 .html 文件）中，则应启用 "in parent doc(在父文档中)" 复选框。

属性	描述
alt	获取原始元素无法显示时的替代文本。
checked	获取复选框/单选元素的选中状态。
className	获取元素的 class 属性的值。
download	获取当用户单击超链接时将下载目标。
disabled	指定应禁用指定的元素/元素组。
height	获取元素的高度。
href	获取链接转到的页面的 URL。
id	获取元素的唯一 ID。
innerHTML	获取元素的 HTML 内容。
loop	获取音频/视频循环播放的状态。
muted	获取音视频元素静音的状态。
rel	获取当前文档和链接文档之间的关系。
scrollLeft	获取元素内容水平滚动的像素数。
scrollTop	获取元素内容垂直滚动的像素数。
src	获取已加载文件的 URL。
style	获取一个元素的内联 CSS 样式。
target	获取打开链接文档的位置或提交表单的位置的目标。
title	获取有关元素的额外信息。
type	获取元素的类型。
value	获取元素的值。
volume	获取音频/视频元素的音量。
width	获取元素的宽度。

create css rule(创建css规则)

创建一个新的 CSS规则。如果样式表属于外部HTML文档（Verge3D应用的 .html 文件通过 iframe嵌入其中），应启用 "in parent doc" 复选框。

set style(设置样式)

为具有指定id的HTML元素设置一个 CSS属性。如果HTML元素位于一个外部的HTML文档中（Verge3D应用的 .html 文件通过 iframe 嵌入其中），应启用 "in parent doc" 复选框。也适用于元素ID的列表。

get style(获取样式)

从指定id的HTML元素获取一个 CSS属性。如果HTML元素位于一个外部的HTML文档中（Verge3D应用的 .html 文件通过 iframe 嵌入其中），应启用 "in parent doc" 复选框。

这个拼图在制作3D配置器类应用时非常有用。例如，你可以使用下面的设置，从一些HTML元素的背景颜色中指定材质颜色：

set css rule(设置css规则)

为指定的CSS规则（可在应用的 .css 文件中找到）设置一个 CSS属性。如果样式表属于外部HTML文档（Verge3D应用的 .html 文件通过 iframe嵌入其中），应启用 "in parent doc" 复选框。

event(事件)

为一个具有指定id的HTML元素注册一个事件监听器。如果该HTML元素位于一个外部的HTML文档中（Verge3D应用的 .html 文件通过 iframe嵌入其中），应启用 "in parent doc" 复选框。一旦有事件发生，放在 "do" 插槽中的对象就会被触发。也适用于元素ID的列表。

get event property(获取事件属性)

输出由 "event(事件)" 拼图产生的事件属性值。

DOM object selector(DOM对象选择器)

container 代表画布容器元素——包含渲染场景的HTML元素；window 代表 DOM窗口对象 ——浏览器标签或加载HTML文档的iframe；document代表 DOM文档对象 ——HTML文档的根节点；body代表 DOM主体对象 ——HTML文档的<body>元素。

query selector(查询选择器)

返回第一个符合指定的 CSS选择器的HTML元素。

create canvas elem(创建canvas元素)

创建一个具有 id 、 width 和 height 属性的canvas元素。将此对象与 replace texture(替换纹理) 拼图一起使用，可用于创建画布纹理。

画布创建完成后，即可通过JavaScript在上面绘图了。您可以在 your_app_name.js 模块的 runCode() 函数中更新画布，或者使用 exec script(执行脚本) 拼图。

要更新画布，可通过ID（指定的id属性）检索画布纹理。


      var canvasTex = puzzles.canvasTextures['my_canvas'];

之后，您可以按以下方式访问HTML画布元素：


        var canvas = canvasTex.image;

您可以使用可用于在HTML画布上绘图的标准方法。例如，下方代码在白色背景上绘制了一张蓝色的笑脸：


    var ctx = canvas.getContext("2d");

    ctx.fillStyle = 'white';
    ctx.strokeStyle = 'blue';

    ctx.fillRect(0, 0, canvas.width, canvas.height);

    ctx.beginPath();
    ctx.arc(75, 75, 50, 0, Math.PI * 2, true); // Outer circle
    ctx.moveTo(110, 75);
    ctx.arc(75, 75, 35, 0, Math.PI, false);  // Mouth (clockwise)
    ctx.moveTo(65, 65);
    ctx.arc(60, 65, 5, 0, Math.PI * 2, true);  // Left eye
    ctx.moveTo(95, 65);
    ctx.arc(90, 65, 5, 0, Math.PI * 2, true);  // Right eye
    ctx.stroke();

最后，如果您想让更新在3D渲染中立即可见需将画布纹理标记为动态。


    canvasTex.needsUpdate = true;

有关使用示例，请查看 Canvas Texture 演示（也可在资源商店中找到）。

draw line(画线)

通过一个动态更新的线条将指定的3D对象与指定的HTML元素连接起来。如果HTML元素位于一个外部HTML文档中（Verge3D应用的 .html 文件通过 iframe) 嵌入其中），应启用 "in parent doc" 复选框。您也可以为该行设置宽度、颜色和偏移。

remove line(移除线)

从指定的对象中移除一条先前创建的线。

bind element(绑定元素)

使一个指定的HTML元素在屏幕空间中跟随一个指定的3D对象的中心。如果HTML元素位于一个外部HTML文档中（Verge3D应用的 .html 文件通过 iframe) 嵌入其中），应启用 "in parent doc" 复选框。

注意：

您可以使用 add annotation(添加注解) 拼图来代替，并参照这里的描述定制注解的外观。

unbind element(解除绑定元素)

取消绑定以前绑定到对象的指定HTML元素。如果HTML元素位于一个外部HTML文档中（Verge3D应用的 .html 文件通过 iframe) 嵌入其中），应启用 "in parent doc" 复选框。

init fullscreen(初始化全屏)

设置一个指定的HTML元素为全屏模式按钮——第一次点击进入全屏模式，第二次点击退出全屏。放在 "on enter do" 和 "on exit do" 插槽里的对象会在进入或退出全屏模式时被触发。如果浏览器不支持全屏，放在 "if unavailable do" 插槽中的对象会被触发（例如在iOS Safari中）。

open web page(打开网页)

当此拼图被触发时，根据下拉选择，一个指定的URL会在一个新的或同一浏览器标签内打开。当从拼图编辑器中触发时，跳出当前页面前会弹出确认提示。

选项：

a new tab: 在新标签中打开URL。为避免被浏览器的新标签页面规则限制，您只能在 when clicked(当点击时) 或 event(事件) 拼图中使用。
the same tab: 在同一标签内打开。
the same tab (ignore frames): 在同一标签内打开。用于让嵌入的iframe页面在其最顶层的浏览上下文中打开页面。
the same tab (parent frame): 在同一标签内打开。用于让嵌入的iframe页面在其父级浏览上下文中打开页面。
replace URL (no reload): 仅将指定的URL放入浏览器地址栏中。

social share link(社交网站分享链接)

生成一个链接，以便在主流社交媒体上分享你的应用。

set URL param(设置URL参数)

如有必要，可通过自动形成一个有效的查询字符串来分配或更新指定URL中的参数值，并返回更新的URL。

当一个应用的配置数据被存储在其URL中时，此对象会很有用。例如，您可以通过以下方式指定一张图片作为纹理使用：


      https://www.example.com/my_awesome_app.html?image_url=https://www.uploadserver.com/path/to/image.jpg

上传一个纹理，检索其服务器端的路径，并将其保存到应用URL的 image_url 参数中，如下所示：

请参阅Verge3D发行版中的 Custom Image 演示案例，了解其完整的工作方式。

take screenshot(截屏)

获取视口的截图并以数据URI 格式输出。

注意：

您需要使用 configure application(配置应用) 拼图为应用启用屏幕截图，否则将会生成全黑的图像。

get URL data(获取URL数据)

检索应用被加载到的窗口的URL数据。

Entire URL - 文本，例如： "https://www.example.com/my_awesome_app.html?image_url=https://www.uploadserver.com/path/to/image.jpg"
Parameters - 字典，例如： {"image_url": "https://www.uploadserver.com/path/to/image.jpg"}
Host name - 文本，例如： "www.example.com"

如果需要获取外部HTML文档的窗口（Verge3D应用的 .html 文件通过 iframe 嵌入其中），应启用 "in parent doc" 复选框。

当一个应用的配置数据被存储在其URL中时，此对象会很有用。例如，您可以通过以下方式指定一张图片作为纹理使用：


      https://www.example.com/my_awesome_app.html?image_url=https://www.uploadserver.com/path/to/image.jpg

然后您可以检索 image_url 参数，加载并应用该纹理，方法如下：

请参阅Verge3D发行版中的 Custom Image 演示案例，了解其完整的工作方式。

download file(下载文件)

下载以数据URI 格式指定的内容到一个文件中。您也可以传递文本、字典、或列表数据，作为文本或JSON文件下载。在这种情况下，给定的对象将被自动转换为适当的数据URI。

此拼图可用于以下情境：

保存屏幕截图
通过保存字典（或列表）到 *.json 文件来保存应用状态
以glTF格式导出模型，以便进一步处理
生成文本式的价格信息、报价、报告等。

open file(打开文件)

调用浏览器的本地对话窗口，从用户的设备中选择文件。当用户选择了文件后，以数据URI 格式返回文件的内容或信息。

opened file(打开的文件)

返回文件内容或元数据(metadata)。

选项：

data

以 Data URI 格式编码的文件内容。

name

文件名。

extension

不带点号的文件扩展名： txt, jpg, mp3等等...

size

以byte计算的文件体积。

mime type

文件媒体类型（又名 MIME 类型）。 Verge3D 应用通常使用的 mime 类型列表包括：

application/json	JSON 文件，也可用于 glTF 资产。
application/octet-stream	二进制文件(.bin)
audio/mpeg	MP3文件
image/jpeg	JPEG图像
image/png	PNG图像
text/csv	使用逗号分隔符的(CSV)文件
text/plain	纯文本文件(TXT)
video/mp4	MPEG-4视频

drop file to(将文件拖到)

返回一个从文件管理器（或其他程序）拖拽的文件，并将其放置在浏览器窗口内给定的HTML元素上。当用户拖放该文件后，将其内容作为 opened file(打开的文件) 拼图返回（使用数据URI 格式）。

您可以激活可选的 drag over 插槽来处理文件移动事件。例如，您可以将其与 raycast(射线) 拼图一起使用，以突出光标或触摸点下方的对象。

如何指定 Web 资源的 URL 路径

部分拼图在使用时需指定其所需要使用的Web资源的URL（又叫做URI）路径，例如：

open web page(打开网页) — 将要打开的网页地址。
replace texture(替换纹理) — 纹理的路径。
load sound(加载声音) — 声音资产的路径。
load scene(加载场景) — glTF 资产。
create text object(新建文本对象) — 字体。

对于此处提到的URL路径，您必须要了解，其与您在本地计算机中看到的路径完全不同。因为网页上的所有资源都是通过 Web浏览器 从 web服务器 中间接获取的。

因此，您应该牢记永远不要使用这样的URL路径：

C:\Users\User\Documents\verge3d_apps\my_app\my_scene.gltf
/Users/User/Downloads/my_sound.mp3
/home/user/Desktop/my_texture.jpg

Web中的路径仅使用正斜杠(/)指定，类似这样：

相对路径

相对于应用HTML指定的路径：

my_scene.gltf or ./my_scene.gltf — 该场景文件位于与应用HTML文件相同的目录中。
sounds/my_sound.mp3 — 声音文件位于与应用HTML存储目录对应的 sounds 子目录中的声音。
../textures/my_texture.jpg — 位于 textures 目录中的纹理文件，该目录位于应用HTML文件目录的上一层中（因此这里有两个点）。

绝对路径

当您知道资源在 web服务器 上的确切位置时，可以使用绝对路径指定其位置：

https://www.my_host.com/my_app/my_scene.gltf — 场景文件存储在 my_host 服务器中的 my_app 中。
/my_app/fonts/my_font.woff — 字体文件存储在任意主机（名称未知或无关紧要）的 my_app 目录的 fonts 子目录中。

Data URI

表示未存储在Web服务器上的编码资源的特殊类型的数据URL。我们用此类链接返回由某些拼图生成或检索的数据。点击此处，了解更多。

Data URI Links(数据URI链接)

数据URI（又称为数据URL）是一种方便的方法，可以嵌入各种资产，如图片、glTF模型、声音、JSON或CSV的链接（技术资料）。

例如，下面的链接代表了Verge3D的logo：


      data:image/png;base64,
      iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC/xhBQAAACBjSFJN
      AAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAABvFBMVEUAAAAASKUAAFsAvukA
      RaMA3voAAEoARaQARKMARqQARqQARKMARaQARqQAQ6IATagCcLwCcbwATagARqQASaYARqQASKUC
      argASKUARqQASqYASKUAR6QAT6kAT6kAR6QAR6UASaUASaUAR6UARKMBWq8BWq8ARKMAQqECaLcC
      abgAQqEAQaECbboCbroAQaECbrsCbroCabcCa7kCb7sCbrsARaQARaQElNAEldEGrd4GseEDg8cD
      hcgGtOIGrt8Eks8I1/cFqNwBUqsAQ6IBVKwGrN4Ekc8El9IJ5/8HvOcBU6sASqYDdb8CdL4ASaYB
      VawHv+gJ5/4EltII0PIJ4PsCc70ARqQEjs0J4vwJ4fsEi8sARaMDdr8J4fwI0fIJ3/sGuuYATKcC
      ZbYI1fUHyfMHyPMI0/QCYrQATagHvecJ4PwEj80ARKMFnNQHyvMBU8IBUsEFmNII3PkHwuoIyvQH
      vugAS6cDecEI1/YCbrsBWK4I0vMJ5v8HyPIIz/ICcr0I2PcIz/EDgMUBXrEJ6P8I1vYBW7ADhMcC
      cb0Hv+kFmNMEkM4GueUJ4PoJ3/oJ3voI3foEltH///+98SuhAAAAOHRSTlMAAAAAAAAAJJPu8Jgn
      EWjT/v7VEAVLvvq8RwQFe/LweDXn6DdT9/hXWvn6XVv5+lz6+fn6/v7w7sPq7QcAAAABYktHRJPh
      A9+2AAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4QsCEC4OPIwcRgAAAQpJREFUGNNjYGBg
      YGRi5+Dk4uZhZmQAAUYWXj5+AQtLQSE+YRagEKOIqJi4lbWNrZ29uISkFCODtIysg6OTs4uLq5uj
      u5y8NIOCooenl7ePr59/QGBQsJIyg4pqSGhYeERkVHRMbFy8mjqDhmZCYlJySmpaekZmVoKWNoOO
      bnZObl5+QWFqUa5DnJ4+g75BsW9SSWlBQX5ZeUWxoQ6DtnhlVXVNbVpdbX1AQ6ORBoO6WlNzS6Nn
      a6tnW3tHk6oKg7JSkVdYpWdtrWdKZ1e3ogKDtLxcT28fSKA/0UFWRpqBUUpSwth+QmvrRHtjMVER
      kGdYhPmETCZZmvLz8bJA/cvKw21mzsHOBuICAHx4PYwwa1fDAAAAJXRFWHRkYXRlOmNyZWF0ZQAy
      MDE3LTExLTAyVDE2OjQ2OjE0KzAxOjAwKvGBdAAAACV0RVh0ZGF0ZTptb2RpZnkAMjAxNy0xMS0w
      MlQxNjo0NjoxNCswMTowMFusOcgAAAAZdEVYdFNvZnR3YXJlAHd3dy5pbmtzY2FwZS5vcmeb7jwa
      AAAAV3pUWHRSYXcgcHJvZmlsZSB0eXBlIGlwdGMAAHic4/IMCHFWKCjKT8vMSeVSAAMjCy5jCxMj
      E0uTFAMTIESANMNkAyOzVCDL2NTIxMzEHMQHy4BIoEouAOoXEXTyQjWVAAAAAElFTkSuQmCC

复制整个片段并粘贴到浏览器地址栏中打开即可在页面显示该图标。

在拼图中，我们广泛使用数据URI链接，因为它们提供了在不同拼图块之间传递类似于文件的数据的便捷方式。例如，您可以使用 open file(打开文件) 或 drag file to(将文件拖到) 拼图加载文件（图像或数据）。然后您可以根据该文件对您的场景进行修改。之后，您可以通过 download file(下载文件)拼图将修改后的场景（或数据，比如价格表文件）上传到用户机器上，或通过 send data(发送数据) 拼图将该文件上传到服务器。在所有这些情况中，数据都将使用数据URI格式传输。

请参阅Verge3D发行版中的 Custom Image 演示案例，了解数据URI的使用方法。

调试Data URI格式的数据也很容易。只需使用 print to console(打印到控制台) 拼图，然后打开 browser console(浏览器控制台) 来观察输出，然后点击控制台内打印的URI，在单独的浏览器标签中预览数据。

在使用拼图时遇到困难？

欢迎您随时在论坛上提问！您还可以加入中文用户社区QQ群(171678760)，在线寻求帮助。