syncfusion-winforms-card-layout

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing CardLayout in Windows Forms

在Windows Forms中实现CardLayout

When to Use This Skill

什么时候使用本技能

Use this skill when you need to:

Create a stack-based card layout that displays one card (control) at a time
Build wizard-style interfaces with sequential card navigation
Implement property pages with card switching
Organize multiple panels or controls as cards within a container
Navigate programmatically between different views or screens

当你需要完成以下需求时可使用本技能：

创建基于栈的卡片布局，每次仅展示一张卡片（控件）
构建支持顺序卡片导航的向导式界面
实现支持卡片切换的属性页
将多个面板或控件作为卡片组织在容器中
通过编程方式在不同视图或屏幕之间导航

Component Overview

组件概述

CardLayout

is a layout manager that organizes controls in a stack-of-cards appearance. Each control added to the layout becomes a "card," and only one card is visible at a time. The container acts as a stack of cards, with the first component added being initially visible. Cards can be configured with custom names, images, and sizing behavior.

Key Capabilities:

Set unique names for each card
Navigate between cards (First, Next, Previous, Last)
Configure layout modes (Default or Fill)
Maintain aspect ratio for child controls
Get/set selected card by name or index

CardLayout

是一个布局管理器，以卡片栈的形式组织控件。添加到布局中的每个控件都会成为一张“卡片”，每次仅一张卡片可见。容器相当于卡片栈，第一个添加的组件默认初始可见。你可以为卡片配置自定义名称、图片和尺寸行为。

核心能力：

为每张卡片设置唯一名称
在卡片之间导航（首张、下一张、上一张、末张）
配置布局模式（默认或填充）
为子控件保持宽高比
通过名称或索引获取/设置选中的卡片

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门

📄 Read: references/getting-started.md

Assembly and NuGet package installation
Adding CardLayout via designer or code
Creating and configuring container panel
Adding child controls as cards
Basic card navigation with Next/Previous methods

📄 阅读： references/getting-started.md

程序集和NuGet包安装
通过设计器或代码添加CardLayout
创建和配置容器面板
添加子控件作为卡片
使用Next/Previous方法实现基础卡片导航

Configuring CardLayout

配置CardLayout

📄 Read: references/configuring-cardlayout.md

Setting custom card names with SetCardName
Getting card names and components
Working with card indices (NextCardIndex, PreviousCardIndex)
Aspect ratio maintenance (MaintainAspectRatio)
Layout modes: Default vs Fill
Setting preferred and minimum sizes

📄 阅读： references/configuring-cardlayout.md

使用SetCardName设置自定义卡片名称
获取卡片名称和对应组件
处理卡片索引（NextCardIndex、PreviousCardIndex）
宽高比保持（MaintainAspectRatio）
布局模式：默认 vs 填充
设置首选尺寸和最小尺寸

Card Navigation

卡片导航

📄 Read: references/card-navigation.md

Selecting cards by name using SelectedCard property
Navigation methods: First(), Next(), Previous(), Last()
Using SmartTag in designer for card selection
Code-based navigation with buttons
ComboBox integration for card selection
Runtime card switching

📄 阅读： references/card-navigation.md

使用SelectedCard属性按名称选择卡片
导航方法：First()、Next()、Previous()、Last()
在设计器中使用SmartTag选择卡片
结合按钮实现基于代码的导航
集成ComboBox实现卡片选择
运行时卡片切换

Child Controls Configuration

子控件配置

📄 Read: references/child-controls.md

Adding child controls as cards to the layout
Image settings for cards
PreferredSize and MinimumSize configuration
Container and child control setup
Styling child controls

📄 阅读： references/child-controls.md

将子控件作为卡片添加到布局中
卡片的图片设置
PreferredSize和MinimumSize配置
容器和子控件设置
子控件样式设置

Quick Start Example

快速入门示例

csharp

using Syncfusion.Windows.Forms.Tools;
using System.Windows.Forms;

public class CardLayoutForm : Form
{
    private CardLayout cardLayout1;
    private Panel cardLayoutPanel;
    private Panel card1;
    private Panel card2;

    public CardLayoutForm()
    {
        // Initialize CardLayout
        cardLayout1 = new CardLayout();
        cardLayoutPanel = new Panel();
        cardLayoutPanel.BackColor = Color.White;
        cardLayoutPanel.Dock = DockStyle.Fill;

        // Set container
        cardLayout1.ContainerControl = cardLayoutPanel;

        // Create cards (panels)
        card1 = new Panel();
        card1.BackColor = Color.LightBlue;
        card1.Controls.Add(new Label { Text = "Card 1", AutoSize = true });

        card2 = new Panel();
        card2.BackColor = Color.LightGreen;
        card2.Controls.Add(new Label { Text = "Card 2", AutoSize = true });

        // Add cards to the main panel
        cardLayoutPanel.Controls.Add(card1);
        cardLayoutPanel.Controls.Add(card2);

        // Set card names
        cardLayout1.SetCardName(card1, "FirstCard");
        cardLayout1.SetCardName(card2, "SecondCard");

        // Navigate between cards
        cardLayout1.SelectedCard = "FirstCard";
        cardLayout1.Next(); // Display SecondCard

        // Add to form
        this.Controls.Add(cardLayoutPanel);
    }
}

csharp

using Syncfusion.Windows.Forms.Tools;
using System.Windows.Forms;

public class CardLayoutForm : Form
{
    private CardLayout cardLayout1;
    private Panel cardLayoutPanel;
    private Panel card1;
    private Panel card2;

    public CardLayoutForm()
    {
        // Initialize CardLayout
        cardLayout1 = new CardLayout();
        cardLayoutPanel = new Panel();
        cardLayoutPanel.BackColor = Color.White;
        cardLayoutPanel.Dock = DockStyle.Fill;

        // Set container
        cardLayout1.ContainerControl = cardLayoutPanel;

        // Create cards (panels)
        card1 = new Panel();
        card1.BackColor = Color.LightBlue;
        card1.Controls.Add(new Label { Text = "Card 1", AutoSize = true });

        card2 = new Panel();
        card2.BackColor = Color.LightGreen;
        card2.Controls.Add(new Label { Text = "Card 2", AutoSize = true });

        // Add cards to the main panel
        cardLayoutPanel.Controls.Add(card1);
        cardLayoutPanel.Controls.Add(card2);

        // Set card names
        cardLayout1.SetCardName(card1, "FirstCard");
        cardLayout1.SetCardName(card2, "SecondCard");

        // Navigate between cards
        cardLayout1.SelectedCard = "FirstCard";
        cardLayout1.Next(); // Display SecondCard

        // Add to form
        this.Controls.Add(cardLayoutPanel);
    }
}

Common Patterns

常用模式

Pattern 1: Wizard Interface

模式1：向导界面

Create sequential steps where users navigate forward/backward through cards:

csharp

private void NextButton_Click(object sender, EventArgs e)
{
    this.cardLayout1.Next();
}

private void PreviousButton_Click(object sender, EventArgs e)
{
    this.cardLayout1.Previous();
}

创建顺序步骤，用户可以在卡片之间前后导航：

csharp

private void NextButton_Click(object sender, EventArgs e)
{
    this.cardLayout1.Next();
}

private void PreviousButton_Click(object sender, EventArgs e)
{
    this.cardLayout1.Previous();
}

Pattern 2: Dropdown Card Selection

模式2：下拉选择卡片

Allow users to select cards from a dropdown list:

csharp

private void CardSelectionComboBox_SelectedIndexChanged(object sender, EventArgs e)
{
    string selectedCardName = CardSelectionComboBox.SelectedItem.ToString();
    this.cardLayout1.SelectedCard = selectedCardName;
}

允许用户从下拉列表中选择卡片：

csharp

private void CardSelectionComboBox_SelectedIndexChanged(object sender, EventArgs e)
{
    string selectedCardName = CardSelectionComboBox.SelectedItem.ToString();
    this.cardLayout1.SelectedCard = selectedCardName;
}

Pattern 3: Fill Container

模式3：填充容器

Make cards stretch to fill the entire container:

csharp

this.cardLayout1.LayoutMode = CardLayoutMode.Fill;

让卡片拉伸以填满整个容器：

csharp

this.cardLayout1.LayoutMode = CardLayoutMode.Fill;

Key Properties

核心属性

Property	Type	Description
`SelectedCard`	string	Gets/sets the current visible card by name
`LayoutMode`	CardLayoutMode	Gets/sets layout mode (Default or Fill)
`NextCardIndex`	int	Returns the index of the next card
`PreviousCardIndex`	int	Returns the index of the previous card
`ContainerControl`	Control	Gets/sets the container for the layout

属性	类型	描述
`SelectedCard`	string	按名称获取/设置当前可见的卡片
`LayoutMode`	CardLayoutMode	获取/设置布局模式（默认或填充）
`NextCardIndex`	int	返回下一张卡片的索引
`PreviousCardIndex`	int	返回上一张卡片的索引
`ContainerControl`	Control	获取/设置布局的容器

Key Methods

核心方法

Method	Purpose
`First()`	Display the first card
`Next()`	Display the next card
`Previous()`	Display the previous card
`Last()`	Display the last card
`SetCardName(Control, string)`	Assign a custom name to a card
`GetCardName(Control)`	Get the name of a card
`GetCardNames()`	Get all card names as array
`GetComponentFromName(string)`	Get control by card name
`SetMaintainAspectRatio(Control, bool)`	Configure aspect ratio maintenance

方法	用途
`First()`	展示第一张卡片
`Next()`	展示下一张卡片
`Previous()`	展示上一张卡片
`Last()`	展示最后一张卡片
`SetCardName(Control, string)`	为卡片分配自定义名称
`GetCardName(Control)`	获取卡片的名称
`GetCardNames()`	以数组形式返回所有卡片名称
`GetComponentFromName(string)`	通过卡片名称获取对应控件
`SetMaintainAspectRatio(Control, bool)`	配置宽高比保持规则