# @galangel/react-tip-magic 中文文档

规范地址：https://npmcn.com/package/%40galangel/react-tip-magic/

版本：1\.3\.0
npm 元数据更新时间：2026-08-20T10:15:05.087Z
中文译文更新时间：2026-11-15T21:24:43.255Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.4 MB，100 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2026-01-13T21:51:47.915Z
- 最新版本发布：2026-08-20T10:15:04.711Z
- 近 30 天下载量：6175（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

一个精致,优雅,能表演的工具提示库,用于与智能的活浮辅助系统进行回放.

## 安装

```sh
npm install @galangel/react-tip-magic
```

也可以使用：`pnpm add @galangel/react-tip-magic`、`yarn add @galangel/react-tip-magic`、`bun add @galangel/react-tip-magic`

## README

# 反射提示魔法 QQ

一个深思熟虑的用于反应的工具提示库——简单使用,令人愉快的经验.

![npm version](https://img.shields.io/npm/v/@galangel/react-tip-magic) ![bundle size](https://img.shields.io/bundlephobia/minzip/@galangel/react-tip-magic) ![license](https://img.shields.io/npm/l/@galangel/react-tip-magic)

## 为什么是小提示魔法?

工具提示看起来很简单,但是要正确处理 它们应该在需要时出现,在不时不要挡道,在用户浏览您的界面时感觉自然.

React Tip Magic 处理细节, 这样你就不用 - 定位, 过渡, 访问, 键盘支持 - 都有一个干净的, 宣示性的 API .

## 快速启动

```bash
npm install @galangel/react-tip-magic
```

```tsx
import { TipMagicProvider } from '@galangel/react-tip-magic';
import '@galangel/react-tip-magic/styles.css';

function App() {
  return (
    <TipMagicProvider>
      <YourApp />
    </TipMagicProvider>
  );
}
```

就是这样。 现在添加 `data-tip` 改为任何元素:

```tsx
<button data-tip="Save your changes">Save</button>
```

* * *

## 工具提示

反应提示魔法的核心. 一个工具提示实例,在元素之间优雅地移动,提供了平稳而连贯的经验.

### 基本用途

```tsx
<button data-tip="Click to save">Save</button>
<button data-tip="Undo last action">Undo</button>
```

### 键盘快捷键

使用工具提示显示快捷键 `data-tip-shortcut` 属性 :

```tsx
<button data-tip="Copy" data-tip-shortcut="⌘C">Copy</button>
<button data-tip="Paste" data-tip-shortcut="⌘V">Paste</button>
<button data-tip="Save" data-tip-shortcut="⌘S">Save</button>
```

### 定位行为( B)

```tsx
{
  /* Position control */
}
<button data-tip="Below the button" data-tip-placement="bottom">
  Hover me
</button>;

{
  /* Smooth transitions between grouped elements */
}
<nav>
  <a data-tip="Home" data-tip-move data-tip-group="nav">
    Home
  </a>
  <a data-tip="About" data-tip-move data-tip-group="nav">
    About
  </a>
  <a data-tip="Contact" data-tip-move data-tip-group="nav">
    Contact
  </a>
</nav>;

{
  /* Interactive tooltips that stay visible on hover */
}
<span data-tip="Click <a href='#'>here</a> to learn more" data-tip-html data-tip-interactive>
  More info
</span>;
```

* * *

## 导游

用分步巡演让用户通过您的界面. 有助于登机、特性介绍或背景指导.

```tsx
import { useTour } from '@galangel/react-tip-magic';

function App() {
  const tour = useTour({
    steps: [
      { target: 'dashboard', title: 'Welcome', content: 'This is your dashboard.' },
      { target: 'create-btn', title: 'Create', content: 'Click here to get started.' },
    ],
    // Built-in Back/Next controls are off by default—turn them on for multi-step tours
    navigation: { showControls: true },
    progress: { show: true },
  });

  return (
    <div>
      <nav data-tip-id="dashboard">Dashboard</nav>
      <button data-tip-id="create-btn" onClick={tour.start}>
        New Project
      </button>
    </div>
  );
}
```

`useTour` 默认为无头: 离开 `navigation.showControls` 取消设置, 并从返回时创建自己的控制 `next`, (中文(简体) ), `prev`, (中文(简体) ), `end` 财务报告和审定财务报表 `progress`。 。 。 .

```tsx
const tour = useTour({ steps });

{
  tour.isActive && (
    <div>
      <span>
        {tour.progress.current} of {tour.progress.total}
      </span>
      <button onClick={tour.prev} disabled={tour.currentStep?.isFirst}>
        Back
      </button>
      <button onClick={tour.next}>{tour.currentStep?.isLast ? 'Finish' : 'Next'}</button>
    </div>
  );
}
```

### 步骤内容为 HTML

步骤 `content` 被注入为 HTML ,以使标题、媒体和控件工作。 使用 `text` 当值是纯文本时, 库应该为您逃出 :

```tsx
{ target: 'profile', text: `Signed in as ${user.name}` }
```

就是其中一个 `content` 或者说 `text` 需要——一个既不是,也不是两者都无法编译的步骤. 对于带有内插值的标记,请保留 `content` 以导出值逃避值 `escapeHtml`数字 :

```tsx
import { escapeHtml } from '@galangel/react-tip-magic';

{ target: 'profile', content: `Signed in as <b>${escapeHtml(user.name)}</b>` }
```

### 当目标不在时

`start()` 返回时 `false` 和改变什么 - 不 `onStart`,没有 `onStepChange`如果DOM里没有步骤的目标, 所以巡演不能让 从来没有报告自己显示。 供应 `onTargetMissing` 自己处理(和保持图书馆关闭) `console.warn`:

```tsx
const tour = useTour({
  steps,
  onTargetMissing: (step) => {
    logger.warn('tour target missing', { target: step.target });
    return 'skip'; // or end the tour, which is the default
  },
});

if (tour.start()) {
  markTourAsSeen();
}
```

恢复取决于旅行方向: `next()` 跳过或结束巡演,同时 `prev()` 财务报告和审定财务报表 `goTo()` 把它留在原地——屏幕上的台阶仍然很好. `goTo()` 从来没有跳过,所以它降落在 你要求的台阶或返回 `false`。 。 。 .

### 重点土地

参观面板是一个对话,所以当一个步骤打开时,焦点会移动到其中. `autoFocus` 选择其中的元素 :

```tsx
const tour = useTour({
  steps,
  // 'panel' (default) | 'primary' — Next/Finish, so Enter advances | false — leave focus alone
  navigation: { showControls: true, autoFocus: 'primary' },
});
```

`'primary'` 当一个步骤没有下/完成按钮时返回面板——永远不要关闭按钮。 每一步可超过 `step.navigation.autoFocus`。 。 。 .

参观还支持进展指标、键盘支持和背景突出(`focus: true`,或 `focus: { dismissOnClick: true }` ——这些都适合你的需要.

* * *

## 小费顾问

键盘快捷键发现菜单 。 按下密钥(默认为F1)以显示界面中所有可用的快捷键,并进行模糊搜索以快速找到需要的东西.

```tsx
import { TipAdvisor } from '@galangel/react-tip-magic';

function App() {
  return (
    <TipMagicProvider>
      <div className="toolbar">
        <button data-tip="Copy" data-tip-shortcut="⌘C">
          Copy
        </button>
        <button data-tip="Paste" data-tip-shortcut="⌘V">
          Paste
        </button>
        <button data-tip="Save" data-tip-shortcut="⌘S">
          Save
        </button>
      </div>

      {/* Press F1 to open the advisor */}
      <TipAdvisor />
    </TipMagicProvider>
  );
}
```

特征 :

-   带有突出显示的匹配的模糊搜索
-   键盘导航( 窄键+ 输入)
-   跳转到预览工具提示位置
-   单击以触发关联元素

* * *

## 数据属性

| 属性 | 说明 | 示例 |
| --- | --- | --- |
| `data-tip` | 工具提示内容 | `data-tip="Hello"` |
| `data-tip-shortcut` | 键盘快捷键徽章 | `data-tip-shortcut="⌘S"` |
| `data-tip-id` | 旅游要素标识符 | `data-tip-id="welcome"` |
| `data-tip-placement` | 位置(上、下、左、右) | `data-tip-placement="bottom"` |
| `data-tip-delay` | 显示延迟 MS | `data-tip-delay="500"` |
| `data-tip-hide-delay` | 隐藏延迟 MS | `data-tip-hide-delay="100"` |
| `data-tip-disabled` | 禁用工具提示 | `data-tip-disabled` |
| `data-tip-html` | 解析内容为 HTML | `data-tip-html` |
| `data-tip-interactive` | 保持工具提示悬浮 | `data-tip-interactive` |
| `data-tip-move` | 平滑移动过渡 | `data-tip-move` |
| `data-tip-group` | 过渡组 | `data-tip-group="nav"` |
| `data-tip-no-arrow` | 隐藏工具提示箭头 | `data-tip-no-arrow` |

* * *

## 程序化 API

更多的控制,请使用 `useTipMagic` 钩:

```tsx
import { useTipMagic } from '@galangel/react-tip-magic';

function MyComponent() {
  const { tooltip } = useTipMagic();

  const handleClick = () => {
    tooltip.show('#my-element', 'Dynamic content');
  };

  return (
    <button id="my-element" onClick={handleClick}>
      Click me
    </button>
  );
}
```

* * *

## 内设

-   **反应 18+** 带有现代钩子
-   **类型脚本** 类型安全
-   **浮动 UI** 用于定位
-   **故事书** 文档

* * *

## 许可证

阿帕奇 - 2.0

* * *

照顾反应社区

[![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png)](https://www.buymeacoffee.com/galangel)

## 常见问题

### @galangel/react-tip-magic 是什么？

一个精致,优雅,能表演的工具提示库,用于与智能的活浮辅助系统进行回放\.

### 如何安装 @galangel/react-tip-magic？

在项目目录运行 npm install @galangel/react-tip-magic，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @galangel/react-tip-magic 支持 TypeScript 吗？

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

### @galangel/react-tip-magic 支持 ESM 还是 CommonJS？

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

### @galangel/react-tip-magic 可以商用吗？

@galangel/react-tip-magic 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @galangel/react-tip-magic 的下载量有多少？

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

### @galangel/react-tip-magic 还在维护吗？

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