ToolJet Star Rating 组件完全指南:星级评分组件的属性、事件、样式与源码实现

原创2026-09-09 18:04:551,937 阅读
文章标签:低代码前端后端企业应用UI组件AI 应用MCP 服务

ToolJet Star Rating 组件完全指南:星级评分组件的属性、事件、样式与源码实现

导读

Star Rating(星级评分)是 ToolJet 应用构建器中用于展示与录入评分结果的表单类组件,支持半星、自定义星数、逐星 Tooltip 提示等能力。本文以 star-rating.md 为核心骨架,系统讲解该组件的 Properties、Events、Exposed Variables、Devices 与 Styles 配置,并结合 frontend 与 server 两侧的组件配置、Rating.jsx 渲染实现以及历史数据迁移脚本,从"怎么配"到"底层怎么跑"完整还原该组件。读完本文,你将能够熟练地在 ToolJet 画布上配置星级评分组件,用 {{components.starrating1.value}} 动态读取评分,并通过事件绑定与表单联动完成业务闭环。


一、组件概述:既能展示,也能录入

Star Rating 组件在画布中以一组图标(默认是五角星)呈现,用户点击图标即可完成评分输入,组件同时会把当前评分值实时暴露给应用的其他部分使用。其核心特性包括:

  • 双形态:既可用于展示固定评分(如详情页的评分回显),也可作为输入控件收集用户评分;
  • 半星支持:开启后可选择 0.5 的评分粒度;
  • 星数可配:初始渲染的图标数量可自定义,default: 5;
  • 逐星 Tooltip:可为每个图标单独配置悬浮提示文案。

在组件管理器中,该组件的注册名为 StarRating,显示名为 Rating,描述为 "Star rating",默认画布尺寸为宽 10、高 30(见 widgets/starrating.js)。前端组件管理器与后端服务端各维护一份同构的配置(server 侧对应文件),前后端配置保持一致,这也是 Inspector 面板中所有属性、样式、事件能够正确渲染的数据来源。


二、Properties:组件属性详解

Properties 区域控制组件的数据行为。下表为文档定义的全部属性,并结合组件配置源码补充了默认值、类型与校验规则:

Property 说明 期望值 源码默认值
Label 用作星级评分的标签文本 String Select your rating
Number of stars 初始加载时图标的总数量 整数 5
Default no of selected stars 初始加载时默认选中的图标数量 整数 5(组件定义块中实际为 3,见下文说明)
Enable half star 开启后可选择半星 {{true}} / {{false}},默认 false false
Tooltips 为每个图标显示提示信息,数组下标与图标索引一一对应 [](字符串数组) []

在源码配置中,各属性还带有更细的类型与校验定义(starrating.js):

  • label:code 类型,validation.schema 为 { type: 'string' },默认值 'Select your rating';
  • maxRating:code 类型,校验为 { type: 'number' },默认 5;
  • defaultSelected:code 类型,校验为 { type: 'number' },默认 5;
  • allowHalfStar:toggle 类型,校验为 { type: 'boolean' },默认 false;
  • tooltips:code 类型,校验为 { type: 'array', element: { type: 'union', schemas: [{ type: 'string' }, { type: 'number' }] } },即数组元素可以是字符串也可以是数字,默认 '[]'。

需要注意两点:

  1. 默认选中数量存在两处默认值:配置校验层的 defaultValue 为 5,而组件拖入画布时生成的 definition.properties.defaultSelected 实际写入 '3'(starrating.js)。也就是说,新建组件时默认选中 3 颗星,与文档所述"默认 5"略有出入,实际以 Inspector 面板中呈现的值为准。
  2. Number of stars 的边界处理:在渲染实现中,_maxRating = !maxRating || maxRating < 0 ? 0 : maxRating(Rating.jsx),即空值或负数会被兜底为 0,避免渲染出非法数量的图标。

此外,文档未提及但源码中已提供的扩展属性还包括(可在 Inspector 的相应分区中看到):

  • Icon Type(iconType):切换图标形态,可选 Stars(默认)或 Hearts;
  • Allow editing(allowEditing):默认 false,关闭后组件仅作展示、不可点击修改;
  • Loading state(loadingState):默认 false,开启后组件显示加载指示器;
  • Collapse when hidden(collapseWhenHidden):默认 false,隐藏时是否折叠占位空间;
  • Disable(disabledState):默认 false,锁定组件使其不可交互。

三、Events:事件绑定

Event 说明
On change 每当用户点击某颗星时触发

在组件配置中,该事件注册为 events: { onChange: { displayName: 'On Change' } }(starrating.js)。触发链路在 Rating.jsx 中非常清晰:点击图标后执行 handleClick(idx),将 idx + 1(因为内部索引从 0 开始)写入暴露变量 value,随后调用 fireEvent('onChange') 广播事件。

你可以在该事件上挂载任意 Action,例如更新变量、运行查询、显示告警等。文档中"Action Reference"的具体内容对应仓库中的 actions 目录,其中各 Action 的用法(如 run-query、set-variable、show-alert、control-component 等)均可在事件处理器中选择。


四、Component Specific Actions(CSA)

原文档说明:当前没有为 Star Rating 组件实现 CSA(组件专属动作),即无法通过"控制组件"动作直接调节该组件。

需要补充的是,从当前仓库源码结构看,组件配置中其实已注册了 actions 数组(starrating.js),包含:

Handle 显示名 参数
setValue Set value value(默认 '0')
setVisibility Set visibility setVisibility(toggle,默认 {{false}})
setDisable Set disable setDisable(toggle,默认 {{false}})
setLoading Set loading setLoading(toggle,默认 {{false}})
resetValue Reset rating 无

同时在渲染实现中,组件通过 setExposedVariable('setValue', setValue) 与 setExposedVariable('resetValue', resetValue) 向外部暴露了可调用句柄(Rating.jsx)。因此可以推断:文档中"暂无 CSA"的描述可能已滞后于当前实现,具体能否在事件处理器与 Run JavaScript 查询中调用 components.starrating1.setValue(...) 等动作,请以你所部署版本的 Inspector 面板为准。若可用,JS 调用语法与 control-component 中一致,例如:

await components.starrating1.setValue(4);
await components.starrating1.resetValue();

值得一提的是,setValue 的底层实现做了严谨的输入校验(Rating.jsx):

  • 仅接受数字或可解析为数字的字符串,空串、NaN、非有限值及其他数据类型一律拒绝;
  • 当 allowHalfStar 开启时,小数按"四舍五入到最近半星"处理(如 4.25~4.75 → 4.5);关闭时按"小数 ≥ 0.5 向上取整、否则向下取整"处理;
  • 最终值被钳制在 [0, maxRating] 区间内。

五、Exposed Variables:暴露变量

变量 说明 访问方式
value 用户每次添加评分后组件保存的评分值 动态访问,如 {{components.starrating1.value}}

组件配置中声明 exposedVariables: { value: 0 }(starrating.js),初始值为 0。在渲染实现中,点击、重置、表单清空三条路径都会同步更新该变量:

  • 点击第 idx 颗星时写入 idx + 1(Rating.jsx);
  • resetValue() 将 value 重置为 defaultSelected(Rating.jsx);
  • 作为表单子组件时,表单执行"清空"会通过 useFormClear 将评分与 value 一并归零(Rating.jsx)。

因此 value 可用于:展示在文本组件中(如 {{components.starrating1.value}} 分)、作为查询参数传给后端(如筛选评分不低于某值的记录)、或参与条件判断与变量计算。


六、General:通用属性——Tooltip

在 Inspector 的 General 折叠区中,可以设置组件的 Tooltip 提示。输入字符串后,鼠标悬停在组件上即会显示该提示文本,用于补充说明组件的用途或输入要求。

从源码看,Tooltip 配置已经升级为"格式 + 内容"的二元结构(starrating.js):

  • Tooltip(格式):tooltipFormat 为 switch 类型,可选 Plain text(默认)、Markdown、HTML 三种渲染格式;
  • Tooltip(内容):tooltip 为 code 类型,校验为字符串,默认 'Tooltip text',占位提示为 Enter tooltip text。

这一结构与历史数据迁移脚本 MigrateStarRatingProperties.ts 相呼应——该脚本会把旧版 general.tooltip 迁移到 properties.tooltip,保证旧应用升级后配置不丢失。


七、Devices:设备可见性

Property 说明 期望值
Show on desktop 桌面视图下是否显示组件 开关按钮,或点击 fx 动态配置逻辑表达式
Show on mobile 移动视图下是否显示组件 开关按钮,或点击 fx 动态配置逻辑表达式

在组件配置中对应 others.showOnDesktop 与 others.showOnMobile(starrating.js),新建组件的默认定义为桌面可见({{true}})、移动端不可见({{false}})(starrating.js)。利用 fx 可将可见性绑定到运行时的逻辑表达式,例如根据当前页面环境或某个变量动态切换。


八、Styles:样式配置

Style 说明 默认值
Star Color 星形图标的显示颜色,可输入 Hex color code 或使用取色器选择 #ffb400
Label color 组件标签的文字颜色,同样支持 Hex 色值或取色器 跟随主题文本色(var(--cc-primary-text))
Visibility 控制组件可见性,可用 fx 动态修改;{{false}} 时应用部署后组件不可见 {{true}}
Disable 锁定组件使其不可交互,可用 fx 动态设置;{{true}} 时组件被锁定 {{false}}

在源码配置中,样式区实际比文档更丰富(starrating.js),按折叠区(accordion)划分如下:

Label 区(标签样式)

  • labelStyle:Standard / Legacy 两种标签渲染风格,默认 standard(Legacy 为兼容旧版应用的渲染路径,对应 Rating.jsx 中独立的 legacy 分支);
  • labelColor:默认 var(--cc-primary-text);
  • labelFontSize:数字输入,默认 12;
  • alignment:Side(默认)/ Top,标签与评分图的相对布局;
  • direction:标签在左(left,默认)或在右(right);
  • auto(Width):是否自动宽度,默认开启;
  • labelWidth:关闭自动宽度后,用滑杆调节标签宽度(默认 33);
  • widthType:宽度基准为 Of the Component(默认)还是 Of the Field。

Icon 区(图标样式)

  • textColor(Star 形态下的 "Selected background"):默认 #ffb400,仅当 iconType = stars 时生效(源码注释标明保留该字段以兼容旧数据);
  • selectedBackgroundHearts(Hearts 形态下的 "Selected background"):默认 #EE5B67,仅当 iconType = hearts 时生效;
  • unselectedBackground(Unselected background):未选中图标颜色,默认 #ffb400。

Container 区(容器样式)

  • boxShadow:默认 0px 0px 0px 0px #00000040;
  • padding:Default(默认)/ None。

样式与属性的迁移同样有据可查:迁移脚本 MigrateStarRatingProperties.ts 会将旧版 styles.visibility、styles.disabledState 迁移为 properties 下的同名属性,将 generalStyles.boxShadow 迁移进 styles.boxShadow,并为缺少 labelStyle 的旧组件补写 legacy 风格,从而保证升级后的组件在 Inspector 中呈现一致的配置结构。


九、源码级实现原理

1. 渲染与动画

组件使用 react-spring 的 useTrail 为整组图标添加入场动画(透明度从 0 到 1、缩放从 0.8 到 1,见 Rating.jsx)。每个图标由 RatingIcon.jsx 独立渲染,内部维护三态图标:选中态(实心)、半星态、未选中态(描边),并通过 getActive / isHalfIcon 决定每个图标呈现哪种状态(Rating.jsx)。

2. 半星交互逻辑

半星判定依赖鼠标位置计算:handleMouseMove 根据图标容器坐标与宽度,按 precision = 0.5 对悬停位置四舍五入,命中 0.5 粒度时切换为半星图标,点击时传入 index - 0.5 作为评分(RatingIcon.jsx)。悬停时整组图标通过 setHoverIndex 联动高亮(Rating.jsx)。

3. Tooltips 渲染

每个图标的 Tooltip 通过 react-bootstrap 的 OverlayTrigger 实现,位置为底部,显示延迟 250ms、隐藏延迟 400ms(RatingIcon.jsx)。Tooltip 文案取自 tooltips[index],即与图标索引一一映射(Rating.jsx),新建组件的默认示例为 ["Very Poor","Poor","Average","Good","Excellent"](starrating.js)。

4. 无障碍(Accessibility)支持

组件在无障碍方面做得比较完整(Rating.jsx、RatingIcon.jsx):

  • 整体容器声明 role="radiogroup",每个图标声明 role="radio" 与 aria-checked、aria-posinset、aria-setsize;
  • 点击后通过 aria-live="polite" 的隐藏区域播报"n out of m stars/hearts";
  • 支持键盘操作:聚焦图标后按 Enter 或空格键即可选中评分(handleKeyDown),不可编辑或禁用时 tabIndex 置为 -1 并增加 pointer-events-none。

5. 表单联动

组件通过 useFormClear 订阅表单的"清空"信号:当所在表单被重置时,评分与 value 自动归零(Rating.jsx),因此可以直接拖入 Form 组件 中作为评分子字段使用。


十、快速上手示例

下面是一个把"展示评分 + 收集评分"串起来的典型用法:

  1. 从组件库将 Rating 拖入画布;
  2. 在 Properties 中设置 Label 为 服务满意度、Number of stars 为 5、Default no of selected stars 为 3,开启 Enable half star,并把 Tooltips 配置为 {{["非常差","较差","一般","满意","非常满意"]}};
  3. 拖入一个文本组件,将其内容绑定为 {{components.rating1.value}} / 5,即可实时回显当前评分;
  4. 为该组件的 On change 事件添加一个 Action(如 run-query 或 set-variable),把 {{components.rating1.value}} 作为参数提交或暂存;
  5. 在 Styles 中按需调整 Star Color、Label color,并用 fx 绑定 Visibility / Disable 实现按条件的展示与锁定。

结语

Star Rating 是 ToolJet 表单类组件中交互最直观的评分控件之一。通过本文你可以看到:文档定义的每个属性在 组件配置 中都有对应的类型、校验与默认值;每个交互行为(点击、半星、Tooltip、重置、表单清空)在 Rating.jsx 与 RatingIcon.jsx 中都有可追溯的实现;连旧应用的配置迁移都有对应的 数据迁移脚本 兜底。理解这一层对应关系后,你不仅能熟练配置组件,还能在排查问题、阅读源码甚至二次开发时快速定位关键代码。

登录后查看全文
ToolJet