Debugger.Source

Debugger.Source 实例表示 JavaScript 源代码片段或 WebAssembly 代码块的序列化文本。这两种情况的区别在于后者其 introductionType 属性始终为 "wasm"，而前者其 introductionType 属性永远不会为 "wasm"。

每个 Debugger 实例都有一个单独的 Debugger.Source 实例集合，这些实例表示已呈现给系统的源代码。

调试器可以在 Debugger.Source 实例上放置其自己的属性，以存储有关特定源代码片段的元数据。

JavaScript 的 Debugger.Source

对于表示 JavaScript 源代码片段的 Debugger.Source 实例，其属性以字符串形式提供源代码本身，并描述其来源。每个 Debugger.Script 实例都引用包含其生成源代码的 Debugger.Source 实例。

如果单个源代码片段同时包含顶级代码和函数定义（可能还有嵌套函数），那么所有这些函数的 Debugger.Script 实例都引用同一个 Debugger.Source 实例。每个脚本都指示其对应的整体源代码的子字符串。

Debugger.Source 实例可能仅表示较大源文档的一部分。例如，HTML 文档可以在多个 <script> 元素和事件处理程序内容属性中包含 JavaScript。在这种情况下，整个 HTML 文档可能只有一个 Debugger.Source 实例，每个 Debugger.Script 都引用其文档的子字符串；或者每个 <script> 元素和属性可能都有一个单独的 Debugger.Source 实例。选择权由实现决定。

如果将给定的源代码片段多次呈现给 JavaScript 实现，并且具有相同的来源元数据，则 JavaScript 实现可以生成一个新的 Debugger.Source 实例来表示每次呈现，或者可以使用单个 Debugger.Source 实例来表示所有这些呈现。

WebAssembly 的 Debugger.Source

对于表示 WebAssembly 代码块的序列化文本的 Debugger.Source 实例，其属性以字符串形式提供序列化文本。

目前仅表示通过 new WebAssembly.Module 评估的整个模块。SpiderMonkey 为每个底层 WebAssembly 模块（每个 Debugger 实例）构造恰好一个 Debugger.Source。

请注意，在撰写本文时，对 WebAssembly 的支持还处于非常初步的阶段。以下许多属性都返回占位符值。

约定

对于以下属性和方法的描述，如果属性或方法的行为在引用 JavaScript 源的实例和引用 WebAssembly 代码块的实例之间有所不同，则文本将分为两个部分，分别以“**如果实例引用 JavaScript 源**”和“**如果实例引用 WebAssembly 代码**”为标题。如果行为没有区别，则不会出现此类强调的标题。

Debugger.Source 原型对象的访问器属性

Debugger.Source 实例从其原型继承以下访问器属性

text

**如果实例引用 JavaScript 源**，则为 JavaScript 源代码（作为字符串）。该值满足 ECMAScript 标准中的 Program、FunctionDeclaration 或 FunctionExpression 产生式。

**如果实例引用 WebAssembly 代码**，则将返回 "[wasm]" 值。

binary

**如果实例引用 WebAssembly 代码**，则为包含 WebAssembly 字节码的 Uint8Array。

url

**如果实例引用 JavaScript 源**，则为加载此脚本代码的文件名或 URL。对于由 eval 或 Function 构造函数创建的脚本，这可能是一个合成的文件名，以有效的 URL 开头，后跟跟踪代码如何引入系统的信息；整个字符串不是有效的 URL。对于 Function.prototype 的脚本，这是 null。源代码可以通过以下方式从 URL 加载

• URL 可能会出现在标记文本中 <script> 元素的 src 属性中。

• URL 可能会传递给 Worker web 工作线程构造函数或 web 工作线程 importScripts 函数。

• URL 可能是 XPCOM JavaScript 模块或下标的名称。

（请注意，传递给 eval、Function 构造函数或类似函数的代码不被认为是从 URL 加载的；此类源的 Debugger.Source 实例上的 url 访问器应返回 undefined。）

**如果实例引用 WebAssembly 代码**，则为调用 new WebAssembly.Module 并附加字符串 "> wasm" 的脚本的 URL。

startLine

**如果实例引用 JavaScript 源**，则为源代码在加载它的文件或 URL 中的 1 为起始的行号。这通常为 1，但如果源代码是 HTML 文档的一部分，则可能具有其他值。

startColumn

**如果实例引用 JavaScript 源**，则为源代码在加载它的文件或 URL 中的 1 为起始的 UTF-16 代码单元列号。这通常为 1，但如果源代码是 HTML 文档的一部分，则可能具有其他值。

id

**如果实例引用 JavaScript 源**，则为一个 int32 计数器，用于识别当前进程中的源代码。此 ID 用于 Gecko 中其他弱引用源代码的地方，例如 nsIScriptError。

sourceMapURL

**如果实例引用 JavaScript 源**，如果此源是由最小化器生成的或从其他语言翻译而来，并且我们知道源映射文档的 URL（将此源代码中的源位置与原始源代码中的相应源位置相关联），则此属性的值为此 URL。否则，此值为 null。

（在网络上，翻译器可以在 JavaScript 源代码中以特殊格式的注释提供源映射 URL，或者通过承载生成的 JavaScript 的 HTTP 回复中的标头提供。）

此属性是可写的，因此您可以通过设置它来更改源映射 URL。所有引用相同源的 Debugger.Source 对象都将看到更改。设置空字符串无效，不会更改现有值。

**如果实例引用 WebAssembly 代码**，则为 null。尝试写入此属性将引发 TypeError。

displayURL

如果脚本包含特殊的 //# sourceURL 注释（如源映射规范中所述），则此属性的值将保存该字符串。否则，此值为 null。

element

引用此源代码所属的 DOM 元素的 Debugger.Object 实例（如果有），或者如果它不属于任何 DOM 元素，则为 undefined。源代码在以下情况下属于 DOM 元素

• 源代码属于 <script> 元素，如果它是元素的文本内容（即，它在标记文本中作为 <script> 元素的主体写出），或者是由其 src 属性引用的源文档。

• 源代码属于 DOM 元素，如果它是事件处理程序内容属性（即，如果它在标记文本中作为属性值写出）。

• 源代码属于 DOM 元素，如果它作为字符串分配给元素的事件处理程序 IDL 属性之一。（请注意，可以将字符串和函数都分配给 DOM 元素的事件处理程序 IDL 属性。如果分配了一个函数，则该函数的脚本源不属于 DOM 元素；函数的定义必须出现在其他地方。）

（如果附加到 DOM 元素的源代码发生更改，则表示被替换代码的 Debugger.Source 实例仍将引用 DOM 元素；此访问器仅反映来源，而不反映当前关系。）

elementAttributeName

如果此源代码属于 DOM 元素，因为它是一个事件处理程序内容属性或事件处理程序 IDL 属性，则这是一个字符串，表示该属性的名称。否则，此值为 undefined。

introductionType

如果实例引用 JavaScript 源代码，则为一个字符串，指示此源代码是如何引入系统的。此访问器返回以下值之一

• "eval"，用于传递给 eval 的代码。

• "debugger eval"，用于调试器评估的代码。

• "Function"，用于传递给 Function 构造函数的代码。

• "GeneratorFunction"，用于传递给生成器构造函数的代码。

• "AsyncFunction"，用于传递给异步函数构造函数的代码。

• "AsyncGenerator"，用于传递给异步生成器构造函数的代码。

• "Worklet"，用于工作线程加载的代码。

• "importScripts"，用于在 Web Worker 中调用 importScripts 的代码。

• "eventHandler"，用于作为字符串分配给 DOM 元素的事件处理程序 IDL 属性的代码。

• "srcScript"，用于属于 <script src="file.js"> 元素的代码。

• "inlineScript"，用于属于 <script>code;</script> 元素的代码。

• "injectedScript"，用于属于脚本的代码，这些脚本将是 "inlineScript"，但它们不是初始文件本身的一部分。

  例如，通过以下方式创建的脚本

  • document.write("<script>code;</script>")

  • var s = document.createElement("script"); s.text = "code";

• "importedModule"，用于通过另一个脚本使用 ESM 静态或动态导入间接加载的代码。

• "javascriptURL"，用于在 javascript: URL 中显示的代码。

• "domTimer"，用于作为字符串传递给 setTimeout/setInterval 的代码。

• "self-hosted"，用于内部自托管 JS 代码。

• undefined，如果实现不知道代码是如何引入的。

如果实例引用 WebAssembly 代码，则为 "wasm"。

introductionScript & introductionOffset

如果实例引用 JavaScript 源代码，并且如果此源代码是通过调用调试对象代码中的函数引入的，则 introductionScript 是引用包含该调用的脚本的 Debugger.Script 实例，而 introductionOffset 是该脚本中调用的字节码偏移量。否则，这两个值都为 undefined。综合来看，这些属性指示了引入调用的位置。

对于这些访问器的目的，对访问器属性的赋值被视为函数调用。因此，通过为相应的 JavaScript 属性赋值来设置 DOM 元素的事件处理程序 IDL 属性会创建一个源，其 introductionScript 和 introductionOffset 指向属性赋值。

由于从网页的原始 HTML 解析的 <script> 元素不是由任何脚本化的调用引入的，因此其源的 introductionScript 和 introductionOffset 访问器都返回 undefined。

如果 <script> 元素被动态插入到文档中，则这些访问器将引用实际上导致脚本运行的调用——通常是使元素成为文档一部分的调用。因此，它们不引用创建元素的调用；将源存储为元素的文本子节点；使元素成为某个未插入的父节点的子节点，该父节点稍后被插入；或类似的操作。

尽管工作线程的主脚本是由对 Worker 或 SharedWorker 的调用引入的，但这些访问器在这样的脚本的源上始终返回 undefined。工作线程的主脚本源和创建工作线程的调用始终位于不同的线程中，但 Debugger 本身是一个单线程设施：其调试对象必须全部在同一个线程中运行。由于创建工作线程的全局变量位于不同的线程中，因此它保证不会是拥有此源的 Debugger 实例的调试对象；因此，创建调用永远不会“在调试对象代码中”。将工作线程与其创建者相关联以及其他多线程调试问题超出了 Debugger 的范围。

如果实例引用 WebAssembly 代码，则 introductionScript 是引用相同底层 WebAssembly 模块的 Debugger.Script 实例。introductionOffset 为 undefined。

Debugger.Source 原型对象的函数属性

下面描述的函数只能使用引用 Debugger.Source 实例的 this 值来调用；它们不能用作其他类型的对象的函数。

reparse()

如果实例引用 JavaScript 源代码，并且如果源代码有可用的文本，则返回一个引用通过重新解析此源代码的文本创建的新脚本的 Debugger.Script 实例。调试器 onNewScript 挂钩不会为新脚本调用。否则，将抛出 Error。