WebIDL

介紹

規範符合

介面定義語言

ECMAScript 綁定

ECMAScript 環境

ECMAScript 型態對應

ECMAScript 特定延伸屬性

本小節定義了數個只影響 ECMAScript 綁定的延伸屬性。

[ArrayClass]

[Clamp]

[Constructor]

[ImplicitThis]

[LenientThis]

[NamedConstructor]

[NoInterfaceObject]

[OverrideBuiltins]

[PutForwards]

[Replaceable]

[NamedPropertiesObject]

[TreatNonCallableAsNull]

[TreatNullAs]

[TreatUndefinedAs]

[Unforgeable]

介面

對於所有滿足以下條件的介面：

• 是一個有常數宣告的回調介面，或
• 是一個沒有以 [NoInterfaceObject] 延伸屬性宣告的非回調介面，

ECMAScript 全域物件上「必須」存在一個對應的屬性。屬性的名稱是介面的標識符，值是一個叫做介面物件的物件。

此屬性具有特性 { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }。下面 4.4.1 小節會介紹介面物件的特性。

除此之外，對於每一個介面上的 [NamedConstructor] 延伸屬性，ECMAScript 全域物件上「必須」存在一個對應的屬性。屬性的名稱是在 “=” 後面出現的標識符，值是一個叫做有名稱的建構子的物件，可以用來建構實作該介面的物件。此屬性具有特性 { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }。下面 4.4.2 小節會介紹介面物件的特徵。

介面物件

一個非回調介面的介面物件是一個函數物件。介面物件具有某些屬性，對應於在該介面上定義的常數與靜態操作，各分別在下面 4.4.5 小節與 4.4.7 小節描述。

一個非回調介面的介面物件 “prototype” 屬性的值「必須」是一個叫做介面原型物件的物件。介面原型物件具有某些屬性，對應於在該介面上定義的屬性與操作，在下面 4.4.3 小節詳述。

回調介面的介面物件「必不可」為函數物件且「必不可」有 “prototype” 屬性。一個回調介面的介面物件「必須」是 Object.prototype 物件。

介面物件的 [[Call]] 方法

有名稱的建構子

介面原型物件

每一個非回調介面，不管有沒有以 [NoInterfaceObject] 延伸屬性宣告，都「必須」存在一個介面原型物件。一個介面的介面原型物件具有對應於在該介面上定義的屬性與操作的屬性。這些屬性分別在下面的 4.4.6 小節與 4.4.7 小節詳述。

與介面物件相同，介面原型物件也有對應於在該介面上定義的常數的屬性，在下面的 4.4.5 小節描述。

若介面上沒有指定 [NoInterfaceObject] 延伸屬性，則介面原型物件也「必須」有名稱為 “constructor”，特性為 { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }，值為介面的介面物件，的屬性。

介面 A 的介面原型物件的內部 [[Prototype]] 屬性的值「必須」依照下面規則得出：

1. 若 A 以 [NamedPropertiesObject] 延伸屬性宣告，則 A 的內部 [[Prototype]] 屬性的值為由下面 4.4.4 小節定義的 A 的名稱屬性物件。
2. 否則，若 A 沒被宣告繼承另一個介面，又若介面以 [ArrayClass] 宣告，則 A 的內部 [[Prototype]] 屬性的值為 Array 原型物件（[ECMA-262]，15.4.4 小節），否則為 Object 原型物件（[ECMA-262]，15.2.4 小節）。
3. 否則，A 的內部 [[Prototype]] 屬性的值為被繼承介面的介面原型物件。

[NoInterfaceObject]
interface Foo {
};

partial interface Window {
  attribute Foo foo;
};

介面原型物件的類字串是介面的標識符與字串 “Prototype” 的串接結果。

名稱屬性物件

常數

每一個定義在介面 A 上的常數都「必須」在介面對象（若存在）上有一個對應的屬性，並有以下特徵：

• 屬性的名稱是常數的標識符。
• 屬性的值是將常數的 IDL 值轉換為 ECMAScript 值的結果。
• 屬性的特性為 { [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: false }。

另外，介面原型物件上「必須」存在有同樣特徵的屬性。

屬性

每一個定義在介面上的屬性都「必須」有對應的屬性。若屬性以 [Unforgeable] 延伸屬性宣告，則在每一個實作介面的物件上都存在該屬性。否則，屬性存在於介面的介面原型物件上。

這些屬性的特徵為下：

• 屬性的名稱是屬性的標識符。
• 屬性的特性為 { [[Get]]: G, [[Set]]: S, [[Enumerable]]: true, [[Configurable]]: 可調節性 }，其中：
  • 若屬性以 [Unforgeable] 延伸屬性宣告，則可調節性為 false，否則為 true。
  • G 屬性是下面定義的屬性 getter。
  • S 屬性是屬性 setter，也在下面定義。
• 屬性 getter 是呼叫後會執行下述步驟，“length” 屬性是 Number 值 0 的 Function 物件：
  1. 若 Type(V) 不是 Object，則拋出 TypeError。
  2. 若 O 不是一個實作屬性來源介面的平台物件則：
     1. 若屬性設有 [LenientThis] 延伸屬性，則回傳 undefined。
     2. 否則，拋出 TypeError。
  3. 設 IDL 值為，以 O 作為物件，執行在屬性的描述中的「獲取」屬性步驟（若屬性宣告為繼承其 getter，使用被繼承屬性的步驟）的結果。
  4. 設 V 為將 IDL 值轉換為 ECMAScript 值的結果。
  5. 回傳 V。
• 若屬性宣告為 readonly 且上面沒有 [PutForwards] 或 [Replaceable] 延伸屬性宣告，則屬性 setter 為 undefined，否則屬性 setter 是呼叫後會執行下述步驟，“length” 屬性是 Number 值 1 的 Function 物件：
  1. 若 Type(V) 不是 Object，則拋出 TypeError。
  2. 若 O 是實作屬性來源介面的平台物件，設 this 合法為 true，否則為 false。
  3. 若 this 合法為 false 且屬性不設有 [LenientThis] 延伸屬性，則拋出 TypeError。
  4. 設 V 為傳到 Function 的第一個參數，或是 undefined（沒傳參數的情形）。
  5. 若屬性以 [Repaceable] 延伸屬性宣告，則：
     1. 設 P 為屬性的標識符。
     2. 呼叫 O 的 [[DefineOwnProperty]]，傳屬性名稱 P、屬性描述 { [[Value]]: V, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } 與 false。
     3. 回傳 undefined。
  6. 若 this 合法為 false，則回傳。
  7. 若屬性以 [PutForwards] 延伸屬性宣告，則：
     1. 設 Q 為使用屬性的標識符作為屬性名呼叫 O 的 [[Get]] 方法結果。
     2. 若 Q 不是一個物件，則拋出 TypeError。
     3. 設 A 為 [PutForwards] 延伸屬性標示的屬性。
     4. 使用 A 的標識符作為屬性名、V 作為屬性值呼叫 Q 的 [[Put]] 方法。
     5. 回傳。
  8. 設 IDL 值為下述方法決定的 IDL 值：
     • 若屬性的型態是一個列舉，則：
       1. 設 S 為呼叫 ToString(V) 的結果。
       2. 若 S 不是列舉的值，則回傳 undefined。
       3. IDL 值是相等於 S 的列舉值。
     • 否則，屬性的型態不是一個列舉。IDL 值是將 V 轉換為 IDL 值得結果。
  9. 以 O 作為物件、執行 IDL 值作為值，執行在屬性的描述中的「設置」屬性步驟。
  10. 回傳 undefined。

請注意設置只讀屬性會因進行設置的腳本使用嚴格模式與否而有不同的行為。在嚴格模式中，這種設置會導致使用者代理拋出 TypeError，在非嚴格模式中，使用者代理會忽略這種設置。

操作

對於每一個定義在介面上的操作的標識符，除非該標識符在操作的參數計數為 0 上的有效重載集合為空，「必須」在介面原型物件（若操作為一般操作）或介面對象（若操作為靜態操作）上有對應的屬性。

這種屬性有以下的特徵：

• 屬性的名稱是標識符。
• 屬性的特性為 { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true }。
• 設 id 為標識符、arg_0..n−1 為傳給函數的參數列、l 為介面，屬性的值是一個行為如下的 Function 物件：
  1. 設 O 為下面步驟決定的值：
     • 若操作是靜態方法，則 O 為 null。
     • 否則，若操作的來源介面具有 [ImplicitThis] 延伸屬性，且 this 值是 null 或 undefined，則 O 是與 Function 物件關聯的 ECMAScript 全局物件。
     • 否則，若 this 值不為 null，則 O 為 this 值。
     • 否則，拋出 TypeError。
  2. 若 O 不為 null 且不是一個實作介面 l 的平台物件，則拋出 TypeError。
  3. 將 S 初始化為一般操作或靜態操作對應於標識符 id、介面 l 與參數計數 n 的有效重載集合。
  4. 設 <操作, 值> 為以 S 與 arg_0..n−1 呼叫重載解決演算法的結果。
  5. 設 R 為（若操作不是靜態方法，在 O 上）執行在具有值作為參數值的操作的描述中列出的步驟得到的結果。
  6. 回傳將 R 轉換為 op 宣告的 ECMAScript 取值型態的結果。
• Function 物件的 “length” 屬性是由下面決定的 Number：
  1. 設 S 為一般操作或靜態操作對應於標識符 id、介面 l 與參數計數 0 的有效重載集合。
  2. 回傳在 S 的裡的函數中最大的參數列長。

「實作」敘述

實作介面的平台物件

如同初始物件，每一個平台物件與一個全局環境關聯。描述每一個平台物件與哪一個全局環境（或是哪一個全局物件）關聯的責任在於使用 WebIDL 的規範。

一個實作一個以上介面的平台物件的主介面是平台物件實作非補充介面中最底層的子介面。平台物件的內部 [[Prototype]] 屬性的值是平台物件的關聯全局環境中主介面的介面原型物件。

實作一個以上介面的平台物件的類字串「必須」是主介面的標識符。

索引屬性與名稱屬性

平台物件與 [[GetOwnProperty]] 方法

平台物件與 [[DefineOwnProperty]] 方法

平台物件與 [[Delete]] 方法

平台物件與 [[Call]] 方法

屬性列舉

實作回調介面的使用者物件

例外

例外物件

拋出例外

例外處理

共通定義

擴展性

以本規範作為參考資料