Angular Lightbox

特性

安装

基本用法

把样式和独立组件 RkLightboxOverlayComponent 引入组件的 imports 数组。

模板插槽

四个模板插槽指令让你完全定制浮层界面，无需 fork 组件。每个插槽都会收到带完整类型的上下文对象。

视频支持

视频幻灯片需要通过 rkLightboxSlide 模板插槽和 RkLightboxVideoSlideComponent显式启用。这样设计是为了让只需要图片的画廊不必打包视频播放器。

全屏

使用 fullscreenSignal, requestFullscreen、 exitFullscreen from @reelkit/angular 来观察或切换全屏状态。

URL 状态

RkLightboxUrlOverlayComponent 是一个独立组件，它的打开状态存放在地址栏里。用 createOverlayUrlState 构建控制器，再作为 [controller]传进去：参数指向某张幻灯片时画廊自己打开，参数消失时关闭。链接可以分享，返回键关闭的是画廊而不是离开页面。

请在注入上下文中调用它 —— 字段初始化器或构造函数。它会立即挂载，并通过 DestroyRef释放，因此画廊打开期间组件被销毁也不会留下监听器。完整选项见 Angular API 参考.

• 打开时压入 一条 历史记录。翻页则是 替换 它，因此走 N 步也不会多出记录，退一步永远就是离开画廊。
• 只有从应用内部打开画廊时返回键才会关闭它 —— 因为那次链接压入了一条记录。在新标签页里直接打开的分享链接背后没有历史，浏览器返回会离开站点；这时用 ✕ 按钮或 Escape 就地移除参数并留在页面上。
• 指向不存在幻灯片的参数 —— 过期的书签、手改的值 —— 会从 URL 中移除，而不是继续声称一张打不开的幻灯片。
• 模板插槽用法不变：url 组件自己执行六次插槽查询，并把每个模板转发给画廊，因此 rkLightboxControls 以及它的兄弟指令放在它内部，和放在 rk-lightbox-overlay.
• 带路由的应用请传入基于 Router构建的适配器。绕过 Router 直接写历史会让它的 location 过期，下一次导航就会把参数丢掉。

带路由的应用请传入适配器。 绕过 Router 直接写历史会让它的 location 过期，下一次导航就会把参数丢掉，所以请基于 Router 构建适配器并作为 adapter:

稳定的链接。 索引是按位置的 —— 收藏下来的 ?photo=3 在列表重新排序后就会打开另一张图片。 urlStableIdKey 按每个条目稳定的 id来寻址，扫描当前列表 —— 一次调用就覆盖了常见场景。

传入 hashCodec: base64UrlCodec 即可把 URL 中的 id 做 base64url 编码 —— 这是可逆的混淆，不是加密哈希。

想按别的字段（比如 slug）来寻址，或者用 locateAsync给无限信息流翻页，就自己构建 codec （传输格式）和 locator （查找）：

无限或分页画廊。 locate 是同步的，因此只能回答已经加载过的图片 —— 只加载了 20 张时，指向第 400 张的分享链接就查不到。 locateAsync 是兜底，只有在 locate 未命中时才调用：把需要的页拉进来，再返回该身份最终对应的索引。在它未完成期间，画廊保持关闭，参数也不动，因此深链能熬过这次请求； null 或请求被拒绝则会移除参数。

RkLightboxUrlOverlayComponent 输入

接受 rk-lightbox-overlay 的所有输入，除了 isOpen，它被控制器取代。输出与 closed 和 slideChange相同；关闭由 URL 驱动，因此 closed 只是一个通知，而不是关闭机制本身。

RkLightboxOverlayComponent 输入

RkLightboxOverlayComponent 输出

LightboxItem 接口

模板插槽上下文类型

过渡动画

把任意 TransitionTransformFn 通过 transitionFn 输入传入。只引入你用到的那个过渡，打包器就能把其余的摇掉。省略时默认为 slideTransition 。

内容加载与错误处理

使用 rkLightboxSlide 模板插槽接管渲染时，上下文里有三个生命周期回调可用于上报加载状态。Lightbox会逐张跟踪状态，并据此显示转圈动画或错误图标。内容预加载器会缓存损坏的 URL，因此再次访问失败的幻灯片不会重试。

生命周期回调

在 rkLightboxSlide 中接上回调

自定义加载模板

Use the rkLightboxLoading 指令替换默认的转圈动画。

自定义错误模板

Use the rkLightboxError 指令替换默认的错误图标。

CSS 类名

所有 CSS 类名都是普通类名（没有 scoped），因此可以在 @reelkit/angular-lightbox/styles.css之后加载的样式表里用更高优先级的选择器覆盖它们。若只是改颜色、尺寸和 z-index，请优先使用下面 主题定制 一节。

主题定制

每一个颜色、尺寸、z-index 和过渡都放在 CSS 自定义属性里。在 :root （或Lightbox的任意祖先元素）上覆盖，即可在不改组件源码的情况下换主题。这些变量与 React Lightbox保持一致，因此覆盖样式可以在不同框架绑定之间通用。

把下面这段放进在 @reelkit/angular-lightbox/styles.css.

无障碍

浮层根节点是一个模态对话框（role="dialog", aria-modal="true"). Set the ariaLabel 输入可以改变屏幕阅读器的播报内容，默认是 “Image gallery”。每张幻灯片都带有 role="group", aria-roledescription="slide"，以及 aria-label ，由图片标题加上位置推导而来。

Lightbox打开时捕获焦点，关闭时把焦点还给触发元素。Tab 和 Shift+Tab 在内部的可聚焦元素之间循环；跑出去的焦点（点击外部、程序化聚焦）会被拉回来。实现基于 captureFocusForReturn 和 createFocusTrap from @reelkit/core.