企业官网建设流程全解析

如何用信号输入迁移把 Angular 的 @Input 字段转换为 input() API？

【免费下载链接】angularDeliver web apps with confidence 🚀项目地址: https://gitcode.com/GitHub_Trending/an/angular

在一个已经使用@Input装饰器声明输入属性的 Angular 项目中，把现有组件迁移到新的信号输入 API（input()）是一个常见的升级任务。Angular 的信号输入 API 自 v19 起被视为 production ready，官方为这一升级提供了自动迁移 schematic，一条命令即可把@Input字段转换为input()声明，并同步更新所有引用处。本文基于 Angular 仓库中的迁移参考文档 signal-inputs.md 与 schematic 定义，说明完整的迁移操作路径。

前提说明：

• 你的项目是一个 Angular CLI 工作区，其中存在使用@Input声明的组件或指令输入。
• 原有的装饰器@InputAPI 仍然完全受支持，迁移是为了切换到官方推荐的新 API（见 inputs 指南）。

迁移会改动哪些代码

迁移对每个可安全迁移的输入做两件事：

1. @Input()类成员更新为等价的信号input()声明；
2. 对已迁移输入的引用更新为调用信号，包括模板、host bindings 和 TypeScript 代码中的引用。

官方文档给出的示例（Before）：

import {Component, Input} from '@angular/core'; @Component({ template: `Name: {{ name ?? '' }}`, }) export class MyComponent { @Input() name: string | undefined = undefined; someMethod(): number { if (this.name) { return this.name.length; } return -1; } }

迁移后（After）：

import {Component, input} from '@angular/core'; @Component({ template: `Name: {{ name() ?? '' }}`, }) export class MyComponent { readonly name = input<string>(); someMethod(): number { const name = this.name(); if (name) { return name.length; } return -1; } }

注意两点变化：模板中的name变成了name()调用；组件内部对this.name的读取也改成了先取信号值再使用。迁移后的输入是只读的InputSignal，input函数只能在组件和指令的属性初始化器中调用（见 inputs 指南）。

运行迁移命令

在工作区根目录执行：

ng generate @angular/core:signal-input-migration

按 collection.json 的定义，该 schematic 还注册了别名signal-inputs和signal-input，因此ng generate @angular/core:signal-inputs是等价写法。

默认行为（见 schema.json）：

• --path默认为./，即迁移整个 Angular CLI 工作区；
• 迁移尽量安全地重构代码，跳过无法安全迁移的输入。

按需使用四个配置选项

迁移支持若干选项用于针对项目情况做细调（选项说明来自 signal-inputs.md）。

用--path限定迁移目录

默认迁移整个工作区。如果只想升级某一部分代码，可以用--path把迁移范围限定到某个子目录。

用--insert-todos标记被跳过的输入

默认情况下，无法安全迁移的输入会被静默跳过。启用--insert-todos后，迁移会为这些输入添加 TODO 注释，并写明跳过原因，例如：

// TODO: Skipped for migration because: // Your application code writes to the input. This prevents migration. @Input() myInput = false;

文档示例表明，当应用代码会对输入写入值时，该输入默认不会被迁移。这个选项适合迁移后快速定位哪些字段需要人工处理。

用--best-effort-mode激进迁移（有风险）

默认迁移只处理可安全迁移的输入。启用--best-effort-mode后，迁移会尽量多地迁移代码，文档明确警告这可能会破坏你的构建（even if it could break your build）。除非你清楚自己在做什么并准备好事后修复，否则不要默认开启它。

用--analysis-dir缩小分析范围（有风险）

默认情况下，无论--path怎么设置，迁移都会分析整个工作区，以保证更新到所有受影响的引用。在大项目中可以用--analysis-dir把分析范围限定到某个子文件夹。文档同样明确警告：该目录之外的引用会被静默跳过，可能导致构建失败。

两个带风险的选项默认值均为false/ 全工作区（path与analysisDir默认./），与 schema 定义一致。

验证迁移结果

迁移完成后的核对方式与文档给出的信息一致：

1. 检查改动是否符合预期模式：被迁移的输入应从@Input()声明变为readonly xxx = input<...>()，且模板、host bindings 与 TS 代码中的引用变为信号调用，即上一节 Before/After 示例展示的形态。
2. 查看被跳过的输入：如果使用了--insert-todos，在代码中搜索 TODO 注释，确认哪些输入未迁移以及文档记录的原因（如代码对输入有写入）。
3. 构建校验：文档在--best-effort-mode与--analysis-dir两处均以“可能破坏构建”作为风险描述，因此运行项目构建来验证迁移结果，是这两类激进选项下必要的收尾动作；即使使用默认安全模式，构建确认改动无误也是合理的验证手段。

可选替代路径：VSCode 重构操作

如果不想跑整个工作区级别的迁移，可以在 VSCode 中逐字段完成转换（同样来自 signal-inputs.md）：

1. 安装最新版本的 Angular VSCode 扩展；
2. 光标点击一个@Input字段，或点击一个 directive/component；
3. 等待 VSCode 的黄色灯泡重构按钮出现；
4. 通过该按钮选择信号输入迁移操作。

该方式是单点式转换，适合只想迁移个别组件或先做试点的场景；批量升级仍以ng generate命令为主路径。

边界与注意事项

• 默认模式是保守的：无法安全迁移的输入（例如应用代码会对输入写入）会被跳过而不是强行改写，迁移后需要依靠--insert-todos或代码 diff 找出这些字段。
• 信号输入有使用限制：input函数带有编译器特殊语义，只能在组件和指令的属性初始化器中调用。
• 同一 schematic 集合中还包含signal-queries、output等其他迁移（见 collection.json 与 migrations 总览），它们各自是独立的升级任务；本文只覆盖@Input到input()这一条路径，不要把多个迁移混在同一次验证中。

【免费下载链接】angularDeliver web apps with confidence 🚀项目地址: https://gitcode.com/GitHub_Trending/an/angular