Skip to main content

快速开始与集成

本节介绍如何在业务项目中集成 @rydeen/angular-framework，并给出一个从 传统 HttpClient 调用 迁移到 基于 AbstractService/AbstractAppPage 的架构化开发 的简单示例。

环境与安装​

  • Angular 版本：推荐 ≥ 16，本工程示例基于 Angular 20
  • 包管理器：pnpm / yarn / npm 均可
pnpm add @rydeen/angular-framework
# 或
npm install @rydeen/angular-framework

框架依赖 @ngx-translate/core 以及 Angular Router / HttpClient / Material（用作示例 UI），请确保已经在项目中按常规方式配置。

在应用中引入​

在基于 standalone 组件的项目中，一般只需要在根模块或 AppConfig 中引入 HttpClient、路由与国际化模块，@rydeen/angular-framework 通过 抽象基类与服务 的方式集成，不需要额外的 Angular Module。

// 示例：main.ts / app.config.ts 中按常规方式配置 HttpClient / TranslateModule
import {provideHttpClient, withInterceptors} from '@angular/common/http';
import {TranslateLoader, TranslateModule} from '@ngx-translate/core';
import {mockInterceptor} from '@rydeen/angular-framework'; // 可选：内置 Mock 拦截器

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withInterceptors([mockInterceptor])),
    provideAnimations(),
    // 省略其它 provider ...
  ],
};

第一个服务：继承 AbstractService​

传统方式中，一个业务 Service 往往直接注入 HttpClient，自己管理：

  • 请求 URL 拼接
  • 请求头与 Token
  • 防重复提交
  • 错误码与国际化文案

在本框架中，这些能力被收敛到 AbstractService 中：

// users.service.ts（示例）
import {Injectable} from '@angular/core';
import {AbstractService, ResultVO, Url} from '@rydeen/angular-framework';
import {AppUrl} from '../core/constants/app.url';
import {User} from './types/users.types';

@Injectable({ providedIn: 'root' })
export class UserService extends AbstractService {
  async listUsers(): Promise<ResultVO<User[]>> {
    // AppUrl.Users.List 为一个 Url 枚举实例，内部封装 path 与 Method
    return await this.request<User[]>(AppUrl.Users.List);
  }

  async createUser(payload: User): Promise<ResultVO<void>> {
    return await this.request<void>(AppUrl.Users.Create, payload);
  }
}

相比直接使用 HttpClient，你不再需要：

  • 手动拼接 baseUrl 与路径
  • 处理 ResultVO 外壳结构
  • 管理设备指纹、签名与重复提交窗口

这些逻辑都在 AbstractService 内部统一实现。

第一个页面：继承 AbstractAppPage​

在示例应用 cross-platform-app 中，所有页面都继承自 AbstractAppPage，而后者又继承自框架层的 AbstractComponent：

// users.ts（简化示例）
import {Component} from '@angular/core';
import {AbstractAppPage} from '../shared/abstracts/abstract.app.page';
import {UserService} from './services/user.service';

@Component({
  selector: 'app-users',
  templateUrl: './users.html',
  styleUrls: ['./users.scss'],
})
export class UsersPage extends AbstractAppPage {
  constructor(private readonly userService: UserService) {
    super();
  }

  async ngOnInit() {
    this.registerHandler('users.queryBtn', async () => {
      const result = await this.userService.listUsers();
      // 处理结果 ...
    });
  }
}

模板中只需统一绑定 UI 事件，并通过 data-id 标记组件：

<!-- users.html（片段） -->
<button
  mat-raised-button
  color="primary"
  data-id="users.queryBtn"
  (click)="onClick($event)">
  查询用户
</button>

如此，页面只关注 「事件 key → 业务处理函数」 的映射，而不关心具体 DOM 结构，实现了：

  • 一致的 UI 事件分发（onClick/onChange/onSubmit）
  • 更清晰的测试与重构边界

接下来，你可以继续阅读「架构设计」与「框架核心组件」章节，了解 AbstractService、AbstractAppPage、事件总线与锁工具等能力。