syncfusion-javascript-splitter

实现 Syncfusion TypeScript Splitter

Syncfusion Splitter 控件可帮助你在 Web 应用中创建复杂、响应式的多窗格布局。它内置调整大小、折叠/展开功能和全面的事件处理，并支持嵌套窗格及完整的编程控制。

何时使用此技能

• 设置 Splitter： 初始配置、依赖项安装、基本初始化
• 配置窗格： 尺寸（像素/百分比）、固定窗格与灵活窗格、最小值/最大值限制
• 方向： 水平布局与垂直布局
• 交互功能： 折叠/展开窗格、编程控制、动态管理窗格
• 内容： 加载 HTML 标记、文本内容或动态内容
• 调整大小： 配置调整大小行为、阻止调整大小、处理调整大小事件
• 样式： 自定义分隔条、调整大小手柄、箭头、颜色
• 复杂布局： 嵌套 Splitter、代码编辑器布局、多层窗格层级结构
• 国际化： 支持阿拉伯语、希伯来语及其他从右向左（RTL）书写的语言
• 事件处理： 使用所有 Splitter 事件（展开/折叠前后、调整大小、创建）
• API 方法： 以编程方式操作 splitter 状态（添加/移除窗格、展开/折叠、刷新）
• 高级配置： 持久化、清理、窗格重排、本地化管理

---

Splitter 概述与主要功能

Splitter 是一种灵活的布局组件，可以：

• 将容器划分为由可调整大小的分隔条隔开的多个窗格
• 支持水平（默认）和垂直方向
• 支持带展开/折叠图标的可折叠窗格
• 支持以像素或百分比设置灵活的尺寸
• 在调整大小时支持最小值/最大值限制
• 支持用于复杂布局的嵌套 Splitter
• 支持通过 CSS 自定义内置样式
• 支持面向从右向左书写语言的RTL
• 使用弹性布局自动调整窗格

---

文档与导航指南

API 参考（完整）

完整 API 参考 — 本文档
所有组件的全面文档：

• Splitter 属性 - 全部 12 个属性及代码示例
• 窗格属性 - 全部 8 个窗格配置属性
• 方法 - 全部 12 个方法及其参数和返回类型（addEventListener、addPane、appendTo、collapse、dataBind、destroy、expand、getRootElement、refresh、removeEventListener、removePane、Inject）
• 事件 - 全部 9 个事件及其参数文档（created、beforeExpand、expanded、beforeCollapse、collapsed、resizeStart、resizing、resizeStop、beforeSanitizeHtml）
• 事件参数 - 所有事件参数属性的完整文档

入门指南

references/getting-started.md

• 软件包依赖项（@syncfusion/ej2-layouts）
• npm 安装与设置
• CSS 导入（fluent2.css 主题）
• Splitter 组件的基本初始化
• HTML 标记与 DOM 结构
• 使用子元素创建窗格

核心概念：窗格与方向

references/split-panes-orientation.md

• 水平布局（默认行为）
• 垂直布局（orientation: 'Vertical' 属性）
• 方向 API 的使用方法
• 窗格分隔条（水平布局中为垂直分隔条，垂直布局中为水平分隔条）
• 使用 addPane() 方法动态管理窗格
• 使用 removePane() 方法动态移除窗格
• 两种方向的完整示例

窗格配置与尺寸

references/pane-configuration.md

• 以像素格式设置窗格尺寸（'200px'、'300px'）
• 以百分比格式设置窗格尺寸（'30%'、'50%'）
• 使用弹性布局自动调整尺寸
• 通过 paneSettings 设置固定窗格尺寸
• 最小值限制（min 属性）
• 最大值限制（max 属性）
• 灵活的末尾窗格行为

展开/折叠行为

references/collapse-expand.md

• 启用可折叠窗格（collapsible: true）
• 内置展开/折叠图标
• 用户触发的折叠/展开操作
• 针对特定窗格索引的编程式 expand() 方法
• 针对特定窗格索引的编程式 collapse() 方法
• 指定初始折叠状态（collapsed: true 属性）
• 事件处理和回调
• beforeExpand、expanded、beforeCollapse、collapsed 事件

窗格内容选项

references/pane-content.md

• 窗格中的 HTML 标记内容
• 文本内容字符串
• 通过子元素提供内部 HTML
• 动态内容属性
• 加载 HTML 元素
• 实用的内容示例

调整大小与约束

references/resizing-behavior.md

• 默认启用调整大小功能
• 调整大小拖动条功能
• 水平与垂直调整大小行为
• 调整大小时相邻窗格自动调整
• 最小值/最大值验证约束
• 禁止调整大小（resizable: false）
• 每个窗格配置中的 resizable 属性
• resizeStart、resizing、resizeStop 事件

样式与自定义

references/styling-customization.md

• 自定义分隔栏 CSS（.e-split-bar）
• 水平分隔栏样式（.e-split-bar-horizontal）
• 垂直分隔栏样式（.e-split-bar-vertical）
• 悬停和激活状态样式
• 自定义调整大小手柄（.e-resize-handler）
• 自定义分隔栏箭头（.e-navigate-arrow）
• 颜色和主题自定义

复杂布局与嵌套

references/layouts-nested.md

• 创建嵌套分隔器
• 代码编辑器风格布局（水平 + 垂直）
• 外层和内层分隔器配置
• 逐步实现嵌套
• 多个嵌套层级
• 复杂的多窗格层级结构

全球化（RTL）

references/globalization.md

• 支持从右向左（RTL）布局
• 配置 enableRtl 属性
• 支持阿拉伯语、希伯来语和其他语言的 RTL 布局
• 默认采用从左向右（LTR）行为（enableRtl: false）
• RTL 样式调整

---

快速入门示例

import { Splitter } from '@syncfusion/ej2-layouts';

// Initialize Splitter with horizontal orientation (default)
let splitObj: Splitter = new Splitter({
    height: '250px',
    width: '600px',
    paneSettings: [
        { size: '200px', content: 'Pane 1' },
        { size: '200px', content: 'Pane 2' },
        { size: '200px', content: 'Pane 3' }
    ]
});

// Render to DOM
splitObj.appendTo('#splitter');

HTML：

<div id="splitter">
    <div></div>
    <div></div>
    <div></div>
</div>

---

常见模式

模式 1：带最小值/最大值的响应式窗格

let splitObj: Splitter = new Splitter({
    height: '300px',
    width: '100%',
    paneSettings: [
        { size: '30%', min: '20%', max: '50%' },
        { size: '40%', min: '30%', max: '60%' },
        { size: '30%', min: '20%', max: '50%' }
    ]
});
splitObj.appendTo('#splitter');

模式 2：带初始状态的可折叠窗格

let splitObj: Splitter = new Splitter({
    height: '300px',
    paneSettings: [
        { collapsible: true, size: '250px', content: 'Sidebar', collapsed: false },
        { collapsible: true, size: '250px', content: 'Details', collapsed: true }
    ]
});
splitObj.appendTo('#splitter');

模式 3：垂直分隔（堆叠）

let splitObj: Splitter = new Splitter({
    height: '400px',
    orientation: 'Vertical',
    paneSettings: [
        { size: '150px' },
        { size: '200px' },
        { size: '150px' }
    ]
});
splitObj.appendTo('#splitter');

模式 4：嵌套分隔器（代码编辑器布局）

// Outer vertical splitter
let verticalSplit: Splitter = new Splitter({
    height: '400px',
    orientation: 'Vertical',
    paneSettings: [
        { size: '250px', min: '30%' }
    ]
});
verticalSplit.appendTo('#verticalSplitter');

// Inner horizontal splitter (inside first pane)
let horizontalSplit: Splitter = new Splitter({
    height: '220px',
    paneSettings: [
        { size: '29%', min: '23%' },
        { size: '20%', min: '15%' },
        { size: '35%', min: '35%' }
    ]
});
horizontalSplit.appendTo('#horizontalSplitter');

模式 5：事件处理——阻止折叠

let splitObj: Splitter = new Splitter({
    height: '300px',
    paneSettings: [
        { collapsible: true, size: '250px', content: 'Important Pane' },
        { collapsible: true, size: '250px', content: 'Other Pane' }
    ],
    beforeCollapse: (args: BeforeExpandEventArgs) => {
        // Prevent collapse of first pane
        if (args.index[0] === 0) {
            args.cancel = true;
            console.log('First pane cannot be collapsed');
        }
    }
});
splitObj.appendTo('#splitter');

模式 6：动态添加/移除窗格

let splitObj: Splitter = new Splitter({
    height: '300px',
    paneSettings: [
        { size: '50%', content: 'Pane 1' },
        { size: '50%', content: 'Pane 2' }
    ]
});
splitObj.appendTo('#splitter');

// Add a new pane
document.getElementById('addBtn').addEventListener('click', () => {
    splitObj.addPane({ size: '200px', content: 'New Pane' }, 1);
});

// Remove a pane
document.getElementById('removeBtn').addEventListener('click', () => {
    splitObj.removePane(1);
});

模式 7：编程式展开/折叠

let splitObj: Splitter = new Splitter({
    height: '300px',
    paneSettings: [
        { collapsible: true, size: '250px', content: 'Pane 1', collapsed: true },
        { collapsible: true, size: '250px', content: 'Pane 2' }
    ]
});
splitObj.appendTo('#splitter');

// Expand pane
document.getElementById('expandBtn').addEventListener('click', () => {
    splitObj.expand(0);
});

// Collapse pane
document.getElementById('collapseBtn').addEventListener('click', () => {
    splitObj.collapse(0);
});

模式 8：跟踪调整大小事件

let splitObj: Splitter = new Splitter({
    height: '300px',
    paneSettings: [
        { size: '250px', content: 'Pane 1' },
        { size: '250px', content: 'Pane 2' }
    ],
    resizeStart: (args: ResizeEventArgs) => {
        console.log('Resize started on pane:', args.index);
    },
    resizing: (args: ResizingEventArgs) => {
        console.log('Resizing... New sizes:', args.paneSize);
    },
    resizeStop: (args: ResizingEventArgs) => {
        console.log('Resize completed. Final sizes:', args.paneSize);
    }
});
splitObj.appendTo('#splitter');

模式 9：持久化分隔器状态

let splitObj: Splitter = new Splitter({
    height: '300px',
    enablePersistence: true, // Save state to localStorage
    paneSettings: [
        { size: '250px', content: 'Pane 1' },
        { size: '250px', content: 'Pane 2' }
    ]
});
splitObj.appendTo('#splitter');
// State automatically persists across page reloads

模式 10：RTL 支持

let splitObj: Splitter = new Splitter({
    height: '300px',
    enableRtl: true,
    paneSettings: [
        { size: '50%', content: 'محتوى عربي' }, // Arabic content
        { size: '50%', content: 'תוכן עברי' }   // Hebrew content
    ]
});
splitObj.appendTo('#splitter');

完整 API 参考

有关所有属性、方法和事件的详细示例，请参阅完整 API 参考。

Splitter 属性

Splitter 组件的所有可用属性完整列表：

属性	类型	默认值	描述
height	string	'100%'	Splitter 容器的高度
width	string	'100%'	Splitter 容器的宽度
orientation	'Horizontal' | 'Vertical'	'Horizontal'	布局方向——参见 方向指南
paneSettings	PanePropertiesModel[]	[]	配置每个窗格
separatorSize	number	1	窗格之间分隔条的宽度
cssClass	string	''	用于设置样式的自定义 CSS 类
enableRtl	boolean	false	启用从右向左布局——参见 RTL 指南
enabled	boolean	true	启用或禁用组件交互
enablePersistence	boolean	false	在页面重新加载后保留窗格状态
enableReversePanes	boolean	false	重新排列窗格
enableHtmlSanitizer	boolean	true	清理 HTML 内容以防止 XSS
locale	string	'en-US'	本地化覆盖设置

→ 查看 api-reference.md 中的示例

窗格属性

paneSettings 数组中每个窗格可用的配置属性：

属性	类型	默认值	描述
size	string	自动	窗格大小，单位为像素（'200px'）或百分比（'30%'）
min	string	无	窗格大小下限
max	string	无	窗格大小上限
collapsible	boolean	false	启用折叠/展开图标
collapsed	boolean	false	初始折叠状态
resizable	boolean	true	允许调整此窗格的大小
content	string | HTMLElement	无	窗格的 HTML 内容
cssClass	string	''	用于设置窗格样式的自定义 CSS 类

→ 查看 api-reference.md 中的示例

方法

方法	参数	返回值	描述
addPane()	paneProperties, index	void	动态添加窗格——参见 拆分窗格
removePane()	index	void	动态移除窗格——参见 拆分窗格
expand()	index	void	以编程方式展开窗格——参见 折叠/展开
collapse()	index	void	以编程方式折叠窗格——参见 折叠/展开
refresh()	—	void	重新渲染组件
destroy()	—	void	清理组件
getRootElement()	—	HTMLElement	获取根元素
dataBind()	—	void	应用待处理的更改
appendTo()	selector?	void	将组件挂载到 DOM——参见 入门指南
addEventListener()	eventName, handler	void	添加事件处理程序
removeEventListener()	eventName, handler	void	移除事件处理程序
Inject()	moduleList	void	注入模块

→ 查看 api-reference.md 中的示例

事件与事件参数

事件	触发时机	参数	描述
created	初始化后	Object	组件已初始化
beforeExpand	窗格展开前	BeforeExpandEventArgs	可取消 — 阻止展开
expanded	窗格展开后	ExpandedEventArgs	展开已完成
beforeCollapse	窗格折叠前	BeforeExpandEventArgs	可取消 — 阻止折叠
collapsed	窗格折叠后	ExpandedEventArgs	折叠已完成
resizeStart	开始调整大小时	ResizeEventArgs	可取消
resizing	调整大小期间	ResizingEventArgs	持续更新
resizeStop	完成调整大小时	ResizingEventArgs	可获取最终尺寸
beforeSanitizeHtml	清理 HTML 前	BeforeSanitizeHtmlArgs	自定义清理

→ 在 api-reference.md 中查看示例

事件参数

BeforeExpandEventArgs（用于：beforeExpand、beforeCollapse）

• cancel（boolean）：设为 true 可取消操作
• element（HTMLElement）：根元素
• event（Event）：原生事件
• index（number[]）：窗格索引
• pane（HTMLElement[]）：窗格元素
• separator（HTMLElement）：分隔条元素

ExpandedEventArgs（用于：expanded、collapsed）

• element（HTMLElement）：根元素
• event（Event）：原生事件
• index（number[]）：窗格索引
• pane（HTMLElement[]）：窗格元素
• separator（HTMLElement）：分隔条元素

ResizeEventArgs（用于：resizeStart）

• cancel（boolean）：设为 true 可停止调整大小
• element（HTMLElement）：正在调整大小的窗格元素
• event（Event）：原生事件
• index（number[]）：窗格索引
• pane（HTMLElement[]）：窗格元素
• separator（HTMLElement）：分隔条元素

ResizingEventArgs（用于：resizing、resizeStop）

• element（HTMLElement）：正在调整大小的窗格元素
• event（Event）：原生事件
• index（number[]）：窗格索引
• pane（HTMLElement[]）：窗格元素
• paneSize（number[]）：当前/最终窗格尺寸
• separator（HTMLElement）：分隔条元素

BeforeSanitizeHtmlArgs（用于：beforeSanitizeHtml）

• cancel（boolean）：如有需要，可阻止清理
• helper（Function）：自定义清理回调
• selectors（SanitizeSelectors）：XSS 阻止列表配置

---

快速参考

Splitter 核心属性：

• height、width → 容器尺寸
• orientation → 'Horizontal'（默认）或 'Vertical'
• paneSettings → 窗格配置数组
• enableRtl → 支持从右向左的布局
• separatorSize → 窗格之间的间隙宽度（默认：1px）

窗格关键属性：

• size → 尺寸（'200px' 或 '30%'）
• min / max → 调整大小限制
• collapsible → 启用折叠图标（默认：false）
• collapsed → 初始状态
• resizable → 允许调整大小（默认：true）
• content → HTML 内容或文本

---

常见用例

• 仪表板布局： 可调整宽度的侧边栏 + 内容区 → 使用可折叠的左侧窗格和灵活的右侧窗格
• IDE/代码编辑器： 使用嵌套 Splitter 的多窗格编辑器 → 文件资源管理器、代码编辑器、控制台
• 响应式管理面板： 带有最小/最大限制的可折叠分区，便于在移动设备上调整大小
• 多文档界面（MDI）： 通过水平和嵌套垂直分割来堆叠/排列多个文档

---

后续步骤

1. 从入门指南开始 → 设置依赖项并进行基本初始化
2. 选择方向 → 并排布局使用 Horizontal，堆叠布局使用 Vertical
3. 配置窗格 → 设置尺寸、最小/最大限制和可折叠行为
4. 添加内容 → 加载 HTML 标记或文本
5. 按需设置样式 → 自定义颜色、边框和调整大小控件
6. 添加嵌套 Splitter → 用于复杂布局（高级）

如有具体实现问题，请参阅上方导航指南中的相应参考文件。