Angular API リファレンス
@reelkit/angular のコンポーネント、ディレクティブ、サービス、ユーティリティの完全なリファレンスです。
ReelComponent
セレクター:rk-reel
入力
| 入力 | 型 | デフォルト | 説明 |
|---|---|---|---|
count | number | 必須 | スライドの総数 |
direction | 'vertical' | 'horizontal' | 'vertical' | スクロールの方向 |
size | [number, number] | undefined | undefined | [幅, 高さ] の形での幅と高さ。省略すると ResizeObserver で自動計測します |
initialIndex | number | 0 | 開始時のスライドのインデックス |
loop | boolean | false | 無限ループを有効にします |
transition | TransitionTransformFn | slideTransition | トランジション効果の関数。組み込み:slideTransition、fadeTransition、flipTransition、cubeTransition、zoomTransition |
transitionDuration | number | 300 | アニメーションの長さ(ms) |
swipeDistanceFactor | number | 0.12 | スワイプのしきい値(0-1) |
enableGestures | boolean | true | タッチやマウスのドラッグによる操作を有効にします |
enableNavKeys | boolean | true | キーボードの矢印キーによる操作を有効にします |
enableWheel | boolean | false | マウスホイールでの操作を有効にします |
wheelDebounceMs | number | 200 | ホイールイベントのデバウンス(ms) |
rangeExtractor | (index: number, count: number) => number[] | defaultRangeExtractor | 描画するインデックスを決める独自の関数 |
keyExtractor | (index: number, indexInRange: number) => string | number | index => index | @for の track 式に使う独自のキー関数(ループ時に便利) |
className | string | '' | ルートのコンテナー要素に適用する CSS クラス |
ariaLabel | string | 'Carousel' | カルーセル領域のアクセシブルなラベル |
出力
| 出力 | 型 | 説明 |
|---|---|---|
afterChange | EventEmitter<{ index: number; indexInRange: number }> | スライドのトランジションが完了したあとに発行されます |
beforeChange | EventEmitter<{ index: number; nextIndex: number; indexInRange: number }> | スライドのトランジションが始まる前に発行されます |
slideDragStart | EventEmitter<number> | ドラッグジェスチャーが始まったときに発行されます |
slideDragEnd | EventEmitter<number> | ドラッグジェスチャーが終わった(指を離した)ときに発行されます |
slideDragCanceled | EventEmitter<number> | ドラッグジェスチャーがキャンセルされた(元に戻った)ときに発行されます |
apiReady | EventEmitter<ReelApi> | ビューの初期化後に 1 回だけ発行され、命令的な API を公開します |
ReelApi インターフェース
(apiReady) 出力から取得します:
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 に適用します。
テンプレートのコンテキスト
<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) |
indexInRange | number | 表示ウィンドウ内での位置(0、1、2) |
size | [number, number] | 現在のスライダーの寸法。[幅, 高さ] のピクセル値 |
ReelIndicatorComponent
セレクター:rk-reel-indicator
入力
| 入力 | 型 | デフォルト | 説明 |
|---|---|---|---|
count | number | undefined | 自動 | アイテムの総数。rk-reel の中に置けば親のコンテキストから自動で接続されます。単独で使うときは明示的に渡してください |
active | number | undefined | 自動 | 現在アクティブなインデックス。rk-reel の中に置けば親のコンテキストから自動で接続されます。単独で使うときは明示的に渡してください |
direction | 'vertical' | 'horizontal' | 'vertical' | インジケーターの向き |
radius | number | 3 | ドットの半径(ピクセル) |
visible | number | 5 | 同時に通常サイズで表示するドットの最大数 |
gap | number | 4 | ドットの間隔(ピクセル) |
activeColor | string | '#fff' | アクティブなドットの色 |
inactiveColor | string | 'rgba(255,255,255,0.5)' | 非アクティブなドットの色 |
edgeScale | number | 0.5 | はみ出した端のドットの縮小率 |
className | string | '' | インジケーターのコンテナーに適用する独自の CSS クラス |
tablistLabel | string | 'Slide navigation' | tablist のランドマークのアクセシブルなラベル |
出力
| 出力 | 型 | 説明 |
|---|---|---|
dotClick | EventEmitter<number> | ドットがクリックされたときに発行され、ドットのインデックスを渡します |
RK_REEL_CONTEXT
rk-reel が子孫に提供する InjectionToken<ReelContextValue> です。rk-reel-indicator の自動接続に内部で使われています。スライダーのコンテキストが必要な独自のコンポーネントでインジェクトしてください。
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);
}
}| プロパティ | 型 | 説明 |
|---|---|---|
index | Signal<number> | 現在のスライドのリアクティブなインデックス |
count | Signal<number> | アイテムの総数のリアクティブな値 |
goTo | (index: number, animate?: boolean) => Promise<void> | プログラムからスライドへ移動します |
BodyLockService
参照カウント付きで body のスクロールを止めます。同時に複数の呼び出し元(たとえばギャラリーとモーダルが両方開いている場合)がそれぞれ独立して止めたり解除したりでき、最後の呼び出し元が解除したときにだけ body が元に戻ります。ルートで 提供されているので、どこでもインジェクトできます。
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(); }
}| メンバー | 型 | 説明 |
|---|---|---|
locked | boolean (getter) | body が現在ロックされているかどうか |
lock() | () => void | body のスクロールを止め、スクロールバーの幅を補正します |
unlock() | () => void | body の元のスクロールのスタイルに戻します |
SoundStateService
メディアを再生するオーバーレイのミュート状態と無効状態を、Angular のシグナルとして持ちます。ルートではなくメディアを持つコンポーネントで提供してください。そうすればオーバーレイごとに状態が分かれます。reelkit の Angular オーバーレイはすべてこれを使います。@reelkit/angular-reel-player も同じクラスを再エクスポートしているので、そちらからの既存のインポートはそのまま動きます。
例外は lightbox です。ビデオスライドはあなた自身のテンプレートから描画されるため、オーバーレイの内側のインスタンスは見えません。<rk-lightbox-overlay> の上で提供してください。
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 はスライドに動画がないときや切り替え中に立てます |
controller | SoundController (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 によって更新します |
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 の状態。
| オプション | 型 | デフォルト | 説明 |
|---|---|---|---|
param | string | 必須 | アクティブなスライドを持つクエリパラメーター(たとえば photo)。 |
adapter | UrlAdapter | History API | 読み書きに使うナビゲーションの仕組み。ルーターを使うアプリでは、Router の位置情報が古くならないよう、Router に連動したアダプターを渡してください。 |
codec | UrlCodec<Id> | 必須 | 通信形式:パラメーターの文字列から安定した識別子へ。対として locator と一緒に使います。デフォルトの ?photo=3 のギャラリーなら ...urlIndexKey(() => images().length) を展開し、並べ替えてもブックマークが保たれるようにするなら独自のものを用意します。 |
locator | UrlLocator<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 です。
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 の公開エクスポートの一覧:
// 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';