バージョン: 4.x

クライアントAPI

IO

ioメソッドは、スタンドアロンビルドではグローバルスコープにバインドされています。

<script src="/socket.io/socket.io.js"></script>
<script>
  const socket = io();
</script>

バージョン4.3.0以降、ESMバンドルも利用可能です。

<script type="module">
  import { io } from "https://cdn.socket.io/4.7.5/socket.io.esm.min.js";

  const socket = io();
</script>

インポートマップを使用する場合

<script type="importmap">
  {
    "imports": {
      "socket.io-client": "https://cdn.socket.io/4.7.5/socket.io.esm.min.js"
    }
  }
</script>

<script type="module">
  import { io } from "socket.io-client";

  const socket = io();
</script>

それ以外のすべてのケース（一部のビルドツール、Node.js、またはReact Nativeの場合）では、socket.io-clientパッケージからインポートできます。

// ES modules
import { io } from "socket.io-client";

// CommonJS
const { io } = require("socket.io-client");

io.protocol

<数値>

プロトコル改訂番号（現在：5）。

プロトコルは、クライアントとサーバー間で交換されるパケットのフォーマットを定義します。クライアントとサーバーの両方で同じ改訂番号を使用する必要があります。

詳細についてはこちらをご覧ください。

io([url][, options])

url <文字列> (デフォルトはwindow.location.host)
options <オブジェクト>
- forceNew <ブール値> 新しい接続を作成するかどうか
戻り値 <Socket>

指定されたURLに対して新しいManagerを作成し、multiplexオプションがfalseで渡されない限り、後続の呼び出しに対して既存のManagerを再利用しようとします。このオプションを渡すことは、"force new connection": trueまたはforceNew: trueを渡すことと同じです。

URLのパス名で指定された名前空間（デフォルトは/）に対して、新しいSocketインスタンスが返されます。たとえば、urlがhttp://localhost/usersの場合、http://localhostにトランスポート接続が確立され、/usersにSocket.IO接続が確立されます。

クエリパラメーターは、queryオプションを使用するか、URLに直接指定することもできます（例：http://localhost/users?token=abc）。

内部で行われる処理を理解するために、次の例

import { io } from "socket.io-client";

const socket = io("ws://example.com/my-namespace", {
  reconnectionDelayMax: 10000,
  auth: {
    token: "123"
  },
  query: {
    "my-key": "my-value"
  }
});

は、簡略版です。

import { Manager } from "socket.io-client";

const manager = new Manager("ws://example.com", {
  reconnectionDelayMax: 10000,
  query: {
    "my-key": "my-value"
  }
});

const socket = manager.socket("/my-namespace", {
  auth: {
    token: "123"
  }
});

利用可能なオプションの完全なリストはこちらにあります。

Manager

Managerは、Engine.IO クライアントインスタンスを管理します。これは、（WebSocketやHTTPロングポーリングなどのトランスポートを使用して）サーバーへの接続を確立する低レベルのエンジンです。

Managerは、再接続ロジックを処理します。

単一のManagerは、複数のSocketで使用できます。このマルチプレクシング機能の詳細についてはこちらをご覧ください。

ほとんどの場合、Managerを直接使用せず、代わりにSocketインスタンスを使用することに注意してください。

コンストラクター

new Manager(url[, options])

url <文字列>
options <オブジェクト>
戻り値 <Manager>

利用可能なオプションの完全なリストはこちらにあります。

import { Manager } from "socket.io-client";

const manager = new Manager("https://example.com");

const socket = manager.socket("/"); // main namespace
const adminSocket = manager.socket("/admin"); // admin namespace

イベント

イベント: 'error'

error <Error> エラーオブジェクト

接続エラーが発生したときに発生します。

socket.io.on("error", (error) => {
  // ...
});

イベント: 'ping'

サーバーからpingパケットを受信したときに発生します。

socket.io.on("ping", () => {
  // ...
});

イベント: 'reconnect'

attempt <数値> 再接続試行回数

正常に再接続されたときに発生します。

socket.io.on("reconnect", (attempt) => {
  // ...
});

イベント: 'reconnect_attempt'

attempt <数値> 再接続試行回数

再接続を試行したときに発生します。

socket.io.on("reconnect_attempt", (attempt) => {
  // ...
});

イベント: 'reconnect_error'

error <Error> エラーオブジェクト

再接続試行エラーが発生したときに発生します。

socket.io.on("reconnect_error", (error) => {
  // ...
});

イベント: 'reconnect_failed'

reconnectionAttempts内で再接続できなかったときに発生します。

socket.io.on("reconnect_failed", () => {
  // ...
});

メソッド

manager.connect([callback])

manager.open([callback])の同義語。

manager.open([callback])

callback <関数>
戻り値 <Manager>

autoConnectがfalseで初期化された場合、新しい接続試行を開始します。

callback引数はオプションであり、試行が失敗/成功したときに呼び出されます。

import { Manager } from "socket.io-client";

const manager = new Manager("https://example.com", {
  autoConnect: false
});

const socket = manager.socket("/");

manager.open((err) => {
  if (err) {
    // an error has occurred
  } else {
    // the connection was successfully established
  }
});

manager.reconnection([value])

value <ブール値>
戻り値 <Manager> | <ブール値>

reconnectionオプションを設定するか、パラメーターが渡されなければそれを返します。

manager.reconnectionAttempts([value])

value <数値>
戻り値 <Manager> | <数値>

reconnectionAttemptsオプションを設定するか、パラメーターが渡されなければそれを返します。

manager.reconnectionDelay([value])

value <数値>
戻り値 <Manager> | <数値>

reconnectionDelayオプションを設定するか、パラメーターが渡されなければそれを返します。

manager.reconnectionDelayMax([value])

value <数値>
戻り値 <Manager> | <数値>

reconnectionDelayMaxオプションを設定するか、パラメーターが渡されなければそれを返します。

manager.socket(nsp, options)

nsp <文字列>
options <オブジェクト>
戻り値 <Socket>

指定された名前空間に対して新しいSocketを作成します。optionsオブジェクトからはauth（{ auth: {key: "value"} }）のみが読み取られます。他のキーは無視され、new Manager(nsp, options)をインスタンス化するときに渡す必要があります。

manager.timeout([value])

value <数値>
戻り値 <Manager> | <数値>

timeoutオプションを設定するか、パラメーターが渡されなければそれを返します。

Socket

Socketは、サーバーとやり取りするための基本クラスです。Socketは特定の名前空間（デフォルトは/）に属し、通信に基礎となるManagerを使用します。

Socketは基本的にEventEmitterであり、ネットワーク経由でサーバーにイベントを送信し、サーバーからイベントを受信します。

socket.emit("hello", { a: "b", c: [] });

socket.on("hey", (...args) => {
  // ...
});

詳細はこちらをご覧ください。

イベント

イベント: 'connect'

このイベントは、接続時と再接続時にSocketインスタンスによって発生します。

socket.on("connect", () => {
  // ...
});

注意

イベントハンドラーは、connectハンドラー自体で登録しないでください。Socketインスタンスが再接続するたびに、新しいハンドラーが登録されます。

悪い例 ⚠️

socket.on("connect", () => {
  socket.on("data", () => { /* ... */ });
});

良い例 👍

socket.on("connect", () => {
  // ...
});

socket.on("data", () => { /* ... */ });

イベント: 'connect_error'

error <Error>

このイベントは、接続失敗時に発生します。

理由	自動再接続？
低レベルの接続を確立できません（一時的な障害）	✅ はい
接続がミドルウェア関数でサーバーによって拒否されました。	❌ いいえ

socket.active属性は、ソケットが短いランダム化された遅延後に自動的に再接続を試行するかどうかを示します。

socket.on("connect_error", (error) => {
  if (socket.active) {
    // temporary failure, the socket will automatically try to reconnect
  } else {
    // the connection was denied by the server
    // in that case, `socket.connect()` must be manually called in order to reconnect
    console.log(error.message);
  }
});

イベント: 'disconnect'

reason <文字列>
details <DisconnectDetails>

このイベントは、切断時に発生します。

socket.on("disconnect", (reason, details) => {
  // ...
});

考えられる理由のリストを以下に示します。

理由	説明	自動再接続？
`ioサーバー切断`	socket.disconnect()を使用して、サーバーがソケットを強制的に切断しました。	❌ いいえ
`ioクライアント切断`	socket.disconnect()を使用して、ソケットを手動で切断しました。	❌ いいえ
`pingタイムアウト`	`pingInterval + pingTimeout` の範囲内でサーバーからPINGが送信されませんでした。	✅ はい
`トランスポートのクローズ`	接続が閉じられました（例：ユーザーが接続を失った、またはネットワークがWiFiから4Gに変更された）。	✅ はい
`トランスポートエラー`	接続でエラーが発生しました（例：HTTPロングポーリングサイクル中にサーバーが強制終了された）。	✅ はい

socket.active属性は、ソケットが短いランダム化された遅延後に自動的に再接続を試行するかどうかを示します。

socket.on("disconnect", (reason) => {
  if (socket.active) {
    // temporary disconnection, the socket will automatically try to reconnect
  } else {
    // the connection was forcefully closed by the server or the client itself
    // in that case, `socket.connect()` must be manually called in order to reconnect
    console.log(reason);
  }
});

属性

socket.active

<boolean>

ソケットが自動的に再接続を試行するかどうか。

この属性は、接続失敗後

socket.on("connect_error", (error) => {
  if (socket.active) {
    // temporary failure, the socket will automatically try to reconnect
  } else {
    // the connection was denied by the server
    // in that case, `socket.connect()` must be manually called in order to reconnect
    console.log(error.message);
  }
});

または切断後に使用できます。

socket.on("disconnect", (reason) => {
  if (socket.active) {
    // temporary disconnection, the socket will automatically try to reconnect
  } else {
    // the connection was forcefully closed by the server or the client itself
    // in that case, `socket.connect()` must be manually called in order to reconnect
    console.log(reason);
  }
});

socket.connected

<boolean>

ソケットが現在サーバーに接続されているかどうか。

const socket = io();

console.log(socket.connected); // false

socket.on("connect", () => {
  console.log(socket.connected); // true
});

socket.disconnected

<boolean>

ソケットが現在サーバーから切断されているかどうか。

const socket = io();

console.log(socket.disconnected); // true

socket.on("connect", () => {
  console.log(socket.disconnected); // false
});

socket.id

<string>

ソケットセッションの一意の識別子。connectイベントのトリガー後に設定され、reconnectイベント後も更新されます。

const socket = io();

console.log(socket.id); // undefined

socket.on("connect", () => {
  console.log(socket.id); // "G5p5..."
});

注意

id属性は、アプリケーションで使用することを意図しない（デバッグ目的でのみ使用）**一時的な**IDです。なぜなら

このIDは、再接続ごとに（たとえば、WebSocket接続が切断された場合、またはユーザーがページを更新した場合）再生成されるためです。
2つの異なるブラウザタブには、2つの異なるIDが割り当てられます。
サーバー上に特定のIDに対して保存されているメッセージキューはありません（つまり、クライアントが切断された場合、このIDに送信されたサーバーからのメッセージは失われます）。

代わりに通常のセッションIDを使用してください（Cookieで送信するか、localStorageに保存してauthペイロードで送信します）。

参照

socket.io

<Manager>

基盤となるManagerへの参照。

socket.on("connect", () => {
  const engine = socket.io.engine;
  console.log(engine.transport.name); // in most cases, prints "polling"

  engine.once("upgrade", () => {
    // called when the transport is upgraded (i.e. from HTTP long-polling to WebSocket)
    console.log(engine.transport.name); // in most cases, prints "websocket"
  });

  engine.on("packet", ({ type, data }) => {
    // called for each packet received
  });

  engine.on("packetCreate", ({ type, data }) => {
    // called for each packet sent
  });

  engine.on("drain", () => {
    // called when the write buffer is drained
  });

  engine.on("close", (reason) => {
    // called when the underlying connection is closed
  });
});

socket.recovered

v4.6.0で追加

<boolean>

前回の再接続中に接続状態が正常に復旧されたかどうか。

socket.on("connect", () => {
  if (socket.recovered) {
    // any event missed during the disconnection period will be received now
  } else {
    // new or unrecoverable session
  }
});

この機能の詳細についてはこちら。

メソッド

socket.close()

v1.0.0で追加

socket.disconnect()の同義語。

socket.compress(value)

value <ブール値>
戻り値 <Socket>

後続のイベント発行に対する修飾子をセットします。値がtrueの場合のみ、イベントデータは圧縮されます。メソッドを呼び出さない場合は、デフォルトでtrueになります。

socket.compress(false).emit("an event", { some: "data" });

socket.connect()

v1.0.0で追加

戻り値 Socket

ソケットを手動で接続します。

const socket = io({
  autoConnect: false
});

// ...
socket.connect();

手動での再接続にも使用できます。

socket.on("disconnect", () => {
  socket.connect();
});

socket.disconnect()

v1.0.0で追加

戻り値 <Socket>

ソケットを手動で切断します。この場合、ソケットは再接続を試行しません。

socket.emit(eventName[, ...args][, ack])

eventName <string> | <symbol>
args <any[]>
ack <Function>
戻り値 true

文字列名で識別されるソケットにイベントを送信します。他のパラメーターを含めることができます。Bufferを含むすべてのシリアル化可能なデータ構造がサポートされています。

socket.emit("hello", "world");
socket.emit("with-binary", 1, "2", { 3: "4", 5: Buffer.from([6, 7, 8]) });

ack引数はオプションで、サーバーの応答で呼び出されます。

クライアント

socket.emit("hello", "world", (response) => {
  console.log(response); // "got it"
});

サーバー

io.on("connection", (socket) => {
  socket.on("hello", (arg, callback) => {
    console.log(arg); // "world"
    callback("got it");
  });
});

socket.emitWithAck(eventName[, ...args])

v4.6.0で追加

eventName <string> | <symbol>
args any[]
戻り値 Promise<any>

サーバーからの確認応答を期待してイベントを送信するPromiseベースのバージョン

// without timeout
const response = await socket.emitWithAck("hello", "world");

// with a specific timeout
try {
  const response = await socket.timeout(10000).emitWithAck("hello", "world");
} catch (err) {
  // the server did not acknowledge the event in the given delay
}

上記の例は、次と同等です。

// without timeout
socket.emit("hello", "world", (val) => {
  // ...
});

// with a specific timeout
socket.timeout(10000).emit("hello", "world", (err, val) => {
  // ...
});

受信側では

io.on("connection", (socket) => {
  socket.on("hello", (arg1, callback) => {
    callback("got it"); // only one argument is expected
  });
});

注意

Promiseをサポートしていない環境では、この機能を使用するためにポリフィルを追加する必要があります。

socket.listeners(eventName)

EventEmitterクラスから継承。

eventName <string> | <symbol>
戻り値 <Function[]>

eventNameという名前のイベントのリスナーの配列を返します。

socket.on("my-event", () => {
  // ...
});

console.log(socket.listeners("my-event")); // prints [ [Function] ]

socket.listenersAny()

v3.0.0で追加

戻り値 <Function[]>

登録されているキャッチオールリスナーのリストを返します。

const listeners = socket.listenersAny();

socket.listenersAnyOutgoing()

v4.5.0で追加

戻り値 <Function[]>

発信パケットの登録済みキャッチオールリスナーのリストを返します。

const listeners = socket.listenersAnyOutgoing();

socket.off([eventName][, listener])

EventEmitterクラスから継承。

eventName <string> | <symbol>
listener <Function>
戻り値 <Socket>

eventNameという名前のイベントのリスナー配列から指定されたlistenerを削除します。

const myListener = () => {
  // ...
}

socket.on("my-event", myListener);

// then later
socket.off("my-event", myListener);

listener引数は省略することもできます。

// remove all listeners for that event
socket.off("my-event");

// remove all listeners for all events
socket.off();

socket.offAny([listener])

v3.0.0で追加

listener <Function>

以前に登録されたリスナーを削除します。リスナーが提供されない場合、すべてのキャッチオールリスナーが削除されます。

const myListener = () => { /* ... */ };

socket.onAny(myListener);

// then, later
socket.offAny(myListener);

socket.offAny();

socket.offAnyOutgoing([listener])

v4.5.0で追加

listener <Function>

以前に登録されたリスナーを削除します。リスナーが提供されない場合、すべてのキャッチオールリスナーが削除されます。

const myListener = () => { /* ... */ };

socket.onAnyOutgoing(myListener);

// remove a single listener
socket.offAnyOutgoing(myListener);

// remove all listeners
socket.offAnyOutgoing();

socket.on(eventName, callback)

EventEmitterクラスから継承。

eventName <string> | <symbol>
listener <Function>
戻り値 <Socket>

指定されたイベントの新しいハンドラーを登録します。

socket.on("news", (data) => {
  console.log(data);
});

// with multiple arguments
socket.on("news", (arg1, arg2, arg3, arg4) => {
  // ...
});
// with callback
socket.on("news", (cb) => {
  cb(0);
});

socket.onAny(callback)

v3.0.0で追加

callback <関数>

新しいキャッチオールリスナーを登録します。

socket.onAny((event, ...args) => {
  console.log(`got ${event}`);
});

注意

確認応答は、キャッチオールリスナーではキャッチされません。

socket.emit("foo", (value) => {
  // ...
});

socket.onAnyOutgoing(() => {
  // triggered when the event is sent
});

socket.onAny(() => {
  // not triggered when the acknowledgement is received
});

socket.onAnyOutgoing(callback)

v4.5.0で追加

callback <関数>

発信パケットの新しいキャッチオールリスナーを登録します。

socket.onAnyOutgoing((event, ...args) => {
  console.log(`got ${event}`);
});

注意

確認応答は、キャッチオールリスナーではキャッチされません。

socket.on("foo", (value, callback) => {
  callback("OK");
});

socket.onAny(() => {
  // triggered when the event is received
});

socket.onAnyOutgoing(() => {
  // not triggered when the acknowledgement is sent
});

socket.once(eventName, callback)

EventEmitterクラスから継承。

eventName <string> | <symbol>
listener <Function>
戻り値 <Socket>

eventNameという名前のイベントに対して、1回限りのlistener関数を追加します。次回eventNameがトリガーされると、このリスナーは削除されてから呼び出されます。

socket.once("my-event", () => {
  // ...
});

socket.open()

v1.0.0で追加

socket.connect()の同義語。

socket.prependAny(callback)

v3.0.0で追加

callback <関数>

新しいキャッチオールリスナーを登録します。リスナーはリスナー配列の先頭に追加されます。

socket.prependAny((event, ...args) => {
  console.log(`got ${event}`);
});

socket.prependAnyOutgoing(callback)

v4.5.0で追加

callback <関数>

発信パケットの新しいキャッチオールリスナーを登録します。リスナーはリスナー配列の先頭に追加されます。

socket.prependAnyOutgoing((event, ...args) => {
  console.log(`got ${event}`);
});

socket.send([...args][, ack])

args <any[]>
ack <Function>
戻り値 <Socket>

messageイベントを送信します。socket.emit(eventName[, ...args][, ack])を参照してください。

socket.timeout(value)

v4.4.0で追加

value <数値>
戻り値 <Socket>

後続のイベント発行に対する修飾子をセットします。サーバーからの確認応答なしに指定されたミリ秒数が経過すると、コールバックがエラーで呼び出されます。

socket.timeout(5000).emit("my-event", (err) => {
  if (err) {
    // the server did not acknowledge the event in the given delay
  }
});

フラグ

フラグ: 'volatile'

v3.0.0で追加

後続のイベント発行に対する修飾子をセットします。パケットは、次の場合に破棄される可能性があります。

ソケットが接続されていない場合
低レベルのトランスポートが書き込み可能でない場合（たとえば、HTTPロングポーリングモードでPOSTリクエストが既に実行されている場合）。

socket.volatile.emit(/* ... */); // the server may or may not receive it

IO​

io.protocol​

io([url][, options])​

Manager​

コンストラクター​

new Manager(url[, options])​

イベント​

イベント: 'error'​

イベント: 'ping'​

イベント: 'reconnect'​

イベント: 'reconnect_attempt'​

イベント: 'reconnect_error'​

イベント: 'reconnect_failed'​

メソッド​

manager.connect([callback])​

manager.open([callback])​

manager.reconnection([value])​

manager.reconnectionAttempts([value])​

manager.reconnectionDelay([value])​

manager.reconnectionDelayMax([value])​

manager.socket(nsp, options)​

manager.timeout([value])​

Socket​

イベント​

イベント: 'connect'​

イベント: 'connect_error'​

イベント: 'disconnect'​

属性​

socket.active​

socket.connected​

socket.disconnected​

socket.id​

socket.io​

socket.recovered​

メソッド​

socket.close()​

socket.compress(value)​

socket.connect()​

socket.disconnect()​

socket.emit(eventName[, ...args][, ack])​

socket.emitWithAck(eventName[, ...args])​

socket.listeners(eventName)​

socket.listenersAny()​

socket.listenersAnyOutgoing()​

socket.off([eventName][, listener])​

socket.offAny([listener])​

socket.offAnyOutgoing([listener])​

socket.on(eventName, callback)​

socket.onAny(callback)​

socket.onAnyOutgoing(callback)​

socket.once(eventName, callback)​

socket.open()​

socket.prependAny(callback)​

socket.prependAnyOutgoing(callback)​

socket.send([...args][, ack])​

socket.timeout(value)​

フラグ​

フラグ: 'volatile'​

IO

io.protocol

io([url][, options])

Manager

コンストラクター

new Manager(url[, options])

イベント

イベント: 'error'

イベント: 'ping'

イベント: 'reconnect'

イベント: 'reconnect_attempt'

イベント: 'reconnect_error'

イベント: 'reconnect_failed'

メソッド

manager.connect([callback])

manager.open([callback])

manager.reconnection([value])

manager.reconnectionAttempts([value])

manager.reconnectionDelay([value])

manager.reconnectionDelayMax([value])

manager.socket(nsp, options)

manager.timeout([value])

Socket

イベント

イベント: 'connect'

イベント: 'connect_error'

イベント: 'disconnect'

属性

socket.active

socket.connected

socket.disconnected

socket.id

socket.io

socket.recovered

メソッド

socket.close()

socket.compress(value)

socket.connect()

socket.disconnect()

socket.emit(eventName[, ...args][, ack])

socket.emitWithAck(eventName[, ...args])

socket.listeners(eventName)

socket.listenersAny()

socket.listenersAnyOutgoing()

socket.off([eventName][, listener])

socket.offAny([listener])

socket.offAnyOutgoing([listener])

socket.on(eventName, callback)

socket.onAny(callback)

socket.onAnyOutgoing(callback)

socket.once(eventName, callback)

socket.open()

socket.prependAny(callback)

socket.prependAnyOutgoing(callback)

socket.send([...args][, ack])

socket.timeout(value)

フラグ

フラグ: 'volatile'