# @carddb/browser 中文文档

规范地址：https://npmcn.com/package/%40carddb/browser/

版本：0\.5\.8
npm 元数据更新时间：2026-07-27T16:08:39.448Z
中文译文更新时间：2026-11-09T06:24:45.877Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40carddb/browser
原文对照：https://npmcn.com/package/%40carddb/browser/?lang=original
项目主页：https://carddb.dev/
源码仓库：https://github.com/carddb/carddb-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：631 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-04-27T23:43:21.247Z
- 最新版本发布：2026-07-27T16:08:39.146Z
- 近 30 天下载量：4943（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

浏览器的卡DB客户端

## 安装

```sh
npm install @carddb/browser
```

也可以使用：`pnpm add @carddb/browser`、`yarn add @carddb/browser`、`bun add @carddb/browser`

## README

# @ carddb/ 浏览器

用于浏览器的卡DB客户端.

## 安装

```bash
npm install @carddb/browser
# or
bun add @carddb/browser
```

## 快速启动

```typescript
import { CardDBClient, BrowserCache, gte, ilike } from '@carddb/browser'

const client = new CardDBClient({
  publishableKey: 'carddb_pk_xxx...', // Browser-safe public key
  cache: new BrowserCache(), // Optional localStorage-based caching
  defaultPublisher: 'pokemon',
  defaultGame: 'tcg',
})

// Search for cards with filtering
const cards = await client.records.search({
  datasetKey: 'cards',
  filter: (f) => f.where('hp', gte(100)).where('name', ilike('%pikachu%')),
})

// Iterate through all results (auto-paginates)
for await (const card of cards) {
  console.log(card.data.name)
}
```

使用 `accessToken` 改为 `publishableKey` 用于用户授权的OAuth甲板工作流程. `secretKey` 只有服务器,而且浏览器客户端在构建时拒绝。 浏览器客户端也拒绝遗留 `apiKey` 因为它模糊不清,可以意外地暴露出密钥 `publishableKey` 专供公共浏览器阅读.

出版商管理助手, 如 `games.create`, (中文(简体) ), `records.upsertBatch`, (中文(简体) ), `imports.run`, (中文(简体) ), `exports.run`,以及 `files.requestUpload` 需要服务器端的秘密证书,并且应当从 `@carddb/node` 在信任的后端中,而不是直接从浏览器代码中。 保留内容管道,源 URL 导入,上传文件导入,批量删除,以及服务器端的出口.

```typescript
const client = new CardDBClient({
  accessToken: oauthAccessToken,
})

const decks = await client.decks.listMine()
const updated = await client.decks.updateMetadata(deck.id, {
  expectedDraftRevision: deck.draftRevision,
  title: 'Updated title',
})
```

## 浏览器缓存

基于本地Storage或会话的浏览器缓存Storage:

```typescript
import { BrowserCache } from '@carddb/browser'

// localStorage (default, persistent across sessions)
const persistentCache = new BrowserCache()

// sessionStorage (cleared when tab closes)
const sessionCache = new BrowserCache({ storage: 'sessionStorage' })

// Custom key prefix (default: 'carddb:')
const customCache = new BrowserCache({ prefix: 'myapp:carddb:' })

// Use with client
const client = new CardDBClient({
  cache: persistentCache,
  cacheTtl: 300, // 5 minutes default
  cacheTtls: {
    publishers: 3600, // 1 hour for publishers
    records: 60, // 1 minute for records
  },
})

// Manual cache management
cache.cleanup() // Remove expired entries
cache.clear() // Clear all CardDB entries
cache.size // Number of cached entries
```

## 套装大小

浏览器包被优化为最小捆绑大小. 树摇被全力支持.

## 完整文档

见 [主读取器](https://npmcn.com/package/README.md) 用于完整文档.

## 许可证

麻省理工学院

## 常见问题

### @carddb/browser 是什么？

浏览器的卡DB客户端

### 如何安装 @carddb/browser？

在项目目录运行 npm install @carddb/browser，或使用 pnpm add / yarn add / bun add。

### @carddb/browser 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @carddb/browser 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @carddb/browser 可以商用吗？

@carddb/browser 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @carddb/browser 的下载量有多少？

根据 npm 官方下载统计，@carddb/browser 在 2026/10/09 – 2026/11/07 这 30 天内被下载 4,943 次，日均约 165 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @carddb/browser 还在维护吗？

最新版本 0\.5\.8 发布于 2026/07/28（3 个月前）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2026/04/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。