# @getjoystick/joystick-js 中文文档

规范地址：https://npmcn.com/package/%40getjoystick/joystick-js/

版本：0\.1\.3
npm 元数据更新时间：2023-05-08T11:30:12.996Z
中文译文更新时间：2026-11-16T07:58:49.351Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：120 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2023-04-06T12:02:40.693Z
- 最新版本发布：2023-05-08T11:30:12.867Z
- 近 30 天下载量：2383（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 0 个）

## 中文简介

Javascript SDK 用于 Joystick

## 安装

```sh
npm install @getjoystick/joystick-js
```

也可以使用：`pnpm add @getjoystick/joystick-js`、`yarn add @getjoystick/joystick-js`、`bun add @getjoystick/joystick-js`

## README

# Javascript 客户端 [Joystick 远程配置](https://www.getjoystick.com/)

[![Test code](https://github.com/getjoystick/joystick-js/actions/workflows/build.yaml/badge.svg?branch=main)](https://github.com/getjoystick/joystick-js/actions/workflows/build.yaml) [![Latest Stable Version](https://img.shields.io/npm/v/@getjoystick/joystick-js)](https://www.npmjs.com/package/@getjoystick/joystick-js) [![Total Downloads](https://img.shields.io/npm/dw/@getjoystick/joystick-js)](https://www.npmjs.com/package/@getjoystick/joystick-js) [![License](https://img.shields.io/npm/l/@getjoystick/joystick-js)](https://www.npmjs.com/package/@getjoystick/joystick-js)

用Joystick的Javascript/Typescript JSON远程配置平台来简化您的应用程序或游戏开发进程. 容易地管理和更新配置,而不需要代码库繁杂或冗长的部署程序。 我们的现代平台提供先进的工作流程管理,自动化版本控制,并与任何Javascript或Typescript项目进行无缝整合. 此外,我们本地的多环境支持 与权限和审查工作流程 确保平稳操作 你整个团队会爱.

用Joystick体验简化配置管理的好处. 今天试一下我们的@getjoystick/joystick-js库,看看对你的应用或游戏动态来说有多容易,从根本上提升你的团队的工作流程.

-   [完全开发者文档](https://docs.getjoystick.com/)
-   [Joystick 远程配置](https://getjoystick.com/)

## 安装

需要节点JS 16 后期. 通过 [无](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm#using-a-node-installer-to-install-nodejs-and-npm)数字 :

```bash
npm install @getjoystick/joystick-js
```

## 使用量

在您的 Javascript 或 Typescript 计划中使用 Joystick 来获取远程配置是一个微风 .

```ts
// Import the package.
import { Joystick } from "@getjoystick/joystick-js";

// Initialize a client with a Joystick API Key
const joystickClient = new Joystick({
  apiKey: process.env.JOYSTICK_API_KEY,
});

(async () => {
  // Request a single configuration
  const contentId1 = await joystickClient.getContent("content-id1");

  // Request a single configuration (typescript)
  const contentId1Typed = await joystickClient.getContent<TypeForContentId1>(
    "content-id1"
  );

  // Request multiple configurations at the same time
  const configurations = await joystickClient.getContents([
    "content-id1",
    "content-id2",
  ]);
  console.log(configurations);

  // {
  //     "content-id1": {...},
  //     "content-id2": {...}
  // }
})();
```

### 指定补充参数

当创建时 `Joystick` 对象,您可以指定额外的参数,用于所有的 API 调用 Joystick API 。 这些附加参数用于AB测试(`userId`),分化(`params`),和后向兼容的版本交付(`semVer`) (中文(简体) ).

详情见 [API 文档](https://docs.getjoystick.com/api-reference/)。 。 。 .

```ts
// Initializing a client with options
const joystickClient = new Joystick({
  apiKey: process.env.JOYSTICK_API_KEY,
  semVer: "0.0.1",
  userId: "user-id-1",
  params: {
    param1: "value1",
    param2: "value2",
  },
  options: {
    cacheExpirationSeconds: 600, // default 600 (10 mins)
    serialized: false, // default false
  },
});
```

### 其他请求选项

#### `fullResponse`

在大多数情况下,你只需要配置的内容. 在高级用途中,如果想要处理AB测试或分解信息,可以指定 `fullResponse` 选项。 客户端会返回您的原始 API 响应 .

```ts
joystickClient
  .getContent("content-id1", { fullResponse: true })
  .then((getContentResponse) => console.log(getContentResponse));

// OR

joystickClient
  .getContents(["content-id1", "content-id2"], { fullResponse: true })
  .then((getContentsResponse) => console.log(getContentsResponse));
```

#### `serialized`

您可以将配置内容序列化 。 设定为 `true`,我们将通过查询参数 `responseType=serialized` 改为 [欢乐棒 API](https://docs.getjoystick.com/api-reference-combine/)。 。 。 .

```ts
joystickClient
  .getContent("content-id1", { serialized: true })
  .then((getContentResponse) => console.log(getContentResponse));

// OR

joystickClient
  .getContents(["content-id1", "content-id2"], { serialized: true })
  .then((getContentsResponse) => console.log(getContentsResponse));
```

可通过设置为每个API 响应设定全球序列化响应的选项 `setSerialized(true)` 初始化客户端时 :

```ts
const joystickClient = new Joystick({
  apiKey: process.env.JOYSTICK_API_KEY,
  options: {
    serialized: true,
  },
});

// OR

joystickClient.setSerialized(true);
```

#### `refresh`

在请求配置时忽略已有缓存 – 通过此选项为 `true`。 。 。 .

```ts
joystickClient
  .getContent("content-id1", { refresh: true })
  .then((getContentResponse) => console.log(getContentResponse));

// OR

joystickClient
  .getContents(["content-id1", "content-id2"], { refresh: true })
  .then((getContentsResponse) => console.log(getContentsResponse));
```

### 处理错误

客户端可以提出不同种类的例外,但基类为: `JoystickError`。 。 。 .

```ts
try {
  await joystickClient.getContents(["content-id1", "content-id2"]);
} catch (e) {
  if (e instanceof ApiHttpError) {
    // Handle HTTP error (i.e. timeout, or invalid HTTP code)
  } else if (e instanceof MultipleContentsApiException) {
    // Handle API exception (i.e. content is not found, or some of the keys can't be retrieved)
  }
}
```

### 缓存

默认情况下,客户端使用 [记忆缓存](https://npmcn.com/package/%40getjoystick/joystick-js/src/internals/cache/in-memory-cache.ts),基于Map,这意味着在应用程序重新启动后缓存将被去除.

您可以通过执行接口指定自己的缓存执行 [Sdk 缓存](https://npmcn.com/package/%40getjoystick/joystick-js/src/internals/cache/sdk-cache.ts)。 。 。 .

见 [`examples/typescript/node-cache`](https://npmcn.com/package/%40getjoystick/joystick-js/examples/typescript/src/node-cache) 或者说 [`examples/typescript/redis-cache`](https://npmcn.com/package/%40getjoystick/joystick-js/examples/typescript/src/redis-cache) 更多细节.

#### 清除缓存

如果您想要清除缓存 :

```ts
joystickClient.clearCache().then(() => console.log("Cache cleared!"));
```

### HTTP 客户端

您可以提供自定义的 HTTP 客户端, 可用于指定自定义代理或收集 HTTP 请求的详细度量衡 .

通过执行接口更改您的 HTTP 客户端执行 [Http 客户端](https://npmcn.com/package/%40getjoystick/joystick-js/src/internals/client/http-client.ts)。 。 。 .

见 [`src/internals/client/axios-client`](https://npmcn.com/package/%40getjoystick/joystick-js/src/internals/client/axios-client.ts) 更多细节.

## 测试

运行单位测试,只是运行:

```bash
npm test
```

## 贷项

-   [欢乐棒](https://github.com/getjoystick)
-   [所有贡献者](https://npmcn.com/package/%40getjoystick/joystick-js/graphs/contributors)

## 许可证

麻省理工学院. 请看 [许可证文件](https://npmcn.com/package/%40getjoystick/joystick-js/LICENSE.md) 更多信息.

## 常见问题

### @getjoystick/joystick-js 是什么？

Javascript SDK 用于 Joystick

### 如何安装 @getjoystick/joystick-js？

在项目目录运行 npm install @getjoystick/joystick-js，或使用 pnpm add / yarn add / bun add。

### @getjoystick/joystick-js 支持 TypeScript 吗？

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

### @getjoystick/joystick-js 支持 ESM 还是 CommonJS？

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

### @getjoystick/joystick-js 可以商用吗？

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

### @getjoystick/joystick-js 的下载量有多少？

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

### @getjoystick/joystick-js 还在维护吗？

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

