【TypeScript】アンビエント宣言(declare)と型定義ファイル(d.ts)の概要

JavaScript

アンビエント宣言について

アンビエント宣言(Ambient Declarations)とはJavaScriptで記述されたライブラリに型情報を付加するための機能です。

JavaScriptのコードはJavaScript環境では実行できますが、TypeScript環境ではエラーになります。

foo = 123;
console.log(foo);

// Cannot find name 'foo'

しかし、アンビエント宣言を利用することでTypeScript環境でもエラーは発生しません。

declare var foo: number;

foo = 123;
console.log(foo);

// 123

アンビエント宣言によりTypeScriptの環境でもJavaScriptのコードを利用できます。
アンビエント宣言はTypeScript環境でJavaScriptライブラリを利用する際に活用されます。

型定義ファイルについて

アンビエント宣言は実際のコードとは別のファイルに記述するのが一般的です。

型定義ファイルはアンビエント宣言を記述するためのファイルです。

型定義ファイルには型定義の情報しか存在していないため、TypeScriptビルド時のみ参照されます。また、型定義ファイルはJavaScriptにコンパイルされることもありません。

型定義ファイルの生成方法

TypeScriptファイルから型定義ファイルとJavaScriptファイルを生成する場合はtsc -dを実行します。1

sample.ts

interface Person {
  firstName: string;
  lastName: string;
}

function greeter(person: Person): string {
  return 'Hello, ' + person.firstName + ' ' + person.lastName;
}
$ tsc -d sample.ts

sample.js

function greeter(person) {
    return 'Hello, ' + person.firstName + ' ' + person.lastName;
}
//# sourceMappingURL=sample.js.map

sample.d.ts

interface Person {
    firstName: string;
    lastName: string;
}
declare function greeter(person: Person): string;

アンビエントモジュールについて

アンビエント宣言はdeclare module 'モジュール名'とすることでモジュール単位での型定義も可能です。
モジュール単位のアンビエント宣言をアンビエントモジュール(Ambient Modules)と呼びます。

たとえば、Vue.jsをTypeScript環境で利用する際に以下のようなアンビエントモジュールを利用することがあります。

index.d.ts

declare module "*.vue" {
  import Vue from "vue";
  export default Vue;
}

上記のアンビエントモジュールを導入することでTypeScriptが.vueの拡張子のファイルを認識できます。

さいごに

Twitter(@nishina555)やってます。フォローしてもらえるとうれしいです!

参考記事