overloads 関数オーバーロード
最終更新：2026-10-22
overloads 関数オーバーロード
オーバーロード宣言は、1つの関数に複数の「シグネチャ説明書」を持たせます。呼び出し側は実引数の形に応じて正確な戻り値型を得られ、実装本体は1つだけ書きます。TS は宣言の順に1つずつ照合し、すべて外れたときにのみエラーを報告します。
| グループ | 関数とクラス |
|---|---|
| 種類 | 構文 |
| strict モード | 不要 |
ℹ️ 説明 エディタは TypeScript を JavaScript にトランスパイルして実行します（型チェックなし）。型チェック結果は各サンプルの出力を参照してください。
📝 構文
function format(value: number): string; // 数値 → 金額の文字列
function format(value: Date): string; // 日付 → 日付文字列
function format(value: number | Date): string { // 実装シグネチャは外部からは見えない
return value instanceof Date
? value.toISOString().slice(0, 10)
: `¥${value.toFixed(2)}`;
}⚙️ パラメータ
| f(...): T; | オーバーロードシグネチャ：関数本体を持たない宣言で、連続して複数行書きます。コンパイラは順番に照合します |
|---|---|
| f(...) { } | 実装シグネチャ：関数本体を持つ唯一のシグネチャです。パラメータ型はすべてのオーバーロードと互換である必要がありますが、呼び出し側からは見えません |
戻り値：命中したオーバーロードシグネチャによって決まります。各オーバーロードは異なる戻り値型を宣言でき、呼び出し側は実引数の形に対応した正確な型を得られます。
▶ サンプル
下のコードを編集して「試す」を押すと、トランスパイル実行結果を確認できます：
出力：
¥42.00
2026-01-15
（トランスパイル後の実行出力。オーバーロードシグネチャはトランスパイル後に消えます——実行時に残るのは実装関数だけで、分岐のオーバーヘッドはありません）💡 ポイント
ℹ️ 説明 コンパイル結果に残るのは実装関数だけです——オーバーロードシグネチャは純粋なコンパイル時構文で、実行時に追加コードは一切ありません。
⚠️ 注意 実装シグネチャは呼び出し側から見えません。そのパラメータ型がすべてのオーバーロードの形をカバーしていないと、正当な呼び出しが実装シグネチャのところで「不一致」としてエラーになります。
💡 ヒント オーバーロードは宣言順に上から下へ照合されます。より具体的なシグネチャを先に、寛容なシグネチャを後に置いてください。さもないと寛容なシグネチャが、具体的なシグネチャに命中すべき呼び出しを横取りします。
🏷️ 関連関数とクラス
💡 関連ケース
ケースは今後追加予定です。
📚 関連チュートリアル
❓ よくある質問
Q オーバーロードとユニオン型パラメータはどう使い分けますか？
A 引数型が戻り値型に影響するときはオーバーロードを使います（それぞれに正確な説明書を1枚ずつ）。内部処理にしか影響せず戻り値が同じなら、ユニオンパラメータ + ナローイングのほうがコード量が少なくなります。
Q 「マッチするオーバーロードがない」というエラーが出るのはなぜですか？
A 2点を確認してください。実引数の型が本当にいずれかのオーバーロードに当てはまるか、そしてシグネチャの順序が適切か（寛容なシグネチャを先に置くと、後ろの具体的なシグネチャが塞がれてしまいます）。
Q アロー関数でもオーバーロードは書けますか？
A 書けません。オーバーロードは function 宣言構文のみ対応します。変数の場合は type Overloaded = { (x: string): A; (x: number): B } というオブジェクト型の形式で表現できます。
