# @desource/image-angular 中文文档 规范地址：https://npmcn.com/package/%40desource/image-angular/ 版本：0\.5\.0 npm 元数据更新时间：2026-10-31T16:16:27.809Z 中文译文更新时间：2026-11-12T01:36:00.631Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40desource/image-angular 原文对照：https://npmcn.com/package/%40desource/image-angular/?lang=original 项目主页：https://github.com/DeSource-Labs/image#readme 源码仓库：https://github.com/DeSource-Labs/image ## 关键信息（来自 npm 元数据） - 包体积（解压后）：147 kB，10 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：2 个 - peer 依赖：ipx ^3\.1\.1 \|\| ^4\.0\.0-beta\.1，@angular/core ^19\.0\.0 \|\| ^20\.0\.0 \|\| ^21\.0\.0 \|\| ^22\.0\.0，@angular/common ^19\.0\.0 \|\| ^20\.0\.0 \|\| ^21\.0\.0 \|\| ^22\.0\.0 - 首次发布：2026-09-07T12:45:24.780Z - 最新版本发布：2026-10-31T16:16:27.448Z - 近 30 天下载量：17247（2026-10-12 至 2026-11-10，npm 官方下载统计） - 已发布版本数：6（近 12 个月 6 个） ## 中文简介 为Angular提供高质量的图像优化,具有响应输出,部署意识提供者选择,数十个内置提供者模块,以及Angular SSR IPX. ## 安装 ```sh npm install @desource/image-angular ``` 也可以使用：`pnpm add @desource/image-angular`、`yarn add @desource/image-angular`、`bun add @desource/image-angular` ## README # 来源图像 Angular 优化图像 **为Angular提供响应性、供应商第一和SSR友好工作流程的高质量图像优化.** [![npm version](https://img.shields.io/npm/v/@desource/image-angular?color=blue&logo=angular&logoColor=white)](https://www.npmjs.com/package/@desource/image-angular) [![Coverage](https://codecov.io/gh/DeSource-Labs/image/branch/main/graph/badge.svg)](https://codecov.io/gh/DeSource-Labs/image) [![SonarCloud](https://sonarcloud.io/api/project_badges/measure?project=DeSource-Labs_image&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=DeSource-Labs_image) [![Ask Context7](https://img.shields.io/badge/Ask%20Context7-059669.svg?logo=data:image/svg%2bxml;base64,PHN2ZyB3aWR0aD0iMjgiIGhlaWdodD0iMjgiIHZpZXdCb3g9IjAgMCAyOCAyOCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTI0IDBINEMxLjc5MDg2IDAgMCAxLjc5MDg2IDAgNFYyNEMwIDI2LjIwOTEgMS43OTA4NiAyOCA0IDI4SDI0QzI2LjIwOTEgMjggMjggMjYuMjA5MSAyOCAyNFY0QzI4IDEuNzkwODYgMjYuMjA5MSAwIDI0IDBaIiBmaWxsPSIjRjdGMkU4IiBmaWxsLW9wYWNpdHk9IjAuNjUiLz4KPHBhdGggZD0iTTEwLjYgMTUuMjk5MkMxMC42IDE3LjQ5OTIgOS43MDAwNSAxOS4zOTkyIDguMjAwMDUgMjEuMDk5MkgxMS42VjIyLjc5OTJINi4zMDAwNVYyMS4xOTkyQzguMDAwMDUgMTkuMzk5MiA4LjYwMDA1IDE3Ljg5OTIgOC42MDAwNSAxNS4yOTkySDEwLjZaTTE3LjQgMTUuMjk5MkMxNy40IDE3LjQ5OTIgMTguMyAxOS4zOTkyIDE5LjggMjEuMDk5MkgxNi40VjIyLjc5OTJIMjEuN1YyMS4xOTkyQzIwIDE5LjM5OTIgMTkuNCAxNy44OTkyIDE5LjQgMTUuMjk5MkgxNy40Wk0xMC42IDEyLjY5OTJDMTAuNiAxMC40OTkyIDkuNzAwMDUgOC41OTkyMiA4LjIwMDA1IDYuODk5MjJIMTEuNlY1LjE5OTIySDYuMzAwMDVWNi43OTkyMkM4LjAwMDA1IDguNTk5MjIgOC42MDAwNSAxMC4wOTkyIDguNjAwMDUgMTIuNjk5MkgxMC42Wk0xNy40IDEyLjY5OTJDMTcuNCAxMC40OTkyIDE4LjMgOC41OTkyMiAxOS44IDYuODk5MjJIMTYuNFY1LjE5OTIySDIxLjdWNi43OTkyMkMyMCA4LjU5OTIyIDE5LjQgMTAuMDk5MiAxOS40IDEyLjY5OTJIMTcuNFoiIGZpbGw9ImJsYWNrIi8+Cjwvc3ZnPgo=)](https://context7.com/desource-labs/image) [![Ask DeepWiki](https://img.shields.io/badge/Ask%20DeepWiki-1c398e.svg?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0OCA0OCIgZmlsbD0iI2NiY2JjYiIgYXJpYS1oaWRkZW49InRydWUiPjxwYXRoIGQ9Ik0xOC42IDIwLjFxMS0uNiAyLjItLjZoLjNhNCA0IDAgMCAxIDIgLjdoLjJ2LjFsMSAxaC4xdi4yaC4xbC4xLjF2LjFxLjcgMSAuNyAyLjN0LS42IDIuMnYuMWwtLjIuMkE0IDQgMCAwIDEgMjMgMjhoLS4ydi4xbC0xLjQuNGgtLjVxLTEuMyAwLTIuMy0uNWwtNC4xLTIuNC04LjMgNC44djkuNWw4LjMgNC44IDguMi00LjhWMzVxMC0xLjIuNi0yLjJ2LS4xbC4yLS4yYTQgNCAwIDAgMSAxLjctMS41bDEuMy0uNGguNnExLjMgMCAyLjMuNmw0LjIgMi4zIDguMi00Ljd2LTkuNmwtOC4yLTQuNy00LjIgMi4zcS0xIC42LTIuMi42aC0uM2E0IDQgMCAwIDEtMi0uNmwtLjItLjEtMS0xaC0uMXYtLjJoLS4xbC0uMS0uMnYtLjFxLS43LTEtLjctMi4yVjguMmwtOC4yLTQuNy04LjMgNC43djkuNWw4LjIgNC44eiIvPjwvc3ZnPg==)](https://deepwiki.com/DeSource-Labs/image) [![MIT license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/DeSource-Labs/image/blob/main/LICENSE) AI协助开发将想法迅速转移到工作产品. DeSource Image将图像准备保留在该开发回路内. 添加一个合适的本地或远程源,然后用组件输入控制其输出. 保留 `/img/hero.jpg` 而不是导出 `hero-480.webp`, (中文(简体) ), `hero-960.webp`,以及 `hero-1600.webp`。DeSource Image 将一个图像输入到提供者 URL,响应 `srcset`, (中文(简体) ), `` 源,占位符,预装元数据,预设,别名,源验证,以及本地IPX路由. 对于MVP和日常产品开发,图像质量成为了模板编辑. 变动 `quality="80"` 改为 `quality="65"` 并保留相同的源文件、组件和 URL. `@desource/image-angular` 提供独立的组件、本地元素指令、可调用服务以及 `IMAGE_LOADER` 页:1 `NgOptimizedImage`。每个渲染 API 保持原生 `` 财务报告和审定财务报表 `` 最后产出中的元素. 提供者配置是可选的 。 在Vercel,Netlify,或AWS Amplify上,DeSource图像从部署环境中选择平台图像服务. 在其它任何地方,它会倒回内置的IPX路径. 明确提供商总是赢. 该套件支持Angular 19, 20, 21和22. ## 角部为什么有源图像 ? 角质 `NgOptimizedImage` 在对本地人进行性能检查和装入指导方面,仍是一个强有力的内在选择 ``。来源图像添加了本地的部署意识提供者选择 `` 输出,每个图像提供者,以及用于Angular SSR的本地IPX. - **已建成快速产品迭代.** 更改模板中的图像质量、格式、裁剪或响应大小。 源文件和文件名保持不变. - **一个源而不是导出变体.** 从一个合适的图像开始,生成每个屏幕所需的宽度和格式. - **部署意识提供者选择.** 离开 `provider` 打开 `auto`. DeSource Image可探测Vercel,Netlify,或AWS 放大并用于本地环境或其他环境. - **`` 是一个一等的API.** 部件和指令生成命令的AVIF/WebP源并有倒置控制. - **原生框架 API.** 使用独立的组件和本地元素指令. 产出仍属本地 `` 财务报告和审定财务报表 `` 标记. - **数十个内置供应商模块.** 导入一个提供者子路径, 使用完整的注册, 或注册一个输入的自定义提供者 . - **内建局部优化器.** Angular SSR中件可以服务于IPX的转换而无需单独的图像服务. - **`NgOptimizedImage` 还行.** `provideDsImage()` 将来源图像注册为角图像 `IMAGE_LOADER`。 。 。 . ### 如何比较 | 选项 | 最适合 | 如何选择优化 | 选择来源图像时 | | --- | --- | --- | --- | | [`NgOptimizedImage`](https://angular.dev/guide/image-optimization) | 角性能检查、加载提示和响应 `` 产出 | 默认普通加载器; 内置或自定义 `IMAGE_LOADER` 在角配置中选择。 更改主机不会自动选择另一个加载器 . | 您需要部署自动检测 本地IPX 本地 ``,而不是维持 `IMAGE_LOADER`,一个更广泛的提供者目录,或者在Angular之外共享图像配置. | | [无相角](https://unpic.pics/img/angular/) | 在可识别的 CDN 或 CMS URL 上已托管的跨框架响应图像 | 检测每个提供者 `src` URL (中文(简体) ). 本地或未知来源需要倒置或明示提供者;部署本身不是选择信号. | Vercel, Netlify, 或 AWS Amplify 应为每个源选择优化器, 包括相对路径, 您还需要预设, 化名, 源规则, ``,或服务器适配器. | 使用 `NgOptimizedImage` 当它的性能指导 和一个装载器覆盖应用程序。 在优化器跟随部署时选择脱源图像, Angular 需要本地 `` 和本地IPX,或同一提供者政策必须在Angular以外工作. ## 安装 ```sh npm install @desource/image-angular ``` 安装 `ipx` 只有在应用程序服务于本地时 `/_ipx` 转换本身: ```sh npm install ipx ``` 由Vercel,Netlify,Cloudinary,Imgix,Sanity等主机提供商或ImageKit不需要本地优化器. 添加 `@desource/image` 只有在应用程序直接进口核心助手或供应商工厂时,才构成直接依赖. ## 配置角 配置是可选的 。 在没有明确提供者的情况下,共享引擎从构建环境中检测出Vercel,Netlify,或AWS Amplify,并倒回IPX. 注册默认在 `app.config.ts`数字 : ```ts import { ApplicationConfig } from '@angular/core'; import { provideDsImage } from '@desource/image-angular'; export const appConfig: ApplicationConfig = { providers: [ provideDsImage({ quality: 80, screens: { sm: 640, md: 768, lg: 1024 }, domains: ['images.example.com'] }) ] }; ``` `provideDsImage()` 也登记角星 `IMAGE_LOADER`,所以同样的配置可以驱动 `NgOptimizedImage`数字 : ```ts import { NgOptimizedImage } from '@angular/common'; import { Component } from '@angular/core'; @Component({ standalone: true, imports: [NgOptimizedImage], template: `Mountain lake` }) export class HeroComponent {} ``` ## Dsimage 组件 ```ts import { ChangeDetectionStrategy, Component } from '@angular/core'; import { DsImageComponent } from '@desource/image-angular'; @Component({ selector: 'app-hero', standalone: true, imports: [DsImageComponent], changeDetection: ChangeDetectionStrategy.OnPush, template: ` ` }) export class HeroComponent { onHeroLoad(): void {} onHeroError(): void {} } ``` 主机组件使用 `display: contents`;可见的节点是生成的本地 ``。 。 。 . `alt` 需要时间。 数字和布尔模板属性被强制。 信号输入在源,修饰器,配置,或原生属性改变时会重新计算输出. ## DsPicture 组件 ```ts import { ChangeDetectionStrategy, Component } from '@angular/core'; import { DsPictureComponent } from '@desource/image-angular'; @Component({ standalone: true, imports: [DsPictureComponent], changeDetection: ChangeDetectionStrategy.OnPush, template: ` ` }) export class HeroPictureComponent {} ``` 该部分使本地 `` 命令 `` 元素和倒置 ``。 。 。 . `format="avif,webp"`, (中文(简体) ), `[format]="['avif', 'webp']"`,则 `legacyFormat` 支持别名. ## 本地标记指令 当模板仍为常规时使用指令 `` 或者说 ``数字 : ```ts import { Component } from '@angular/core'; import { DsImageDirective, DsPictureDirective } from '@desource/image-angular'; @Component({ standalone: true, imports: [DsImageDirective, DsPictureDirective], template: ` A coastal village A coastal village at sunset ` }) export class CardComponent { onImageLoad(): void {} onImageError(): void {} } ``` 指令产出的使用 `(dsLoad)` 财务报告和审定财务报表 `(dsError)` 所以他们不会与本地的DOM事件相冲突。 构成部分产出使用情况 `(load)` 财务报告和审定财务报表 `(error)`。 。 。 . A 类 `dsPicture` 元素必须包含一个后退 ``。指令管理生成 `` 倒计时. ## 响应图像 `sizes` 接受正则浏览器字符串、断点短手字符串或对象: ```html ``` ```ts sizes = { sm: '100vw', md: '50vw', lg: 600 }; ``` 核心引擎将候选宽度复制,在需要时将其按供货商支持的大小夹住,并生成确定性 `srcset` 财务报告和审定财务报表 `sizes` 属性. ## 占位符和预装 ```html ``` - `placeholder` 生成一个小的转换图像. - 拖倒控制了宽度、高度、质量和模糊度. - 字符串可以是自定义的URL或数据URL. - 完整图像被预装出屏幕并仅在解码成功后替换占位符. - `placeholderClass` 仅存在于占位符可见时. - `preload` 插入响应 `` 输入文档头. - 相同的预装链接在拆卸时被计算出参考值并被移除. - `priority` 设置急速装入和高优先级。 使用 `preload` 当需要头链接时. SSR和初始水合输出使用相同的属性. ## 土著属性 组成部分直接暴露共同的本土属性,包括: `class`, (中文(简体) ), `style`, (中文(简体) ), `id`, (中文(简体) ), `role`,ARIA标签, `referrerpolicy`, (中文(简体) ), `crossorigin`, (中文(简体) ), `usemap`,以及 `data-testid`。 。 。 . 使用 `nativeAttrs` 用于任意图像属性 : ```html ``` 对于 ``,使用时 `imgAttrs`, (中文(简体) ), `imgClass`,以及 `imgStyle` 倒置图像。 生成属性, 如 `src`, (中文(简体) ), `srcset`,维度,加载,和解码均由指令/组件所拥有,不能不慎被推翻. ## 可调用助手服务 ```ts import { inject } from '@angular/core'; import { DsImageService } from '@desource/image-angular'; const $img = inject(DsImageService).create(); const url = $img('/img/hero.jpg', { width: 800, format: 'webp', quality: 75 }); const attrs = $img.getAttrs({ src: '/img/hero.jpg', alt: 'Hero', width: 800 }); ``` 打电话的帮手也暴露了 `getImage`, (中文(简体) ), `getSizes`, (中文(简体) ), `getMeta`, (中文(简体) ), `getPicture`, (中文(简体) ), `getPreloadLink`,并配置了预设快捷键. ## 供应商和预设 为共同部署路径提供方便: ```ts import { provideDsAwsAmplifyImage, provideDsIpxImage, provideDsVercelImage } from '@desource/image-angular'; provideDsIpxImage(); provideDsVercelImage(); provideDsAwsAmplifyImage(); ``` 从核心包注册内置或自定义提供者 : ```ts import { cloudinaryProvider } from '@desource/image/providers/cloudinary'; import { provideDsImage } from '@desource/image-angular'; provideDsImage({ provider: 'cloudinary', providers: { cloudinary: cloudinaryProvider({ cloudName: 'demo' }) }, presets: { avatar: { width: 96, height: 96, fit: 'cover', quality: 80 } } }); ``` ```html ``` 供应商模块和定制供应商公用事业记录如下: [`@desource/image`](https://github.com/DeSource-Labs/image/tree/main/packages/core)。 。 。 . ## 角 SSR 中的本地IPX 将图像中间软件置于静态文件和角 SSR 处理器之前: ```ts import { createDsImageMiddleware } from '@desource/image-angular/server'; app.use( createDsImageMiddleware({ dirs: [browserDistFolder], domains: ['images.example.com'], maxAge: 60 * 60 * 24 * 30 }) ); ``` 将基于 Sharp 的优化器从 Angular 服务器捆绑出 : ```json { "projects": { "app": { "architect": { "build": { "options": { "externalDependencies": ["@desource/image-angular/server"] } } } } } } ``` 中间软件装入 `ipx` 懒惰,只处理请求 `/_ipx`。从服务器进程解析本地目录。 默认拒绝远程优化; 添加信任 `domains`,或设置 `allowAllDomains: true` 仅供有意公开优化者使用. 主机供应商生成平台URL,应当与该平台的图像配置相配对. 例如,使用有Vercel图像设置的Vercel提供者,而不是使用IPX中间软件. ## 链接 - [仓库](https://github.com/DeSource-Labs/image) - [核心一揽子计划](https://github.com/DeSource-Labs/image/tree/main/packages/core) - [反应软件包](https://github.com/DeSource-Labs/image/tree/main/packages/react) - [Svelte 软件包](https://github.com/DeSource-Labs/image/tree/main/packages/svelte) - [安全政策](https://github.com/DeSource-Labs/image/blob/main/SECURITY.md) ## 许可证 麻省理工学院,2026年 ## 常见问题 ### @desource/image-angular 是什么？ 为Angular提供高质量的图像优化,具有响应输出,部署意识提供者选择,数十个内置提供者模块,以及Angular SSR IPX\. ### 如何安装 @desource/image-angular？ 在项目目录运行 npm install @desource/image-angular，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@angular/core（^19\.0\.0 \|\| ^20\.0\.0 \|\| ^21\.0\.0 \|\| ^22\.0\.0）、@angular/common（^19\.0\.0 \|\| ^20\.0\.0 \|\| ^21\.0\.0 \|\| ^22\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @desource/image-angular 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @desource/image-angular 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @desource/image-angular 可以商用吗？ @desource/image-angular 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @desource/image-angular 的下载量有多少？ 根据 npm 官方下载统计，@desource/image-angular 在 2026/10/12 – 2026/11/10 这 30 天内被下载 17,247 次，日均约 575 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @desource/image-angular 还在维护吗？ 最新版本 0\.5\.0 发布于 2026/11/01（11 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/09/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。