README

这个仓库是用来做什么的？

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

注意：它使用有限功能的jQuery插件SmartWizard，适用于ActiveForm验证，因此不是所有javascript插件库中的选项都可以在此插件中更改或自定义。

使用的外部库

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

新增功能

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

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

2019年4月24日：按标题分组步骤字段

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"更改。这里是完整的指南。

如何设置

使用composer安装扩展

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

或在composer.json文件的require部分中添加

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

所有功能和主题的演示

• 最小选项

• 添加自定义按钮

• 自定义字段顺序

• 启用Ajax验证

• 禁用ActiveForm验证

• 自定义表单字段

• 跨步骤的单个模型

• 单步骤的多个模型

• 表格步骤

• 启用预览步骤

• 启用表单持久性

• 启用跳过步骤

• 启用编辑步骤

• 分组步骤字段

• 主题

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

文档

• GitHub Wiki

可用选项

小部件选项

wizardContainerId (字符串)

向导主要容器的ID。

forceBsVersion (整数)（自V1.5.0起）

如果您的某些扩展依赖于 yiisoft\yii2-bootstrap4，即使您在网站上整体使用 yiisoft\yii2-bootstrap，也必须强制使用 bootstrap 版本，因为扩展首先检查 yii2-bootstrap4，如果找到，则加载 yii2-bootstrap4 资产。尽管我们不推荐这样做，但仍有场景下人们以这种方式使用，并且会出现布局问题。此选项的默认值是 false，表示小部件将自动检测，您可以使用提供的常量 FormWizard::BS_3 或 FormWizard::BS_4。

editMode (布尔值)（自 V1.6.4 以来）

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

formOptions (数组)

指定 ActiveForm 属性。

labelNext (字符串)

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

labelPrev (字符串)

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

labelFinish (字符串)

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

labelAddRow (字符串)

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

classNext (字符串)

下一步按钮的 CSS 类，默认 btn btn-info。

iconNext (字符串)

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

classPrev (字符串)

上一步按钮的 CSS 类，默认 btn btn-info。

iconPrev (字符串)

上一步图标按钮的 HTML 字符串，默认 <i class="formwizard-arrow-left-alt1-ico"></i>。

classFinish (字符串)

完成按钮的 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 (布尔值)（自 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 (布尔值)（自 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 选项中使用。以下 2 个选项在用作 options 内部时被特别识别。

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

    • itemsList (字符串/数组)：此选项可用于 dropdown，checkboxList 或 radioList。它与 type 选项结合使用。如果您提供了数组 itemsList 并使用 'type' => 'checkbox'，则它将调用 checkboxList()，如果提供字符串，则相同适用于 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 是一个包含 rowIndex 的 JSON 对象。

  • persistenceEvents (数组)：接受一个包含以下名称的事件数组。（目前只支持 afterRestore）。

    • afterRestore：接受一个字符串形式的回调函数 "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 (字符串)

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

• none
• slide
• fade

showStepURLhash (布尔值)

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

useURLHash (布尔值)

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

toolbarPosition

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

toolbarButtonPosition

工具栏按钮位置（左，右），默认值为左。

toolbarExtraButtons

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

markDoneSteps (布尔值)

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

markAllPreviousStepsAsDone (布尔值)

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

removeDoneStepOnNavigateBack (布尔值)

在导航回已完成的步骤后，将清除活动步骤之后的已完成步骤，默认值为 false。

enableAnchorOnDoneStep (布尔值)

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

小部件常量

图标

• 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>'。

Bootstrap 版本

• 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