iTick Web browser js SDK
[![npm version][npm-version-img]][npm-link]
[![CDNJS][cdn-js-img]][cdn-js-link]
[![install size][npm-install-size-img]][npm-install-size-link]
[![npm bundle size][bundle-size-img]][bundle-size-link]
[![license badge][license-img]][license-link]
[English](https://github.com/itick-org/javascript-sdk/blob/main/README.md) | [簡體中文](https://github.com/itick-org/javascript-sdk/blob/main/README.zh-CN.md) | [繁體中文](https://github.com/itick-org/javascript-sdk/blob/main/README.zh-HK.md)
可直接在web瀏覽器運行的 iTick API SDK，提供基礎、股票、指數、期貨、基金、外匯、加密貨幣數據的 REST API 查詢和 WebSocket 實時數據訂閱功能。用於訪問 iTick API 的實時金融市場數據。
## ✨ 特性
- **全面的市場覆蓋**：訪問全球金融市場，包括股票、加密貨幣、外匯、指數、期貨和基金
- **實時數據**：基於 WebSocket 的實時數據流，支持自動重連
- **RESTful API**：簡潔直觀的 REST API，用於獲取歷史數據和快照
- **類型安全**：完整的 TypeScript 支持和全面的類型定義
- **自動重連**：內置自動重連機制（5 秒間隔，可設置無限次嘗試）
- **心跳保活**：自動 ping/pong 機制（30 秒間隔）保持連接穩定
- **模組化設計**：按資產類型劃分獨立模組，結構更清晰
- **靈活訂閱**：支持報價、盤口、成交和 K 線數據訂閱
## 支持的瀏覽器
| Chrome | Firefox | Safari | Opera | Edge |
| :------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------: |
|  |  |  |  |  |
| Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ |
## 🚀 安裝
### 項目安裝
使用 npm:
```bash
npm install @itick/browser-sdk
```
使用 yarn:
```bash
yarn add @itick/browser-sdk
```
使用 pnpm:
```bash
pnpm add @itick/browser-sdk
```
### CDN
```html
```
## 🎯 快速開始
### 基礎用法
```javascript
import { StockClient } from "@itick/browser-sdk";
// 使用 API Token 初始化客戶端
const token = process.env.ITICK_TOKEN;
const client = new StockClient(token);
// 獲取股票報價
async function getQuote() {
try {
const response = await client.getQuote({ region: "US", code: "AAPL" });
if (response.code === 0 && response.data) {
console.log("最新價格:", response.data.ld);
console.log("漲跌幅:", response.data.chp);
}
} catch (error) {
console.error("錯誤:", error.message);
}
}
getQuote();
```
### 通過 WebSocket 獲取實時數據
```javascript
import { CryptoClient } from "@itick/browser-sdk";
const client = new CryptoClient(token);
// 創建帶訂閱數據的 WebSocket 連接 SDK內部已處理連接和重連後直接訂閱 subscribeData 數據 無需再發送訂閱數據
const socket = client.createSocket({
maxReconnectTimes: 10, // 最大重連次數 不傳則使用默認值 0 無限制重連
pingInterval: 30000, // ping 間隔 默認30 秒
reconnectInterval: 5000, // 重連間隔 默認5 秒
subscribeData: {
codes: ["BTCUSDT$BA", "ETHUSDT$BA"],
types: ["quote", "tick"],
},
});
// 創建自定義 WebSocket 連接
const socket = client.createSocket();
// 連接成功或者重連連成功後發送訂閱數據
socket.onSocketOpen(() => {
socket.subscribeData({
codes: ["BTCUSDT$BA", "ETHUSDT$BA"],
types: ["quote", "tick"],
});
});
// 處理接收到的消息
socket.onSocketMessage((res) => {
console.log("收到數據:", res);
});
// 處理錯誤
socket.onSocketError((error) => {
console.error("WebSocket 錯誤:", error);
});
// 完成後斷開連接
// socket.disconnectSocket();
```
## 📚 API 參考
### 基礎模組
金融產品清單和市場節假日信息以及開市休市時間信息。
```typescript
import { BaseClient } from "@itick/browser-sdk";
const client = new BaseClient(token);
// 獲取值種列表
await client.getSymbolList({ type: "stock", region: "US" });
await client.getSymbolList({ type: "crypto", region: "BA" });
await client.getSymbolList({ type: "forex", region: "GB" });
// 獲取市場假期
await client.getSymbolHolidays("US");
await client.getSymbolHolidays("HK");
```
#### BaseClient 方法參考表
| 方法名 | 參數說明 | 返回值類型 | 描述 | 詳細參數 |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- | :------------------------------------------------- | :----------------------------------------------------------------------- |
| `getSymbolList` | `options`: `Object`
