# @guidelytech/guide-runtime 中文文档

规范地址：https://npmcn.com/package/%40guidelytech/guide-runtime/

版本：0\.18\.0
npm 元数据更新时间：2026-11-09T02:02:13.917Z
中文译文更新时间：2026-11-17T08:19:29.701Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40guidelytech/guide-runtime
原文对照：https://npmcn.com/package/%40guidelytech/guide-runtime/?lang=original
项目主页：https://github.com/GuidelyTech/Guidely/tree/main/packages/guide-runtime#readme
源码仓库：https://github.com/GuidelyTech/Guidely

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

- 包体积（解压后）：2.2 MB，39 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-10-17T21:03:02.033Z
- 最新版本发布：2026-11-09T02:02:13.743Z
- 近 30 天下载量：4983（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

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

## 安装

```sh
npm install @guidelytech/guide-runtime
```

也可以使用：`pnpm add @guidelytech/guide-runtime`、`yarn add @guidelytech/guide-runtime`、`bun add @guidelytech/guide-runtime`

## README

# @ guidelytech/ guide- runtime

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

```bash
pnpm add @guidelytech/guide-runtime
```

```ts
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"),按钮为: `variant`s, 焦点移入卡片并恢复到闭合和屏幕阅读器上 通知,卡片夹住 `100vw - 32px`40px触摸目标.

`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 是什么？

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

### 如何安装 @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 和提交记录判断。

