angular-archwizard, Angular 2 +的向导组件

分享于 

32分钟阅读

GitHub

  繁體 雙語
A wizard component for angular 2
  • 源代码名称:angular-archwizard
  • 源代码网址:http://www.github.com/madoar/angular-archwizard
  • angular-archwizard源代码文档
  • angular-archwizard源代码下载
  • Git URL:
    git://www.github.com/madoar/angular-archwizard.git
    Git Clone代码到本地:
    git clone http://www.github.com/madoar/angular-archwizard
    Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/madoar/angular-archwizard
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
    
    概述角度 archwizard ( 以前称为 ng2-archwizard )

    Build StatusDependency StatusDev-Dependency StatusDependency Licence StatusCode ClimateTest CoverageNPM Version

    这个项目包含一个具有向导组件和一些支持组件和 Angular 组件的一些支持组件和指令的函数式 MODULE。

    插件生成

    运行 npm run build 以生成项目。 构建构件将存储在 dist/ 目录中。

    运行单元测试

    运行 npm test 以通过 Karma 执行单元测试。

    安装

    angular-archwizard 可以作为NPM软件包使用。 要在项目目录中安装 angular-archwizard,请执行以下操作:

    
    $ npm install --save angular-archwizard
    
    
    
    

    之后,可以通过将 ArchwizardModule 添加到 MODULE 声明中,在 Angular 项目中导入 angular-archwizard,如下所示:

    import { ArchwizardModule } from'angular-archwizard';
    @NgModule({
     imports: [
     ArchwizardModule ],
    })exportclassModule { }

    如何使用向导

    要在 Angular 项目中使用这里向导组件,只需将 aw-wizard 组件添加到组件的html模板中:

    <aw-wizard>
     <aw-wizard-stepstepTitle="Title of step 1">
     Content of Step 1
     <buttontype="button"awNextStep>Next Step</button>
     <buttontype="button" [awGoToStep]="{stepIndex: 2}">Go directly to third Step</button>
     </aw-wizard-step>
     <aw-wizard-stepstepTitle="Title of step 2"awOptionalStep>
     Content of Step 2
     <buttontype="button"awPreviousStep>Go to previous step</button>
     <buttontype="button"awNextStep>Go to next step</button>
     </aw-wizard-step>
     <aw-wizard-stepstepTitle="Title of step 3">
     Content of Step 3
     <buttontype="button"awPreviousStep>Previous Step</button>
     <buttontype="button" (click)="finishFunction()">Finish</button>
     </aw-wizard-step>
    </aw-wizard>

    组件

    <向导>

    <aw-wizard> 环境是环境,你可以在其中定义属于你的向导的步骤。 除了包含的向导步骤,angular-archwizard 还允许你在向导中定义导航栏 inside的位置和布局。 若要设置位置,导航栏的布局和许多它的他设置,可以将以下参数传递给 aw-wizard 组件:

    [navBarLocation ]

    可以通过 navBarLocation 输入值指定包含 inside的导航栏所在的导航栏的位置。 此值可以是 topbottomleft 或者 right,其中值指定导航栏的显示位置。 另外,topbottom 将导致水平导航栏,当 leftright 导向左侧或者右侧的垂直导航栏时。 如果没有 navBarLocation,导航栏将显示在向导的顶部。

    [navBarLayout ]

    可以更改的另一个选项是导航栏的设计或者布局。 目前存在五个不同的导航栏布局。 这些是 smalllarge-filledlarge-emptylarge-filled-symbolslarge-empty-symbols

    在导航栏中,前三个布局在导航栏中显示带有或者没有 background的圆的圆。 第二个布局 large-filled-symbolslarge-empty-symbols 可以在导航栏中为导航栏中的每个步骤在圆的中心添加一个符号。

    [navBarDirection ]

    通常导航栏中的步骤从左至右或者从上到下排列。 在某些情况下,像从右到左写的语言,可以能需要更改这个 direction 来从右向左布局步骤。 要从右到左布局步骤,你可以将 right-to-left 传递到向导组件的navBarDirection 输入。

    [navigationMode ]

    angular-archwizard 支持三种不同的导航模式:

    • 严格的导航模式: 第一种导航模式是严格导航。 这里模式描述当前的状态,换句话说,的当前导航行为。 当前只能以线性方式导航到向导步骤,如果完成前面步骤的所有步骤都已经完成。 在这种模式下,不可能在不同步骤之间跳转,换句话说,从步骤1 到步骤 1,然后转到步骤 2到步骤 4. 这里规则的唯一例外是可选步骤,用户可以跳过。 因此,你需要按照顺序执行这些步骤 1 -> 2 -> 3 -> 4
    • 半严格的导航模式: 第二种导航模式是半严格。 这里模式允许用户在任意顺序之间按任意顺序进行导航。 这意味着在这种导航模式下,用户可以按照顺序完成这些步骤 1 -> 3 -> 2 -> 4 如果已经满足退出条件。 这种模式只有一个限制,用户在完成之前的步骤后可以进入完成步骤。 同样可选步骤在这里模式下为 skipable。
    • 免费:navigation导航模式: 第三种导航模式是自由导航。 这种模式让用户可以在不同的步骤之间自由地导航,包括完成步骤,以任何他想要的顺序。
    [defaultStepIndex ]

    默认情况下,向导总是以第一个向导步骤开始,初始化后。 重置同样适用,向导通常将它的重置为第一个步骤。 有时候这需要改变。 如果需要使用另一个默认向导步骤,则可以通过使用向导组件的[defaultStepIndex] 输入来设置它。 例如要在第二个步骤中启动向导,需要设置 [defaultStepIndex]="2"

    如果 Angular 未被 [] 包围,请注意将把给定的输入值解释为字符串 !

    [disableNavigationBar ]

    有时可能需要通过导航栏禁用导航。 在这种情况下,通过将向导组件的输入 [disableNavigationBar] 设置为 true,可以通过导航栏禁用导航。

    禁用导航栏后,用户不能再使用导航栏在各个步骤之间导航。 禁用导航栏并不限制使用 awNextStepawPreviousStep 或者 awGoToStep 指令的元素( 按钮或者链接)。

    参数概述

    可能的<aw-wizard> 参数:

    参数 NAME 可能的值默认值
    [navBarLocation ]top | bottom | left | right顶端
    [navBarLayout ]small | large-filled | large-empty | large-filled-symbols | large-empty-symbols
    [navBarDirection ]left-to-right | right-to-left从左到右
    [navigationMode ]strict | semi-strict | free严格
    [defaultStepIndex ]number0
    [disableNavigationBar ]booleanfalse

    <aw-wizard-step>

    angular-archwizard 包含两种定义向导步骤的方法。 这两种方法之一是使用 <aw-wizard-step> 组件。

    [stepId ]

    向导步骤可以有自己的唯一标识。 这个id可以被用来定位到步骤。

    [stepTitle ]

    向导步骤需要包含标题,该标题显示在向导的导航栏中。 若要设置步骤的标题,请将 stepTitle 输入属性添加到向导步骤的定义中,并选择所选步骤标题。

    [navigationSymbol ]

    有时,在导航栏中的圆中心添加符号是有用的,它属于步骤。 angular-archwizard 通过向导步骤的[navigationSymbol] 输入属性支持这一点。

    注意,并非所有的布局都显示符号。 只有 large-filled-symbolslarge-empty-symbols 显示符号 !

    如果要将 2 添加到属于第二步的导航栏中的圆,可以如下所示:

    <aw-wizard-stepstepTitle="Second Step" [navigationSymbol]="{ symbol: '2' }"></aw-wizard-step>

    除了普通符号之外,还可以从字体中使用 icon 作为符号。 要使用字体中的icon,需要首先搜索属于要插入的icon的unicode。 之后,你可以使用数字字符引用格式中的unicode作为步骤的符号。 这里外,你需要指定 icon 所属的font-family,否则不能正确显示符号。

    可以通过给定 [navigationSymbol] json输入对象的fontFamily 字段来指定所使用符号的font-family。 例如如果你想用 FontAwesome inside icon f2dd show在导航栏中显示一个步骤圆圈,那么你可以通过下面的[navigationSymbol] 输入属性来完成这个步骤:

    <aw-wizard-stepstepTitle="Second Step" [navigationSymbol]="{ symbol: '&#xf2dd;' fontFamily: 'FontAwesome' }"></aw-wizard-step>
    [canEnter ]

    有时要求只允许用户在某个验证方法返回 true 时输入特定的步骤。 在这种情况下,你可以使用目标向导步骤的[canEnter] 输入。 输入可以是布尔值,如果可以输入目标步骤,或者 MovingDirection 函数,返回 boolean 或者 Promise<boolean>。 这个函数将在每次执行操作时,用 direction 调用,在执行操作时,会导致当前步骤的变更。 然后返回 true,当步骤变更应该成功和 false 时返回。

    [canExit ]

    在你可以通过(。到下一步和上一步) 或者 Promise<boolean> 来决定步骤时,如果你有额外的检查或者验证,那么你可以通过向导的[canExit] 属性传递布尔值或者函数,并返回一个布尔值或者。 在执行操作时,将考虑这里布尔函数或者函数,这将导致当前步骤的转换。 如果 [canExit] 被绑定到一个布尔值,那么它需要是 true,以保留在 direction ( 向前和向后) 中的步骤。 如果只应该在一个 direction 中退出,则可以传递函数,并将一个 MovingDirection 返回给 [canExit] 并返回。 当执行操作时,将调用这里函数,这将导致当前步骤的更改。

    ( stepEnter )

    在进入向导步骤之前,如果需要调用某个函数进行初始化工作,你可以在向导步骤中添加 stepEnter 属性,如下所示:

    <aw-wizard-stepstepTitle="Second Step" (stepEnter)="enterSecondStep($event)"></aw-wizard-step>

    这将导致在向导移到这里步骤时调用 enterSecondStep 函数。 当向导的第一步包含 stepEnter 函数时,当用户从后面步骤移到第一步时,它不仅被调用。 事件发射器将调用给定函数,该参数包含用户的MovingDirection。 如果用户后退,例如从第三步到第二步或者第一步,那么 MovingDirection.Backwards 将被传递给函数。 如果用户前进,MovingDirection.Forwards 将被传递给函数。

    ( stepExit )

    类似于 stepEnter,如果希望每次向带有 awNextStep 或者 awPreviousStep 指令的组件退出一个函数时,可以向向导步骤中添加 stepExit 属性。 stepEnter 一样,可以用类型为 MovingDirection的参数调用给定函数,该参数在该函数中,步骤被退出。

    参数概述

    可能的<aw-wizard-step> 参数:

    参数 NAME 可能的值默认值
    [stepId ]string
    [stepTitle ]string
    [navigationSymbol ]{symbol: string, fontFamily?: string}{symbol: ''}
    [canEnter ]function(MovingDirection): boolean | function(MovingDirection): Promise<boolean> | booleantrue
    [canExit ]function(MovingDirection): boolean | function(MovingDirection): Promise<boolean> | booleantrue
    ( stepEnter )function(MovingDirection): void
    ( stepExit )function(MovingDirection): void

    <aw-wizard-completion-step>

    除了"正常"步骤组件 <aw-wizard-step> 之外,还可以定义可选的<aw-wizard-completion-step>aw-wizard-completion-step 指的是 final 向导步骤,即用户成功完成了向导的signalises向导。 用户输入 aw-wizard-completion-step 后,包括属于该向导的可选步骤( 包括属于该向导的可选步骤) 将被标记为已经完成。 这里外,用户被禁止将 aw-wizard-completion-step 保留到另一步骤,一旦输入。

    向导完成步骤的给定参数与常规向导步骤相同。 唯一不同的是,不能将 (stepExit)[canExit] 参数传递给 aw-wizard-completion-step,因为它不能退出。

    参数概述

    可能的<aw-wizard-completion-step> 参数:

    参数 NAME 可能的值默认值
    [stepId ]string
    [stepTitle ]string
    [navigationSymbol ]{symbol: string, fontFamily?: string}{symbol: ''}
    [canEnter ]function(MovingDirection): boolean | function(MovingDirection): Promise<boolean> | booleantrue
    ( stepEnter )function(MovingDirection): void

    指令

    [awEnableBackLinks ]

    在某些情况下,可能需要允许用户保留输入的aw-wizard-completion-step。 在这种情况下,你可以通过将指令 [awEnableBackLinks] 添加到 aw-wizard-completion-step 来启用这一点。

    <aw-wizard-completion-stepawEnableBackLinks>
     Final wizard step
    </aw-wizard-completion-step>
    参数概述

    可能的awEnableBackLinks 参数:

    参数 NAME 可能的值默认值
    ( stepExit )function(MovingDirection): void

    [awWizardStepTitle ]

    有时,在 <aw-wizard-step><aw-wizard-completion-step> 中定义带有 stepTitle 属性的标题是不够的。 例如如果标题应该以其他字体书写,则为一个示例。 另一个例子是要根据屏幕或者窗口的可以用宽度选择标题。 在这种情况下,你可能需要为向导步骤的标题指定 html。 可以通过在 ng-template 组件上使用 [awWizardStepTitle] 指令 inside 来实现这一点。

    <aw-wizard-step (stepEnter)="enterStep($event)">
     <ng-templateawWizardStepTitle>
     <spanclass="hidden-sm-down">Delivery address</span>
     <spanclass="hidden-md-up">Address</span>
     </ng-template>
    </aw-wizard-step>

    注意,只有在 Angular 4中引入 ng-template,才可以将 [awWizardStepTitle] 与 Angular 一起使用。

    [awOptionalStep ]

    如果需要定义可选步骤,不需要继续执行下一步,可以将 awOptionalStep 指令添加到要声明的步骤。

    [awSelectedStep ]

    在某些情况下,设置默认向导步骤不是通过 static 编号是更好的选择。 设置默认向导步骤的另一种方法是使用 awSelectedStep 指令。 向任意向导步骤附加 awSelectedStep 指令时,它将标记为默认向导步骤,该步骤在向导启动后直接显示。

    [awGoToStep ]

    angular-archwizard 有三个指令,允许在各个步骤之间移动。 这些指令是 awPreviousStepasNextStepawGoToStep 指令。

    awGoToStep 指令需要接收输入,告知向导应该导航到哪个步骤,当有 awGoToStep 指令的元素被点击时,该向导就会出现。

    这里输入接受不同的参数:

    • 目标步骤索引: 输入的一个可能参数是目标步骤索引。 目标步骤索引始终为零,换句话说,的第一个步骤 inside的索引始终为零。

      要将目标步骤索引传递给 awGoToStep 指令,需要将以下json对象传递给该指令:

      <button [awGoToStep]="{ stepIndex: 2 }" (finalize)="finalizeStep()">Go directly to the third Step</button>
    • 目标步骤 id: 输入的另一个可能参数是目标步骤的唯一步骤 id。 可以为所有向导步骤通过它的输入 [stepId] 设置这里步骤 id。

      要向 awGoToStep 指令传递唯一目标步骤 id,需要将以下json对象传递给该指令:

      <button [awGoToStep]="{ stepId: 'unique id of the third step' }" (finalize)="finalizeStep()">Go directly to the third Step</button>
    • 当前步骤和目标步骤之间的步骤偏移: 或者,也可以将目标向导步骤设置为源步骤的偏移量,或者为绝对步骤索引或者唯一步骤id设置一个值:

      <button [awGoToStep]="{ stepOffset: 1 }" (finalize)="finalizeStep()">Go to the third Step</button>

    在所有的上面 示例中,单击"转到第三步"按钮会将用户移动到下一步( 第三步) 与按钮所属的步骤。 如果按钮是第二步的一部分,点击它将把用户移到第三步。

    在所有 上面 情况下,在 awGoToStep 指令中使用 [] 来告诉 Angular 这个参数被解释为javascript是很重要的。

    除了 static 值,你还可以从组件of类传递一个局部变量,它的中包含单击元素的当前步骤。 如果步骤转换依赖于某些应用程序依赖逻辑,这会很有用,这取决于用户输入。 这里,在 awGoToStep 指令中使用 [] 来告诉 Angular 这个参数被解释为javascript是很重要的。

    ( preFinalize )

    有时需要将事件发射器绑定到特定元素,该元素可以执行步骤转换。 这样的事件发射器可以绑定到元素的(preFinalize) 输出,该元素包含 awGoToStep 指令。 在向导转换到给定步骤之前,调用这里事件发射器。

    ( postFinalize )

    另外,也可以将事件发射器绑定到 (postFinalize),后者在向导转换到给定步骤后直接执行。

    ( 终结器)

    在调用终结事件发射器时,你还可以将它简单地绑定到 (finalize)finalizepreFinalize的同义词。

    参数概述

    可能的参数:

    参数 NAME 可能的值默认值
    [goToStep ]`WizardStepStepOffset
    ( preFinalize )function(): void
    ( postFinalize )function(): void
    ( 最终)function(): void

    [awNextStep ]

    通过向按钮或者链接 inside 添加一个 awNextStep 指令,你会自动向按钮或者链接添加一个 onClick 侦听器。 这里侦听器将自动更改当前选定的向导步骤,方法是单击该组件后的下一个向导步骤。

    <button (finalize)="finalizeStep()"awNextStep>Next Step</button>
    ( 终结器)

    awGoToStep 指令类似,awNextStep 指令提供了 preFinalizepostFinalizefinalize 输出,每次成功退出时都会调用这些输出,方法是单击包含 nextStep 指令的元素。

    在给定的代码剪切 上面 中,单击文本 Next Step 按钮,导致每次调用 finalize 函数,按钮被按下。

    参数概述

    可能的参数:

    参数 NAME 可能的值默认值
    ( preFinalize )function(): void
    ( postFinalize )function(): void
    ( 最终)function(): void

    [awPreviousStep ]

    通过向按钮或者链接添加 awPreviousStep 指令,可以将 onClick 监听器自动添加到按钮或者链接中,从而将向导更改为上一步骤。 这里侦听器将自动更改当前选定的向导步骤,方法是单击该组件后的前一个向导步骤。

    <button (finalize)="finalizeStep()"awPreviousStep>Previous Step</button>
    ( 终结器)

    awGoToStepawNextStep 指令一样,awPreviousStep 指令提供了一个 preFinalizepostFinalizefinalize 输出,每次成功退出时都会调用该元素,通过单击包含 awPreviousStep 指令的元素来调用。

    参数概述

    可能的参数:

    参数 NAME 可能的值默认值
    ( preFinalize )function(): void
    ( postFinalize )function(): void
    ( 最终)function(): void

    [awWizardStep ]

    在某些情况下,将向导步骤移到自定义组件可能是个好主意。 可以通过定义将 awWizardStep 指令添加到组件中来完成,该指令包含向导步骤。

    <aw-wizard>
     <aw-wizard-stepstepTitle="Steptitle 1">
     Step 1
     </aw-wizard-step>
     <custom-stepawWizardStepstepTitle="Steptitle 2"></custom-step>
     <aw-wizard-stepstepTitle="Steptitle 3">
     Step 3
     </aw-wizard-step>
    </aw-wizard>
    参数概述

    可能的awWizardStep 参数:

    参数 NAME 可能的值默认值
    [stepId ]string
    [stepTitle ]string
    [navigationSymbol ]{symbol: string, fontFamily?: string}{symbol: ''}
    [canEnter ]function(MovingDirection): boolean | function(MovingDirection): Promise<boolean> | booleantrue
    [canExit ]function(MovingDirection): boolean | function(MovingDirection): Promise<boolean> | booleantrue
    ( stepEnter )function(MovingDirection): void
    ( stepExit )function(MovingDirection): void

    [awWizardCompletionStep ]

    在自定义组件中定义普通向导步骤的可能性之外,还可以在自定义组件中定义向导完成步骤。 若要在自定义组件中定义向导完成步骤,需要将 [awWizardCompletionStep] 指令添加到自定义组件中,该自定义组件包含向导完成步骤。

    <aw-wizard>
     <aw-wizard-stepstepTitle="Steptitle 1">
     Step 1
     </aw-wizard-step>
     <custom-stepawWizardCompletionStepstepTitle="Completion steptitle">
     </custom-step>
    </aw-wizard>
    参数概述

    可能的awWizardCompletionStep 参数:

    参数 NAME 可能的值默认值
    [stepId ]string
    [stepTitle ]string
    [navigationSymbol ]{symbol: string, fontFamily?: string}{symbol: ''}
    [canEnter ]function(MovingDirection): boolean | function(MovingDirection): Promise<boolean> | booleantrue
    ( stepEnter )function(MovingDirection): void

    [awResetWizard ]

    有时还需要将向导重置为它的初始状态。 在这种情况下,你可以使用 awResetWizard 指令。 可以将这里指令添加到按钮或者链接中,例如。 单击这里元素时,向导将自动重置为它的defaultStepIndex

    此外,还可以定义 EventEmitter,这是在重新设置向导时调用的。 这里 EventEmitter 可以绑定到 awResetWizard 指令的(finalize) 输入。

    参数概述

    可能的awResetWizard 参数:

    参数 NAME 可能的值默认值
    ( 最终)function(): void

    访问向导组件实例

    有时需要直接访问向导组件。 在这种情况下,你可以通过以下方式在你自己的组件中获取所使用向导组件的实例:

    @ViewChild(WizardComponent)publicwizard: WizardComponent;

    获取 WizardComponent 对象后,可以通过 wizard.model 获取该向导的WizardState 实例,然后通过 wizard.navigation 获取 NavigationMode 实例。

    自定义向导样式表

    有时你喜欢在向导的某些部分使用自己的自定义 CSS,就像它的导航栏。 这是很容易做到的。 有多种方法可以供选择:

    在向导周围使用包装器:

    <divclass="my-custom-css-wrapper">
     <aw-wizard></aw-wizard>
    </div>

    或者将你的css包装类直接添加到向导元素:

    <aw-wizardclass="my-custom-css-wrapper"></aw-wizard>

    当覆盖已经在现有导航栏布局中定义的css属性时,需要使用 important。! 此外,还需要添加 encapsulation: ViewEncapsulation.None 用于定义该向导并重写它的布局的组件。 有关如何编写自己导航栏的其他信息,请查看现有导航栏布局,可以在 https://github.com/madoar/angular-archwizard/blob/master/src/components/wizard-navigation-bar.component.horizontal.lesshttps://github.com/madoar/angular-archwizard/blob/master/src/components/wizard-navigation-bar.component.vertical.less 找到。

    使用动态插入和删除的步骤

    在某些情况下,可以能需要删除或者插入向导初始化后的一个或者多个步骤。 在这种情况下,向导支持删除和插入DOM中的步骤。

    如果需要动态删除或者插入步骤,请注意包含向导的Angular 组件需要触发生命周期阶段中的一个 detectChanges() 调用。 可以通过将以下行添加到组件类来触发这里调用:

    constructor(private_changeDetectionRef: ChangeDetectorRef) {}ngAfterViewInit(): void {
     // Force another change detection in order to fix an occuring ExpressionChangedAfterItHasBeenCheckedErrorthis._changeDetectionRef.detectChanges();
    }

    如果早期步骤与当前步骤相比,已经被移除或者插入,向导将调整当前步骤的索引。

    请确保不删除步骤,向导当前显示,因为向导将是 inside 无效状态,这可以能导致异常。

    示例

    你可以在这里找到一个使用 angular-archwizard的基本示例项目。 示例的源可以在 angular-archwizard-demo 存储库中找到。 它说明了向导的外观以及不同的设置如何改变它的布局和行为。


    COM  angular  component  向导  
    相关文章