# @clickbar/dot-diver 中文文档

规范地址：https://npmcn.com/package/%40clickbar/dot-diver/

版本：1\.0\.7
npm 元数据更新时间：2024-08-22T19:53:49.156Z
中文译文更新时间：2026-11-10T01:29:29.345Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：41.7 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-03-26T20:16:53.146Z
- 最新版本发布：2024-08-22T19:53:48.646Z
- 近 30 天下载量：26863（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 0 个）

## 中文简介

通过点标记访问对象属性的类型和工具.

## 安装

```sh
npm install @clickbar/dot-diver
```

也可以使用：`pnpm add @clickbar/dot-diver`、`yarn add @clickbar/dot-diver`、`bun add @clickbar/dot-diver`

## README

# 点数驱动器 QQ

一个轻量级,强大的,没有依赖性的TypeScript工具库,提供类型和功能,在点标记中与对象路径相配合. 轻松地潜入你的物体,同时保持全面的型号安全!~~

Dot Notation是一种通俗而方便的方法,可以访问物体中深层嵌入的属性. 通过Dot Diver,您可以在TypeScript项目中安全地使用对象路径,确保类型正确性和生产率!

示例

```typescript
import { getByPath } from '@clickbar/dot-diver'

const object = {
  a: 'Hello world',
}

const result = getByPath(object, 'a') // result is 'Hello world'
```

  

## \* 特性

-   QQ 有阵列、 拖曳和对象的工作
-   QQ 有只读属性的工作
-   \* 包括测试
-   \* 与自行车依赖有关的工作类型
-   无依赖关系
-   小脚印

  
  

## \* 安装

使用您最喜欢的软件包管理器安装软件包 :

无

```sh
npm install -D @clickbar/dot-diver
```

线条

```sh
yarn add -D @clickbar/dot-diver
```

小时

```sh
pnpm install -D @clickbar/dot-diver
```

  
  

## 使用量

### 🔎 `getByPath` 和 `setByPath`

  

```ts
import { getByPath, setByPath } from '@clickbar/dot-diver'

// Define a sample object with nested properties
const object = {
  a: 'hello',
  b: {
    c: 42,
    d: {
      e: 'world',
    },
  },
  f: [{ g: 'array-item-1' }, { g: 'array-item-2' }],
}

// Example 1: Get a value by path
const value1 = getByPath(object, 'a') // Output: 'hello'
console.log(value1)

const value2 = getByPath(object, 'b.c') // Output: 42
console.log(value2)

const value3 = getByPath(object, 'b.d.e') // Output: 'world'
console.log(value3)

const value4 = getByPath(object, 'f.0') // Output: { g: 'array-item-1' }
console.log(value4)

const value5 = getByPath(object, 'f.1.g') // Output: 'array-item-2'
console.log(value5)

// Example 2: Set a value by path
setByPath(object, 'a', 'new hello')
console.log(object.a) // Output: 'new hello'

setByPath(object, 'b.c', 100)
console.log(object.b.c) // Output: 100

setByPath(object, 'b.d.e', 'new world')
console.log(object.b.d.e) // Output: 'new world'

setByPath(object, 'f.0', { g: 'new array-item-1' })
console.log(object.f[0]) // Output: { g: 'new array-item-1' }

setByPath(object, 'f.1.g', 'new array-item-2')
console.log(object.f[1].g) // Output: 'new array-item-2'
```

  
  

### 路径和路径值

  

```typescript
import type { Path, PathValue } from '@clickbar/dot-diver'

// Define a sample object type with nested properties
type MyObjectType = {
  a: string
  b: {
    c: number
    d: {
      e: boolean
    }
  }
  f: [{ g: string }, { g: string }]
}

// Example 1: Using the Path type
type MyObjectPaths = Path<MyObjectType>

// MyObjectPaths will be a union type representing all valid paths in dot notation:
// 'a' | 'b' | 'f' | 'b.c' | 'b.d' | 'b.d.e' | 'f.0' | 'f.1' | 'f.0.g' | 'f.1.g'

// Example 2: Using the PathValue type
type ValueAtPathA = PathValue<MyObjectType, 'a'> // Output: string
type ValueAtPathB_C = PathValue<MyObjectType, 'b.c'> // Output: number
type ValueAtPathB_D_E = PathValue<MyObjectType, 'b.d.e'> // Output: boolean
type ValueAtPathF_0 = PathValue<MyObjectType, 'f.0'> // Output: { g: string }
type ValueAtPathF_0_G = PathValue<MyObjectType, 'f.0.g'> // Output: string
```

  
  

### 具有周期依赖性的对象

  

```typescript
import type { Path, PathValue } from '@clickbar/dot-diver'

// Define an object type with nested properties and a cyclic dependency
type Node = {
  id: number
  label: string
  parent: Node
  children: Node[]
}

// Example 1: Using the Path type with a Depth limit
type NodePathsDepth2 = Path<Node, 2> // Depth limit of 2

// NodePathsDepth2 will be a union type representing all valid paths in dot notation up to a depth of 3:
// 'id' | 'label' | 'parent' | 'children' | 'parent.id' | 'parent.label' | 'parent.parent' | 'parent.children' | `parent.parent.${any}` | `parent.children.${any}` | `children.${number}` | `children.${number}.${any}`

// Example 2: Using the PathValue type with a Depth limit
type ValueAtPathParent_Id = PathValue<Node, 'parent.id', 3> // Output: number
type ValueAtPathChildren_0_Label = PathValue<Node, 'children.0.label', 3> // Output: string | undefined
type ValueAtPathParent_Parent_Parent = PathValue<Node, 'parent.parent.parent.parent', 3> // Output: unknown (due to the depth limit)
```

默认深度为当前 **10个**。 。 。 .  
目前,在使用所提供设备时无法定制 `getByPath` 财务报告和审定财务报表 `setByPath` 函数. 这一点对此有进一步的解释 [问题](https://github.com/clickbar/dot-diver/issues/1)。 。 。 .

  
  

### QQ 自定义深度限制

你仍然可以定制它, 通过执行你自己的功能, 它只是叫我们. 示例

  

```typescript
import { getByPath, setByPath } from '@clickbar/dot-diver'

import type { Path, SearchableObject, PathValue } from '@clickbar/dot-diver'

function getByPathDepth5<T extends SearchableObject, P extends Path<T, 5> & string>(
  object: T,
  path: P,
): PathValue<T, P, 5> {
  return getByPath(object, path) as PathValue<T, P, 5>
}

function setByPathDepth5<
  T extends SearchableObject,
  P extends Path<T, 5> & string,
  V extends PathValue<T, P, 5>,
>(object: T, path: P, value: V): void {
  setByPath(object, path, value as PathValue<T, P>)
}

export { getByPathDepth5 as getByPath, setByPathDepth5 as setByPath }
```

之间的交叉点 `Path<T, 5>` 财务报告和审定财务报表 `string` 为 TypeScript 成功缩小类型所必需 `P` 根据用户提供的 `path` 输入. 没有十字路口 `path` 会只是类型 `Path<T, 5>` 财务报告和审定财务报表 `PathValueEntry` 这将是一个各种可能的返回类型的联盟. 通过使用相交点,TypeScript被迫应用 `Path` 从所提供的用户输入中推断出类型.

  
  

## 问 题

### 为什么我的路径被截断在一个有索引签名的对象中?

看这个 [问题](https://github.com/clickbar/dot-diver/issues/2)。 。 。 .

  

### 为什么我的路径在阵列内被截断?

你的道路没有被截断。 键盘仍然会验证它们. 一些IDE 显示有问题 `children.${number}` 路径. 如果可以,则定义数组为tuple. 这将包括自动补全中的所有路径 .

  

### "Type即时演绎过深 可能无限"

如果打字符达到最大深度极限, 就会发生这种情况 。 这个库应该可以防止这种情况,但是如果一个对象有许多循环依赖,它仍然可以发生.  
例如:

```typescript
type TestType = {
  a: TestType
  b: [TestType]
  c: TestType[]
  d: {
    e: TestType
  }
  f: TestType2
}
```

您可以尝试通过重用 `getByPath` 财务报告和审定财务报表 `setByPath` 函数. 见 [本节](https://npmcn.com/package/%40clickbar/dot-diver/#readme-%EF%B8%8F-customizing-the-depth-limit) 用于自定义深度限制.

  

## 捐款

如果您想向 Dot Diver 投稿, 请随意将寄存器叉出, 更改, 并提交拉动请求 。 我们感谢任何帮助和反馈.

见 [捐款额](https://npmcn.com/package/%40clickbar/dot-diver/CONTRIBUTING.md) 更多信息.

  

## \* 安全脆弱性

请看 [警卫](https://npmcn.com/package/%40clickbar/dot-diver/SECURITY.md) 详细情况.

  

## 许可证

Dot Diver根据以下规定获得许可: [MIT 许可证](https://npmcn.com/package/%40clickbar/dot-diver/LICENSE.md)。 。 。 .

  

潜水快乐

## 常见问题

### @clickbar/dot-diver 是什么？

通过点标记访问对象属性的类型和工具\.

### 如何安装 @clickbar/dot-diver？

在项目目录运行 npm install @clickbar/dot-diver，或使用 pnpm add / yarn add / bun add。

### @clickbar/dot-diver 支持 TypeScript 吗？

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

### @clickbar/dot-diver 支持 ESM 还是 CommonJS？

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

### @clickbar/dot-diver 可以商用吗？

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

### @clickbar/dot-diver 的下载量有多少？

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

### @clickbar/dot-diver 还在维护吗？

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