@guidelytech/guide-runtime

中文文档
0.18.0发布于 2026/11/09MITTypeScriptESM + CJS近 30 天下载 4983

浏览器运行时间: 选择器、 定位、 覆盖和步骤渲染

中文使用文档
文档目录7 节
  1. 选择器
  2. 主机和主题
  3. 渲染
  4. 主计长
  5. 部件
  6. 卫生剂
  7. 撰写

@ guidelytech/ guide- runtime

指南SDK和仪表板编辑器使用的无框架DOM引擎:元素分辨率, 影子DOM主机和主题,阶梯渲染器(浮-地定位),向导控制器, 核对表 / 调查/ 资源中心部件、 允许列表 HTML 消毒器和作者拾取器.

pnpm add @guidelytech/guide-runtime
import { runGuide } from "@guidelytech/guide-runtime";

const controller = runGuide(publishedGuide, {
  theme: config.theme,
  ctx: () => targetingContext,
  onEvent: (e) => console.log(e.name, e.stepId),
  onNavigate: (url) => router.push(url),
});
controller.start();

选择器

导出说明
resolveTarget(target | selectors, root?)调整策略id, (中文(简体) ), data-attr, (中文(简体) ), aria, (中文(简体) ), css, (中文(简体) ), text, (中文(简体) ), xpath; 策略只有在完全匹配一个可见元素时才会获胜.
waitForTarget(target, { timeoutMs, signal, root, pollMs })变异观察员+ 250米投票;以 TargetTimeoutError 编号 : AbortError。 。 。 . timeoutMs: 0 永远等待.
generateSelectors(el)拾取者的强力第一策略:稳定的id(生成的ids如 :r1:, (中文(简体) ), radix-…长数字运行被跳过, data-testid编号 :data-tour编号 :data-*, (中文(简体) ), aria-label, (中文(简体) ), name编号 :role,短而独特的 CSS 路径(nth-of-type 仅在需要时), text 倒扣/链接/标题.
describeElement(el){ selectors, textSnapshot, rect, tag }。 。 。 .
textSnapshotOf(el), (中文(简体) ), isVisible(el), (中文(简体) ), isStableId(id), (中文(简体) ), isGuidelyElement(el), (中文(简体) ), querySelectorStrategy(strategy, root), (中文(简体) ), normalizeText(text), (中文(简体) ), urlMatches(pattern, url)助会者.

主机和主题

ensureHost() 附加单曲 <div id="guidely-root"> 带有全部打开的阴影根 样式( e):host{all:initial})和有礼貌的活区. createScope(theme, appearance) 创建一个 装货箱(--g-primary, (中文(简体) ), --g-bg, (中文(简体) ), --g-text, (中文(简体) ), --g-radius, (中文(简体) ), --g-font, (中文(简体) ), --g-z, (中文(简体) ), --g-overlay· ; data-theme="light|dark", (中文(简体) ), data-anim) (中文(简体) ). auto 如下 prefers-color-scheme· ; prefers-reduced-motion 禁用动画. resolveTheme, (中文(简体) ), applyTheme, (中文(简体) ), destroyHost, (中文(简体) ), DEFAULT_THEME, (中文(简体) ), HOST_ID, (中文(简体) ), STYLES 也被导出.

渲染

renderStep({ scope, step, index, total, target, asModal, onButton, onClose, onOpen }) 制造任何 步骤类型和返回 { el, card, destroy }数字 :

  • modal ——中卡,可选的叠加, role="dialog" aria-modal, Tab 焦点陷阱.
  • tooltip 编号 : popover 以浮井为锚地(offset, (中文(简体) ), flip编号 :autoPlacement, (中文(简体) ), shift, (中文(简体) ), arrow, (中文(简体) ), autoUpdate, (中文(简体) ), role="tooltip", (中文(简体) ), aria-describedby 设定目标.
  • spotlight ——四重覆被绕入目标(目标仍可点击)+环+锚地卡.
  • hotspot ——在目标拐角处脉冲点,点击或徘徊时打开卡.
  • banner 固定上下行, role="status"。 。 。 .
  • slideout - 转角卡. custom ——消毒处理 customHtml 只; 元素为 data-g-action="next|back|dismiss|complete|skip" 作为按钮.

Chrome: 关闭按钮( 退出时) showClose),图像,标题,消毒体,进步 ("2 of 4"),按钮为: variants, 焦点移入卡片并恢复到闭合和屏幕阅读器上 通知,卡片夹住 100vw - 32px40px触摸目标.

anchor(reference, floating, options) 财务报告和审定财务报表 trackRect(el, cb) 揭发定位原始人.

主计长

runGuide(guide, options): GuideController - 选项: theme, (中文(简体) ), ctx, (中文(简体) ), onEvent, (中文(简体) ), onNavigate, (中文(简体) ), onAction (单位:千美元)start_guide 编号 : event 编号 : open_resource_center, (中文(简体) ), onError, (中文(简体) ), onEnd, (中文(简体) ), eventBus (计: advanceOn: "event", (中文(简体) ), startAtStep, (中文(简体) ), currentUrl, (中文(简体) ), container, (中文(简体) ), doc。 。 。 .

主计长: start(), (中文(简体) ), next(), (中文(简体) ), back(), (中文(简体) ), goTo(stepId), (中文(简体) ), dismiss(), (中文(简体) ), complete(), (中文(简体) ), skip(), (中文(简体) ), resume() (重新检查一个步骤等待其URL), destroy(), (中文(简体) ), getState()。 。 。 .

处理 advanceOn (单位:千美元)button, (中文(简体) ), element_click, (中文(简体) ), element_visible, (中文(简体) ), event, (中文(简体) ), delay, (中文(简体) ), any, (中文(简体) ), 分支evaluateRules(branch.when, ctx) ),分级目标,多页 步骤(step.url,目标等待 skip 编号 : show_as_modal 编号 : end_guide 编号 : wait 后退, 发送 guide_viewed, (中文(简体) ), guide_started, (中文(简体) ), step_viewed, (中文(简体) ), step_completed, (中文(简体) ), guide_completed, (中文(简体) ), guide_skipped, (中文(简体) ), guide_dismissed通过试验/渔获物包裹并报告制作情况 onError。 。 。 .

部件

  • renderChecklist({ scope, config, progress, open, onTaskClick, onDismiss, onOpen, onClose }) → { open, close, toggle, isOpen, setProgress, destroy }· ; isChecklistComplete(config, progress)。 。 。 .
  • renderSurvey({ scope, config, title, onSubmit, onDismiss, onChange }) → { getAnswers, showThankYou, destroy }· ; isQuestionVisible(question, answers) 评价 showWhen。 。 。 .
  • renderResourceCenter({ scope, config, guides, search, onStartGuide, onOpenChecklist, onArticleView, onOpen, onClose, hideLauncher }) → { open, close, toggle, isOpen, destroy }。 。 。 .

卫生剂

sanitizeHtml(html), (中文(简体) ), sanitizeToFragment(html), (中文(简体) ), setSanitizedHtml(el, html) - 许可名单 p br strong b em i u a ul ol li img h1-h4 code pre blockquote span div hr button属性 href src alt title target rel class (+ 数) data-g-action编号 :data-g-value页:1 script/style/iframe/object/embed/form/input, (中文(简体) ), on* 处理者, javascript:编号 :data: URL( 除外) data:image/* 打开 img页:1 rel="noopener noreferrer" 打开 target="_blank"。 。 。 .

撰写

  • startAuthoring({ onPick, onExit, dashboardOrigin, message }) → { setStatus, setPicking, stop } 工具栏、悬浮轮廓、捕捉相接点呼叫 onPick({ selectors, textSnapshot, rect, url, element })。 。 。 .
  • previewStep(step, theme, { appearance, onEnd }) → { controller, destroy }。 。 。 .
  • highlightSelectors(selectors, { durationMs }) → { counts, resolved, destroy }。 。 。 .

版本与发布记录

@guidelytech/guide-runtime 共发布 21 个版本,首次发布于 2026/10/18;过去 12 个月发布了 21 个版本。

版本发布日期距今
0.18.0latest2026/11/098 天前
0.17.02026/11/098 天前
0.16.02026/11/0413 天前
0.15.02026/10/3018 天前
0.14.02026/10/2820 天前
0.13.02026/10/2820 天前

关于 @guidelytech/guide-runtime 的常见问题

@guidelytech/guide-runtime 是什么?

浏览器运行时间: 选择器、 定位、 覆盖和步骤渲染

如何安装 @guidelytech/guide-runtime?

在项目目录运行 npm install @guidelytech/guide-runtime,或使用 pnpm add / yarn add / bun add。

@guidelytech/guide-runtime 支持 TypeScript 吗?

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

@guidelytech/guide-runtime 支持 ESM 还是 CommonJS?

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

@guidelytech/guide-runtime 可以商用吗?

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

@guidelytech/guide-runtime 的下载量有多少?

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

@guidelytech/guide-runtime 还在维护吗?

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