Angular API リファレンス

@reelkit/angular のコンポーネント、ディレクティブ、サービス、ユーティリティの完全なリファレンスです。

ReelComponent

セレクター:rk-reel

入力

入力型デフォルト説明
countnumber必須スライドの総数
direction'vertical' | 'horizontal''vertical'スクロールの方向
size[number, number] | undefinedundefined[幅, 高さ] の形での幅と高さ。省略すると ResizeObserver で自動計測します
initialIndexnumber0開始時のスライドのインデックス
loopbooleanfalse無限ループを有効にします
transitionTransitionTransformFnslideTransitionトランジション効果の関数。組み込み:slideTransition、fadeTransition、flipTransition、cubeTransition、zoomTransition
transitionDurationnumber300アニメーションの長さ(ms)
swipeDistanceFactornumber0.12スワイプのしきい値(0-1)
enableGesturesbooleantrueタッチやマウスのドラッグによる操作を有効にします
enableNavKeysbooleantrueキーボードの矢印キーによる操作を有効にします
enableWheelbooleanfalseマウスホイールでの操作を有効にします
wheelDebounceMsnumber200ホイールイベントのデバウンス(ms)
rangeExtractor(index: number, count: number) => number[]defaultRangeExtractor描画するインデックスを決める独自の関数
keyExtractor(index: number, indexInRange: number) => string | numberindex => index@for の track 式に使う独自のキー関数(ループ時に便利)
classNamestring''ルートのコンテナー要素に適用する CSS クラス
ariaLabelstring'Carousel'カルーセル領域のアクセシブルなラベル

出力

出力型説明
afterChangeEventEmitter<{ index: number; indexInRange: number }>スライドのトランジションが完了したあとに発行されます
beforeChangeEventEmitter<{ index: number; nextIndex: number; indexInRange: number }>スライドのトランジションが始まる前に発行されます
slideDragStartEventEmitter<number>ドラッグジェスチャーが始まったときに発行されます
slideDragEndEventEmitter<number>ドラッグジェスチャーが終わった(指を離した)ときに発行されます
slideDragCanceledEventEmitter<number>ドラッグジェスチャーがキャンセルされた(元に戻った)ときに発行されます
apiReadyEventEmitter<ReelApi>ビューの初期化後に 1 回だけ発行され、命令的な API を公開します

ReelApi インターフェース

(apiReady) 出力から取得します:

typescript
import { type ReelApi } from '@reelkit/angular';

@Component({ ... })
export class AppComponent {
  api: ReelApi | undefined;

  // In template: (apiReady)="api = $event"

  prev()  { this.api?.prev(); }
  next()  { this.api?.next(); }
  jump(i: number) { this.api?.goTo(i, true); }  // animated
}
メソッド型説明
next()() => void次のスライドへ移動します
prev()() => void前のスライドへ移動します
goTo(index, animate?)(number, boolean?) => Promise<void>指定したスライドのインデックスへ移動します
adjust()() => voidスライドの位置を計算し直します(レイアウトが変わったあとに便利)
observe()() => voidキーボードイベントの監視を始めます
unobserve()() => voidキーボードイベントの監視を止めます

RkReelItemDirective

セレクター:[rkReelItem] — rk-reel の中の ng-template に適用します。

テンプレートのコンテキスト

html
<ng-template rkReelItem let-i let-indexInRange="indexInRange" let-size="size">
  <!-- $implicit (let-i)  : number         — absolute slide index -->
  <!-- indexInRange        : number         — position in the visible window (0, 1, or 2) -->
  <!-- size                : [number,number] — [width, height] of the container -->
</ng-template>
変数型説明
$implicit (let-i)numberスライドの絶対インデックス(0 から count-1)
indexInRangenumber表示ウィンドウ内での位置(0、1、2)
size[number, number]現在のスライダーの寸法。[幅, 高さ] のピクセル値

ReelIndicatorComponent

セレクター:rk-reel-indicator

入力

入力型デフォルト説明
countnumber | undefined自動アイテムの総数。rk-reel の中に置けば親のコンテキストから自動で接続されます。単独で使うときは明示的に渡してください
activenumber | undefined自動現在アクティブなインデックス。rk-reel の中に置けば親のコンテキストから自動で接続されます。単独で使うときは明示的に渡してください
direction'vertical' | 'horizontal''vertical'インジケーターの向き
radiusnumber3ドットの半径(ピクセル)
visiblenumber5同時に通常サイズで表示するドットの最大数
gapnumber4ドットの間隔(ピクセル)
activeColorstring'#fff'アクティブなドットの色
inactiveColorstring'rgba(255,255,255,0.5)'非アクティブなドットの色
edgeScalenumber0.5はみ出した端のドットの縮小率
classNamestring''インジケーターのコンテナーに適用する独自の CSS クラス
tablistLabelstring'Slide navigation'tablist のランドマークのアクセシブルなラベル

出力

出力型説明
dotClickEventEmitter<number>ドットがクリックされたときに発行され、ドットのインデックスを渡します

RK_REEL_CONTEXT

rk-reel が子孫に提供する InjectionToken<ReelContextValue> です。rk-reel-indicator の自動接続に内部で使われています。スライダーのコンテキストが必要な独自のコンポーネントでインジェクトしてください。

typescript
import { inject } from '@angular/core';
import { RK_REEL_CONTEXT } from '@reelkit/angular';

@Component({ ... })
export class MyCustomControl {
  private readonly ctx = inject(RK_REEL_CONTEXT, { optional: true });

  jump(index: number) {
    this.ctx?.goTo(index, true);
  }
}
プロパティ型説明
indexSignal<number>現在のスライドのリアクティブなインデックス
countSignal<number>アイテムの総数のリアクティブな値
goTo(index: number, animate?: boolean) => Promise<void>プログラムからスライドへ移動します

BodyLockService

参照カウント付きで body のスクロールを止めます。同時に複数の呼び出し元(たとえばギャラリーとモーダルが両方開いている場合)がそれぞれ独立して止めたり解除したりでき、最後の呼び出し元が解除したときにだけ body が元に戻ります。ルートで提供されているので、どこでもインジェクトできます。

typescript
import { inject } from '@angular/core';
import { BodyLockService } from '@reelkit/angular';

@Component({ ... })
export class OverlayComponent {
  private readonly bodyLock = inject(BodyLockService);

  open() { this.bodyLock.lock(); }
  close() { this.bodyLock.unlock(); }
}
メンバー型説明
lockedboolean (getter)body が現在ロックされているかどうか
lock()() => voidbody のスクロールを止め、スクロールバーの幅を補正します
unlock()() => voidbody の元のスクロールのスタイルに戻します

SoundStateService

メディアを再生するオーバーレイのミュート状態と無効状態を、Angular のシグナルとして持ちます。ルートではなくメディアを持つコンポーネントで提供してください。そうすればオーバーレイごとに状態が分かれます。reelkit の Angular オーバーレイはすべてこれを使います。@reelkit/angular-reel-player も同じクラスを再エクスポートしているので、そちらからの既存のインポートはそのまま動きます。

例外は lightbox です。ビデオスライドはあなた自身のテンプレートから描画されるため、オーバーレイの内側のインスタンスは見えません。<rk-lightbox-overlay> の上で提供してください。

typescript
import { inject } from '@angular/core';
import { SoundStateService } from '@reelkit/angular';

@Component({
  // Provide it on the component that owns the media, so two overlays
  // on one page never share a muted state.
  providers: [SoundStateService],
  // ...
})
export class OverlayComponent {
  readonly soundState = inject(SoundStateService);

  // Use in template:
  // [muted]="soundState.muted()"
  // [hidden]="soundState.disabled()"
  // (click)="soundState.toggle()"
}
メンバー型説明
muted()Signal<boolean>現在ミュートかどうか。最初はミュートです
disabled()Signal<boolean>音を操作できない間は true になり、サウンドボタンが隠れます。値を立てるのはオーバーレイ側で、RkReelPlayerOverlayComponent はスライドに動画がないときや切り替え中に立てます
controllerSoundController (getter)下地になっている core の SoundController。syncMutedToVideo に渡すと <video> がミュート状態に追従します
toggle()() => voidミュートを切り替えます
setDisabled()(value: boolean) => voidいま音を操作できるかどうかを設定します
reset()() => void最初の状態に戻します。ミュートで、操作は可能です

シグナルブリッジのユーティリティ

コアのシグナルシステム(@reelkit/core)と Angular ネイティブのシグナル API をつなぐユーティリティ関数です。ReelComponent が内部で使っており、独自のフレームワーク連携にも使えます。

関数シグネチャ説明
toAngularSignal(source: Subscribable<T>, destroyRef: DestroyRef) => Signal<T>コアの Subscribable を、読み取り専用の Angular の Signal につなぎます
animatedSignalBridge(source: AnimatedValue, zone: NgZone, cdRef: ChangeDetectorRef, destroyRef: DestroyRef) => Signal<number>コアのアニメーションする値を Angular の Signal につなぎ、zone の外で requestAnimationFrame によって更新します
typescript
import { DestroyRef, inject } from '@angular/core';
import { toAngularSignal } from '@reelkit/angular';
import { createSliderController } from '@reelkit/core';

// Custom component using low-level signal bridge
const destroyRef = inject(DestroyRef);
const controller = createSliderController({ count: 10 }, {});
const index = toAngularSignal(controller.state.index, destroyRef);

createOverlayUrlState

OverlayUrlStateOptions

オーバーレイ用の URL 状態コントローラーを作ります。それを <rk-lightbox-url-overlay> の [controller] 入力に渡します。インジェクションコンテキスト(フィールドの初期化子かコンストラクター)の中で呼んでください。すぐに接続し、DestroyRef で解放されます。手順:Angular Lightbox のページの URL の状態。

オプション型デフォルト説明
paramstring必須アクティブなスライドを持つクエリパラメーター(たとえば photo)。
adapterUrlAdapterHistory API読み書きに使うナビゲーションの仕組み。ルーターを使うアプリでは、Router の位置情報が古くならないよう、Router に連動したアダプターを渡してください。
codecUrlCodec<Id>必須通信形式:パラメーターの文字列から安定した識別子へ。対として locator と一緒に使います。デフォルトの ?photo=3 のギャラリーなら ...urlIndexKey(() => images().length) を展開し、並べ替えてもブックマークが保たれるようにするなら独自のものを用意します。
locatorUrlLocator<Id>必須識別子を位置に対応させ、その妥当性を自分で判断します:locate(同期)、locateAsync(ページングされたギャラリー向けの非同期フォールバック)、identify(書き込み)。

createRouterUrlAdapter

@reelkit/angular/ng-router-url-adapter

Angular の Router に連動した UrlAdapter です。ルーターを使うアプリで createOverlayUrlState の adapter オプションに渡すと、ナビゲーションの信頼できる情報源が Router だけに保たれます。Router の裏で history.pushState を書くと、その位置情報が古くなり、次のナビゲーションでパラメーターが消えます。書き込むのはクエリだけなので、パス、フラグメント、?tag=a&tag=b のような繰り返しのキーはそのまま残ります。変更のたびに、Router が同じページで push したのか、replace したのか、履歴をたどったのかを報告するので、routerLink から開いたギャラリーは 1 回戻るだけで閉じます。インジェクションコンテキストの中で呼んでください。ルーターの購読は DestroyRef で解放されます。

独自のサブパスから提供されるので、ルーティングを使わないアプリのバンドルに @angular/router が入ることはありません。@angular/router は任意の peer dependency です。

typescript
import { createRouterUrlAdapter } from '@reelkit/angular/ng-router-url-adapter';

protected readonly photo = createOverlayUrlState({
  param: 'photo',
  adapter: createRouterUrlAdapter(),
  ...urlIndexKey(() => this.images().length),
});

アクセシビリティ

<rk-reel> は aria-roledescription="carousel" を持つ role="region" として描画されます。ariaLabel 入力を指定すると、スクリーンリーダー向けの名前が付きます。控えめなライブリージョンが、スライドが変わるたびに「Slide N of M」と読み上げます。非アクティブなスライドには inert 属性が付くので、フォーカスや支援技術での移動では飛ばされます。

<rk-reel-indicator> は、ドットにローミング tabindex を持つ role="tablist" として描画されます。矢印キーでフォーカスが移動し、Enter か Space でスライドが有効になります。

<rk-reel> を囲む独自のモーダルを作るなら、フォーカスを戻したり閉じ込めたりするために captureFocusForReturn、createFocusTrap、getFocusableElements が @reelkit/angular から再エクスポートされています。

パッケージのエクスポート

@reelkit/angular の公開エクスポートの一覧:

typescript
// Components & directives
import {
  ReelComponent,
  ReelIndicatorComponent,
  RkReelItemDirective,
  RkSwipeToCloseDirective,
} from '@reelkit/angular';

// Types
import type {
  ReelApi,
  ReelContextValue,
  RkReelItemContext,
  CoreSignal,
  Subscribable,
  AnimatedValue,
  RangeExtractor,
  SliderDirection,
  Disposer,
  DisposableList,
  GestureController,
  SliderController,
  ContentLoadingController,
  ContentPreloader,
  ContentPreloaderConfig,
  SoundController,
  BodyLock,
  TransitionTransformFn,
  SlideTransformStyle,
  SwipeToCloseDirection,
} from '@reelkit/angular';

// Context
import { RK_REEL_CONTEXT } from '@reelkit/angular';

// Services
import { BodyLockService, SoundStateService } from '@reelkit/angular';

// Signal bridges
import { toAngularSignal, animatedSignalBridge } from '@reelkit/angular';

// Core re-exports
import {
  // Signals & reactivity
  createSignal, createComputed, reaction, batch,

  // Transitions
  slideTransition, fadeTransition, flipTransition,
  cubeTransition, zoomTransition, getSlideProgress,

  // Content loading & preloading
  createContentLoadingController, createContentPreloader,

  // Sound
  createSoundController, syncMutedToVideo,

  // Fullscreen
  fullscreenSignal, requestFullscreen, exitFullscreen,

  // DOM & cleanup
  observeDomEvent, createDisposableList, createBodyLock, sharedBodyLock,

  // Size detection
  observeElementSize, getViewportSize, observeViewportSize,
  isMobileWidth, fitAspectRatio, isTouchDevice,

  // Autoplay & download
  createTimerController, createSlideshowController, downloadFile,

  // Focus management
  captureFocusForReturn, createFocusTrap, getFocusableElements,

  // Slider & gestures
  createSliderController, createGestureController,
  defaultRangeExtractor, createDefaultKeyExtractorForLoop,

  // Video
  captureFrame, createSharedVideo,

  // Utilities
  animate, noop, clamp, abs, first, last, extractRange,
} from '@reelkit/angular';