WebIDL

WebIDLハンドブック

WebIDLの概要

WebIDLとは

WebIDL（Web Interface Definition Language）は、Webブラウザ上のAPIを記述するための言語仕様です。主にWeb APIやDOMインターフェースの定義に使用されます。

主な用途

• DOM APIの定義
• Web APIの仕様記述
• ブラウザ実装の標準化
• JavaScript APIのインターフェース定義

基本構文

基本的な定義形式

// インターフェースの基本定義
interface Example {
    readonly attribute DOMString name;
    void method(long parameter);
};

コメント

// 単一行コメント

/* 
  複数行
  コメント
*/

インターフェース定義

基本的なインターフェース

[Exposed=Window]
interface Person {
    constructor();
    readonly attribute DOMString name;
    readonly attribute unsigned long age;
    
    void introduce();
    boolean isAdult();
};

部分インターフェース

partial interface HTMLElement {
    void customMethod();
    readonly attribute DOMString customAttribute;
};

コールバックインターフェース

callback interface EventListener {
    void handleEvent(Event event);
};

データ型

プリミティブ型

• boolean
• byte
• octet
• short
• unsigned short
• long
• unsigned long
• long long
• unsigned long long
• float
• unrestricted float
• double
• unrestricted double
• DOMString
• ByteString
• USVString

型定義例

interface TypeExample {
    // 数値型
    attribute long numericValue;
    attribute unsigned long positiveValue;
    
    // 文字列型
    attribute DOMString text;
    attribute USVString unicodeText;
    
    // 真偽値
    attribute boolean flag;
    
    // バッファ
    attribute ArrayBuffer data;
    attribute Uint8Array bytes;
};

メンバー定義

属性（Attributes）

interface AttributeExample {
    // 読み取り専用属性
    readonly attribute DOMString id;
    
    // 読み書き可能属性
    attribute DOMString name;
    
    // 静的属性
    static readonly attribute DOMString version;
};

メソッド（Operations）

interface OperationExample {
    // 基本的なメソッド
    void simpleMethod();
    
    // 引数を持つメソッド
    long calculate(long a, long b);
    
    // オーバーロード
    void process();
    void process(DOMString data);
    
    // 静的メソッド
    static DOMString getClassName();
};

継承とミックスイン

インターフェース継承

interface Animal {
    readonly attribute DOMString species;
    void makeSound();
};

interface Dog : Animal {
    void bark();
};

ミックスイン

interface mixin Movable {
    void move(double x, double y);
};

interface Character includes Movable {
    attribute DOMString name;
};

例外処理

例外定義

[Exposed=Window]
exception CustomError {
    readonly attribute DOMString message;
    readonly attribute unsigned short code;
};

例外を投げるメソッド

interface ExceptionExample {
    [Throws]
    void riskyOperation() raises(CustomError);
};

拡張属性

主要な拡張属性

• [Exposed]
• [Constructor]
• [CEReactions]
• [Unforgeable]
• [SameObject]
• [Throws]
• [NewObject]

拡張属性の使用例

[Exposed=(Window,Worker)]
interface Example {
    [SameObject] readonly attribute DOMString id;
    
    [NewObject] Promise<void> asyncOperation();
    
    [CEReactions] void updateDOM();
};

プラットフォーム連携

プラットフォーム固有の定義

[Exposed=Window]
interface DeviceAPI {
    [SecureContext]
    Promise<sequence<Device>> getDevices();
    
    [Exposed=Worker]
    void processInWorker();
};

セキュリティ考慮事項

[SecureContext, Exposed=Window]
interface SecureAPI {
    Promise<ArrayBuffer> encrypt(ArrayBuffer data);
    Promise<ArrayBuffer> decrypt(ArrayBuffer data);
};

ベストプラクティス

命名規則

• インターフェース名: パスカルケース（例: AudioContext）
• メソッド名: キャメルケース（例: getCurrentTime）
• 属性名: キャメルケース（例: sampleRate）
• 定数: 大文字スネークケース（例: MAX_VALUE）

一般的なパターン

[Exposed=Window]
interface BestPracticeExample {
    // コンストラクタ
    constructor();
    
    // 読み取り専用ID
    [SameObject] readonly attribute DOMString id;
    
    // イベントハンドラ
    attribute EventHandler onchange;
    
    // 非同期操作
    Promise<void> initialize();
    
    // オプション引数
    void configure(optional Configuration config = {});
};

ドキュメント化

/**
 * インターフェースの説明
 *
 * @param {type} paramName - パラメータの説明
 * @returns {type} - 戻り値の説明
 * @throws {ErrorType} - エラーの説明
 */
interface DocumentedExample {
    /**
     * メソッドの説明
     */
    DOMString processData(DOMString input);
};

外部リンク

• WebIDL Level 1仕様
• WebIDL Level 2仕様（ドラフト）
• MDN Web Docs - WebIDL
• W3C Web APIガイドライン