# @cmath10/js-mapper 中文文档

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

版本：1\.2\.2
npm 元数据更新时间：2022-04-05T19:46:05.870Z
中文译文更新时间：2026-11-10T03:59:29.456Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：28.6 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=12
- 运行依赖：0 个
- 首次发布：2021-05-05T20:05:22.029Z
- 最新版本发布：2022-04-05T19:46:05.803Z
- 近 30 天下载量：10133（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 0 个）

## 中文简介

地图员

## 安装

```sh
npm install @cmath10/js-mapper
```

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

## README

# JsMapper - JavaScript 绘图助手

该组件通过可再用地图帮助将对象转换成相机. 其中一个主要用途是: 将 JSON API 响应转换为适当形式.

用法示例:

```javascript
import JsMapper, { JsMap } from '@cmath10/js-mapper'

const mapper = new JsMapper()
  .set('StudioPayload', new JsMap()
    .route('name', '_name')
  )
  .set('FilmPayload', new JsMap()
    .route('id', '_id')
    .route('name', '_name')
  )
  .set('FilmCollectionPayload', new JsMap()
    .route('studio', '_studio')
    .filter('studio', 'StudioPayload')
    .route('films', '_films')
    .filter('films', '[FilmPayload]')
  )

const collection = mapper.map('FilmCollectionPayload', {
  _studio: { _name: 'Lucasfilm Ltd. LLC' },
  _films: [{
    _id: 1,
    _name: 'Star Wars. Episode IV: A New Hope',
  }, {
    _id: 6,
    _name: 'Star Wars. Episode III. Revenge of the Sith',
  }],
})
```

结果是

```json
{
  "studio": { "name": "Lucasfilm Ltd. LLC" },
  "films": [{
    "id": 1,
    "name": "Star Wars. Episode IV: A New Hope"
  }, {
    "id": 6,
    "name": "Star Wars. Episode III. Revenge of the Sith"
  }]
}
```

## 安装

```bash
yarn add @cmath10/js-mapper
```

或者说

```bash
npm i @cmath10/js-mapper
```

## API 密码

JsMapper - 绘制对象的帮助类 :

```javascript
import JsMapper from '@cmath10/js-mapper'
```

方法:

-   `map(typeOrMap, source, destination = undefined)` ——将源对象映射到目的地对象,如果是目的地 未指定对象,它将被创建;您也可以提供映射实例,而不是使用映射类型 未经登记;
-   `set(type, map)` 按类型名称设置地图实例(如果类型名称尚未注册,则添加);
-   `get(type, clone = true)` —— 按类型名称返回映射实例, 如果是旗帜 `clone` 设置将返回地图副本;
-   `unset(type)` 从映射器实例中按类型名称删除地图;

**重要说明**: 您可以以 `map` 方法,只需为单个对象注册地图 例如名称 `MapTypeName` 并使用如下方法: `mapper.map('[MapTypeName]', %array of objects%)`

JsMap - 地图类, 累积绘图信息 :

```javascript
import { JsMap } from '@cmath10/js-mapper'
```

-   `destination(destination)` ——定点工厂,默认工厂为 `() => ({})`· ;
-   `route(destinationMember, sourceMember, fallback = undefined)` - 按源成员设置路径提取器 成员可能是一条很深的路 `path.to.source.property`;如果路径无法到达,并定义了后退, 后退将用作提取值;
-   `forMember(destinationMember, extractor)` - 为目的地成员设置自定义提取器;
-   `filter(destinationMember, filter)` - 为价值处理设置自定义过滤器;
-   `inject(destinationMember, injector)` 为目的地成员设置自定义注射器;
-   `exclude(destinationMember)` - 从地图中删除目的地成员;
-   `clone()` - 制作地图;

### 提取器

提取器用于从源取出值。 可用的提取器 :

```javascript
import {
  JsMapCallbackExtractor,
  JsMapExtractor,
  JsMapPathExtractor,
} from '@cmath10/js-mapper'
```

#### JsMap 外延显示器

`JsMapExtractor` 是基本的提取器类。 提取无,只是丢出一个错误( 如抽象类, 无 (执行)。 所有其他提取器应扩展这一类,并执行其 `extract` 方法.

#### JsMapPath 外部显示器

按属性路径提取源值 。 如果路径不合法, 则丢出一个错误, 且返回未定义 。 用于 默认.

#### JsMapCall Back 调用器

通过调用函数提取值, 如 `(source: unknown) => unknown`数字 :

```javascript
const mapper = new JsMapper()
  .set('Demo', new JsMap()
    .forMember('text', new JsMapCallbackExtractor(source => source._text))
  )

mapper.map('Demo', { _text: 'text' }) // { text: 'text' }
```

苏打:

```javascript
const map = new JsMap()
  .forMember('text', source => source._text)
```

### 过滤器

过滤器在注入目的地之前用于处理值. 可用的过滤器 :

```javascript
import {
  JsMapCallbackFilter,
  JsMapFilter,
  JsMapFilterChain,
  JsMapMappingFilter,
} from '@cmath10/js-mapper'
```

#### JsMapFilter 地图

`JsMapFilter` 是基本的过滤类,默认使用,实际上只是返回源值. `JsMapper` 正在注入每个实例 `JsMapFilter` 因此,可以创建复杂过滤器 以嵌入式绘图处理链。 所有其他过滤器应扩展此类 .

#### JsMapCallBackFilter 页面存档备份,存于互联网

这是一个简单的过滤器正在使用调用函数来处理值:

```javascript
const mapper = new JsMapper()
  .set('Demo', new JsMap()
    .route('text', 'text')
    .filter('text', new JsMapCallbackFilter(value => {
      if (typeof value === 'string') {
        return value.toUpperCase()
      }

      throw new Error()
    }))
  )

mapper.map('Demo', { text: 'text' }) // { text: 'TEXT' }
```

回调函数被推定为 `(value: unknown) => unknown`。糖类:

```javascript
const map = new JsMap()
    .route('text', 'text')
    .filter('text', value => {
      if (typeof value === 'string') {
        return value.toUpperCase()
      }

      throw new Error()
    })
```

#### 地图绘制 过滤器

此过滤器正在使用映射类型将映射应用到一个值( 已取消的映射机会) :

```javascript
const mapper = new JsMapper()
  .set('FilmPayload', new JsMap()
    .route('id', '_id')
    .route('name', '_name')
  )
  .set('Demo', new JsMap()
    .route('film', '_film')
    .filter('film', new JsMapMappingFilter('FilmPayload'))
  )

mapper.map('Demo', { _film: {
  _id: 1,
  _name: 'Star Wars. Episode IV: A New Hope',
} }) // { film: { id: 1, name: 'Star Wars. Episode IV: A New Hope' } }
```

苏打:

```javascript
const map = new JsMap()
    .route('film', '_film')
    .filter('film', 'FilmPayload')
```

#### JsMapFilter 钱

这种过滤器为创建过滤管道提供了机会:

```javascript
const mapper = new JsMapper()
  .set('FilmPayload', new JsMap()
    .route('id', '_id')
    .route('name', '_name')
    .filter('name', new JsMapFilterChain([
      new JsMapCallbackFilter(value => value.toUpperCase()),
      new JsMapCallbackFilter(value => '<<' + value + '>>'),
    ]))
  )
  .set('Demo', new JsMap()
    .route('film', '_film')
    .filter('film', new JsMapFilterChain([
      new JsMapMappingFilter('FilmPayload'),
      new JsMapCallbackFilter(value => value.name)
    ]))
  )

mapper.map('Demo', { _film: {
  _id: 1,
  _name: 'Star Wars. Episode IV: A New Hope',
} }) // { film: '<<STAR WARS. EPISODE IV: A NEW HOPE>>' }
```

苏打:

```javascript
const mapper = new JsMapper()
  .set('FilmPayload', new JsMap()
    .route('id', '_id')
    .route('name', '_name')
    .filter('name', [
      value => value.toUpperCase(),
      value => '<<' + value + '>>',
    ])
  )
  .set('Demo', new JsMap()
    .route('film', '_film')
    .filter('film', ['FilmPayload', film => film.name])
  )
```

### 喷出器

注射器用于向目的地物体注入已加工值。 可用注射器 :

```javascript
import {
  JsMapInjector,
} from '@cmath10/js-mapper'
```

`JsMapInjector` 是默认使用的基本注射器类。 它使用目的地成员名作为属性密钥. 如果属性为函数, 它将被用作设置器( 即以新目标调用 ) `this` 作为参数). 所有其他注射者应延长这一类.

比较示例 :

```javascript
const mapper = new JsMapper()
  .set('DatePayload', new JsMap()
    .destination(() => new Date())
    .route('setHours', 'hours')
  )

mapper.map({ hours: 0 }).getHours() // 0
mapper.map({ hours: 1 }).getHours() // 1
```

自定义注射器示例 :

```javascript
const mapper = new JsMapper()
  .set('DatePayload', new JsMap()
    .destination(() => new Date())
    .route('hours', 'hours')
    .inject('hours', new class extends JsMapInjector {
      inject(destination, path, value): void {
        destination.setHours(value)
      }
    })
  )

mapper.map({ hours: 0 }).getHours() // 0
mapper.map({ hours: 1 }).getHours() // 1
```

## 常见问题

### @cmath10/js-mapper 是什么？

地图员

### 如何安装 @cmath10/js-mapper？

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

### @cmath10/js-mapper 支持 TypeScript 吗？

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

### @cmath10/js-mapper 支持 ESM 还是 CommonJS？

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

### @cmath10/js-mapper 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=12。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cmath10/js-mapper 可以商用吗？

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

### @cmath10/js-mapper 的下载量有多少？

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

### @cmath10/js-mapper 还在维护吗？

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