syncfusion-maui-numeric-entry

.NET MAUI 数値入力の実装

Syncfusion .NET MAUI 数値入力コントロールは、数値データをユーザーフレンドリーかつ高度に入力できるよう設計されています。通貨、パーセンテージ、小数、その他の設定可能な数値形式など、幅広い数値形式に対応しています。豊富な機能により、数値入力の検証と書式設定を簡素化しながら、ユーザーエクスペリエンス全体を向上させます。

このスキルを使用する場面

次のようなニーズがある場合に、このスキルを使用してください。

• 検証と書式設定に対応した数値入力を受け付ける
• 通貨、パーセンテージ、または小数の入力フィールドを作成する
• 上下ボタンによる値の増減を実装する
• 数値を最小値と最大値の範囲内に制限する
• 文化圏固有のパターンで数値を書式設定する
• キーボードショートカット（矢印キー、ページキー）による数値入力を提供する
• 価格入力フィールド、数量セレクター、または評価システムを構築する
• 年齢入力、割引計算、または測定値フィールドを作成する
• ボタンコントロール付きの読み取り専用数値表示を実装する
• 数値入力にモダンな半透明ガラス効果を追加する

コンポーネントの概要

**Syncfusion .NET MAUI 数値入力（SfNumericEntry）**は、高度な機能を備えた数値入力専用のコントロールです。

主な機能

• 数値の検証：アルファベット入力を制限し、Enter キーの押下時またはフォーカス喪失時に検証します
• 書式のサポート：通貨（C）、パーセンテージ（P）、小数（N）、カスタム書式に対応します
• 値の操作：上下ボタン、キーボードの矢印キー、マウススクロールで値を変更できます
• 範囲の制限：最小値と最大値の制約を適用します
• カスタマイズ：外観、フォント、色、境界線、ボタンを自由に制御できます
• カルチャのサポート：さまざまな地域の数値形式に適応します
• アクセシビリティ：AutomationId のサポートにより WCAG に準拠します

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

参照する場面： Numeric Entry を初めてセットアップするとき、または基本的な実装が必要なとき

説明するトピック：

• .NET MAUI プロジェクトの作成
• Syncfusion.Maui.Inputs NuGet パッケージのインストール
• ConfigureSyncfusionCore() を使用した MauiProgram.cs でのハンドラー登録
• 名前空間と基本的な Numeric Entry コントロールの追加（XAML/C#）
• Enter キーの押下時またはフォーカス喪失時の検証を伴う値の編集
• CustomFormat プロパティによる数値形式の変更
• AllowNull による null 値の受け入れまたは制限
• UI のカスタマイズ（PlaceholderColor、TextColor、Font プロパティ）
• キャレットと選択範囲の制御（CursorPosition、SelectionLength）
• メソッド：Focus()、Unfocus()
• イベント：Focused、Unfocused と FocusEventArgs

基本機能と設定

📄 参照： references/basic-features.md

参照する場面： プレースホルダー、クリアボタン、イベント、境界線、またはテキスト配置を設定するとき

説明するトピック：

• Placeholder プロパティによるプレースホルダーテキストの設定
• クリアボタンの表示（ShowClearButton）と色（ClearButtonColor）
• ClearButtonPath によるカスタムクリアボタンのパス設定
• ValueChanged イベントによる値変更の通知
• 値変更モード（OnLostFocus、OnKeyFocus）
• Completed イベント（Return キーの押下）
• ClearButtonClicked イベント
• 境界線のカスタマイズ（Stroke、ShowBorder）
• テキスト配置（HorizontalTextAlignment、VerticalTextAlignment）
• SelectAllOnFocus によるフォーカス時のテキスト全選択
• ReturnType によるキーボードの Return キーの種類の設定
• Return コマンド（ReturnCommand、ReturnCommandParameter）
• UI テストとアクセシビリティのための AutomationId

値の書式設定

📄 参照： references/formatting.md

参照するタイミング： 値を通貨、パーセンテージ、またはカスタム数値形式で表示する必要がある場合

説明するトピック：

• 通貨形式（C2）：$1,234.56
• パーセンテージ形式（P2）：45.50%
• 小数形式（N2）：1,234.56
• 0 および # 指定子を使用したカスタム書式文字列
• ゼロプレースホルダーを使用した整数桁の書式設定
• 小数桁の書式設定
• カスタム書式の組み合わせ（例：「$00.00##」）
• Culture プロパティを使用したカルチャベースの書式設定
• パーセンテージの表示モード（Value と Compute）
• MaximumNumberDecimalDigits を使用した小数桁の最大数

値の制限

📄 参照： references/restrictions.md

参照するタイミング： 最小値や最大値を適用する、または null 値を防止する必要がある場合

説明するトピック：

• AllowNull プロパティで null 値を制限する
• AllowNull が false の場合の動作（0 または Minimum を返す）
• Minimum と Maximum を使用して値を範囲内に制限する
• デフォルト値（double.MinValue、double.MaxValue）
• IsEditable プロパティでテキスト編集を禁止する
• ボタン、キー、スクロールによる値の変更は引き続き可能
• 範囲の検証とエッジケース

上下ボタン

📄 参照： references/updown-buttons.md

参照するタイミング： 増減ボタン、またはキーボード／マウスによる値の変更を実装する場合

説明するトピック：

• キーボードの矢印キーや Page キーで値を増減する
• SmallChange（矢印キー、マウススクロール、上下ボタン）
• LargeChange（Page Up／Down キー）
• 上下ボタンの配置モード：
  • Hidden（デフォルト、ボタンを表示しない）
  • Inline（横並びのボタン）
  • InlineVertical（縦に積み重ねたボタン）
• ボタンの配置（Left、Right、Both）
• ボタンの順序（UpThenDown、DownThenUp）
• ボタンの色のカスタマイズ（UpDownButtonColor）
• カスタムボタンテンプレート（UpButtonTemplate、DownButtonTemplate）
• 自動反転動作（AutoReverse を使用して最小値／最大値で再開）

リキッドグラス効果

📄 参照： references/liquid-glass-effect.md

参照するタイミング： モダンな半透明のガラスデザインを実装する場合（.NET 10、iOS 26 以降、macOS 26 以降）

説明するトピック：

• リキッドグラス効果の概要
• 数値入力を SfGlassEffectView でラップする
• ガラス効果を適用するため、Background を Transparent に設定する
• EffectType と EnableShadowEffect を構成する
• プラットフォーム要件と制限