MTAppjQuery P7

MTAppMaxLength

テキスト入力欄に最大文字数を設定し、残り文字数カウンタの表示と超過警告を行う jQuery プラグイン。送信時に超過欄があれば alert で知らせて送信を止める。

テキスト入力欄（input / textarea）に最大文字数を設定し、残り文字数カウンタの表示と超過時の警告を行う jQuery プラグインです。入力のたびに残り文字数を更新し、超過すると入力欄とカウンタを赤く表示します。さらにフォーム送信時に、超過している欄があれば alert で知らせて送信を止めます。

構文

$(selector).MTAppMaxLength(options);

$.fn プラグイン（$(selector).MTAppMaxLength(...)）です。対象要素（this）を返すのでチェーンできます。

パラメータ

options {Object} — maxLength のみ必須。以下のプロパティを持ちます。

プロパティ	型	既定値	説明
`maxLength`	number	`0`	必須。最大文字数（1 以上）。`1` 未満のときは何もせず対象要素をそのまま返す
`addAttr`	boolean	`false`	`true` で対象要素に `maxlength` 属性を付与する
`viewCount`	boolean	`true`	残り文字数カウンタを表示するか。`false` でカウンタ要素を `hidden` クラスで隠す（カウント自体は動作）
`eachAlert`	boolean	`false`	送信時の警告を欄ごとに出すか。`false` のときは超過欄があればまとめて 1 回警告
`overStyle`	Object	`{ border: '1px solid #ff0000', color: '#ff0000' }`	超過時に入力欄へ適用する CSS（プロパティ／値のペア）
`overStatusStyle`	Object	`{ color: '#ff0000' }`	超過時にカウンタへ適用する CSS
`l10n`	Object \| null	`null`	表示文言の上書き（後述の L10N キー）。指定したキーだけ上書きされる

L10N キー

l10n で上書きできるキーと既定値（言語は mtappVars.language で自動判定）。

キー	日本語	英語	用途
`characters`	文字	（空文字）	文字数の単位
`maximumCharacters`	最大文字数	Maximum characters	未入力時のカウンタ見出し
`remainingCharacters`	残り文字数	Remaining characters	入力中（範囲内）のカウンタ見出し
`overCharacters`	最大文字数を[_1]文字超えています	[_1] characters over	超過時のカウンタ表示（[_1] に超過文字数）
`field`	欄	field	欄ごと警告のラベル接尾辞
`alertMessageEach`	最大文字数を超えています。	Number of characters exceeds maximum allowed.	欄ごと警告の本文
`alertMessageTotal`	最大文字数を超えている入力欄があります。	There are fields whose number of characters exceeds maximum allowed.	まとめ警告の本文

戻り値

{jQuery} — 対象要素（チェーン可能）。maxLength が 1 未満の場合も this を返します。

保存される値

このメソッドは保存される値を変換しません（文字数のカウント・超過警告・送信ブロックのみ）。入力されたテキストがそのまま保存されます。上限を超えた状態では送信時に警告して送信を止めるため、通常は上限内のテキストが保存されます。

使用例

基本（残り文字数を表示）

$('#customfield_summary').MTAppMaxLength({ maxLength: 120 });

属性も付与し、欄ごとに警告

$('input.text').MTAppMaxLength({
    maxLength: 40,
    addAttr: true,   // maxlength="40" を付与
    eachAlert: true  // 送信時、超過欄ごとに警告
});

カウンタを隠して超過チェックだけ行う

$('#customfield_title').MTAppMaxLength({ maxLength: 32, viewCount: false });

超過時の見た目と文言をカスタマイズ

$('#customfield_note').MTAppMaxLength({
    maxLength: 200,
    overStyle: { background: '#ffecec', color: '#c00' },
    l10n: { remainingCharacters: 'あと', characters: '字' }
});

user.js での記述例

user.js（「デザイン → user.js を編集」）に書く場合は、mtappVars.screen_id で画面を判定して呼び出します。

(function ($) {
    if (typeof mtappVars !== 'object') return;
    if (mtappVars.screen_id === 'edit-entry') {
        $('#customfield_summary').MTAppMaxLength({ maxLength: 120 });
    }
})(jQuery);

生成される HTML

対象要素は mtappmaxlength-wrapper でラップされ、直後に残り文字数カウンタ（mtappmaxlength-status）が追加されます。対象要素自身には mtappmaxlength-item クラスが付きます。

<span class="mtappmaxlength-wrapper">
    <input type="text" id="customfield_summary" class="text mtappmaxlength-item">
    <span class="mtappmaxlength-status">残り文字数 : 105文字</span>
</span>

viewCount: false のときはカウンタに hidden クラスが付きます。

<span class="mtappmaxlength-status hidden"></span>

補足

カウンタの表示は入力文字数で 3 段階に変化します。未入力＝「最大文字数 : N文字」、範囲内＝「残り文字数 : (N − 入力数)文字」、超過＝「最大文字数を M文字超えています」（M＝超過分）。
超過時は overStyle／overStatusStyle がインライン CSS として適用され、範囲内に戻すと解除されます。
送信時の検証は、最初にマッチした要素の所属フォームに submit.MTAppMaxLength ハンドラとして 1 つだけ登録され、ページ内の すべての .mtappmaxlength-item を対象にチェックします。超過欄があれば送信を中止して警告し（eachAlert で欄ごと／まとめを切替）、無ければ送信します。
文字数は String.length（UTF-16 コードユニット数）で数えます。サロゲートペアの絵文字などは 2 としてカウントされます。

構文