ToolJet Star Rating 组件完全指南:星级评分组件的属性、事件、样式与源码实现
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' }] } },即数组元素可以是字符串也可以是数字,默认'[]'。
需要注意两点:
- 默认选中数量存在两处默认值:配置校验层的
defaultValue为5,而组件拖入画布时生成的definition.properties.defaultSelected实际写入'3'(starrating.js)。也就是说,新建组件时默认选中 3 颗星,与文档所述"默认 5"略有出入,实际以 Inspector 面板中呈现的值为准。 - 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"的隐藏区域播报"nout ofmstars/hearts"; - 支持键盘操作:聚焦图标后按
Enter或空格键即可选中评分(handleKeyDown),不可编辑或禁用时tabIndex置为-1并增加pointer-events-none。
5. 表单联动
组件通过 useFormClear 订阅表单的"清空"信号:当所在表单被重置时,评分与 value 自动归零(Rating.jsx),因此可以直接拖入 Form 组件 中作为评分子字段使用。
十、快速上手示例
下面是一个把"展示评分 + 收集评分"串起来的典型用法:
- 从组件库将 Rating 拖入画布;
- 在 Properties 中设置 Label 为
服务满意度、Number of stars 为5、Default no of selected stars 为3,开启 Enable half star,并把 Tooltips 配置为{{["非常差","较差","一般","满意","非常满意"]}}; - 拖入一个文本组件,将其内容绑定为
{{components.rating1.value}} / 5,即可实时回显当前评分; - 为该组件的 On change 事件添加一个 Action(如 run-query 或 set-variable),把
{{components.rating1.value}}作为参数提交或暂存; - 在 Styles 中按需调整 Star Color、Label color,并用 fx 绑定 Visibility / Disable 实现按条件的展示与锁定。
结语
Star Rating 是 ToolJet 表单类组件中交互最直观的评分控件之一。通过本文你可以看到:文档定义的每个属性在 组件配置 中都有对应的类型、校验与默认值;每个交互行为(点击、半星、Tooltip、重置、表单清空)在 Rating.jsx 与 RatingIcon.jsx 中都有可追溯的实现;连旧应用的配置迁移都有对应的 数据迁移脚本 兜底。理解这一层对应关系后,你不仅能熟练配置组件,还能在排查问题、阅读源码甚至二次开发时快速定位关键代码。