Clipboard API 和事件

script-may-access-clipboard 标志的设置如下：

1. 如果动作为 copy 或 cut 且脚本线程被允许修改剪贴板，则：

   1. 设置该动作的 script-may-access-clipboard 标志。

2. 如果动作为 paste 且脚本线程被允许从剪贴板读取，则：

   1. 设置该动作的 script-may-access-clipboard 标志。

复制动作由以下步骤组成：

1. 如果 script-triggered 标志已设置，则：

   1. 如果 script-may-access-clipboard 标志未设置，则：

      1. 从复制动作返回 false，终止此算法。

2. 触发一个名为 copy 的剪贴板事件。

3. 如果该事件未被取消，则：

   1. 将所选内容（如有）复制到剪贴板。在网页中选定内容时，实现应该创建替代的 text/html 和 text/plain 剪贴板格式。

   2. 触发一个名为 clipboardchange 的剪贴板事件。

4. 否则，如果该事件被取消，则：

   1. 调用将内容写入剪贴板算法，传递 DataTransferItemList 列表 items、一个 clear-was-called 标志和一个 types-to-clear 列表。

5. 从复制动作返回 true。

剪切动作由以下步骤组成：

1. 如果 script-triggered 标志已设置，则：

   1. 如果 script-may-access-clipboard 标志未设置，则：

      1. 从剪切动作返回 false，终止此算法。

2. 触发一个名为 cut 的剪贴板事件。

3. 如果该事件未被取消，则：

   1. 如果在一个启用了剪切的可编辑上下文中存在选区，则：

      1. 将所选内容（如有）复制到剪贴板。在网页中选定内容时，实现应该创建替代的 text/html 和 text/plain 剪贴板格式。

      2. 从文档中删除选区的内容并折叠选区。

      3. 触发一个名为 clipboardchange 的剪贴板事件。

      4. 排队任务以触发由于修改而应触发的任何事件，详见 § 5.3 与其他脚本和事件的集成。

   2. 否则，如果不存在选区或者上下文不可编辑，则：

      1. 返回 false。

4. 否则，如果该事件被取消，则：

   1. 调用将内容写入剪贴板算法，传递 DataTransferItemList 列表 items、一个 clear-was-called 标志和一个 types-to-clear 列表。

   2. 触发一个名为 clipboardchange 的剪贴板事件。

5. 从剪切动作返回 true。

粘贴动作由以下步骤组成：

1. 如果 script-triggered 标志已设置，则：

   1. 如果 script-may-access-clipboard 未设置，则：

      1. 从粘贴动作返回 false，终止此算法。

2. 触发一个名为 paste 的剪贴板事件。

3. 如果该事件未被取消，则：

   1. 如果在一个启用了粘贴的可编辑上下文中存在选区或光标，则：

      1. 将剪贴板上找到的最合适内容（如有）插入到该上下文中。

      2. 排队任务以触发由于修改而应触发的任何事件，详见 § 5.3 与其他脚本和事件的集成。

   2. 否则：

      1. 返回 false。

4. 否则，如果事件被取消：

   1. 返回 false。

5. 从该动作返回 true。

9.1.1. check clipboard read permission

1. 设 hasGesture 为 true（如果 this 的相关全局对象具有瞬时激活），否则为 false。

2. 如果 hasGesture 则：

   1. 如果当前脚本是由于用户与用户代理或操作系统创建的“粘贴”元素交互而运行的，则返回 true。

3. 返回 false。

9.2.1. check clipboard write permission

1. 设 writeWithoutGesture 为 { name: "clipboard-write", allowWithoutGesture: true } 权限的权限状态。

2. 如果 writeWithoutGesture 为 granted，则返回 true。

3. 设 hasGesture 为 true（如果 this 的相关全局对象具有瞬时激活），否则为 false。

4. 如果 hasGesture 则：

   1. 设 systemCopy 为 true（如果当前脚本是由于用户与用户代理或操作系统创建的“剪切”或“复制”元素交互而运行的）。

   2. 如果 systemCopy 为 true，则返回 true。

   3. 返回请求使用 { name: "clipboard-write", allowWithoutGesture: false } 权限的结果。

      注意： 用户代理可以选择请求更强的权限，这将隐式更新此权限。

5. 返回请求使用 { name: "clipboard-write", allowWithoutGesture: true } 权限的结果。

write content to the clipboard

输入：

items，一个要写入的 DataTransferItemList 项列表

clear-was-called，一个布尔值

types-to-clear，一个列表

输出：

无

1. 如果 items 列表不为空，则：

   1. 清除剪贴板。

   2. 对于列表中的每个部分：

      1. 如果数据类型是 text/plain，则：

         1. 根据操作系统和区域设置约定确保编码正确。

         2. 根据平台约定规范化行尾。

         3. 使用适当的操作系统剪贴板格式描述将文本置于剪贴板上。

      2. 否则，如果数据类型列在强制数据类型列表中，则：

         1. 使用适当的操作系统剪贴板格式描述将该部分置于剪贴板上。

      3. 否则：

         1. 这留给实现处理……

            将事情留给实现处理并不好。这里应该发生什么？

            注意： 由于操作系统剪贴板实现中的限制，脚本不应假定自定义格式可供系统上的其他应用程序使用。例如，在 Microsoft Windows 中可注册的自定义剪贴板格式数量有限。虽然可以将任何字符串用于 setData() 的 type 参数，但强烈建议坚持使用强制数据类型。

2. 否则，items 列表为空。遵循以下步骤以确定是否清除剪贴板：

   1. 如果项目列表为空且 clear-was-called 标志为 true，则：

      1. 如果 types-to-clear 列表为空，则：

         1. 清除剪贴板。

      2. 否则：

         1. 以操作系统和特定于实现的方式从剪贴板中移除 types-to-clear 列表中的类型。

            “从剪贴板移除特定类型”功能处于风险之中。它似乎并不那么重要，而且不清楚它是否能轻易地在相关平台上实现。

write blobs and option to the clipboard

输入：

items，一个 序列<Blob>

presentationStyle，一个 剪贴板项 的 表现样式

输出：

无

1. 设 webCustomFormats 为一个 序列<Blob>。

2. 对于 items 中的每个 item：

   1. 设 formatString 为在给定 item 的 type 的情况下，运行特定操作系统公认格式的结果。

   2. 如果 formatString 为空，则遵循以下步骤：

      1. 设 webCustomFormatString 为 item 的 type。

      2. 设 webCustomFormat 为一个空的 type。

      3. 如果 webCustomFormatString 以 `"web "` 前缀开头，则移除该前缀并将剩余字符串存储在 webMimeTypeString 中。

      4. 设 webMimeType 为在给定 webMimeTypeString 的情况下，解析 MIME 类型的结果。

      5. 如果 webMimeType 解析失败，则中止所有步骤。

      6. 令 webCustomFormat 的 type 的本质等于 webMimeType。

      7. 将 item 的 type 设置为 webCustomFormat。

      8. 将 webCustomFormat 追加到 webCustomFormats 中。

   3. 设 payload 为 UTF-8 解码 item 的底层字节序列的结果。

   4. 将 payload 和 presentationStyle 插入到系统剪贴板中，并使用 formatString 作为原生剪贴板格式。

   某些操作系统包含多个剪贴板（例如 Linux 的 "primary"、"secondary"、"selection"）。定义数据被写入其中的剪贴板。

3. 在给定 webCustomFormats 的情况下写入 Web 自定义格式。

os specific well-known format

输入：

mimeType，一个 type

输出：

wellKnownFormat，一个特定于平台的字符串类型。在 Mac 上是 NSPasteboardType，在 Windows 上是 LPCWSTR，在 Linux 上是 const char*。

对于 Windows，请参阅 https://docs.microsoft.com/en-us/windows/win32/dataxchg/standard-clipboard-formats 和 https://docs.microsoft.com/en-us/windows/win32/dataxchg/about-atom-tables?redirectedfrom=MSDN。对于 Mac，请参阅 https://developer.apple.com/documentation/appkit/nspasteboardtype。

1. 设 wellKnownFormat 为空字符串。

2. 如果 mimeType 的本质是 "text/plain"，则：

   在 Windows 上，遵循以下描述的约定：

   1. 将 CF_UNICODETEXT 分配给 wellKnownFormat。

   在 MacOS 上，遵循以下描述的约定：

   1. 将 NSPasteboardTypeString 分配给 wellKnownFormat。

   在 Linux、ChromeOS 和 Android 上，遵循以下描述的约定：

   1. 将 "text/plain" 分配给 wellKnownFormat。

3. 否则，如果 mimeType 的本质是 "text/html"，则：

   在 Windows 上，遵循以下描述的约定：

   1. 将 CF_HTML 分配给 wellKnownFormat。

   在 MacOS 上，遵循以下描述的约定：

   1. 将 NSPasteboardTypeHTML 分配给 wellKnownFormat。

   在 Linux、ChromeOS 和 Android 上，遵循以下描述的约定：

   1. 将 "text/html" 分配给 wellKnownFormat。

4. 否则，如果 mimeType 的本质是 "image/png"，则：

   在 Windows 上，遵循以下描述的约定：

   1. 将 "PNG" 分配给 wellKnownFormat。

   在 MacOS 上，遵循以下描述的约定：

   1. 将 NSPasteboardTypePNG 分配给 wellKnownFormat。

   在 Linux、ChromeOS 和 Android 上，遵循以下描述的约定：

   1. 将 "image/png" 分配给 wellKnownFormat。

5. 否则，如果 mimeType 的本质是 "image/svg+xml"，则：

   在 Windows 上，遵循以下描述的约定：

   1. 将 CFSTR_MIME_SVG_XML 分配给 wellKnownFormat。

   在 MacOS 上，遵循以下描述的约定：

   1. 将 UTTypeSVG 分配给 wellKnownFormat。

   在 Linux、ChromeOS 和 Android 上，遵循以下描述的约定：

   1. 将 "image/svg+xml" 分配给 wellKnownFormat。

6. 返回 wellKnownFormat。

well-known mime type from os specific format

输入：

osFormatName，一个特定于平台的字符串类型。在 Mac 上是 NSPasteboardType，在 Windows 上是 LPCWSTR，在 Linux 上是 const char*。

输出：

mimeType，一个 MIME 类型

对于 Windows，请参阅 https://docs.microsoft.com/en-us/windows/win32/dataxchg/standard-clipboard-formats 和 https://docs.microsoft.com/en-us/windows/win32/dataxchg/about-atom-tables?redirectedfrom=MSDN。对于 Mac，请参阅 https://developer.apple.com/documentation/appkit/nspasteboardtype。

在 Windows 上，遵循以下描述的约定：

1. 如果 osFormatName 为 "UnicodeText"，则设置 mimeTypeString 为 "text/plain"。

2. 否则，如果 osFormatName 为 "HTML Format"，则设置 mimeTypeString 为 "text/html"。

3. 否则，如果 osFormatName 为 "PNG"，则设置 mimeTypeString 为 "image/png"。

4. 否则，如果 osFormatName 为 CFSTR_MIME_SVG_XML，则设置 mimeTypeString 为 "image/svg+xml"。

在 MacOS 上，遵循以下描述的约定：

1. 如果 osFormatName 为 NSPasteboardTypeString，则设置 mimeTypeString 为 "text/plain"。

2. 否则，如果 osFormatName 为 NSPasteboardTypeHTML，则设置 mimeTypeString 为 "text/html"。

3. 否则，如果 osFormatName 为 NSPasteboardTypePNG，则设置 mimeTypeString 为 "image/png"。

4. 否则，如果 osFormatName 为 UTTypeSVG，则设置 mimeTypeString 为 "image/svg+xml"。

在 Linux、ChromeOS 和 Android 上，遵循以下描述的约定：

1. 如果 osFormatName 为 "text/plain"，则设置 mimeTypeString 为 "text/plain"。

2. 否则，如果 osFormatName 为 "text/html"，则设置 mimeTypeString 为 "text/html"。

3. 否则，如果 osFormatName 为 "image/png"，则设置 mimeTypeString 为 "image/png"。

4. 否则，如果 osFormatName 为 "image/svg+xml"，则设置 mimeTypeString 为 "image/svg+xml"。

1. 设 mimeType 为在给定 mimeTypeString 的情况下，解析 MIME 类型的结果。

2. 返回 mimeType。

read web custom format

输入：

item，一个 剪贴板项

1. 设 webCustomFormatMap 为特定操作系统自定义映射名称。

2. 从系统剪贴板读取 webCustomFormatMap。

   更详细地说明读取 webCustomFormatMap 的过程。

3. 如果 webCustomFormatMap 为空，则返回 item。

4. 设 webCustomFormatMapString 为从 webCustomFormatMap 反序列化的 JSON 字符串。

   注意： 需要一个 JSON 读取器来反序列化来自 webCustomFormatMap 的内容。

5. 对于 webCustomFormatMapString 中的每个 (key, value)：

   1. 设 mimeType 为在给定 key 的情况下，解析 MIME 类型的结果。

   2. 如果 mimeType 解析失败，则继续循环。

   3. 设 representation 为一个新的表示。

   4. 将 representation 的MIME 类型设置为 mimeType。

   5. 将 representation 的isCustom 标志设置为 true。

   6. 在给定 value 的情况下，从系统剪贴板读取 webCustomFormat。

   7. 如果读取成功，则将 representation 的数据设置为来自系统剪贴板的结果数据，否则继续循环。

   8. 将 representation 追加到 item 的表示列表中。

write web custom formats

输入：

items，一个 序列<Blob>

1. 设 idx 为初始化为 0 的数字。

2. 设 webCustomFormatMap 为特定操作系统自定义映射名称。

3. 设 webCustomFormatMapString 为一个空的 JSON 字符串。

4. 对于 items 中的每个 item：

   1. 设 webCustomFormat 为特定操作系统自定义名称。

   2. 设 webCustomFormatIdx 为将 idx 追加到 webCustomFormat 的结果。

   3. 使用 JSON 序列化器将 item 的 type 作为键，将 webCustomFormatIdx 作为值插入到 webCustomFormatMapString 中。

      注意： 需要一个 JSON 写入器来将内容序列化为 webCustomFormatMapString。

   4. 使用 webCustomFormatIdx 作为格式将 item 插入到系统剪贴板中。

   5. 递增 idx。

   6. 如果 idx 大于 100，则跳出此循环。

5. 使用 webCustomFormatMap 作为格式将 webCustomFormatMapString 插入到系统剪贴板中。

os specific custom map name

输出：

webCustomFormatMap，一个字符串

在 Windows 上，遵循以下描述的约定：

1. 将 "Web Custom Format Map" 分配给 webCustomFormatMap。

2. 返回 webCustomFormatMap。

在 MacOS 上，遵循以下描述的约定：

1. 将 "org.w3.web-custom-format.map" 分配给 webCustomFormatMap。

2. 返回 webCustomFormatMap。

在 Linux、ChromeOS 和 Android 上，遵循以下描述的约定：

1. 将 "application/web;type=\"custom/formatmap\"" 分配给 webCustomFormatMap。

2. 返回 webCustomFormatMap。

os specific custom name

输出：

webCustomFormat，一个字符串

在 Windows 上，遵循以下描述的约定：

1. 将 "Web Custom Format" 分配给 webCustomFormat。

2. 返回 webCustomFormat。

在 MacOS 上，遵循以下描述的约定：

1. 将 "org.w3.web-custom-format.type-" 分配给 webCustomFormat。

2. 返回 webCustomFormat。

在 Linux、ChromeOS 和 Android 上，遵循以下描述的约定：

1. 将 "application/web;type="custom/format" 分配给 webCustomFormat。

2. 返回 webCustomFormat。

fire a clipboard event

输入：

e，要触发的 ClipboardEvent

输出：

无

1. 设 clear-was-called 为 false。

2. 设 types-to-clear 为一个空列表。

3. 设 clipboard-event-data 为一个新的 DataTransfer 对象，具有空的 items 列表。

4. 设 clipboard-entry 为当前剪贴板内容的序列号，如果操作系统剪贴板不支持序列号，则为 null。

5. 设 trusted 为 true（如果事件由用户代理生成），否则为 false。

6. 设置 target 如下：

   1. 如果上下文是可编辑的，则：

      1. 将 target 设置为包含文档顺序中可见选区或光标起点的元素，如果不存在可见选区或光标，则为 body 元素。

   2. 否则，如果上下文不可编辑，则：

      1. 将 target 设置为聚焦节点，如果没有节点拥有焦点，则为 body 元素。

7. 处理事件如下：

   1. 如果 e 为 "paste"，则：

      1. 将 clipboard-event-data 的内部拖拽数据存储模式标志设置为 只读。

      2. 如果 trusted 为 true，或者实现被配置为允许脚本生成的事件读取操作系统剪贴板：

         1. 对于操作系统剪贴板上的每个 clipboard-part，执行以下步骤：

            1. 如果 clipboard-part 包含纯文本，则：

               1. 确保文本处于脚本引擎内部使用的编码中。

               2. 设 new-data 为一个新的 DataTransferItem，拖拽数据项种类设置为 string，拖拽数据项类型字符串设置为 text/plain。

               3. 将 new-data 的数据设置为纯文本。

               4. 将 new-data 添加到 clipboard-event-data 的 items 中。

            2. 如果 clipboard-part 表示文件引用，则对于每个文件引用：

               1. 确定引用文件的 MIME 类型。

               2. 设 new-data 为一个新的 DataTransferItem，拖拽数据项种类设置为 file，拖拽数据项类型字符串设置为相应的 MIME 类型，如果文件类型未知，则为 application/octet-stream。

               3. 将 new-data 的数据设置为文件引用数据。

               4. 将 new-data 添加到 clipboard-event-data 的 items 中。

            3. 如果 clipboard-part 包含 HTML 或 XHTML 格式的文本（根据操作系统描述此类剪贴板格式的约定），则：

               1. 如果实现支持粘贴 HTML，则实现必须通过调用处理 html 粘贴事件（传入 clipboard-part 和 clipboard-event-data）来处理标记。

            4. 如果 clipboard-part 包含其他受支持的二进制或基于文本的格式的数据（参见强制数据类型），则：

               1. 确定数据的 MIME 类型。

               2. 设 new-data 为一个新的 DataTransferItem，拖拽数据项种类设置为 file，拖拽数据项类型字符串设置为相应的 MIME 类型。

               3. 将 new-data 的数据设置为二进制或基于文本的数据。

               4. 将 new-data 添加到 clipboard-event-data 的 items 中。

      3. 更新 clipboard-event-data 的 files 属性，以匹配 clipboard-event-data 的 items 中的条目。

      4. 更新 clipboard-event-data 的 types 属性，以匹配 clipboard-event-data 的 items 中的条目。

   2. 如果 e 为 "copy" 或 "cut"，则：

      1. 将关联的 DataTransfer 对象的内部拖拽数据存储模式标志设置为 读/写。

8. 将 e 的 clipboardData 设置为 clipboard-event-data。

9. 将 e 的 isTrusted 设置为 trusted。

10. 将 e 的 composed 设置为 true。

11. 在该 target 上分发该事件 e，该事件冒泡且可取消，并使用 ClipboardEvent 接口。

    事件分发期间访问数据的实现要求定义在 [HTML] 中。下面给出了一些额外的剪贴板事件特定的处理规则：

    为什么在这里？为什么不在 HTML 规范中？

    1. 如果脚本调用 clearData() 或 clear() 且 DataTransfer 对象的内部拖拽数据存储模式标志为 读/写，则：

       1. 将 clear-was-called 标志设置为 true。如果给定了参数，则将该参数添加到 types-to-clear 列表中。

    2. 如果脚本调用 setData() 或修改了项，且 clear-was-called 标志为 true，则：

       1. 如果 types-to-clear 列表为空，则：

          1. 将 clear-was-called 标志设置为 false，然后……

       2. 否则，如果 setData() 的 type 参数或新项的拖拽数据项类型字符串在 types-to-clear 列表中找到，则：

          1. 从列表中删除它。如果列表现在为空，则将 clear-was-called 标志设置为 false。

    3. 如果脚本调用 getData() 或访问 DataTransferItemList 中的项且 clipboard-entry 已设置，则：

       1. 检查剪贴板数据的序列号是否匹配 clipboard-entry。如果剪贴板不再包含相同的条目，则将 DataTransferItemList 对象的内部拖拽数据存储模式设置为 受保护。

    警告！监听粘贴事件的恶意脚本可能会建立一个永无止境的循环，以便读取用户将来放入剪贴板的内容。在没有剪贴板序列号的平台上，应实施其他限制。

处理 HTML 粘贴事件

输入：

clipboard-part，要处理的剪贴板部分

clipboard-event-data，此事件的 DataTransfer 对象

输出：

无

1. 令 new-data 为一个新的 DataTransferItem，其 拖拽数据项类型 设置为“纯 Unicode 字符串”，拖拽数据项类型字符串 相应地设置为 text/html 或 application/xhtml+xml。

2. 从 clipboard-part 中提取标记并使用相关解析器构建 DOM 树。

3. 如果标记的源 URL 已知，则使用该源 URL 作为基础 URL 解析 HREF 和 SRC 属性中的所有相对 URL，并将相应属性设置为解析后的绝对 URL。

4. 如果标记来源于本地应用程序，则检查是否存在对本地文件和/或其他 OS 剪贴板内容部分的引用。如果找到此类引用，则对子部分的引用必须替换为使用 cid: URL 方案的 content-id 引用 [RFC2392]。为此，请按照以下步骤处理引用本地文件或剪贴板部分的每个属性：

   这些步骤是必要的吗？我们是否了解支持多个具有内部引用的部分的本机（平台）剪贴板实现？

   此功能处于风险之中，因为尚不清楚是否需要它，而且难以以跨平台的方式进行测试。

   1. 如果 clipboard-event-data 的 items 已包含所引用的文件或剪贴板部分的条目，则

      1. 将 itemNumber 设置为现有条目的索引。

   2. 否则，

      1. 令 new-file-data 为一个新的 DataTransferItem，其 拖拽数据项类型 设置为“文件”，并且如果已知文件或剪贴板部分的 MIME 类型，则将 拖拽数据项类型字符串 设置为该 MIME 类型，如果文件类型未知，则设置为 application/octet-stream。

      2. 令 file-info 为一个新的 File 对象，其 name 设置为 HTML 属性内容的名称部分，并将 lastModified 设置为所引用文件的时间戳，如果条目引用的是剪贴板部分，则设置为 0。

      3. 将 new-file-data 的内部 File 对象设置为 file-info。

      4. 将 new-file-data 添加到 clipboard-event-data 的 items 中，并令 itemNumber 为该条目在 DataTransferItemList 中的索引。

   3. 更新引用本地文件或剪贴板部分的 DOM 属性，使其包含字符串 'cid:' 后跟 itemNumber。

5. 序列化处理后的 DOM 并使用生成的 HTML 代码更新 new-data。

6. 将 new-data 添加到 clipboard-event-data 的 items 中。