README

TwbsMaxlength小部件是出色的Bootstrap Maxlength插件的包装，用于显示maxlength属性的可视反馈指示器。请查看演示页面了解更多信息！

安装

安装此扩展的首选方法是使用composer。

运行

php composer.phar require --prefer-dist raoul2000/yii2-twbsmaxlength-widget "*"

或添加

"raoul2000/yii2-twbsmaxlength-widget": "*"

到您的composer.json文件的require部分。

基本用法

使用TwbsMaxlength小部件非常简单。在下面的示例中，我们将“Bootstrap Maxlength”插件附加到输入文本控件，通过HTML5的maxlength属性设置最大长度为20个字符

<input type="text" class="form-control" id="txtinput1" name="xyz" maxlength="20" />

<?php
	raoul2000\widget\twbsmaxlength\TwbsMaxlength::widget(['selector' => '#txtinput1']);
?>

用户无法在文本输入控件中输入超过20个字符。当用户输入第10个字符（默认值为硬编码）时，控件底部将出现一个小的警告。

请记住，仅在需要将“Bootstrap Maxlength”插件附加到现有的HTML输入标签（文本或textarea）时才使用selector选项。

ActiveForm

大多数情况下，文本或textarea输入控件是由ActiveForm小部件生成的。当然，TwbsMaxlength也能够处理此类用例。

<?php 
	use raoul2000\widget\twbsmaxlength\TwbsMaxlength;
	
	$form = ActiveForm::begin(); 

	echo $form->field($model, 'name')
		->textInput(['maxlength' => true])		
		->widget(TwbsMaxlength::className());

	ActiveForm::end();
?>

上面的代码仅在Yii2 v2.0.3版本中有效，该版本包含一个功能，可以自动设置ActiveField文本输入的maxlength属性，基于相关的string验证规则（了解更多...）

要使用textarea，只需添加带有值为TwbsMaxlength::INPUT_TEXTAREA的type配置参数。

<?php 
	use raoul2000\widget\twbsmaxlength\TwbsMaxlength;
	
	$form = ActiveForm::begin(); 

	echo $form->field($model, 'name')
		->textInput(['maxlength' => true])		
		->widget(TwbsMaxlength::className(),['type' => TwbsMaxlength::INPUT_TEXTAREA]);

	ActiveForm::end();
?>

遗留支持

如果您正在使用低于2.0.3版本的Yii2，则无需担心：TwbsMaxlength小部件实现了与Yii2 2.0.3相同的特征。如果您没有自己设置maxlength HTML5属性，则小部件将在模型的属性定义的验证规则中查找此值。如果找到规则字符串并且设置了最大长度，则将其用于向HTML输入元素注入maxlength。否则，“Bootstrap Maxlength”插件将不会启用。

让我们通过著名的ContactForm模型来示例。我们使用StringValidator来定义'subject'属性的最大长度（在此处将设置为10）

class ContactForm extends Model
{
    public $subject;
    
    /**
     * @return array the validation rules.
     */
    public function rules()
    {
        return [
        	['subject','string', 'length'=> [4,10]],
        ];
    }
    // ....

现在，无需设置maxlength HTML5属性，因为小部件会为我们设置它。我们可以简单地写

<?php 
	use raoul2000\widget\twbsmaxlength\TwbsMaxlength;
	
	$form = ActiveForm::begin(); 

	echo $form->field($model, 'subject')->widget(TwbsMaxlength::className());

	ActiveForm::end();
?>

就这样！查看创建的输入标签，您会看到maxlength HTML5属性已设置为10，正如在'subject'属性验证规则中定义的那样。

插件选项

Bootstrap Maxlength接受几个选项来自定义其行为。这些选项可以在配置小部件时初始化在clientOptions数组中。

<?php
  use raoul2000\widget\twbsmaxlength\TwbsMaxlength;
  
  $form = ActiveForm::begin(); 
  
  echo $form->field($model, 'body')
  	->textinput(['maxlength' => true])
  	->widget(
      TwbsMaxlength::className(), 
      [
          'clientOptions' => [
              'threshold'         => 10,
              'preText'           => 'You have ',
              'separator'         => ' of ',
              'postText'          => ' chars remaining.',
              'warningClass'      => "label label-success",
              'limitReachedClass' => "label label-danger"
      ]
  ]);
  
  ActiveForm::end();
?>

有关插件选项的更多信息，请参阅 bootstrap-maxlength GitHub 页面。

小部件选项

textarea

要生成一个 textarea 元素而不是默认生成的经典文本输入（默认生成），请在配置小部件时使用 type 选项。

<?php 
    use raoul2000\widget\twbsmaxlength\TwbsMaxlength;
    
	$form = ActiveForm::begin(); 

	echo $form->field($model, 'body')
		->textinput(['maxlength' => true])
		->widget(
			TwbsMaxlength::className(),
			[
	    		'type' => TwbsMaxlength::INPUT_TEXTAREA
	    	]
	    );

	ActiveForm::end();
?>

设置阈值

阈值是一个表示在达到 maxlength 限制之前剩余字符数的数值。当达到阈值时，会向用户显示一个警报，通知其最大长度即将达到。您可以像设置其他任何 clientOption 插件选项一样设置阈值值。

<?php
  use raoul2000\widget\twbsmaxlength\TwbsMaxlength;
  
  $form = ActiveForm::begin(); 
  
  echo $form->field($model, 'body')
  	->textinput(['maxlength' => true])
  	->widget(
  		TwbsMaxlength::className(), 
      	[
        	'clientOptions' => [ 'threshold' => 10]
      	]
	);
  
  ActiveForm::end();
?>

TwbsMaxlength 提供了一种根据最大长度值动态计算阈值值的方法。此选项名称为 thresholdPolicy。TwbsMaxlength 小部件包含 3 个内置的阈值策略

TwbsMaxlength::THRESHOLD_HALF
TwbsMaxlength::THRESHOLD_TWO_THIRD（默认）
TwbsMaxlength::THRESHOLD_THREE_QUARTERS

在下面的示例中，警报将在用户输入允许的总字符数的 3/4 之后显示。例如，如果“主题”验证规则将最大长度设置为 40，则当输入 30 个字符时，将显示警报。

<?php 
    use raoul2000\widget\twbsmaxlength\TwbsMaxlength;
    
	$form = ActiveForm::begin(); 

	echo $form->field($model, 'subject')
		->textinput(['maxlength' => true])
		->widget(
			TwbsMaxlength::className(),
			[
    			'thresholdPolicy' => TwbsMaxlength::THRESHOLD_THREE_QUARTERS,
    		]
    	);

	ActiveForm::end();
?>

请注意，thresholdPolicy 仅在与 ActiveForms 一起使用时可用。

许可证

yii2-twbsmaxlength-widget 在 BSD 3-Clause 许可证下发布。有关详细信息，请参阅附带文件 LICENSE.md。

raoul2000 / yii2-twbsmaxlength-widget

维护者

详细信息