GrapesJS Style Manager 之 Sector 模块完全指南：属性、API 与底层实现剖析

GrapesJS Style Manager 之 Sector 模块完全指南：属性、API 与底层实现剖析

【免费下载链接】grapesjsFree and Open source Web Builder Framework. Next generation tool for building templates without coding项目地址: https://gitcode.com/GitHub_Trending/gr/grapesjs

在 GrapesJS 的 Style Manager（样式管理器）中，Sector（分类/分区）是承载 CSS 属性分组的最核心概念——它将纷繁复杂的 CSS 属性（如排版、尺寸、背景、弹性布局等）按语义归类，让用户能按区块高效地自定义组件样式。本文基于 docs/api/sector.md 官方 API 文档，并结合packages/core/src/style_manager/下的模型、视图、配置与测试源码，系统讲解 Sector 的完整属性定义、全部实例方法与底层实现原理。读完本文，你将掌握如何在 GrapesJS 中创建、查询、更新、删除 Sector，理解其可见性、展开状态与属性过滤机制，并能独立定制出符合业务场景的样式管理面板。

Sector 在 Style Manager 中的定位

GrapesJS 官方 API 文档（docs/api/style_manager.md）开篇即定义："With Style Manager you build categories (called sectors) of CSS properties which could be used to customize the style of components."——即 Style Manager 通过「Sector」这种分类容器来组织可作用于组件样式的 CSS 属性。

从代码结构看，Sector 是整个 Style Manager 数据层的中枢：

• Sector（packages/core/src/style_manager/model/Sector.ts）继承自 Backbone 风格的基础Model，封装单个分类的模型逻辑；
• Sectors（packages/core/src/style_manager/model/Sectors.ts）继承Collection，是Sector的集合容器；
• SectorView（packages/core/src/style_manager/view/SectorView.ts）负责 Sector 在面板中的渲染与交互；
• StyleManager（packages/core/src/style_manager/index.ts）作为模块入口，提供addSector、getSector、getSectors、removeSector等对 Sector 集合的操作。

当用户选中一个组件时，Style Manager 面板中呈现的就是一组 Sector 列表，每个 Sector 内再展开对应的属性编辑器（Property View）。因此，Sector 是理解 Style Manager 工作原理的第一站。

Sector 的属性定义（Properties）

根据 docs/api/sector.md，Sector 暴露的公开属性如下：

对应到源码，Sector模型在defaults()中给出了默认值与更多内部字段（见 Sector.ts）：

defaults() { return { id: '', name: '', open: true, // 默认展开 visible: true, // 默认可见 extendBuilded: true, properties: [], // 初始为空，构造时会被替换为 Properties 集合 }; }

补充说明源码中出现的几个字段：

• visible（Boolean）：Sector 是否可见。Style Manager 会根据当前选中组件是否具有可样式化的属性来动态调整该值，见后文isVisible一节。
• extendBuilded（Boolean）：当使用buildProps构建属性时，是否用用户传入的属性定义覆盖（extend）内置属性定义，默认true。
• properties在构造完成后不再是普通数组，而是被替换为一个Properties集合实例（propsModel = new Properties(props, { em })），后续通过getProperties()访问。

id 的自动生成规则

官方文档说明id是可选项。源码中，如果构造 Sector 时未显式提供id，会自动从name生成：

!this.get('id') && this.set('id', name.replace(/ /g, '_').toLowerCase());

即：将name中的空格替换为下划线_并转为小写。例如名称为My Sector的 Sector，其 id 会自动变为my_sector。这一规则在编写配置时值得注意——它决定了后续通过getSector(id)查询时需要使用的 id 值。

properties 的构建：buildProps 与内置属性工厂

Sector 构造函数会根据配置构建属性列表，核心逻辑为（Sector.ts）：

1. 若提供了buildProps（字符串数组，如['display', 'position']），则调用this.buildProperties()，通过em.Styles.builtIn（内置PropertyFactory）把属性名批量解析为完整的属性定义；
2. 若properties数组中的元素是字符串，则将其视为属性名，同样调用buildProperties()解析；
3. 若同时存在buildProps与properties，则通过extendProperties()将用户定义与内置定义合并，extendBuilded决定合并方向（extend(prop, mProp)还是直接用mProp）；
4. 每个属性定义还会经过checkExtend()处理extend指令，支持基于已有属性（含嵌套属性）做扩展。

这套机制意味着：Sector 的 properties 配置既可以只给属性名字符串，也可以给完整的 Property 定义对象，还可以混合使用。示例：

const editor = grapesjs.init({ styleManager: { sectors: [ { id: 'my-sector', name: '我的分类', open: false, properties: [ 'display', // 字符串：由内置工厂解析 { property: 'my-prop', type: 'select', options: [{ id: 'a', label: 'A' }] }, // 完整定义 ], }, ], }, });

Sector 实例方法详解

以下逐一讲解 docs/api/sector.md 中定义的 Sector 全部实例方法，并结合源码说明其行为与边界。

getId()

获取 Sector 的 id：

getId(): string { return this.get('id')!; }

返回String。若创建时未指定 id，返回的是按上述规则自动生成的 id。

getName()

获取 Sector 名称，返回String。源码实现（Sector.ts）并非简单返回name字段，而是优先查找国际化翻译：

getName(): string { const id = this.getId(); return this.em?.t(`styleManager.sectors.${id}`) || this.get('name'); }

也就是说，如果当前 i18n 语言包中存在styleManager.sectors.<id>对应的翻译，则返回翻译文本；否则回退到name字段。GrapesJS 内置英文语言包（packages/core/src/i18n/locale/en.js）中预置了general、layout、typography、decorations、extra、flex、dimension等 Sector id 的翻译，因此默认 Sector 在不同语言环境下会自动切换显示名称。

setName(value)

更新 Sector 名称，参数value为String类型的新名称：

setName(value: string) { return this.set('name', value); }

此方法只更新name字段，不会改变id。若需要同时影响 id，应显式调用模型层面的set('id', ...)（API 文档未暴露此方法，属于模型内部能力）。

isOpen()

检查 Sector 是否处于展开状态，返回Boolean：

isOpen() { return !!this.get('open'); }

setOpen(value)

更新 Sector 的展开状态，参数value为Boolean：

setOpen(value: boolean) { return this.set('open', value); }

设置后会触发模型的change:open事件，进而驱动视图更新（见下文「视图层联动」）。

isVisible()

检查 Sector 是否可见，返回Boolean：

isVisible() { return !!this.get('visible'); }

源码中visible的取值并非静态配置，而是由 Style Manager 在每次选中目标变化时动态计算（见 index.ts 中__upProps的逻辑）：遍历每个 Sector 的 Property，调用prop.__checkVisibility()判断各属性对当前组件是否可样式化（受组件stylable/unstylable配置影响），只要 Sector 内存在任一可见属性，Sector 本身即保持可见；若所有属性都不可见，则该 Sector 自动隐藏。测试用例（packages/core/test/specs/style_manager/model/Sectors.ts）验证了：选中带stylable列表的组件时，无关 Sector 的isVisible()变为false，且其中所有属性的isVisible()也同步为false；选中带unstylable列表的组件时则相反。

getProperties(opts)

获取 Sector 的属性（Property）列表，返回Array<Property>：

getProperties(opts: { withValue?: boolean; withParentValue?: boolean } = {}) { const props = this.properties; const res = (props.models ? [...props.models] : props) as Property[]; return res.filter((prop) => { let result = true; if (opts.withValue) { result = prop.hasValue({ noParent: true }); } if (opts.withParentValue) { const hasVal = prop.hasValue({ noParent: true }); result = !hasVal && prop.hasValue(); } return result; }); }

两个可选参数的行为区别如下：

例如，选中一个类名为.btn的按钮时，.btn规则自身设置了color: red，而margin定义在父级规则上。此时：

const sector = styleManager.getSector('typography'); sector.getProperties({ withValue: true }); // 包含 color，不包含 margin sector.getProperties({ withParentValue: true }); // 包含 margin（继承值），不包含 color

此外，源码中还提供了两个 API 文档未列出、但对二次开发很有用的内部方法：getProperty(id)按 id 查找单个属性，addProperty(property, opts)向 Sector 追加属性（opts.at可指定插入位置索引）。

视图层联动：open 与 visible 如何作用于界面

Sector 的模型状态变化会实时反映到 Style Manager 面板。SectorView（packages/core/src/style_manager/view/SectorView.ts）在构造时监听模型事件：

this.listenTo(model, 'destroy remove', this.remove); this.listenTo(model, 'change:open', this.updateOpen); this.listenTo(model, 'change:visible', this.updateVisibility);

• updateOpen()：根据model.isOpen()为 Sector 根元素添加/移除open样式类，并直接控制属性容器display为''或none，实现展开/折叠。
• updateVisibility()：根据model.isVisible()设置根元素的display样式，实现 Sector 整体显隐。
• 用户点击 Sector 标题栏（click [data-sector-title]）时，toggle()会调用model.setOpen(!model.get('open'))翻转展开状态。

渲染时，视图根据model.getName()渲染标题标签，并根据model.getId()生成形如sm-sector__typography的 CSS 类名（${pfx}sector ${pfx}sector__${id} no-select），方便针对特定 Sector 定制样式。同时SectorView.render()会创建PropertiesView渲染其内部的属性集合。

通过 StyleManager 模块操作 Sector

docs/api/sector.md聚焦 Sector 本身，而实际开发中 Sector 的增删查改通常经由 docs/api/style_manager.md 中的 StyleManager 模块方法完成，两者是同一数据体系的两面。常用方法如下：

addSector(id, sector, options)

新增 Sector。若 id 已存在，则直接返回已有的 Sector 而不重复创建（幂等语义），该行为在测试中也有明确验证（packages/core/test/specs/style_manager/index.ts）：

const styleManager = editor.StyleManager; const sector = styleManager.addSector('mySector', { name: 'My sector', open: true, properties: [{ name: 'My property' }], }, { at: 0 }); // 传入 { at: 0 } 可把新 Sector 放到列表开头，默认追加到末尾

getSector(id, opts)

按 id 查询 Sector，返回Sector | null；传入{ warn: true }时，若不存在会通过编辑器输出'<sectorId>' sector not found警告日志（源码见 index.ts 与_logNoSector）。

getSectors(opts)

获取全部 Sector：

const sectors = styleManager.getSectors(); // 返回 Sectors 集合 const sectorsArray = styleManager.getSectors({ array: true }); // 返回 Sector 数组 const visibleSectors = styleManager.getSectors({ visible: true }); // 仅返回可见 Sector

removeSector(id)

按 id 移除 Sector 并返回被移除的实例。

组合示例：动态管理 Sector

const sm = editor.StyleManager; // 新增 sm.addSector('advanced', { name: '高级', properties: ['opacity', 'transition', 'transform'], }); // 改名并展开 const sec = sm.getSector('advanced'); sec && sec.setName('高级样式'); sec && sec.setOpen(true); // 仅取当前组件实际用到的属性 const usedProps = sec?.getProperties({ withValue: true }) ?? []; // 删除 sm.removeSector('advanced');

默认 Sector 配置：一份可对照的完整示例

Style Manager 的默认配置（packages/core/src/style_manager/config/config.ts）内置了 6 个 Sector，是理解 Sector 定义格式最直接的参考：

sectors: [ { name: 'General', open: false, properties: ['display', 'float', 'position', 'top', 'right', 'left', 'bottom'] }, { name: 'Flex', open: false, properties: ['flex-direction', 'flex-wrap', 'justify-content', 'align-items', 'align-content', 'order', 'flex-basis', 'flex-grow', 'flex-shrink', 'align-self'] }, { name: 'Dimension', open: false, properties: ['width', 'height', 'max-width', 'min-height', 'margin', 'padding'] }, { name: 'Typography', open: false, properties: ['font-family', 'font-size', 'font-weight', 'letter-spacing', 'color', 'line-height', 'text-align', 'text-shadow'] }, { name: 'Decorations',open: false, properties: ['background-color', 'border-radius', 'border', 'box-shadow', 'background'] }, { name: 'Extra', open: false, properties: ['opacity', 'transition', 'transform'] }, ],

观察可知：默认 Sector 都未显式指定id，因此其 id 由「名称转小写、空格转下划线」规则自动生成（如Typography→typography、Decorations→decorations），并与英文语言包中styleManager.sectors的翻译键一一对应。properties全部使用属性名字符串，交由内置PropertyFactory（builtIn）解析成完整的属性定义。你也可以在grapesjs.init({ styleManager: { sectors: [...] } })时整体覆盖或自定义这套 Sector 列表。

小结

Sector 是 GrapesJS Style Manager 的分组基石，承担了 CSS 属性的分类组织、展开折叠、动态显隐与国际化命名等职责。通过本文可以掌握：

• 属性体系：id、name、open、properties四个公开属性，以及源码层的visible、extendBuilded等扩展字段，id 自动生成规则与properties的字符串/对象混用构建方式；
• 实例方法：getId、getName（含 i18n 回退）、setName、isOpen、setOpen、isVisible、getProperties（含withValue/withParentValue过滤语义）；
• 运行机制：模型change:open/change:visible事件驱动SectorView实时更新界面，Style Manager 根据组件可样式化属性动态计算 Sector 可见性；
• 集成方式：通过editor.StyleManager的addSector/getSector/getSectors/removeSector与 Sector 联动，配合默认配置与测试用例理解各 API 的实际行为边界。

无论你是想定制默认样式面板、按组件类型动态展示属性分类，还是基于 Style Manager 构建自定义主题编辑器，Sector 都是你绕不开的入口。

【免费下载链接】grapesjsFree and Open source Web Builder Framework. Next generation tool for building templates without coding项目地址: https://gitcode.com/GitHub_Trending/gr/grapesjs