README

这个仓库是做什么的？

这是一个用于使用 yii\widgets\ActiveForm 和 \yii\db\ActiveRecord 创建分步表单或表单向导的 Yii2 插件。它使用了 smart wizard 库 来创建表单界面，该界面使用 3 个内置主题和 3 个额外主题，此外还可以创建自己的定制主题。

注意：它使用了 SmartWizard 插件的有限功能，以适应 ActiveForm 验证的需求，因此不允许从该插件内部更改或自定义 JavaScript 插件库中的所有选项。

使用的外部库

• Smart Wizard.
• jQuery >= v2.2.4
• Bootstrap v3.3.7 及 Bootstrap v4

新增功能

2020年1月19日：启用 编辑模式

2020年1月11日：启用 跳过步骤验证

2019年4月24日：使用标题分组步骤字段 Group Step Fields

2019年4月2日：启用 持久化

2019年3月25日：启用 预览步骤、表格步骤

关于 Bootstrap 版本的使用

该扩展会检测你是否正在使用 yiisoft/yii2-bootstrap 或 yiisoft/yii2-bootstrap4，并为扩展加载适当的资源。它首先检查 "yiisoft/yii2-bootstrap4" 是否存在，如果存在，则加载 Bootstrap4 资源；否则，将回退到使用 Bootstrap3。因此，请确保你正在遵循正确的指南使用 yiisoft/yii2-bootstrap4"，并从你的 composer.json 中删除 "yiisoft/yii2-bootstrap": "~2.0.0",，并将这里的 minimum-stability:"dev" 改为以下完整指南 guide。

如何设置

使用 composer 安装扩展

php composer.phar require  buttflattery/yii2-formwizard "@dev"

或将其添加到 composer.json 文件中的 require 部分

"buttflattery/yii2-formwizard":"@dev"

所有功能和主题的演示

• 最小化选项

• 添加自定义按钮

• 自定义字段顺序

• 启用 Ajax 验证

• 禁用 ActiveForm 验证

• 自定义表单字段

• 跨步骤的单个模型

• 单步骤的多个模型

• 表格步骤

• 启用预览步骤

• 启用表单持久化

• 启用跳过步骤

• 启用编辑步骤

• 分组步骤字段

• 主题

  • 主题箭头
  • 主题圆形
  • 主题点
  • 主题材料
  • 主题材料垂直
  • 主题标签

文档

• GitHub Wiki

可用选项

小部件选项

wizardContainerId (字符串)

向导主容器的ID。

forceBsVersion (int)（自V1.5.0版本起）

强制使用Bootstrap版本，即使你整体上使用的是yiisoft\yii2-bootstrap，但某些扩展依赖于yiisoft\yii2-bootstrap4。因为扩展首先检查yii2-bootstrap4，如果找到，则会加载yii2-bootstrap4资源。同时安装这两个扩展时，小部件将始终选择bootstrap4。虽然我们不推荐这样做，但仍然存在人们以这种方式使用且存在布局问题的情况。此选项的默认值是false，表示小部件将自动检测，您可以使用提供的常量FormWizard::BS_3或FormWizard::BS_4。

editMode (boolean)（自V1.6.4版本起）

如果表单向导应加载为编辑模式。默认值是false。有关详细信息，请参阅Wiki。

formOptions (数组)

指定ActiveForm属性。

labelNext (字符串)

下一步按钮标签，默认值下一步。

labelPrev (字符串)

上一步按钮标签，默认值上一步。

labelFinish (字符串)

完成按钮标签，默认值完成。

labelAddRow (字符串)

表格步骤的添加按钮标签，默认值添加。

classNext (字符串)

Next按钮的CSS类，默认btn btn-info。

iconNext (字符串)

Next按钮的HTML字符串，默认为<i class="formwizard-arrow-right-alt1-ico"></i>。

classPrev (字符串)

Previous按钮的CSS类，默认btn btn-info。

iconPrev (字符串)

Previous图标HTML字符串，默认为<i class="formwizard-arrow-left-alt1-ico"></i>。

classFinish (字符串)

Finish按钮的CSS类，默认btn btn-success。

iconFinish (字符串)

图标HTML字符串，默认为<i class="formwizard-check-alt-ico"></i>。

classAdd (字符串)

添加行按钮的CSS类，默认为btn btn-info

iconAdd (字符串)

按钮的HTML字符串，默认为<i class="formwizard-plus-ico"></i>

enablePreview (boolean)（自V1.2.0版本起）

在表单向导的最后一个步骤中添加一个预览步骤，您可以预览所有分组输入，点击任何步骤即可快速编辑，默认为false。请参阅Wiki中的代码示例

当使用'enablePreview'=>true时，您可以使用以下选项自定义类。

• previewTitle (字符串)：预览步骤标题，默认为最终预览。
• previewDescription (字符串)：预览步骤的描述，默认为所有步骤的最终预览。
• previewFormInfoText (字符串)：预览步骤表单描述，默认为审查以下信息并点击更改。
• previewEmptyText (字符串)：用于显示空输入值的文本，默认为NA。
• classListGroup (字符串)：列表组的CSS类，默认为'list-group'。
• classListGroupHeading (字符串)：列表组标题元素的CSS类，默认为'list-group-heading'。
• classListGroupItem (字符串)：列表组项的CSS类，默认为'list-group-item-success'。
• classListGroupBadge (字符串)：显示输入标签的列表组徽章的CSS类，默认为'success'。

enablePersistence (boolean)（自V1.3.0版本起）

启用将未保存的表单保存到本地存储以供以后使用，默认为false。

steps (数组)

步骤数组的步骤（array），每个步骤可以拥有针对该步骤的专用模型，或者为所有步骤使用单个模型。在指定步骤时，以下选项被识别。

• type (字符串)：步骤的类型，默认为default。如果您需要通过指定类型为tabular来为步骤提供表格输入，可以使用提供的常量，如FormWizard::STEP_TYPE_TABULAR或FormWizard::STEP_TYPE_DEFAULT。

• isSkipable (布尔值)：当前步骤是否可以跳过，有关详细信息，请参阅wiki。

• limitRows (整数)：限制表格步骤添加行功能的行数，与FormWizard::STEP_TYPE_TABULAR结合使用，默认为无限-1。查看Wiki。

• model (对象 | 模型数组)：用于创建步骤字段的\yii\model\ActiveRecord模型对象或模型数组。

  注意：当使用'type'=>'tabular'并添加了表格步骤功能时，您必须记住，您不能提供不同的模型，尽管在编辑模式下您可以提供多个实例，但只能是对同一模型的实例。

  添加新记录时可以如下所示

  $addressModel = new Address();
  
  "steps"=>[
    [
      'title'=>'Step Title',
      'type' => FormWizard::STEP_TYPE_TABULAR,
      'model'=> $addressModel
    ]
  ]

  在编辑模式下，您可以提供多个Address实例

  //either using model directly
    $addressModel = Address::find()
        ->where(
          ['=','user_id',Yii::$app->user->id]
        )->all();
  
    //or using the model relation if you have `getAddress()` defined inside
    //the `User` model. `$user` has the selected user in code below
    $addressModel = $user->address;
  
  "steps"=>[
    [
        'title'=>'Step Title',
        'type' => FormWizard::STEP_TYPE_TABULAR,
        'model'=> $addressModel
    ]
  ]

  有关表格步骤代码示例，请参阅wiki

• title (字符串)：要在步骤标签中显示的步骤标题。

• previewHeading：预览步骤的标题，如果启用，则文本将作为预览步骤中步骤字段的标题显示。

• description (字符串)：步骤的简要描述。

• formInfoText (文本)：在步骤表单字段顶部显示的文本。

• fieldOrder (数组)：步骤中字段的默认顺序，如果指定，则根据数组中字段的顺序填充字段，如果没有指定，则根据fieldConfig选项中的顺序排序字段，如果没有指定fieldConfig选项，则使用从模型返回属性的默认顺序。

• stepHeadings (数组)：接受一个数组集合，用于将步骤字段分组在标题下，它接受具有以下键的数组。Wiki代码示例

  • text (字符串)：要显示的标题文本。
  • before (字符串)：在要出现标题之前的位置的字段。
  • icon (字符串)：图标标记，如<i class="fa-user"></i>或要显示的带有URL的图像标签，默认为<i class="formwizard-quill-ico"></i>。如果不希望使用图标，可以传递false。

• fieldConfig (数组)：此选项主要用于自定义步骤的表单字段。在fieldConfig中识别了3个选项，其中2个是except和only。以下为详细信息

• except (数组)：不应填充或应忽略的步骤中的字段列表，例如

    'fieldConfig'=>[
        'except'=>[
            'created_on','updated_on'
        ]
    ]

  默认情况下，所有安全加载值的属性都会被填充，并且默认情况下会忽略id或primary_key。

• only (数组)：应填充步骤的字段列表，只有列表中指定的字段将可用，其他所有字段将被忽略。

• 除了上述选项之外，fieldConfig在自定义字段时还识别一些针对每个字段分别特定的特殊选项，例如

  'fieldConfig'=>[
      'username'=>[
          'options'=>[
              'class'=>'my-class'
          ]
      ]
  ]

  自V1.6.8以来

  当使用多模型步骤时，您可能会遇到模型中存在类似列/字段名的情况，仅指定字段名无法解决问题。您可以在字段名前加上模型名，该小部件使用 $model->formName() 方法，因此如果您在模型中重写了 formName() 函数，请使用相关的名称。

  以下是一个示例，其中您需要在同一步骤中同时使用 book 和 user 模型，并且两个表中都有 name 字段。

  'fieldConfig'=>[
      'user.name'=>[
          'options'=>[
              'class'=>'my-class'
          ]
      ],
      'book.name'=>[
          'options'=>[
              'class'=>'my-class'
          ]
      ],
   ]

  您应该以 name=>value 对的形式指定模型的字段名及其自定义设置。在指定表单/模型的 field_name 时，可以使用以下特殊选项。

  • 选项

  • 容器选项

  • 输入选项

  • 模板

  • 标签选项

  • 小部件

  • 多字段（布尔值）

  • 提示

  • tabularEvents（与表格步骤一起使用）

  • persistenceEvents（与 enablePersistence 一起有效）查看Wiki 查看Wiki以使用上述选项自定义字段 详细信息

  • depends (数组) 自 V 1.7.2（与表格步骤一起使用）。

  • options (数组)：您可以指定字段的HTML属性（name-value对）。

    'field_name'=>['options'=>['class'=>'my-class']]`

    所有这些由

    • checkbox(), radio()：uncheck，label，labelOptions
    • checkboxList(), radioList()：tag，unselect，encode，separator，itemOptions，item。

    可以在 options 选项中使用。以下两个选项在 options 内部使用时会被该小部件特别识别。

    • type (字符串)：要创建的表单字段的类型，可以是 text、dropdown、checkbox、radio、textarea、file、password、hidden。此选项的默认值为 text。

    • itemsList (字符串/数组)：此选项可以与 dropdown、checkboxList 或 radioList 一起使用。它与 type 选项结合使用。如果您为 itemsList 提供一个数组并使用 'type'=>'checkbox'，则将调用 checkboxList()，如果提供字符串，则调用 checkbox()，对于 radioList 和 radio 也是如此。

  • labelOptions (数组)：用于自定义字段标签的HTML和特殊选项，您可以使用以下设置

    • label (字符串)：标签文本。
    • options (数组)：标签的HTML属性（name-value对）。

  • template (字符串)：用于字段的模板，默认值使用的是 {label}\n{input}\n{hint}\n{error}。

  • containerOptions (数组)：容器标签的HTML属性，以 name=>value 对的形式。

  • widget：如果您想使用小部件而不是默认字段，则可以使用此选项。您可以指定小部件类名 'widget'=>widget::class，小部件的选项将在 options 选项中提供。 -inputOptions (数组)：这与 ActiveForm field() 方法使用的 inputOptions 相同。

  • multifield (布尔值)：一个布尔值，用于决定字段名是否应包含数组，例如，使用多文件上传小部件需要将字段的 name 属性声明为数组，如 field_name[] 而不是 field_name。您可以通过将其设置为 true 来传递此选项，默认值为 false。

  • hint (字符串)：用于为字段提供提示文本。如果没有为任何字段提供自定义提示文本，它将尝试显示模型内部通过重写attributeHints()提供的自定义提示，否则不会显示任何提示。

  • tabularEvents (数组)：接受一个数组作为参数，包含以下值：beforeClone、afterClone和afterInsert，形式为"eventName"=>"function(event){}"，详情请见这里

    • beforeClone：接受一个回调函数function(event){}，用于在克隆源元素之前对其进行预处理，函数回调中的$(this)引用的是第一行的元素。
    • afterClone：接受一个回调函数function(event){}，用于在克隆源元素之后对其进行后处理，函数回调中的\$(this)引用的是第一行的元素。
    • afterInsert：接受一个回调函数function(event, params){console.log(params)}，用于在克隆的新元素之后进行后处理，函数回调中的$(this)引用的是新添加的行。参数params是一个JSON对象，包含rowIndex。

  • persistenceEvents (数组)：接受一个事件数组，目前只支持afterRestore。

    • afteRestore：接受一个作为字符串的回调函数"function(event,params){}"，用于执行恢复后的操作，它提供两个参数event和params，其中params是一个JSON对象，格式为{fieldId: "field_name",fieldValue: "field_value"}。

  • depends (数组)：与表格步骤一起使用，当您有依赖输入并且希望根据依赖输入的值显示或隐藏它们时，请使用此参数。请参阅WIKI以获取代码示例。它接受以下特殊参数

    • attribute (字符串)：当前字段所依赖的属性/字段的名称，此参数是必需的。
    • when (字符串)：要检查的值，或与当前输入需要显示的值进行比较的值，此参数是必需的。
    • condition (字符串)：用于评估依赖输入值的条件，与when中给出的值进行比较。默认条件是==。
    • then (回调)：接受一个new JsExpression()编码的回调函数function(id){}，它接受一个参数id，该参数包含当前输入的ID。如果没有提供，则会在when选项匹配的情况下，对应用到的输入ID调用jQuery.show()。
    • else (回调)：接受一个new JsExpression()编码的回调函数function(id){}，它接受一个参数id，该参数包含当前输入的ID。如果没有提供，则会在when选项匹配的情况下，对应用到的输入ID调用jQuery.show()。

小部件插件（SmartWizard）选项

只有以下SmartWizard插件的选项允许自定义

theme

要使用的主题名称，插件主要支持6种主题

• default：const THEME_DEFAULT
• dots：const THEME_DOTS
• arrows：const THEME_ARROWS
• circles：const THEME_CIRCLES
• material：const THEME_MATERIAL
• material-v：const THEME_MATERIAL_V

transitionEffect (字符串)

滑动步骤时使用的效果可以是以下之一：

• 无
• 滑动
• 渐隐

showStepURLhash (布尔值)

根据步骤显示URL哈希，默认值为 false。

useURLHash (布尔值)

启用根据URL哈希选择步骤，默认值是 false。

toolbarPosition

工具栏的位置（none, top, bottom, both），默认值 top。

toolbarButtonPosition

工具栏按钮的位置（left, right），默认值是 left。

toolbarExtraButtons

指定要在工具栏上显示的额外按钮及其事件。

markDoneSteps (布尔值)

将已访问的步骤标记为完成，默认值是 true。

markAllPreviousStepsAsDone (布尔值)

当通过URL哈希选择步骤时，所有前面的步骤将被标记为完成，默认值是 true。

removeDoneStepOnNavigateBack (布尔值)

在导航回操作步骤后，完成步骤将被清除，默认值是 false。

enableAnchorOnDoneStep (布尔值)

启用/禁用完成步骤的导航，默认值是 true。

Widget Constants

图标

• FormWizard::ICON_NEXT 默认为 '<i class="formwizard-arrow-right-alt1-ico"></i>'。
• FormWizard::ICON_PREV 默认为 '<i class="formwizard-arrow-left-alt1-ico"></i>'。
• FormWizard::ICON_FINISH 默认为 '<i class="formwizard-check-alt-ico"></i>'。
• FormWizard::ICON_ADD 默认为 '<i class="formwizard-plus-ico"></i>'。
• FormWizard::ICON_RESTORE 默认为 '<i class="formwizard-restore-ico"></i>'。

Boostrap 版本

• FormWizard::BS_3 默认为 3。
• FormWizard::BS_4 默认为 4。

步骤类型

• FormWizard::STEP_TYPE_DEFAULT 默认为 'default'。
• FormWizard::STEP_TYPE_TABULAR 默认为 'tabular'。
• FormWizard::STEP_TYPE_PREVIEW 默认为 'preview'。

主题

• FormWizard::THEME_DEFAULT 默认为 'default'。
• FormWizard::THEME_DOTS 默认为 'dots'。
• FormWizard::THEME_ARROWS 默认为 'arrows'。
• FormWizard::THEME_CIRCLES 默认为 'circles'。
• FormWizard::THEME_MATERIAL 默认为 'material'。
• FormWizard::THEME_MATERIAL_V 默认为 'material-v'。
• FormWizard::THEME_TAGS 默认为 'tags'。

我应该和谁联系？

• buttflattery@gmail.com
• yii2plugins@omaraslam.com