# @steppy/angular 中文文档

规范地址：https://npmcn.com/package/%40steppy/angular/

版本：0\.9\.0
npm 元数据更新时间：2026-11-02T13:50:43.340Z
中文译文更新时间：2026-11-02T14:00:49.001Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：101 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：rxjs ^7\.4\.0，@angular/core \>=20\.0\.0 \<23\.0\.0，@steppy/player 0\.9\.0，@angular/common \>=20\.0\.0 \<23\.0\.0，@angular/router \>=20\.0\.0 \<23\.0\.0
- 首次发布：2026-10-22T13:09:36.552Z
- 最新版本发布：2026-11-02T13:50:42.924Z
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

Steppy应用内游览覆盖的Angular适配器：provideSteppyTours()，以及SteppyTours服务

## 安装

```sh
npm install @steppy/angular
```

也可以使用：`pnpm add @steppy/angular`、`yarn add @steppy/angular`、`bun add @steppy/angular`

## README

# @steppy /角

Steppy的应用内导览的Angular适配器：引导弹出窗口 实时应用程序，从您的端到端测试运行的相同Markdown场景编译。 覆盖层本身是 `<steppy-tour-host>` 从 `@steppy/player/tour`;这 package以Angular的方式安装它。

-   `provideSteppyTours({...})`：配置，在 `app.config.ts`.
-   `<steppy-tours />`：叠加，放置 **一次** 在应用程序外壳中。
-   `SteppyTours`：一个根服务to `start()` / `stop()` / `next()` 旅游, 与 `active`， `current` 和 `lastError` 信号和信号 `events` 流。
-   `steppyTourStart`：点击时开始游览的指令。

Angular 20-22, zone.js或无区，ssr安全(没有任何渲染或加载 服务器)。你的应用不需要 `CUSTOM_ELEMENTS_SCHEMA`.

## 安装

```bash
npm install @steppy/angular @steppy/player
```

`@steppy/player` 是与适配器版本相同的对等依赖项。

要使用未发布的构建版本，请从Steppy签出中构建两个版本：

```bash
npm --prefix packages/player ci
npm --prefix packages/player run build
npm --prefix packages/angular ci
npm --prefix packages/angular run build
```

然后，在您的应用程序中，要么依赖于文件夹 （`"@steppy/player": "file:<checkout>/packages/player"`， `"@steppy/angular": "file:<checkout>/packages/angular/dist"`, `"preserveSymlinks": true` 这样Angular就不会被加载两次)， 或者安装tarball `npm pack` 从这两个文件夹中取出。

## 使用

```ts
// app.config.ts
import { inject } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { TranslateService } from '@ngx-translate/core';
import { map } from 'rxjs';
import { provideSteppyTours } from '@steppy/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideSteppyTours({
      // Written by `steppy tours` (an app-assets target in public/tours).
      fallbackManifest: 'tours/tours.manifest.json',
      // Optional: follow your i18n library. Without it the tours follow <html lang>.
      locale: () => {
        const translate = inject(TranslateService);
        return toSignal(translate.onLangChange.pipe(map((e) => e.lang)), { initialValue: translate.getCurrentLang() ?? '' });
      },
    }),
  ],
};
```

```ts
// app.component.ts
@Component({
  selector: 'app-root',
  imports: [RouterOutlet, SteppyToursComponent, SteppyTourStart],
  template: `
    <button steppyTourStart="create-invoice">Show me how</button>
    <router-outlet />
    <steppy-tours (tourComplete)="onDone($event)" />
  `,
})
export class AppComponent {}
```

```ts
// anywhere
const tours = inject(SteppyTours);
await tours.start('send-invoice', { params: { invoiceId: 1001 } });
```

### 适配器为您做了什么

-   **懒惰，只加载浏览器。** 后导入叠加模块 第一次渲染，并且只在浏览器中。
-   **路由器导航。** 从入口路线开始的游览 与导航 `Router.navigateByUrl`，在Angular区域内，所以路由 视图在zone.js应用中渲染。拒绝或重定向的守卫 导航立即使游览失败。`tour-error`,故 `entry-params`） 而不是让它等待一个永远不会渲染的元素。集 `navigate: 'document'` 对于整个页面加载，或传递您自己的函数。
-   **区。** 叠加的观察者、轮询和帧运行在Angular之外 区域，所以他们从不驱动变化检测；事件、输出和路由器 回到里面来。
-   **`start()` 从任何地方。** 它等待 `<steppy-tours>` 去上马 叠加加载(`readyTimeout`（默认为10秒），最后一个调用获胜，并且它 解决了 `false` -从不拒绝-当旅行无法开始时。

破坏 `<steppy-tours>` 暂停巡回演出而不是解散 它（覆盖层保留其恢复记录）。呼叫 `tours.stop()` 首先结束它。

输入在 `<steppy-tours>` 覆盖 `provideSteppyTours()` 设置: `fallbackManifest`， `manifest`， `buildId`， `guideOrigin`， `locale`， `targetTimeout`， `baseZIndex`， `disabled`， `strings`， `source`。输出: `tourStart`， `tourStep`， `tourComplete`， `tourDismiss`， `tourOffpath`， `tourError`.

哈希路由(`withHashLocation()`)不支持应用内导览。

完整的参考-创作之旅，覆盖的选项和事件， 远程模式、CSP和可信类型- is `docs/tours.md` 在草原上 存储库。

## 开发

```bash
npm ci
npm test        # the zoneless suite, then the zone.js suite (ng test --configuration zone)
npm run build   # ng-packagr → dist/; publish dist/, never this folder
```

覆盖层被specs中的假元素所取代(`src/testing/`),除了 在 `real-overlay.spec.ts`。该浏览器针对一个真实的Angular + PrimeNG进行了测试 应用程序是 `tests/integration/test_tour_angular_it.py` (演示是 `fixtures/tour-demo-angular/`）。

## 常见问题

### @steppy/angular 是什么？

Steppy应用内游览覆盖的Angular适配器：provideSteppyTours\(\)，以及SteppyTours服务

### 如何安装 @steppy/angular？

在项目目录运行 npm install @steppy/angular，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：rxjs（^7\.4\.0）、@angular/core（\>=20\.0\.0 \<23\.0\.0）、@steppy/player（0\.9\.0）、@angular/common（\>=20\.0\.0 \<23\.0\.0）、@angular/router（\>=20\.0\.0 \<23\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @steppy/angular 支持 TypeScript 吗？

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

### @steppy/angular 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @steppy/angular 可以商用吗？

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

### @steppy/angular 还在维护吗？

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