# @ecl/gallery 中文文档

规范地址：https://npmcn.com/package/%40ecl/gallery/

版本：5\.4\.1
npm 元数据更新时间：2026-11-10T09:35:01.620Z
中文译文更新时间：2026-11-13T05:26:18.712Z
软件包许可：EUPL-1\.2

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

原始 npm 页面：https://www.npmjs.com/package/%40ecl/gallery
原文对照：https://npmcn.com/package/%40ecl/gallery/?lang=original
项目主页：https://github.com/ec-europa/europa-component-library
源码仓库：https://github.com/ec-europa/europa-component-library

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

- 包体积（解压后）：94.3 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：7 个
- 首次发布：2025-01-22T12:08:59.832Z
- 最新版本发布：2026-11-10T09:35:00.626Z
- 近 30 天下载量：3603（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：45（近 12 个月 24 个）

## 中文简介

ECL 图片库

## 安装

```sh
npm install @ecl/gallery
```

也可以使用：`pnpm add @ecl/gallery`、`yarn add @ecl/gallery`、`bun add @ecl/gallery`

## README

# ECL 图片库

npm 软件包 : `@ecl/gallery`

```shell
npm install --save @ecl/gallery
```

### 参数

-   **格丽德** (boolean) (默认: 假) 显示相册为网格
-   **"网格 温度"** (int) (默认: 0) 拟使用的模板 Id. 只显示网格
-   **"栏"** (int) (默认:3)列数. 只显示网格
-   **"论"** (字符串) (默认:"3-2") 图像宽比. 只显示网格
-   **"画面"** (boolean) (默认:虚假) 缩略图应该有缩放动画吗?
-   **编号** (字符串)(默认:随机) 画廊独有的代号
-   **"重叠"** (对象) (默认: )
    -   “ 关闭”( 对象)( 默认 : q): 类型按钮的对象
    -   “ 先前” (对象)( 默认 : q): 类型按钮的对象
    -   "next"(对象)(默认:qq):类型按钮的对象
    -   “反分隔符”(字符串)(默认为:')
    -   “ full screen label” (字符串)(默认:')
    -   "下载"(对象)(默认:qq):类型链接的对象
    -   "共享"(对象)(默认:qq):类型链接的对象
    -   “ 已公布 标签” (字符串)(默认: “ ” ): 发布日期标签
    -   “ sr overlay label” (字符串)(默认为 : “ ”) 覆盖的 aria- 标签
-   **“项目”** (阵列) (默认: \[\])
    -   "标题"(字符串)(默认:")
    -   “ title always visible” (布尔语)(默认:虚假)
    -   "描述"(字符串)(默认:")
    -   "meta" (字符串)(默认:")
    -   “ icon”( 对象)( 默认 : q): 类型图标的对象
    -   "thumbnail"(对象)(默认:-) 缩略图, 遵循 ECL 图片结构; 如果为空, 倒回“ 图片 ”
    -   "图片"(对象)(默认:QQ) 全尺寸图片, 遵循ECL 图片结构; 总是需要, 甚至对于视频项目
    -   "video"(对象)(默认:QQ) 视频项目的视频对象
    -   "嵌入式 video"(对象)(默认: ) 嵌入式视频对象( 基于框架)
    -   "sr video audio" (字符串)(默认为:"'):用于显示是否有音频描述的额外文本;用于屏幕阅读器
    -   覆盖中共享按钮的“ share path” (字符串)(默认为 : “ ”) URL
    -   "公示 日期"(字符串)(默认:")
    -   "video 长" (字符串)(默认:")
-   **“ 可见项目”** (整数) (默认: 8) 可扩展画廊中的可见项数
-   **"扩张"** (boolean) (默认:真实)可折叠/可扩展相册
-   **"sr gallery label" (英语)** (字符串) (默认:"'"):为画廊添加标签,提供指示;为屏幕阅读器
-   **"sr video label" (中文(简体) )** (字符串) (默认:"'"):视频项目的附加标签;屏幕阅读器
-   **"sr video player" (英语)** (字符串) (默认:''):视频播放器的额外标签;屏幕阅读器
-   **"脚"** (对象) (默认: ) 页脚链接
-   **“视图 全 标签”** (字符串) (默认为: “ ” ) 视图的所有按钮标签
-   **“视图 全部 扩展 标签”** (字符串)(默认为:") 展廊被扩展时的标签
-   **“反标签”** (字符串)(默认:") 计数器的标签
-   **"残疾"** (boolean) (默认:虚假) 关闭悬停时的标题显示
-   **"残疾 重叠"** (boolean) (默认:虚假) 禁用覆盖功能
-   **"满" "活"** (boolean) (默认:虚假) 桌面和平板电脑视图的全宽画廊
-   **"所选项目 d"** (int)(默认:0)
-   **"超级"** (字符串)(默认为:") 额外类(空格分隔)
-   **“外部属性”** (阵列) (默认: \[\]) 额外属性
    -   名称 (字符串) 属性名称, 如“ 数据测试 ”
    -   值 (字符串) 属性值, 如 : “ data- test-1 ”

### 示例:

```twig
{% include '@ecl/gallery/gallery.html.twig' with {  
  id: 'my-gallery',
  view_all_label: 'View all', 
  counter_label: 'Media files in this gallery' , 
  visible_items: 6,
  disable_overlay: false,
  sr_video_label: 'Video',
  sr_video_player: 'Video player',
  items: [ 
    { 
      thumbnail: {
        img: {
          src: 'path/to/thumbnail.jpg', 
          alt: 'Image 1',
        },
      }, 
      picture: {
        img: {
          src: 'path/to/image.jpg', 
          alt: 'Image 1',
        },
      }, 
      title: 'The EU in brief',
      description: 
        'The EU in brief, institutions and bodies, countries, symbols, history, facts and figures', 
      meta: 'Copyright, Author, Licence for image 1', 
      share_href: '/share#example-image.jpg', 
    }, 
    { 
      picture: {
        img: {
          src: 'path/to/image2.jpg', 
          alt: 'Image 2',
        },
      }, 
      title: 'Living in the EU',
      description: 'Living, working, travelling in the EU', 
      meta: 'Copyright, Author, Licence for image 2', 
      share_href: '/share#example-image2.jpg', 
    }, 
    ... 
  ], 
  footer: { 
    link: { 
      label: "Link to further media items", 
      path: "/example", 
      aria_label: "View all link aria-label value" 
    }, 
    icon: { 
      name: "external", 
      size: "s" 
    } 
  },
  overlay: { 
    published_label: 'Published',
    close: { 
      variant: 'ghost', 
      label: 'Close', 
    }, 
    previous: { 
      variant: 'ghost', 
      label: 'Previous', 
      icon_position: 'before', 
    }, 
    next: { 
      variant: 'ghost', 
      label: 'Next', 
    }, 
    counter_separator: 'of', 
    full_screen_label: 'View original',
    share: { 
      label: 'Share', 
      icon: { 
        name: 'share-network',
        family: 'phosphor',
        size: 'fluid', 
      }, 
    }, 
  }, 
} %}
```

## 常见问题

### @ecl/gallery 是什么？

ECL 图片库

### 如何安装 @ecl/gallery？

在项目目录运行 npm install @ecl/gallery，或使用 pnpm add / yarn add / bun add。

### @ecl/gallery 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/ecl\_\_gallery 是否存在。

### @ecl/gallery 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ecl/gallery 可以商用吗？

@ecl/gallery 使用 EUPL-1\.2 许可。声明的许可为 EUPL-1\.2，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @ecl/gallery 的下载量有多少？

根据 npm 官方下载统计，@ecl/gallery 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,603 次，日均约 120 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ecl/gallery 还在维护吗？

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