Back to Details

syncfusion-aspnetcore-switch

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion ASP.NET Core Switch Component

Syncfusion ASP.NET Core Switch组件实现教程

When to Use This Skill

何时使用本技能

Use this skill when your users need to:
  • Create toggle buttons/switches for boolean input (on/off, enabled/disabled, yes/no)
  • Add Switch controls to forms for user state selection
  • Configure Switch appearance (labels, size, colors)
  • Handle Switch state changes with event handlers
  • Style and customize the Switch component
  • Integrate Switch with ASP.NET Core models and backend logic
  • Implement validation and form submission with Switch values
当用户需要以下操作时使用本技能：
  • 创建切换按钮/开关用于布尔值输入（开/关、启用/禁用、是/否）
  • 为表单添加Switch控件供用户选择状态
  • 配置Switch外观（标签、尺寸、颜色）
  • 通过事件处理程序处理Switch状态变更
  • 对Switch组件进行样式定制
  • 将Switch与ASP.NET Core模型及后端逻辑集成
  • 结合Switch值实现验证与表单提交

About the Switch Component

关于Switch组件

The Syncfusion Switch (Toggle Button) is a lightweight, accessible input control for toggling between two states. Built on TypeScript/JavaScript, it integrates seamlessly with ASP.NET Core Razor markup and C# backend code.
Key Features:
  • Binary state toggle (checked/unchecked)
  • Custom on/off labels
  • Keyboard navigation support
  • Event-driven change detection
  • CSS-based customization
  • WCAG accessibility compliance
  • Lightweight and responsive
Syncfusion Switch（切换按钮）是一款轻量级、可访问的输入控件，用于在两种状态间切换。它基于TypeScript/JavaScript构建，可无缝集成到ASP.NET Core Razor标记和C#后端代码中。
核心特性：
  • 二元状态切换（选中/未选中）
  • 自定义开/关标签
  • 支持键盘导航
  • 事件驱动的变更检测
  • 基于CSS的定制
  • 符合WCAG无障碍标准
  • 轻量级且响应式

Documentation and Navigation Guide

文档与导航指南

Getting Started with Switch

Switch入门

📄 Read: references/getting-started.md
  • TagHelper registration and setup
  • NuGet package installation and verification
  • Creating your first Switch control
  • Setting on/off labels
  • Basic initialization and rendering
📄 阅读： references/getting-started.md
  • TagHelper注册与设置
  • NuGet包安装与验证
  • 创建首个Switch控件
  • 设置开/关标签
  • 基础初始化与渲染

Switch Properties and Configuration

Switch属性与配置

📄 Read: references/switch-properties.md
  • Understanding Switch properties (checked, disabled, name, value)
  • Property binding with ASP.NET Core models
  • Data model integration for forms
  • Binding Switch state to C# properties
  • Default values and initial state
📄 阅读： references/switch-properties.md
  • 理解Switch属性（checked、disabled、name、value）
  • 与ASP.NET Core模型进行属性绑定
  • 表单数据模型集成
  • 将Switch状态绑定到C#属性
  • 默认值与初始状态设置

Switch Events and State Management

Switch事件与状态管理

📄 Read: references/switch-events.md
  • Change event handler implementation
  • Detecting state transitions
  • Form submission with Switch values
  • Server-side validation
  • Tracking user interactions
📄 阅读： references/switch-events.md
  • 变更事件处理程序实现
  • 检测状态转换
  • 结合Switch值提交表单
  • 服务端验证
  • 跟踪用户交互

Styling and Customization

样式与定制

📄 Read: references/styling-customization.md
  • CSS classes for customization (wrapper, handle, inner)
  • Theme application (Material, Fabric, Bootstrap)
  • Custom appearance with CSS
  • Theme Studio integration
  • Advanced styling techniques
📄 阅读： references/styling-customization.md
  • 用于定制的CSS类（wrapper、handle、inner）
  • 主题应用（Material、Fabric、Bootstrap）
  • 使用CSS自定义外观
  • Theme Studio集成
  • 高级样式技巧

Advanced How-To Patterns

高级实现模式

📄 Read: references/advanced-how-to.md
  • Change Switch size (default vs small)
  • Enable right-to-left (RTL) support
  • Prevent or intercept state changes
  • Set disabled state based on conditions
  • Submit Switch values through forms
📄 阅读： references/advanced-how-to.md
  • 更改Switch尺寸（默认 vs 小型）
  • 启用从右到左（RTL）支持
  • 阻止或拦截状态变更
  • 根据条件设置禁用状态
  • 通过表单提交Switch值

Quick Start Example

快速入门示例

Basic Switch Implementation

基础Switch实现

cshtml
<!-- In ~/Pages/Shared/_ViewImports.cshtml (if not already added) -->
@addTagHelper *, Syncfusion.EJ2

<!-- In ~/Pages/Index.cshtml -->
<div class="switch-container">
    <label>Enable Notifications</label>
    <ejs-switch id="switchId"></ejs-switch>
</div>
cshtml
<!-- 在~/Pages/Shared/_ViewImports.cshtml中（若未添加） -->
@addTagHelper *, Syncfusion.EJ2

<!-- 在~/Pages/Index.cshtml中 -->
<div class="switch-container">
    <label>启用通知</label>
    <ejs-switch id="switchId"></ejs-switch>
</div>

Switch with Labels

带标签的Switch

cshtml
<ejs-switch id="switchWithLabels" 
            onLabel="ON" 
            offLabel="OFF">
</ejs-switch>
cshtml
<ejs-switch id="switchWithLabels" 
            onLabel="ON" 
            offLabel="OFF">
</ejs-switch>

Switch with Event Handling

带事件处理的Switch

cshtml
<ejs-switch id="switchWithEvent" 
            change="onChange">
</ejs-switch>

<script>
    function onChange(args) {
        console.log('Switch state changed:', args.checked);
        // Update UI or call server
    }
</script>
cshtml
<ejs-switch id="switchWithEvent" 
            change="onChange">
</ejs-switch>

<script>
    function onChange(args) {
        console.log('Switch状态已变更:', args.checked);
        // 更新UI或调用服务端
    }
</script>

Common Patterns

常见模式

Pattern 1: Bind Switch to Form Model
cshtml
<!-- Page Model: public bool NotificationEnabled { get; set; } -->
<ejs-switch id="notificationSwitch" 
            checked="@Model.NotificationEnabled"
            change="onNotificationChange">
</ejs-switch>

<script>
    function onNotificationChange(args) {
        // Update form data for submission
        document.getElementById('notificationValue').value = args.checked;
    }
</script>
Pattern 2: Disabled State with Conditional Logic
cshtml
<!-- Disable Switch based on condition -->
<ejs-switch id="premiumSwitch" 
            disabled="@(!Model.IsPremiumUser)">
</ejs-switch>
Pattern 3: Group Multiple Switches
cshtml
<div class="preferences">
    <div class="preference-item">
        <label>Email Notifications</label>
        <ejs-switch id="emailSwitch"></ejs-switch>
    </div>
    <div class="preference-item">
        <label>SMS Notifications</label>
        <ejs-switch id="smsSwitch"></ejs-switch>
    </div>
</div>
模式1：将Switch绑定到表单模型
cshtml
<!-- 页面模型: public bool NotificationEnabled { get; set; } -->
<ejs-switch id="notificationSwitch" 
            checked="@Model.NotificationEnabled"
            change="onNotificationChange">
</ejs-switch>

<script>
    function onNotificationChange(args) {
        // 更新表单数据以便提交
        document.getElementById('notificationValue').value = args.checked;
    }
</script>
模式2：带条件逻辑的禁用状态
cshtml
<!-- 根据条件禁用Switch -->
<ejs-switch id="premiumSwitch" 
            disabled="@(!Model.IsPremiumUser)">
</ejs-switch>
模式3：分组多个Switch
cshtml
<div class="preferences">
    <div class="preference-item">
        <label>邮件通知</label>
        <ejs-switch id="emailSwitch"></ejs-switch>
    </div>
    <div class="preference-item">
        <label>短信通知</label>
        <ejs-switch id="smsSwitch"></ejs-switch>
    </div>
</div>

Key Properties

核心属性

PropertyTypeDescriptionWhen to Use
checked
booleanInitial state (true = on, false = off)Set default switch position on page load
disabled
booleanDisable interaction (true/false)Show but prevent changes (permissions, loading)
name
stringHTML form name attributeForm submission and server-side binding
value
stringHTML form valueCustom value sent to server
onLabel
stringText shown in "on" stateClarify the enabled option
offLabel
stringText shown in "off" stateClarify the disabled option
change
functionEvent handler for state changesReact to user interaction
cssClass
stringCustom CSS class for stylingApply theme or custom appearance
属性类型描述使用场景
checked
boolean初始状态（true=开，false=关）页面加载时设置Switch默认位置
disabled
boolean禁用交互（true/false）显示但阻止变更（权限控制、加载状态）
name
stringHTML表单name属性表单提交与服务端绑定
value
stringHTML表单value属性发送到服务端的自定义值
onLabel
string"开"状态下显示的文本明确启用选项含义
offLabel
string"关"状态下显示的文本明确禁用选项含义
change
function状态变更的事件处理程序响应用户交互
cssClass
string用于样式定制的自定义CSS类应用主题或自定义外观

Common Use Cases

常见使用场景

  1. User Preferences - Enable/disable notifications, emails, analytics tracking
  2. Feature Toggles - Toggle experimental features, beta versions, maintenance mode
  3. Form Options - Accept/agree to terms, agree to share data, consent forms
  4. Admin Controls - Enable/disable users, features, or system settings
  5. Subscription States - Activate/deactivate subscriptions, trial versions, licenses
  1. 用户偏好设置 - 启用/禁用通知、邮件、分析跟踪
  2. 功能开关 - 切换实验性功能、测试版本、维护模式
  3. 表单选项 - 接受/同意条款、同意共享数据、授权表单
  4. 管理员控制 - 启用/禁用用户、功能或系统设置
  5. 订阅状态 - 激活/停用订阅、试用版本、许可证

Next Steps

后续步骤

  1. Start Here: Review Getting Started for initial setup
  2. Configure: Explore Switch Properties for your use case
  3. Handle Events: Learn Event Handling for interactivity
  4. Customize: Check Styling for appearance
For complete reference, visit the Syncfusion ASP.NET Core Switch Documentation.
  1. 入门： 查看入门指南完成初始设置
  2. 配置： 根据你的使用场景探索Switch属性
  3. 事件处理： 学习事件处理实现交互性
  4. 定制： 查看样式定制调整外观
如需完整参考，请访问Syncfusion ASP.NET Core Switch官方文档。