@gravity-ui/onboarding

中文文档
1.12.4发布于 2026/10/12MITTypeScriptCommonJS近 30 天下载 7904

基于登入方案创建提示, 并管理您服务的促销活动 。 与React、任何其他框架或香草JS一起使用.

中文使用文档
文档目录16 节
  1. 安装
  2. 如何使用登机
  3. 登入配置
  4. 登入选项
  5. 常见的预设配置
  6. 合并预设
  7. Async 预设
  8. 活动
  9. 登入插件
  10. 如何使用宣传管理器
  11. 1. 启动促销管理器并安排进度更新
  12. 2. 在您组件中的触发促进
  13. 条件和制约因素
  14. 宣传管理器事件
  15. JSON 配置
  16. 入职一体化

@gravity-ui/登上飞机 npm package CI

基于登入方案创建提示, 并管理您服务的促销活动 . 与React、任何其他框架或香草JS一起使用.

  • 小型. 登机~4Kb,宣传-管理~8kb. 零依赖关系
  • 测试的很好. ~80%的测试覆盖率
  • 小代码脚印。创建登入情景配置,并用几行代码连接每个步骤.
  • 没有UI。使用自己的组件
  • 良好的类型脚本支持

目录

安装

npm i @gravity-ui/onboarding

软件包内容

此包包含两个工具 :

  • 入职 - 基于入职为服务用户创建提示的工具. 创建带有步骤的预设,绑定元素和调用方法. 登入会保持用户的进步并计算下一条提示以显示.

  • Promo管理器 - 管理您向用户推入的任何促销活动的工具:横幅,告密者,新功能的广告,UX调查,教育弹出. 将所有 promos 配置并指定条件 。 Promo管理器会保持用户进度并计算出下一个显示的Promo.

登入指南

你可以试试看 游乐场

如何使用登机

基本反应示例
// onboarding/lib.ts
import {createOnboarding, createPreset} from '@gravity-ui/onboarding';

export const {
  useOnboardingStep,
  useOnboardingPreset,
  useOnboardingHint,
  useOnboarding,
  controller,
} = createOnboarding({
  config: {
    presets: {
    // createPreset - wrapper for better type inference
      todoListFirstUsage: createPreset({
        name: '',
        steps: [
          createStep({
            slug: 'createTodoList',
            name: 'create-todo-list',
            description: 'Click button to create todo list',
          }),
          /* other scanario steps */
        ],
      }),
    },
  },
  // onboarding state from backend
  baseState: () => {/* ... */},
  getProgressState: () => {/* ... */},
  // save new onboarding state to backend
  onSave: {
    state: (state) => {/* ... */},
    progress: (progress) => {/* ... */},
  },
});
// Hint.tsx
import { useCallback } from 'react';
import { Popup } from '@gravity-ui/uikit';
import { useOnboardingHint } from './lib.ts';

export const OnboardingHint = () => {
  const { anchorRef, hint, open, onClose } = useOnboardingHint();

  const handleClose = useCallback(() => {
    onClose();
  }, [onClose]);

  return (
    <>
      <Popup
        anchorElement={anchorRef.current}
        open={open}
        onOpenChange={handleClose}
      >
        <h3>{hint?.step.name}</h3>
        {hint?.step.description}
      </Popup>
    </>
  );
};
// todo-list.tsx
import { useOnboardingStep } from './onboarding/lib';

export const SomeFeature = () => {
  const { pass, ref } = useOnboardingStep('createTodoList');

  return (
    <Button
      onClick={() => {
        pass();
        handleAddTodoList();
      }}
      ref={ref}
      // ...
    >
      "Add new list"
    </Button>
  );

};

如果无法访问目标元素,则可以使用 useOnboardingStepBySelector

// todo-list.tsx
import {useOnboardingStepBySelector} from '../todo-list-onboarding.ts';

const ref = useRef()
useOnboardingStepBySelector({
  element: ref.current,
  selector: '.deep_nested_element',
  step: 'createFirstIssue'
});

return (
  <Button
    onClick={() => {
      pass();
      handleAddTodoList();
    }}
    ref={ref}
    // ...
  >
    "Add new list"
  </Button>
);

登入配置

登入选项

您可以配置登入

const onboardingOptions = {
  config: {
    presets: {/**/},
  },
  globalSwitch: 'off', // optional.  turn off onboarding globally. For example in some entire env 
  ignoreUnknownPresets: true, // optional. will not thorow error for unknown presets
  baseState: {/**/}, // initial state for current user
  getProgressState: () => {/**/}, // function to load user progress
  customDefaultState: {/**/}, // optional. will apply this value for user with no base state
  onSave: {
    // functions to save user state
    state: (state) => {/**/},
    progress: (progress) => {/**/},
  },
  showHint: (state) => {}, // optional. function to show hint. Only for vanilla js usage
  logger: { // optional. you can specify custom logger
    level: 'error' as const,
    logger: {
      debug: () => {/**/},
      error: () => {/**/},
    },
  },
  debugMode: true, // optional. true will show a lot of debug messages. Recommended for dev environment
  plugins: [/**/], // optional. you can use existing plugins or write your own
  // optional. you can subscribe to onboarding events
  hooks: {
    showHint: ({preset, step}) => {/**/},
    stepPass: ({preset, step}) => {/**/},
    addPreset: ({preset}) => {/**/},
    beforeRunPreset: ({preset}) => {/**/},
    runPreset: ({preset}) => {/**/},
    finishPreset: ({preset}) => {/**/},
    beforeSuggestPreset: ({preset}) => {/**/},
    beforeShowHint: ({stepData}) => {/**/},
    stateChange: ({state}) => {/**/},
    hintDataChanged: ({state}) => {/**/},
    closeHint: ({hint, eventSource}) => {/**/},
    closeHintByUser: ({hint, eventSource}) => {/**/},
    init: () => {/**/},
    wizardStateChanged: ({wizardState}) => {/**/},
    applyDefaultState: ({wizardState}) => {/**/},
  },
};

常见的预设配置

对于默认的预设,您可以指定属性 :

const onboardingOptions = {
  config: {
    presets: {
      // you can use goPrevStep and goNextStep in steps
      createProject: createPreset(({goPrevStep, goNextStep}) => ({
        // preset name should be unique
        name: 'Creating project', // text for user
        type: 'default', // optional. 'default'(default value) | 'interlal' | 'combined'
        visibility: 'visible', // optional. 'visible'(defaule value) | 'initialHidden' | 'alwaysHidden';
        description: '', // optional, text for user
        steps: [
          {
            slug: 'openBoard', // step slug must be unique across all presets
            name: '', // text to show in popup
            description: '', // text to show in popup
            placement: 'top', // optional. Hint placement for step
            passMode: 'onAction', // optional. 'onAction'(default value) | 'onShowHint' - trigger step pass on hint show
            hintParams: {
              // you can use theese actions in Hint component to display buttons
              actions: [
                {
                  children: 'Go back',
                  view: 'action' as const,
                  onClick: () => {
                    goNextStep()
                  },
                },
                {
                  children: 'Go next',
                  view: 'action' as const,
                  onClick: () => {
                    goNextStep()
                  },
                },
              ],
            }, // optional. any custom properties for hint
            closeOnElementUnmount: false, // optional. default valeue - false. Will close hint when element umnounts. 'True' not reccomended in general^ but may me helpful for some corners
            passRestriction: 'afterPrevious', // optional. afterPrevious will block pass step is previous not passed
            hooks: {
              // optional
              onStepPass: () => {/**/},
              onCloseHint: () => {/**/},
              onCloseHintByUser: () => {/**/},
            },
          },
        ],
        hooks: {
          // optional
          onBeforeStart: () => {/**/},
          onStart: () => {/**/},
          onEnd: () => {/**/},
        },
      })),
    },
  },
};

合并预设

对于合并预设,您需要在配置中添加内部预设并指定 pickPreset 函数.

import {createInternalPreset, createCombinedPreset, createOnboarding} from '@gravity-ui/onboarding';

createOnboarding({
    config: {
        presets: {
            //  you need to add internal presets. Here it is internal1 and internal2
            internal1:  createInternalPreset({
                name: 'Internal2',
                type: 'internal' as const,
                steps: [/* ... */]
            }),
            internal2:  createInternalPreset({
                name: 'Internal2',
                type: 'internal' as const,
                steps: [/* ... */],
            }),
            // combined preset has no steps
            combined: createCombinedPreset({
                name: 'combined',
                type: 'combined' as const,
                // pickPreset calls on preset start and resolve combined preset to specific internal preset
                pickPreset: () => {
                    if(someCondition) {
                        return 'internal1'
                    }
                    
                    return 'internal2'
                },
                internalPresets: ['internal1', 'internal2'],
            }),
        },
    },
});

您可以在 测试数据

Async 预设

对于大型登入,在用户实际达到一步之前,可能不需要将文本和i18n捆绑入预设. 您可以使用 config.asyncPresets数字 :

// heavy-presets.ts — lives in its own chunk, pulls i18n with it
import {createAsyncPresets, createPreset} from '@gravity-ui/onboarding';
import {i18n} from './i18n';

export default createAsyncPresets({
  createProject: createPreset({
    name: i18n('createProject.name'),
    steps: [/* ... */],
  }),
  viewReports: createPreset({
    name: i18n('viewReports.name'),
    steps: [/* ... */],
  }),
});

将同步地图包入 createAsyncPresets ——此身份帮助保留了字面地图类型如此 Presets 财务报告和审定财务报表 Steps 工会的推定是正确的 createOnboarding 电话站.

// lib.ts
import {createOnboarding, createPreset} from '@gravity-ui/onboarding';

createOnboarding({
  config: {
    presets: {
      // sync presets stay inlined
      quickTour: createPreset({ /* ... */ }),
    },
    // single loader — one import = one code-split chunk = one request
    asyncPresets: () => import('./heavy-presets').then((m) => m.default),
  },
  // ...rest unchanged
});

语义:

  • 装入器被引用 最多一次 每个控制器生命周期,第一次使用任何预设的身体-触摸方法(runPreset, (中文(简体) ), addPreset, (中文(简体) ), suggestPresetOnce, (中文(简体) ), passStep, (中文(简体) ), stepElementReached, (中文(简体) ), finishPreset, (中文(简体) ), resetPresetProgress,向导打开,读取 userPresets) (中文(简体) ). 被禁用的控制器从不触发加载器.
  • 虽然装载机在飞行中,但同时通话也有同样的承诺——没有重复请求.
  • 如果加载器拒绝,则错误会被记录并泡出至呼叫器,拒绝被缓存——随后的调用会浮出相同的错误而无需再取加载器. 要在持续失败后重试(例如用户点击"再试"),重新创建控制器.
  • 仍然静态地推断出Aync地图上的淤泥—— useOnboardingStep('slugFromAsyncPreset') 保持类型安全.
  • 如果一个同步密钥与同步密钥相撞,同步预设获胜并被记录出错.
  • 结构分解的消费者 controller.options.config.presets 在模块级别上,只看到同步子集,直到加载器解决。 通过控制器方法或 userPresets 获取( 重生成) stateChange 而不是决心.

活动

您可以使用事件系统 。 可用事件 : showHint, (中文(简体) ), stepPass, (中文(简体) ), addPreset, (中文(简体) ), beforeRunPreset, (中文(简体) ), runPreset, (中文(简体) ), finishPreset, (中文(简体) ), beforeSuggestPreset, (中文(简体) ), stepElementReached, (中文(简体) ), beforeShowHint, (中文(简体) ), stateChange, (中文(简体) ), hintDataChanged, (中文(简体) ), closeHint, (中文(简体) ), init, (中文(简体) ), wizardStateChange

controller.events.subscribe('beforeShowHint', callback);

召回可作同声. 有些事件可以取消目标动作 : stepElementReached, (中文(简体) ), beforeShowHint, (中文(简体) ), beforeSuggestPreset

controller.events.subscribe('stepElementReached', async () => {
    /* ... */
    if(someCondition) {
        // forbid show hint
        return false
    }
});

登入插件

您可以使用插件

  • 多标签同步插件 - 同步关闭提示和状态(试验在标签之间). 如果用户在多个分页中打开页面,则无需多次黑入一个提示. 状态同步还同步完成/未完成的情景状态和向导,但 可能导致内存漏出。默认已禁用,可自行冒险启用
  • 向导缓冲 - 如果你有一个向导, 用户可以看见他的情景并启动它们, 则有用 。 插件
    • 如果打开向导, 在启动时加载进度
    • 如果显示向导元素可见时显示提示
    • 关闭向导时关闭提示
    • 启动预设时关闭提示并删除未完成预设的进度
    • 预设完成时扩展向导
  • 推进预设插件 - 在预设周围添加逻辑 visibility: 'alwaysHidden'。这些预设被认为是促发预设,并附加附加逻辑.
    • 打开向导时不显示宣传预设提示
    • 隐藏向导时不显示正则预设提示
    • 如果需要显示提示, 则在用户状态下切换启用状态( 可选)
    • (可选)在发布(建议PresetOce)预设时切换启用的用户状态

示例

import {createOnboarding} from '@gravity-ui/onboarding';
import {
  MultiTabSyncPlugin,
  PromoPresetsPlugin,
  WizardPlugin,
} from '@gravity-ui/onboarding/dist/plugins';

const {controller} = createOnboarding({
  /* ... */
  plugins: [
    new MultiTabSyncPlugin({
      enableStateSync: false, // Experimantal. Default - false(recommended). Sync all onboarding state.
      enableCloseHintSync: true, // closes hont in all browser tabs,
      changeStateLSKey: 'onboarding.plugin-sync.changeState', // localStorage key for state sync
      closeHintLSKey: 'onboarding.plugin-sync.closeHint', // localStorage key for close hint in all tabs
    }),
    new PromoPresetsPlugin({
      turnOnWhenShowHint: true, // Default - true. Force to turn on onboarding, when promo hint should be shown
      turnOnWhenSuggestPromoPreset: true, // Default - true. Force to turn on onboarding, when promo preset suggested
    }),
    new WizardPlugin(),
  ],
});

你可以自己写插件

import {createOnboarding} from '@gravity-ui/onboarding';
import {WizardPlugin} from '@gravity-ui/onboarding/dist/plugins';

const myPlugin = {
  apply: (onboarding) => {
    /**
     * Do something with onboarding controller
     * For exampe subscribe on event
     *  onboarding.events.subscribe('init', () => {});
     */
  },
};

const {controller} = createOnboarding({
  /**/
  plugins: [new WizardPlugin(), myPlugin],
});

宣传管理器

如何使用宣传管理器

1. 启动促销管理器并安排进度更新

// promo-manager.ts

import { createPromoManager } from '@gravity-ui/onboarding/dist/promo-manager';
import { ShowOnceForPeriod } from '@gravity-ui/onboarding/dist/promo-manager/helpers';

export const { controller, usePromoManager, useActivePromo } = createPromoManager({
    config: {
        promoGroups: [{
            slug: 'poll',
            conditions: [ShowOnceForPeriod({month: 1})],
            promos: [
                {
                    slug: 'issuePoll',
                    conditions: [ShowOncePerMonths(6)],
                    meta: {...}
                },
            ],
        }],
    },
    progressState: () => {/* ... */},
    getProgressState: () => {/* ... */},
    onSave: {
        progress: (state) => () => {/* ... */},
    },
});

2. 在您组件中的触发促进

// TriggerExample.tsx

import { usePromoManager } from './promo-manager';

const { status, requestStart, skipPromo } = usePromoManager('issuePoll');

useMount(() => {
    requestStart();
});

useUnmount(() => {
    skipPromo();
});

if(status === 'active') {
    // allowed to run. Do something
}

条件和制约因素

您可以为每个促销项目使用条件。 或利用约束来设定相隔相间的限制.

只有

  • 所有宣传条件都回归真实
  • 所有 promo 组条件返回为真
  • 所有限制都通过
import {
    ShowOnceForSession,
    ShowOnceForPeriod,
    MatchUrl,
    LimitFrequency
} from '@gravity-ui/onboarding/dist/promo-manager/helpers';

const groupOfPolls = {
    slug: 'groupOfPolls',
    promos: [
        {slug: 'somePoll', conditions: [ShowOnceForPeriod({month: 1})]},
        {slug: 'pollForPageWithparam', conditions: [
            MatchUrl('param=value'),
            ShowOnceForPeriod({month: 5})
        ]}
    ],
}

const groupOfHints = {
    slug: 'groupOfHints',
    conditions: [ShowOnceForSession()],
    promos: [
        {slug: 'someHint'},
        {slug: 'hintForSpecificPage', conditions: [
            MatchUrl('/folder/\\w{5}/page$'),
        ]},
    ],
}

const {controller} = createPromoManager({
    config: {
        constraints: [
            LimitFrequency({
                slugs: ['somePoll', 'groupOfHints'], // can use promos slugs and group slugs
                interval: {days: 1},
            })
        ],
        promoGroups: [groupOfHints, groupOfPolls]
    },
});


你可以写你自己的条件.


const user = {/**/} // get user from state
const usersWithLanguage = (language) => user.language = language;

const promo = {slug: 'somePoll', conditions: [usersWithLanguage('english')]};

宣传管理器事件

Promo管理器可以对事件进行推介.

const promo = {
    slug: 'promo1',
    conditions: [],
    trigger: {on: 'someCustomEvent', timeout: 1000}
}

const {controller} = createPromoManager({
    config: {
        promoGroups: [{
            slug: 'group',
            conditions: [],
            promos: [promo],
        }]
    },
});

controller.sendEvent('someCustomEvent')

您还可以使用 UrlEventPlugin 运行 promos 在特定的url。 当用户打开页面时, Promo 会运行 .

const {controller} = createPromoManager({
    config: {
        promoGroups: [
            {
                slug: '1',
                promos: [
                    {
                        slug: 'promo1',
                        conditions: [MatchUrl('/folder/\\w{5}/page$'),],
                        trigger: {on: 'pageOpened', timeout: 2000},
                    },
                ],
            },
        ],
    },
    plugins: [new UrlEventsPlugin({eventName: 'pageOpened'})],
})

JSON 配置

您可以定义条件,限制为JSON可序列对象. 这样你就可以从json中取出配置,分析并使用. 它可以用于编辑配置而不重建工程和发布.


const usersWithLanguage = (language) => user.language = language;

const {controller} = createPromoManager({
    config: { // config section now can be parsed from json
        constraints: [
            {
                helper: 'LimitFrequency',
                args: [{
                    slugs: ['somePoll', 'groupOfHints'], // can use promos slugs and group slugs
                    interval: {days: 1},
                }],
            },
        ],
        promoGroups: [{
            slug: 'groupOfPolls',
            promos: [
                {
                    slug: 'somePoll',
                    conditions: [{
                        helper: 'ShowOnceForPeriod',
                        args: [{month: 1}]
                    }]
                },
                {
                    slug: 'pollForPageWithparam',
                    conditions: [
                        {
                            helper: 'MatchUrl',
                            args: ['param=value']
                        },
                        {
                            helper: 'usersWithLanguage',
                            args: ['English']
                        },
                    ]
                }
            ],
        }]
    },
    conditionHelpers: {
        usersWithLanguage,
    },
});

入职一体化

您可以使用登入 PromoPresetsPlugin 显示广告和教育提示。 您可以使用promo管理器限制频率,并与其他在役的promo设置约束.

import {
    createOnboarding
} from "./index";

const {controller: onboardingController} = createOnboarding({
    config: {
        presets: {
            coolNewFeature: {
                name: 'Cool feature',
                visibility: 'alwaysHidden',
                steps: [/**/]
            },
            coolNewFeature2: {
                name: 'Cool feature2',
                visibility: 'alwaysHidden',
                steps: [/**/],
            }
        }
    },
    plugins: [new PromoPresetsPlugin(),]
   /**/ 
})

const {controller} = createPromoManager({
    ...testOptions,
    config: {
        promoGroups: [
            {
                slug: 'hintPromos',
                conditions: [ShowOnceForSession()], // only 1 promo hint for session
                promos: [
                    {
                        slug: 'coolNewFeature', // slug = onboarding preset name 
                        conditions: [/**/], //  you can add additional conditions
                    },
                ],
            },
        ],
    },
    onboarding: {
        getInstance: () => onboardingController,
        groupSlug: 'hintPromos',
    },
});

版本与发布记录

@gravity-ui/onboarding 共发布 82 个版本,首次发布于 2023/07/21;过去 12 个月发布了 6 个版本。

版本发布日期距今
1.12.4latest2026/10/121 个月前
1.12.32026/10/091 个月前
1.12.22026/10/051 个月前
1.12.12026/07/243 个月前
1.12.02026/04/256 个月前
1.11.72025/12/0311 个月前

关于 @gravity-ui/onboarding 的常见问题

@gravity-ui/onboarding 是什么?

基于登入方案创建提示, 并管理您服务的促销活动 。 与React、任何其他框架或香草JS一起使用.

如何安装 @gravity-ui/onboarding?

在项目目录运行 npm install @gravity-ui/onboarding,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^18.0.0)、react-dom(^18.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gravity-ui/onboarding 支持 TypeScript 吗?

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

@gravity-ui/onboarding 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@gravity-ui/onboarding 可以商用吗?

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

@gravity-ui/onboarding 的下载量有多少?

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

@gravity-ui/onboarding 还在维护吗?

最新版本 1.12.4 发布于 2026/10/12(1 个月前);至今共发布 82 个版本,其中过去 12 个月发布了 6 个;首次发布于 2023/07/21。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。