GrapesJS Property 属性模型完全指南从配置定义到 CSS 目标同步【免费下载链接】grapesjsFree and Open source Web Builder Framework. Next generation tool for building templates without coding项目地址: https://gitcode.com/GitHub_Trending/gr/grapesjs本篇指南系统讲解 GrapesJS 开源 Web 构建框架中样式管理器Style Manager的核心数据模型Property属性。Property 是样式管理器中每一个可编辑 CSS 属性如color、text-align、margin的模型载体负责值的解析、默认值回退、可见性判断以及与选中目标组件或 CSS 规则之间的双向同步。读完本文你将掌握 Property 的完整配置字段、全部公开 API、内置属性类型体系number / select / color / composite / stack 等并能在 docs/api/property.md 的基础上通过editor.StyleManager自行定义、扩展和联动属性。Property 在 Style Manager 中的定位GrapesJS 的 Style Manager 将可编辑样式按扇区Sector— 属性Property两级组织每个扇区包含一组属性每个属性对应一个或一组CSS 属性。Property 就是这一层级的模型对象其 API 文档见 docs/api/property.md而扇区模型的 API 见 docs/api/sector.md。在编辑器初始化时通过styleManager配置扇区与属性const editor grapesjs.init({ styleManager: { sectors: [ { name: My Sector, open: false, properties: [ { property: min-height, type: select, default: 100px, options: [{ id: 100px, label: 100 }] }, ], }, ], }, });默认配置见 packages/core/src/style_manager/config/config.ts内置了General、Flex、Dimension、Typography、Decorations、Extra六个扇区这些扇区引用的属性名如display、width、margin、box-shadow均来自内置属性工厂。编辑器实例化后通过editor.StyleManager获取模块即可用addProperty、getProperty、getProperties、removeProperty、select、addBuiltIn等 API 操作属性方法清单见 docs/api/style_manager.md。addProperty返回的正是Property模型实例const styleManager editor.StyleManager; const property styleManager.addProperty(mySector, { label: Minimum height, property: min-height, type: select, default: 100px, options: [{ id: 100px, label: 100 }, { id: 200px, label: 200 }], }, { at: 0 });Property 基础配置字段Properties创建 Property 时可配置以下基础字段即 docs/api/property.md 中的Properties小节字段类型说明idString属性 id例如my-property-idpropertyString关联的 CSS 属性名例如text-aligndefaultString属性的默认值labelString在 UI 中显示的标签例如Text AlignonChangeFunction?值变化回调onChange回调签名及用法onChange: ({ property, from, to }) { console.log(Changed property, property.getName(), { from, to }); }在源码 packages/core/src/style_manager/model/Property.ts 中PropertyProps接口还暴露了更多可用于配置的字段与上述基础字段共同构成完整的属性定义name显示名称初始化时会基于property自动推导capitalize(prop).replace(/-/g, )因此通常无需手动指定type属性类型决定使用哪个 Property 子类详见下文类型体系info属性说明信息value当前值iconUI 图标functionNameCSS 函数名如url、translateX配合值渲染成functionName(value)的形式visible是否可见默认truefixedValues固定候选值数组默认[initial, inherit]内置属性工厂另有[initial, inherit, auto]的变体full是否在 UI 中独占整行full-width默认falseimportant为true时值会被追加!importanttoRequire若为true属性默认隐藏仅当目标通过stylable-require显式声明需要它时才显示——官方建议将全部 SVG 相关属性配置为toRequire: true再在 SVG 组件上按需requirerequires依赖同目标上其他属性值条件全部满足才显示例如requires: { display: [flex, block], position: [absolute] }requiresParent依赖选中目标父元素的计算样式例如内置的flex-basis依赖父元素display: flexisVisible自定义可见性判断函数例如isVisible: ({ component }) component?.is(image)仅图片组件选中时显示status、className、parentTarget、extend等内部/扩展字段。defaults()中定义的基础默认值为name: 、property: 、type: 、defaults: 、info: 、value: 、icon: 、functionName: 、status: 、visible: true、fixedValues: [initial, inherit]、full: false、important: false、toRequire: false。属性类型体系type 决定模型与视图getType()返回属性类型类型在属性创建时确定并据此分配对应的 Property 子类默认类型为base。类型注册表见 packages/core/src/style_manager/model/Properties.ts内置类型与对应的模型/视图如下type模型视图说明basePropertyPropertyView默认类型通用文本输入number/integerPropertyNumberPropertyNumberView数值 单位输入selectPropertySelectPropertySelectView下拉选择radioPropertyRadioPropertyRadioView单选按钮组sliderPropertySliderPropertySliderView滑块colorPropertyPropertyColorView颜色选择器filePropertyPropertyFileView文件如图片 urlcompositePropertyCompositePropertyCompositeView组合属性子属性聚合为一个 CSS 简写stackPropertyStackPropertyStackView堆叠属性多层如 box-shadow内置属性工厂 packages/core/src/style_manager/model/PropertyFactory.ts 预定义了 70 个常用 CSS 属性例如数值型top、margin-*、padding-*、width、height、font-size、line-height等默认单位集unitsSize [px,%,em,rem,vh,vw]时间单位[s,ms]角度单位[deg,rad,grad]单选型float、position、text-align颜色型color默认black、background-color、border-color文件型background-imagefunctionName: url滑块型opacitymin: 0, max: 1, step: 0.01下拉型display、flex-direction、font-family、border-style、overflow、cursor等组合型margin、padding、border、border-radius堆叠型transition、box-shadow、text-shadow、background、transform。这些内置定义可通过styleManager.getBuiltIn(width)获取、getBuiltInAll()获取全部、addBuiltIn(prop, definition)新增或扩展。transform还演示了fromStyle/toStyle自定义逻辑把transform: rotateZ(45deg)拆解为transform-type与transform-value两个子属性。Property 核心 API 详解以下方法全部定义在 packages/core/src/style_manager/model/Property.ts测试用例覆盖见 packages/core/test/specs/style_manager/model/Properties.ts。标识类方法getId / getType / getName / getLabelgetId()返回属性 idthis.get(id)。getType()返回属性类型字符串默认base。getName()返回 CSS 属性名内部实际读取的是property字段。getLabel(opts {})返回 UI 标签。可传opts.locale默认true决定是否优先使用 i18n 模块的翻译串styleManager.properties.id找不到翻译时回退到name或label字段。值读取类方法getValue / hasValue / hasValueParent / getDefaultValuegetValue(opts {})返回当前值当属性没有值且未传noDefault时返回默认值即!hasValue() !noDefault ? getDefaultValue() : val。hasValue(opts {})判断属性是否有值。判定条件是value非undefined且非空串若传opts.noParent true则忽略来自父目标的值parentTarget。测试中hasValue()与hasValue({ noParent: true })的组合被广泛用于验证继承值场景见 Properties.ts 中 289-316 行等用例。hasValueParent()指示当前值是否来自父目标如另一个 CSSRule等价于hasValue() !hasValue({ noParent: true })。getDefaultValue()返回默认值优先读取default字段回退到defaults字段。getStyle生成 CSS 样式对象getStyle(opts {})返回该属性对应的 CSS 样式对象。传opts.camelCase可将属性名转为驼峰形式// 属性为 color 且值为 red 时 console.log(property.getStyle()); // { color: red };实现上内部调用__getFullValue()它会根据functionName包装成fn(value)如url(...)并在important为真时追加!important。对 composite/stack 类型getStyle被子类覆写见 PropertyComposite.ts 的getStyleFromProps可生成简写或拆分的多属性对象。upValue更新值并同步到目标upValue(value, opts {})是更新值的主入口变化会传播到选中的目标如 CSS 规则value新值字符串传入null或时等价于执行清除逻辑opts.partial若为true对目标的更新视为未完成不进入 UndoManageropts.noTarget若为true变化不会传播到选中目标。调用链为upValue → __parseValueparseValue 解析→ _upset 触发 change→ __upTargets → __upTargetsStyle → styleManager.addStyleTargets最终调用目标的addStyle写入样式参见 StyleManager.addStyleTargets 与测试中compTypeProp.upValue(1px 2px 3px 4px)后断言rule1.getStyle()的用例。parseValue还负责解析!important后缀以及 CSS 函数如translateX(10deg)解析为{ value: 10, unit: deg, functionName: translateX }并支持opts.numeric数值拆分。可见性与清理类方法isVisible / clear / canClearisVisible()返回属性是否可见读取visible字段。clear(opts {})清除值同样会传播到选中目标如清除对应 CSS 属性传opts.noTarget true可阻止传播。内部通过__getClearProps()将value置空并携带__clear标记。composite 类型覆写了clear会递归清除所有子属性。canClear()判断当前值是否直接来自选中目标因而可以被清除子属性场景下委托给父属性的__canClearProp。层级类方法getParent / isFullgetParent()若当前属性是子属性composite/stack 的成员返回其父 Property否则返回null。isFull()指示属性是否在 UI 中独占整行读取full字段。实战注册属性、监听变化与自定义类型注册一个下拉属性并监听变化const prop styleManager.addProperty(typography, { property: text-transform, type: select, default: none, options: [ { id: none, label: None }, { id: uppercase, label: UPPERCASE }, { id: capitalize, label: Capitalize }, ], onChange: ({ property, from, to }) { console.log(${property.getName()} changed, { from, to }); }, }); // 编程式更新值同步到选中目标 prop.upValue(uppercase);借助 PropertySelect 的动态选项能力见 PropertySelect.tsgetOptions()获取选项、setOptions([...])整体替换、addOption({ id, label })追加选项、getOptionLabel(id)结合 i18n 返回标签适用于字体列表等需要异步加载的选项。Number 属性的单位与范围见 PropertyNumber.ts可通过units: [px,%,em]、min、max、step配置输入约束使用getUnits()、getUnit()、getMin()、getMax()、getStep()读取upUnit(unit)更新单位并同步目标。注册自定义属性类型用于扩展 UI 控件见 StyleManager.addTypestyleManager.addType(my-custom-prop, { create({ props, change }) { const el document.createElement(div); el.innerHTML input typerange classmy-input min10 max50/; const inputEl el.querySelector(.my-input); inputEl.addEventListener(change, (event) change({ event })); inputEl.addEventListener(input, (event) change({ event, partial: true })); return el; }, emit({ props, updateStyle }, { event, partial }) { updateStyle(${event.target.value}px, { partial }); }, update({ value, el }) { el.querySelector(.my-input).value parseInt(value, 10); }, destroy() {}, });之后即可在扇区定义或addProperty中使用type: my-custom-prop。值同步与父目标机制Property 的值与目标样式并非同一存储属性模型持有value而实际 CSS 落在目标组件内联样式或 CSSRule上。__upTargets通过StyleManager.addStyleTargets({ [name]: value })把值写入所有选中目标反向地当选中目标变化时StyleManager.__upProp会读取目标样式并回填到属性__up标记避免循环触发。当属性自身没有值时Style Manager 会沿父规则链如标签选择器规则、id 规则等见getParentRules寻找继承值并通过__setParentTarget记录来源这正是hasValueParent()与hasValue({ noParent: true })存在的原因——UI 上可以据此区分直接设置的值与继承的值并决定clear()是否可用canClear()。总结Property 是 GrapesJS 样式管理器的最小可编辑单元本文覆盖了它的全部基础配置字段、9 种内置类型、15 个公开方法及其源码实现路径。实际开发中建议用addProperty注册业务属性、用onChange做联动、用requires/requiresParent/isVisible控制上下文相关的显隐、用addBuiltIn扩展全局内置属性、用addType实现完全自定义的 UI 控件。相关实现与验证可直接查阅 Property.ts、PropertyFactory.ts、Properties.ts 及测试套件 Properties.ts。【免费下载链接】grapesjsFree and Open source Web Builder Framework. Next generation tool for building templates without coding项目地址: https://gitcode.com/GitHub_Trending/gr/grapesjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
GrapesJS Property 属性模型完全指南：从配置定义到 CSS 目标同步
GrapesJS Property 属性模型完全指南从配置定义到 CSS 目标同步【免费下载链接】grapesjsFree and Open source Web Builder Framework. Next generation tool for building templates without coding项目地址: https://gitcode.com/GitHub_Trending/gr/grapesjs本篇指南系统讲解 GrapesJS 开源 Web 构建框架中样式管理器Style Manager的核心数据模型Property属性。Property 是样式管理器中每一个可编辑 CSS 属性如color、text-align、margin的模型载体负责值的解析、默认值回退、可见性判断以及与选中目标组件或 CSS 规则之间的双向同步。读完本文你将掌握 Property 的完整配置字段、全部公开 API、内置属性类型体系number / select / color / composite / stack 等并能在 docs/api/property.md 的基础上通过editor.StyleManager自行定义、扩展和联动属性。Property 在 Style Manager 中的定位GrapesJS 的 Style Manager 将可编辑样式按扇区Sector— 属性Property两级组织每个扇区包含一组属性每个属性对应一个或一组CSS 属性。Property 就是这一层级的模型对象其 API 文档见 docs/api/property.md而扇区模型的 API 见 docs/api/sector.md。在编辑器初始化时通过styleManager配置扇区与属性const editor grapesjs.init({ styleManager: { sectors: [ { name: My Sector, open: false, properties: [ { property: min-height, type: select, default: 100px, options: [{ id: 100px, label: 100 }] }, ], }, ], }, });默认配置见 packages/core/src/style_manager/config/config.ts内置了General、Flex、Dimension、Typography、Decorations、Extra六个扇区这些扇区引用的属性名如display、width、margin、box-shadow均来自内置属性工厂。编辑器实例化后通过editor.StyleManager获取模块即可用addProperty、getProperty、getProperties、removeProperty、select、addBuiltIn等 API 操作属性方法清单见 docs/api/style_manager.md。addProperty返回的正是Property模型实例const styleManager editor.StyleManager; const property styleManager.addProperty(mySector, { label: Minimum height, property: min-height, type: select, default: 100px, options: [{ id: 100px, label: 100 }, { id: 200px, label: 200 }], }, { at: 0 });Property 基础配置字段Properties创建 Property 时可配置以下基础字段即 docs/api/property.md 中的Properties小节字段类型说明idString属性 id例如my-property-idpropertyString关联的 CSS 属性名例如text-aligndefaultString属性的默认值labelString在 UI 中显示的标签例如Text AlignonChangeFunction?值变化回调onChange回调签名及用法onChange: ({ property, from, to }) { console.log(Changed property, property.getName(), { from, to }); }在源码 packages/core/src/style_manager/model/Property.ts 中PropertyProps接口还暴露了更多可用于配置的字段与上述基础字段共同构成完整的属性定义name显示名称初始化时会基于property自动推导capitalize(prop).replace(/-/g, )因此通常无需手动指定type属性类型决定使用哪个 Property 子类详见下文类型体系info属性说明信息value当前值iconUI 图标functionNameCSS 函数名如url、translateX配合值渲染成functionName(value)的形式visible是否可见默认truefixedValues固定候选值数组默认[initial, inherit]内置属性工厂另有[initial, inherit, auto]的变体full是否在 UI 中独占整行full-width默认falseimportant为true时值会被追加!importanttoRequire若为true属性默认隐藏仅当目标通过stylable-require显式声明需要它时才显示——官方建议将全部 SVG 相关属性配置为toRequire: true再在 SVG 组件上按需requirerequires依赖同目标上其他属性值条件全部满足才显示例如requires: { display: [flex, block], position: [absolute] }requiresParent依赖选中目标父元素的计算样式例如内置的flex-basis依赖父元素display: flexisVisible自定义可见性判断函数例如isVisible: ({ component }) component?.is(image)仅图片组件选中时显示status、className、parentTarget、extend等内部/扩展字段。defaults()中定义的基础默认值为name: 、property: 、type: 、defaults: 、info: 、value: 、icon: 、functionName: 、status: 、visible: true、fixedValues: [initial, inherit]、full: false、important: false、toRequire: false。属性类型体系type 决定模型与视图getType()返回属性类型类型在属性创建时确定并据此分配对应的 Property 子类默认类型为base。类型注册表见 packages/core/src/style_manager/model/Properties.ts内置类型与对应的模型/视图如下type模型视图说明basePropertyPropertyView默认类型通用文本输入number/integerPropertyNumberPropertyNumberView数值 单位输入selectPropertySelectPropertySelectView下拉选择radioPropertyRadioPropertyRadioView单选按钮组sliderPropertySliderPropertySliderView滑块colorPropertyPropertyColorView颜色选择器filePropertyPropertyFileView文件如图片 urlcompositePropertyCompositePropertyCompositeView组合属性子属性聚合为一个 CSS 简写stackPropertyStackPropertyStackView堆叠属性多层如 box-shadow内置属性工厂 packages/core/src/style_manager/model/PropertyFactory.ts 预定义了 70 个常用 CSS 属性例如数值型top、margin-*、padding-*、width、height、font-size、line-height等默认单位集unitsSize [px,%,em,rem,vh,vw]时间单位[s,ms]角度单位[deg,rad,grad]单选型float、position、text-align颜色型color默认black、background-color、border-color文件型background-imagefunctionName: url滑块型opacitymin: 0, max: 1, step: 0.01下拉型display、flex-direction、font-family、border-style、overflow、cursor等组合型margin、padding、border、border-radius堆叠型transition、box-shadow、text-shadow、background、transform。这些内置定义可通过styleManager.getBuiltIn(width)获取、getBuiltInAll()获取全部、addBuiltIn(prop, definition)新增或扩展。transform还演示了fromStyle/toStyle自定义逻辑把transform: rotateZ(45deg)拆解为transform-type与transform-value两个子属性。Property 核心 API 详解以下方法全部定义在 packages/core/src/style_manager/model/Property.ts测试用例覆盖见 packages/core/test/specs/style_manager/model/Properties.ts。标识类方法getId / getType / getName / getLabelgetId()返回属性 idthis.get(id)。getType()返回属性类型字符串默认base。getName()返回 CSS 属性名内部实际读取的是property字段。getLabel(opts {})返回 UI 标签。可传opts.locale默认true决定是否优先使用 i18n 模块的翻译串styleManager.properties.id找不到翻译时回退到name或label字段。值读取类方法getValue / hasValue / hasValueParent / getDefaultValuegetValue(opts {})返回当前值当属性没有值且未传noDefault时返回默认值即!hasValue() !noDefault ? getDefaultValue() : val。hasValue(opts {})判断属性是否有值。判定条件是value非undefined且非空串若传opts.noParent true则忽略来自父目标的值parentTarget。测试中hasValue()与hasValue({ noParent: true })的组合被广泛用于验证继承值场景见 Properties.ts 中 289-316 行等用例。hasValueParent()指示当前值是否来自父目标如另一个 CSSRule等价于hasValue() !hasValue({ noParent: true })。getDefaultValue()返回默认值优先读取default字段回退到defaults字段。getStyle生成 CSS 样式对象getStyle(opts {})返回该属性对应的 CSS 样式对象。传opts.camelCase可将属性名转为驼峰形式// 属性为 color 且值为 red 时 console.log(property.getStyle()); // { color: red };实现上内部调用__getFullValue()它会根据functionName包装成fn(value)如url(...)并在important为真时追加!important。对 composite/stack 类型getStyle被子类覆写见 PropertyComposite.ts 的getStyleFromProps可生成简写或拆分的多属性对象。upValue更新值并同步到目标upValue(value, opts {})是更新值的主入口变化会传播到选中的目标如 CSS 规则value新值字符串传入null或时等价于执行清除逻辑opts.partial若为true对目标的更新视为未完成不进入 UndoManageropts.noTarget若为true变化不会传播到选中目标。调用链为upValue → __parseValueparseValue 解析→ _upset 触发 change→ __upTargets → __upTargetsStyle → styleManager.addStyleTargets最终调用目标的addStyle写入样式参见 StyleManager.addStyleTargets 与测试中compTypeProp.upValue(1px 2px 3px 4px)后断言rule1.getStyle()的用例。parseValue还负责解析!important后缀以及 CSS 函数如translateX(10deg)解析为{ value: 10, unit: deg, functionName: translateX }并支持opts.numeric数值拆分。可见性与清理类方法isVisible / clear / canClearisVisible()返回属性是否可见读取visible字段。clear(opts {})清除值同样会传播到选中目标如清除对应 CSS 属性传opts.noTarget true可阻止传播。内部通过__getClearProps()将value置空并携带__clear标记。composite 类型覆写了clear会递归清除所有子属性。canClear()判断当前值是否直接来自选中目标因而可以被清除子属性场景下委托给父属性的__canClearProp。层级类方法getParent / isFullgetParent()若当前属性是子属性composite/stack 的成员返回其父 Property否则返回null。isFull()指示属性是否在 UI 中独占整行读取full字段。实战注册属性、监听变化与自定义类型注册一个下拉属性并监听变化const prop styleManager.addProperty(typography, { property: text-transform, type: select, default: none, options: [ { id: none, label: None }, { id: uppercase, label: UPPERCASE }, { id: capitalize, label: Capitalize }, ], onChange: ({ property, from, to }) { console.log(${property.getName()} changed, { from, to }); }, }); // 编程式更新值同步到选中目标 prop.upValue(uppercase);借助 PropertySelect 的动态选项能力见 PropertySelect.tsgetOptions()获取选项、setOptions([...])整体替换、addOption({ id, label })追加选项、getOptionLabel(id)结合 i18n 返回标签适用于字体列表等需要异步加载的选项。Number 属性的单位与范围见 PropertyNumber.ts可通过units: [px,%,em]、min、max、step配置输入约束使用getUnits()、getUnit()、getMin()、getMax()、getStep()读取upUnit(unit)更新单位并同步目标。注册自定义属性类型用于扩展 UI 控件见 StyleManager.addTypestyleManager.addType(my-custom-prop, { create({ props, change }) { const el document.createElement(div); el.innerHTML input typerange classmy-input min10 max50/; const inputEl el.querySelector(.my-input); inputEl.addEventListener(change, (event) change({ event })); inputEl.addEventListener(input, (event) change({ event, partial: true })); return el; }, emit({ props, updateStyle }, { event, partial }) { updateStyle(${event.target.value}px, { partial }); }, update({ value, el }) { el.querySelector(.my-input).value parseInt(value, 10); }, destroy() {}, });之后即可在扇区定义或addProperty中使用type: my-custom-prop。值同步与父目标机制Property 的值与目标样式并非同一存储属性模型持有value而实际 CSS 落在目标组件内联样式或 CSSRule上。__upTargets通过StyleManager.addStyleTargets({ [name]: value })把值写入所有选中目标反向地当选中目标变化时StyleManager.__upProp会读取目标样式并回填到属性__up标记避免循环触发。当属性自身没有值时Style Manager 会沿父规则链如标签选择器规则、id 规则等见getParentRules寻找继承值并通过__setParentTarget记录来源这正是hasValueParent()与hasValue({ noParent: true })存在的原因——UI 上可以据此区分直接设置的值与继承的值并决定clear()是否可用canClear()。总结Property 是 GrapesJS 样式管理器的最小可编辑单元本文覆盖了它的全部基础配置字段、9 种内置类型、15 个公开方法及其源码实现路径。实际开发中建议用addProperty注册业务属性、用onChange做联动、用requires/requiresParent/isVisible控制上下文相关的显隐、用addBuiltIn扩展全局内置属性、用addType实现完全自定义的 UI 控件。相关实现与验证可直接查阅 Property.ts、PropertyFactory.ts、Properties.ts 及测试套件 Properties.ts。【免费下载链接】grapesjsFree and Open source Web Builder Framework. Next generation tool for building templates without coding项目地址: https://gitcode.com/GitHub_Trending/gr/grapesjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
