Angular 署名フィールド | ng-hub-ui-signature
マウス、タッチ、ペン入力をスケーラブルな SVG フォーム値として保存する、アクセシブルな Angular 署名フィールド。取り消し、やり直し、PNG エクスポートに対応します。
API リファレンス
signature の完全な仕様をここにまとめました。バインド、リッスン、プロジェクション、テーマ設定ができるすべてが一か所に集約されています。必要なものを接続し、好きなようにスタイリングしてください — standalone で signal フレンドリーです。
インプット
18 個のインプットで signature を調整。通常の Angular @Input と同じようにバインドできます。
| 名前 | 型 | デフォルト | 説明 |
|---|---|---|---|
label | string | '' | 表示されるフィールドラベル。描画面のアクセシブルな名前でもあります。キャンバスは aria-labelledby でラベルに結び付けられているため、読み上げられる名前が表示テキストとずれることはありません。ラベルをクリックすると描画面にフォーカスが移ります。 |
formText | string | '' | フィールドのヘルパーテキスト。どこに表示されるかは [formTextType] が決めます。既定では描画面の下、またはラベル行の末尾にある疑問符の奥です。投影された <ng-template hubFormText> は下側のブロックの文字列を置き換え、tooltip モードでもそのブロックに残ります。tooltip は文字列しか受け取れず、マークアップが失われるためです。 |
formTextType | 'bottom' | 'tooltip' | 'bottom' | [formText] を表示する場所。bottom は描画面の下に置き、求められなくても読めるようにします。tooltip は 1 文を超える内容向けに、ラベル行の末尾にある疑問符の奥に置きます。ヘルパーテキストがあるときは常に疑問符が描画され、[ariaLabel] だけで名前を付けた素の描画面でも同様です。その吹き出しは <body> に追加されるため、tooltip モードでは ng-hub-ui-utils のツールチップ用スタイルシートも必要です。 |
height | number | 160 | キャンバスの論理的な高さ(CSS ピクセル)。 |
strokeColor | string | 'currentColor' | 新しい SVG ストロークに記録される色。既定の currentColor はストロークを取り込む前に描画面を基準に解決されるため、アーカイブにはキャンバスが解析できないキーワードではなく具体的な色が保存されます。 |
strokeWidth | number | 2 | 新しい SVG ストロークに記録される基本の太さ。 |
readonly | boolean | false | 署名を保持したまま、描画を禁止します。 |
controls | boolean | true | クリア、元に戻す、やり直しのアクションを表示します。 |
labels | Partial<HubSignatureLabels> | {} | アプリケーション全体の翻訳済みアクションラベルを、このフィールドに限って上書きします。 |
ariaLabel | string | '' | 表示される [label] がない描画面のアクセシブルな名前。ラベルを持つフィールドは aria-labelledby によってそのラベルから名前を得るため、両者が食い違うことはなく、その場合この入力は参照されません。空のままにすると [labels]、次に HUBUI.SIGNATURE.ARIA_LABEL、最後に英語のフォールバック Signature の順で解決されます。 |
labelType | HubLabelType | 'stacked' | ラベルをフィールドに対してどう配置するか: 'stacked' または 'horizontal'。'floating' は、ファミリー内のほかのテキスト以外のフィールドと同様に stacked にフォールバックします。フローティングラベルは空のテキストコントロールの値が占める場所を再利用し、:placeholder-shown で駆動されますが、キャンバスにはそのどちらもありません。 |
classlist | string | '' | ホスト要素 <hub-signature> 自体に適用される追加のクラス。描画面には適用されず、描画面は自身の .hub-signature__canvas を保持します。キャンバスのスタイルは子孫セレクターで指定するか、--hub-signature-* スロットでテーマ設定してください。 |
formControlName | string | — | 周囲のフォームグループ内のコントロール名。HubFormControl から継承されます。HubFormControl 自身がこれを入力として宣言しているため、フィールドを使う場所では ReactiveFormsModule を引き続きインポートする必要があります。ディレクティブがなくてもエラーは発生せず、フィールドがフォームと同期されないだけです。 |
required | boolean | null | null | 必須のアスタリスクを描画し、描画面に aria-required を設定します。双方向です。リアクティブなバインディングでは、コントロールのバリデーターから導出されてそれと同期され続けるため、そこで手動でバインドすると上書きされ、開発モードでは警告が出ます。明示的に設定するのは、テンプレート駆動またはバインドなしのフィールドだけにしてください。 |
disabled | boolean | false | 描画を拒否し、アクション行を無効にして aria-disabled を設定します。双方向で、setDisabledState() によっても書き込まれます。formControlName のフィールドでは control.disable() / control.enable() を使うのが望ましいです。Angular 自身のディレクティブも disabled 入力を宣言しているため、バインディングは両方に届き、1 つの状態に対して 2 つの情報源が生まれてしまいます。 |
showValid | boolean | false | オプトインの成功状態。touched かつ有効なフィールドは、描画面に成功の境界線とリングを適用し、[validFeedback] が指定されていればそれを描画します。既定値はグローバルな provideHubForms({ showValid }) に従い、成功状態は決して自動では表示されません。フィールドが無効の間は効果がありません。 |
validFeedback | string | null | null | フィールドの下に表示される成功メッセージ。オプトインの両方の条件が必要です。[showValid] がオンで、コントロールが touched かつ有効であることです。 |
invalidFeedbackTemplateFn | ((key: string, value: any) => string) | null | null | 無効時のフィードバックメッセージビルダーをフィールドごとに上書きします。グローバルな provideHubForms() のものより優先されます。文字列ではなくマークアップが必要な場合は、代わりに <ng-template hubValidationError key="required"> を投影してください。テンプレートはどちらよりも優先されます。 |
アウトプット
signature の動作に反応 — ロジックを接続できる 5 個のイベント。
| 名前 | 型 | 説明 |
|---|---|---|
valueChange | OutputEmitterRef<string> | ユーザー操作による変更(確定したストローク、clear()、undo()、redo())の後に SVG 値を発行し、何も残っていなければ空文字列を発行します。writeValue() や fromStrokes() によるプログラムからの書き込みでは何も発行されないため、フォームの値が自分自身にエコーバックされることはありません。 |
drawStart | OutputEmitterRef<HubSignatureDrawEvent> | ユーザーがポインターまたはキーボードでストロークを開始したときに発行されます。値をポーリングしなくても、自動保存の一時停止や送信ボタンの有効化など、描画の動きにホストが反応できます。HubSignatureDrawEvent は PointerEvent | KeyboardEvent です。入力デバイスが重要な場合は instanceof で絞り込んでください。 |
drawEnd | OutputEmitterRef<HubSignatureDrawEvent> | ユーザーがストロークを終え、確定した後に発行されます。ユーザーの描画に対してのみ発火するため、プログラムからの書き込みが描画に見えることはなく、完了ではなくキャンセルされたストローク(pointercancel、Escape、フォーカスが描画面から外れた場合)では何も発行されません。 |
disabledChange | OutputEmitterRef<boolean> | 双方向 [(disabled)] の書き込み側。Angular が setDisabledState() を呼び出したとき、つまりバインドされたコントロールが無効化または有効化されたときにも発火するため、リアクティブなフィールドで [(disabled)] をバインドしたホストは、コントロールがそれを駆動する様子を確認できます。 |
requiredChange | OutputEmitterRef<boolean | null> | 双方向 [(required)] の書き込み側。リアクティブなバインディングでは、コントロールのステータスが変わり、その required バリデーターが追加または削除されるたびに発火します。値はそこから得られます。 |
メソッド
signature をコードから操作 — プログラム操作のための 10 個のメソッドを備えています。
| 名前 | シグネチャ | 戻り値 | 説明 |
|---|---|---|---|
clear | clear(): void | — | すべてのストロークを削除し、空の値を発行します。 |
undo | undo(): void | — | 最後に確定したストロークを削除します。 |
redo | redo(): void | — | 最後に取り消したストロークを復元します。 |
cancelStroke | cancelStroke(event?: PointerEvent): void | — | 進行中のストロークを通知せずに破棄します。pointercancel にバインドされており、Escape やフォーカスが描画面から外れた場合もこの経路を通ります。キャンセルされた操作がフォームの値に届いてはなりません。 |
toSvg | toSvg(): string | — | 拡大縮小可能な SVG のフォーム値を返します。 |
toDataUrl | toDataUrl(type?: string): string | — | 描画された署名をエクスポートします。既定は PNG です。 |
resizeCanvas | resizeCanvas(): void | — | 要素を再測定し、デバイスピクセルのビットマップを作り直して再描画します。[height] が自動的に実行しますが、フィールドが幅ゼロでレイアウトされた後に表示されるようになった場合(閉じたモーダル、非アクティブなタブ、折りたたまれたアコーディオンの中など)は手動で呼び出してください。自動測定は最初のレンダリング時に 1 度行われるだけで、ResizeObserver はありません。フィールドが空のうちに呼び出してください。ストロークは取り込まれた座標を保持するため、署名済みのフィールドを新しい幅に再測定すると署名の枠が変わり、toSvg() が出力する viewBox が内部のジオメトリと一致しなくなります。 |
isEmpty | isEmpty(): boolean | boolean | 何かが描画されているかどうか。シリアライズされた SVG を解析しなくてもフォームがフィールドを検証でき、これまではそれが問い合わせる唯一の方法でした。 |
toStrokes | toStrokes(): HubSignatureStroke[] | HubSignatureStroke[] | 確定したストロークを構造化されたジオメトリとして返します。toSvg() が引き続き正式なフォーム値で、こちらは署名の再生や、点のグループを保存していたライブラリからの移行など、点そのものが必要な呼び出し側向けです。 |
fromStrokes | fromStrokes(strokes: readonly HubSignatureStroke[]): void | — | 構造化されたジオメトリからフィールドを再描画します。writeValue() と同様にプログラムからの書き込みであり、ユーザーによる変更を Angular フォームに通知しません。 |
テンプレート
自分好みに — 2 個のテンプレートスロットでカスタムマークアップをプロジェクションできます。
| 名前 | 説明 | サンプル |
|---|---|---|
hubFormText | マークアップとしてのヘルパーテキスト。描画面の下のブロックで [formText] の文字列を置き換えます。どちらも ng-hub-ui-forms のエクスポートなので、hub-input 向けに書いたマークアップをそのままここへ移せます。formTextType="tooltip" でも、tooltip は文字列しか受け取れずマークアップが失われるため、このブロックに残ります。疑問符は引き続き [formText] の文字列で開きます。 | <ng-template hubFormText>Sign with a pointer, or carry the pen with <kbd>Space</kbd>.</ng-template> |
hubValidationError | 1 つのバリデーションエラーキーに対するメッセージ。[invalidFeedbackTemplateFn] とグローバルな provideHubForms() のビルダーのどちらよりも優先されます。名前を指定したキーだけが上書きされ、ほかのエラーは引き続きビルダーにフォールバックします。エラーのペイロードは暗黙のコンテキスト値として渡されます。 | <ng-template hubValidationError key="required">Sign before filing the contract.</ng-template> |