stock-sdk 1.0.1 → 1.0.3

package/README.md

@@ -2,6 +2,19 @@
 
 基于腾讯财经 `qt.gtimg.cn` 非官方接口封装的 TypeScript SDK，支持 A 股、港股、美股、公募基金实时行情查询。
 
+**同时支持浏览器端和 Node.js 端使用。**
+
+## 特性
+
+- ✅ 零依赖，轻量级（使用原生 fetch 和 TextDecoder）
+- ✅ 支持浏览器和 Node.js 18+ 双端运行
+- ✅ 同时提供 ESM 和 CommonJS 两种模块格式
+- ✅ 完整的 TypeScript 类型定义
+- ✅ A 股、港股、美股、公募基金实时行情
+- ✅ 资金流向、盘口大单等扩展数据
+- ✅ 内置全部 A 股代码列表（5000+）
+- ✅ 支持批量获取全市场行情（并发控制）
+
 ## 安装
 
 ```bash
@@ -13,7 +26,11 @@ yarn add stock-sdk
 ## 快速开始
 
 ```typescript
-import StockSDK from 'stock-sdk';
+// ESM (浏览器 / Node.js)
+import { StockSDK } from 'stock-sdk';
+
+// CommonJS (Node.js)
+// const { StockSDK } = require('stock-sdk');
 
 const sdk = new StockSDK();
 
@@ -21,8 +38,8 @@ const sdk = new StockSDK();
 const fullQuotes = await sdk.getFullQuotes(['sz000858', 'sh600000']);
 console.log(fullQuotes);
 
-// 简要行情
-const simpleQuotes = await sdk.getSimpleQuotes(['s_sz000858', 's_sh000001']);
+// 简要行情（参数格式与 getFullQuotes 相同）
+const simpleQuotes = await sdk.getSimpleQuotes(['sz000858', 'sh000001']);
 console.log(simpleQuotes);
 ```
 
@@ -59,12 +76,21 @@ interface FullQuote {
   volume2: number;       // 成交量(手)
   amount: number;        // 成交额(万)
   turnoverRate: number | null;  // 换手率%
-  pe: number | null;            // 市盈率
+  pe: number | null;            // 市盈率(TTM)
+  amplitude: number | null;     // 振幅%
   circulatingMarketCap: number | null;  // 流通市值(亿)
   totalMarketCap: number | null;        // 总市值(亿)
   pb: number | null;            // 市净率
   limitUp: number | null;       // 涨停价
   limitDown: number | null;     // 跌停价
+  volumeRatio: number | null;   // 量比
+  avgPrice: number | null;      // 均价
+  peStatic: number | null;      // 市盈率(静)
+  peDynamic: number | null;     // 市盈率(动)
+  high52w: number | null;       // 52周最高价
+  low52w: number | null;        // 52周最低价
+  circulatingShares: number | null;  // 流通股本(股)
+  totalShares: number | null;        // 总股本(股)
   raw: string[];                // 原始字段数组
 }
 ```
@@ -79,13 +105,68 @@ console.log(quotes[0].price); // 111.70
 
 ---
 
+### `getAllAShareQuotes(options?): Promise<FullQuote[]>`
+
+获取全部 A 股实时行情（使用内置股票代码列表，包含 5000+ 只股票）。
+
+返回的每只股票数据格式与 `getFullQuotes` 相同。
+
+**参数**
+
+- `options` — 可选配置对象
+  - `batchSize` — 单次请求的股票数量，默认 `800`
+  - `concurrency` — 最大并发请求数，默认 `5`
+  - `onProgress` — 进度回调函数 `(completed: number, total: number) => void`
+
+**示例**
+
+```typescript
+// 获取全部 A 股行情
+const allQuotes = await sdk.getAllAShareQuotes();
+console.log(`共获取 ${allQuotes.length} 只股票行情`);
+
+// 自定义配置
+const allQuotes = await sdk.getAllAShareQuotes({
+  batchSize: 500,      // 每次请求 500 只
+  concurrency: 3,      // 最多 3 个并发
+  onProgress: (completed, total) => {
+    console.log(`进度: ${completed}/${total}`);
+  },
+});
+```
+
+---
+
+### `getAllQuotesByCodes(codes, options?): Promise<FullQuote[]>`
+
+批量获取指定股票的全量行情（支持自定义股票列表）。
+
+返回的每只股票数据格式与 `getFullQuotes` 相同。
+
+**参数**
+
+- `codes` — 股票代码数组
+- `options` — 可选配置对象（同 `getAllAShareQuotes`）
+
+**示例**
+
+```typescript
+const codes = ['sz000858', 'sh600000', 'sh600519', /* ... */];
+const quotes = await sdk.getAllQuotesByCodes(codes, {
+  batchSize: 100,
+  concurrency: 2,
+});
+```
+
+---
+
 ### `getSimpleQuotes(codes: string[]): Promise<SimpleQuote[]>`
 
 获取简要行情（股票 / 指数）。
 
 **参数**
 
-- `codes` — 代码数组，格式 `s_<market><code>`，如 `['s_sz000858', 's_sh000001']`
+- `codes` — 代码数组，格式与 `getFullQuotes` 相同，如 `['sz000858', 'sh000001']`
 
 **返回**
 
@@ -108,7 +189,7 @@ interface SimpleQuote {
 **示例**
 
 ```typescript
-const quotes = await sdk.getSimpleQuotes(['s_sh000001']);
+const quotes = await sdk.getSimpleQuotes(['sh000001']);
 console.log(quotes[0].name);  // 上证指数
 ```
 
@@ -311,20 +392,48 @@ console.log(raw[0].fields); // ['51', '五 粮 液', '000858', ...]
 
 ---
 
+### `codeList`
+
+导出的全部 A 股代码列表（包含沪市、深市、北交所）。
+
+```typescript
+import { codeList } from 'stock-sdk';
+
+console.log(codeList.length);  // 5000+
+console.log(codeList[0]);      // 'bj920000'
+```
+
+---
+
+## 浏览器使用说明
+
+在浏览器端使用时，SDK 会自动使用浏览器原生的 `TextDecoder` 来解码 GBK 编码的响应数据，无需额外的 polyfill。
+
+```html
+<script type="module">
+  import { StockSDK } from 'https://unpkg.com/stock-sdk/dist/index.js';
+  
+  const sdk = new StockSDK();
+  const quotes = await sdk.getFullQuotes(['sz000858']);
+  console.log(quotes[0].name, quotes[0].price);
+</script>
+```
+
+> **注意**：由于 `qt.gtimg.cn` 接口不支持 CORS，在浏览器端使用时需要配置代理服务器。
+
 ## 开发
 
 ```bash
 # 安装依赖
-npm install
+yarn install
 
 # 运行测试
-npm test
+yarn test
 
 # 构建
-npm run build
+yarn build
 ```
 
 ## 许可证
 
 ISC
-