所属产品: Mingcedar Studio DESIGNER
状态色 / 文本行为详解 | Mingcedar Studio
状态色和文本行为的共同目标，是把运行状态表达清楚。配置合理时，用户可以快速识别对象当前状态；配置不当时，页面会干扰视觉重点，并可能与真实业务状态不一致。
<section id="preface" class="docs-block docs-block-intro"> <span class="section-kicker">状态</span> <h2>使用前说明</h2> <p>状态色和文本行为的共同目标，是把运行状态表达清楚。配置合理时，用户可以快速识别对象当前状态；配置不当时，页面会干扰视觉重点，并可能与真实业务状态不一致。</p> <div class="docs-task-grid"> <article id="preface-item-1" class="docs-task-card"> <span>状态</span> <strong>先记一个总原则</strong> <p>能用更简单的行为表达时，优先选择更简单的行为。只需要真 / 假两态时，优先选 State Color；只有当规则确实无法由简单行为表达时，再考虑 Script Color。</p> </article><article id="preface-item-2" class="docs-task-card"> <span>状态</span> <strong>颜色行为和文本行为的区别</strong> <p>颜色行为控制填充、边框、显隐和状态灯；文本行为控制页面显示的文字内容。</p> </article><article id="preface-item-3" class="docs-task-card"> <span>状态</span> <strong>常见配置误区</strong> <p>常见问题包括：简单行为即可满足需求时仍将对象配置为脚本行为；或将质量 bad、报警、停机等含义不同的状态混用同一种颜色。状态表达越混乱，页面后续维护成本越高。</p> </article> </div> </section> <section id="visual-selection" class="docs-block"> <span class="section-kicker">选型</span> <h2>先做选型：该用哪一种状态色行为</h2> <p>根据数据类型和状态数量选择颜色行为，再配置对应字段。布尔状态、数值区间和离散状态码分别使用适合的行为。</p> <div class="docs-detail-list"> <article id="visual-selection-item-1" class="docs-detail-row"> <strong>State Color：最适合真 / 假两态</strong> <p>如果对象只有两个明确状态，例如运行 / 停止、开 / 关、自动 / 手动，优先考虑 State Color。它的优势是结构直观，后续维护人员可以直接理解状态来源和显示结果。</p> <ul> <li>适合二值状态</li><li>适合按钮、灯、开关、启停件</li><li>优先于复杂脚本色</li> </ul> <pre class="docs-code-block"><code>var running = ReadTagBoolean("PLC_LINE01.PUMP01.RUN", false);
running</code></pre> </article><article id="visual-selection-item-2" class="docs-detail-row"> <strong>State Color 字段填写</strong> <p>在 Setup Script 中准备状态变量，Condition 返回 true 或 false。在 Action → Apply result 中选择需要应用的 TRUE / FALSE 状态，并为启用的 Fill color、Border color、Visibility 通道配置结果。需要质量边框时，在 Quality Override 中启用 Follow data quality (border / hide)。</p> <ul> <li>Setup Script：读取 running、alarm、quality 等变量</li><li>Condition：返回布尔值</li><li>TRUE state / FALSE state：分别设置显示结果</li><li>Quality Override：表达数据质量，不替代业务状态</li> </ul> </article><article id="visual-selection-item-3" class="docs-detail-row"> <strong>Blink Color：不是普通状态色，而是带闪烁节奏的二值提示</strong> <p>Blink Color 最适合报警灯、强提醒块、二值告警提示。它和普通二值状态色的区别，不在于状态来源，而在于它会在 true / false 或 on / off 之间做闪烁节奏表达。</p> <ul> <li>适合报警和提醒</li><li>不建议大面积滥用</li><li>闪烁只该服务重点状态</li> </ul> <pre class="docs-code-block"><code>var alarm = ReadTagBoolean("PLC_LINE01.PUMP01.ALARM", false);
alarm</code></pre> </article><article id="visual-selection-item-4" class="docs-detail-row"> <strong>Range Color：模拟量区间映射</strong> <p>当一个数值要映射成多个颜色区间时，用 Range Color 最合适。温度、压力、负载、电流、液位这类连续数值都很适合。核心不是写很多 if，而是先定 limits，再定每个区间的颜色。</p> <ul> <li>适合模拟量和区间显示</li><li>优先让规则落在 limits 上</li><li>将区间边界与显示规则集中配置</li> </ul> <pre class="docs-code-block"><code>var temp = ReadTagDouble("PLC_LINE01.PUMP01.TEMP", 0);
temp</code></pre> </article><article id="visual-selection-item-5" class="docs-detail-row"> <strong>Range Color 的区间数量</strong> <p>Range Color 的颜色和显隐配置应与区间数量对应。4 个 Limits 会形成 5 个区间。用户应先按工艺单位确定边界，再配置低、正常、偏高、报警等区间状态。</p> <ul> <li>先确认单位：例如 °C、bar、%、rpm</li><li>再确定 Limits：例如 20, 40, 60, 80</li><li>最后配置每个区间颜色和显隐</li><li>固定状态码不使用 Range Color</li> </ul> </article><article id="visual-selection-item-6" class="docs-detail-row"> <strong>Discrete Color：固定离散状态映射</strong> <p>Discrete Color 用七个递增阈值划分八个区间。特定枚举值匹配或未知状态分支应使用 Multi-State Color。</p> <ul> <li>适合状态码和枚举值</li><li>适合离散状态而不是连续区间</li><li>比 Range Color 更适合固定状态列表</li> </ul> </article><article id="visual-selection-item-7" class="docs-detail-row"> <strong>Discrete Color 的状态表</strong> <p>State actions 的 Value < 使用阈值。默认 0、1、2、4、8、16、32 中，2 和 3 同属 [2, 4)，32 及以上进入 Final (+∞)。未定义状态码没有独立默认分支。</p> <ul> <li>State value 返回数值</li><li>按“小于”阈值依次匹配区间</li><li>最终状态包含最后阈值及以上的数值</li><li>需要严格枚举判断时使用 Multi-State Color</li> </ul> </article><article id="visual-selection-item-8" class="docs-detail-row"> <strong>Multi-State Color：多个条件按优先级命中</strong> <p>如果一个对象同时可能有报警、手动、自动、待机等多个互斥状态，而且这些状态之间有优先级，就该用 Multi-State Color。第一个命中的条件优先，后面的条件不会再继续覆盖。</p> <ul> <li>适合多条件互斥状态</li><li>第一命中优先</li><li>适合 alarm > manual > auto > idle 这种顺序</li> </ul> <pre class="docs-code-block"><code>var alarm = ReadTagBoolean("PLC_LINE01.PUMP01.ALARM", false);
var manual = ReadTagBoolean("PLC_LINE01.PUMP01.MANUAL", false);
var running = ReadTagBoolean("PLC_LINE01.PUMP01.RUN", false);</code></pre> </article><article id="visual-selection-item-9" class="docs-detail-row"> <strong>Multi-State Color 的优先级</strong> <p>Multi-State Color 按条件顺序命中，前面的条件优先级更高。配置时应把报警、故障、禁用等高优先级状态放在前面，把运行、待机、普通状态放在后面，并明确 Else 状态。</p> <ul> <li>Condition1 优先级最高</li><li>报警和故障通常放在前面</li><li>运行和待机通常放在后面</li><li>Use Else 用于未命中时的默认状态</li> </ul> </article><article id="visual-selection-item-10" class="docs-detail-row"> <strong>Script Color：通过表达式配置显示</strong> <p>当填充、边框、显隐需要一起被脚本控制，或者条件组合已经超出简单状态行为的表达能力时，再考虑 Script Color。脚本需要明确的返回类型和可维护的条件结构。</p> <ul> <li>适合复杂组合规则</li><li>适合 fill / border / visible 联动</li><li>简单状态优先使用标准行为</li> </ul> <pre class="docs-code-block"><code>var state = ReadTagInteger("PLC_LINE01.PUMP01.STATE", 0);
var fillColor = state === 1 ? "#22C55E" : "#EF4444";
var borderColor = "#0f172a";
var isVisible = true;</code></pre> </article><article id="visual-selection-item-11" class="docs-detail-row"> <strong>Script Color：使用模板参数提供颜色字符串</strong> <p>在 Action 中启用 Fill color 或 Border color 后，填写返回颜色字符串的表达式；旧字段名分别为 Fill 和 Stroke。模板参数写成 `'<FILL_COLOR>'` 或 `"<FILL_COLOR>"`，边框颜色同理。Visibility 和 Condition 填写布尔表达式。</p> <pre class="docs-code-block"><code>Fill: '<FILL_COLOR>'
Stroke: '<STROKE_COLOR>'
Visibility: running === true</code></pre> </article><article id="visual-selection-item-12" class="docs-detail-row"> <strong>显示布尔量或位状态：用 State Color 或 Discrete Color</strong> <p>State Color 的 Condition 返回布尔值，例如 ReadTagBoolean("PLC_LINE01.PUMP01.RUN", false)。读取状态字单个位可用 ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[3]", false)。模板名称作为读取方法的字符串参数，例如 ReadTagBoolean("<PLC>.<RUN_TAG>", false)。完整 Tag 名称字符串本身不是状态值。</p> <ul> <li>两态布尔量优先使用 State Color</li><li>Discrete Color 的 State value 需要数值，可显式将布尔值转换为 0 / 1</li><li>模板占位符先替换，再由读取方法获取数据</li> </ul> </article><article id="visual-selection-item-13" class="docs-detail-row"> <strong>读取某个位的语法：TAG[bit]</strong> <p>读取状态字中的单个位时，可在完整 Tag 后追加 `[0]` 到 `[31]`，也就是 `TAG[bit]` 语法；位号还必须落在父 Tag 实际类型位宽内。其中 `[0]` 表示最低位。需要写入单个位时，不在 Tag 表达式中写 `[n]`，应使用 Write Tag Bit 并在 Bit Index 中填写位号。</p> <ul> <li>读取位语法：`TAG[bit]`</li><li>读取位：`PLC_LINE01.PUMP01.STATUS[0]`</li><li>模板读取位：`'<PLC>.<STATUS_TAG>[3]'`</li><li>位号范围：0 到 31，且小于父 Tag 实际类型位宽</li><li>写位使用 Write Tag Bit</li> </ul> </article><article id="visual-selection-item-14" class="docs-detail-row"> <strong>位读取和位写入的区别</strong> <p>位读取可以直接在 Tag 点名后追加 `[n]`，例如 `PLC_LINE01.PUMP01.STATUS[3]`；位写入不能把 `[n]` 放在写值目标中。Write Tag Bit 的目标应填写父级整数 Tag，例如 `PLC_LINE01.PUMP01.STATUS`，位号填写在 Bit Index 中。这样运行端才能读取当前整数值，计算目标位后的新整数值，再提交写入。</p> <ul> <li>读取位：`ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[3]", false)`</li><li>写位目标：`PLC_LINE01.PUMP01.STATUS`</li><li>写位位号：Bit Index = 3</li><li>写位动作：Set、Reset、Toggle</li> </ul> <pre class="docs-code-block"><code>// 读取状态字第 3 位
ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[3]", false)
// 写位时使用字段
Target Tag: PLC_LINE01.PUMP01.STATUS
Bit Index: 3
Bit Action: Set</code></pre> </article> </div> <div class="docs-note-grid"> <figure id="visual-selection-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ColorStateBehaviorEditorForm.png" alt="State Color" loading="lazy" decoding="async"> <figcaption> <strong>State Color</strong> <p>只要是明确二值状态，优先从 State Color 开始想，而不是先写脚本。</p> </figcaption> </figure><figure id="visual-selection-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ColorBlinkBehaviorEditorForm.png" alt="Blink Color" loading="lazy" decoding="async"> <figcaption> <strong>Blink Color</strong> <p>闪烁适合报警和强提醒，不适合作为普通状态色的常态表达。</p> </figcaption> </figure><figure id="visual-selection-image-3" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ColorRangeBehaviorEditorForm.png" alt="Range Color" loading="lazy" decoding="async"> <figcaption> <strong>Range Color</strong> <p>连续数值优先用区间映射表达，避免在脚本中堆叠多层判断。</p> </figcaption> </figure><figure id="visual-selection-image-4" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ColorSwapBehaviorEditorForm.png" alt="Discrete Color" loading="lazy" decoding="async"> <figcaption> <strong>Discrete Color</strong> <p>离散状态码映射时，比区间色更适合用 Discrete Color。</p> </figcaption> </figure><figure id="visual-selection-image-5" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ColorSwapMultiBehaviorEditorForm.png" alt="Multi-State Color" loading="lazy" decoding="async"> <figcaption> <strong>Multi-State Color</strong> <p>多个互斥状态要按优先级命中时，Multi-State Color 更可靠。</p> </figcaption> </figure><figure id="visual-selection-image-6" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ColorScriptBehaviorEditorForm.png" alt="Script Color" loading="lazy" decoding="async"> <figcaption> <strong>Script Color</strong> <p>复杂规则可以交给 Script Color，但前提是确实需要这种复杂度。</p> </figcaption> </figure><figure id="visual-selection-image-7" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/TextBehaviorEditorFormTagText.png" alt="用 Tag Text 显示位状态" loading="lazy" decoding="async"> <figcaption> <strong>位 / 布尔量的文本显示</strong> <p>想把布尔量或某个位显示成文字用 Tag Text，想显示成颜色用 State Color。</p> </figcaption> </figure> </div> </section><section id="quality-border" class="docs-block"> <span class="section-kicker">质量</span> <h2>Quality Override：显示数据质量</h2> <p>质量边框（旧称 Quality Border）按 Tag 的 good / bad 状态显示数据可信度。当前编辑器在 Quality Override 区域配置；设备运行、停止和报警仍由业务状态表达。</p> <div class="docs-detail-list"> <article id="quality-border-item-1" class="docs-detail-row"> <strong>质量边框的含义</strong> <p>质量边框显示 Tag 数据是否可信。设备报警、停机和运行状态应使用对应状态 Tag 或业务规则表达。</p> </article><article id="quality-border-item-2" class="docs-detail-row"> <strong>配置质量边框</strong> <p>需要提示数据来源异常时，在颜色编辑器的 Quality Override 中启用 Follow data quality (border / hide)，或在 Script Text / Tag Text 中启用 Use quality outline colors，再配置 Good 和 Bad 颜色。</p> </article><article id="quality-border-item-3" class="docs-detail-row"> <strong>质量 bad 时的页面表达</strong> <p>质量 bad 时，页面应明确表达当前数据不可信。颜色、边框和显隐可以体现数据质量异常，避免用户将该状态误解为正常业务状态。业务报警、停机和运行状态仍应由实际状态 Tag 或报警规则表达。</p> </article><article id="quality-border-item-4" class="docs-detail-row"> <strong>GOOD / BAD 颜色如何分层</strong> <p>Good / Bad 颜色表达数据质量。可用填充色表示运行、停止或报警，用质量边框提示数据是否可信。</p> </article><article id="quality-border-item-5" class="docs-detail-row"> <strong>对象隐藏的适用场景</strong> <p>颜色编辑器提供 Hide when quality is bad。启用后，质量异常时隐藏组件。应同时提供数据异常提示，避免用户误以为对象不存在；不要假定所有行为编辑器都有此选项。</p> </article> </div> <div class="docs-note-grid"> <figure id="quality-border-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ColorBlinkBehaviorEditorForm.png" alt="Blink 质量边框" loading="lazy" decoding="async"> <figcaption> <strong>闪烁质量边框</strong> <p>在 Quality Override 中启用质量覆盖后，Good / Bad 边框颜色显示数据可信度。</p> </figcaption> </figure><figure id="quality-border-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ColorScriptBehaviorEditorForm.png" alt="Script Color 质量边框" loading="lazy" decoding="async"> <figcaption> <strong>脚本颜色质量边框</strong> <p>脚本颜色表达业务状态，质量边框提示 Tag 数据是否可信。</p> </figcaption> </figure><figure id="quality-border-image-3" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ColorValueDialog.png" alt="颜色选择器" loading="lazy" decoding="async"> <figcaption> <strong>颜色选择器</strong> <p>质量色、状态色和边框色建议用颜色选择器统一确认，减少手输色值造成的不一致。</p> </figcaption> </figure> </div> </section><section id="text-behaviors" class="docs-block"> <span class="section-kicker">文本</span> <h2>文本行为：内容显示该用哪一种</h2> <p>Script Text 用表达式生成文本，Tag Text 显示单个 Tag，Localized Text 按语言键显示固定文案。</p> <div class="docs-detail-list"> <article id="text-behaviors-item-1" class="docs-detail-row"> <strong>Script Text：通过表达式生成显示文本</strong> <p>需要拼接数值、格式化数字或按条件选择文案时，使用 Script Text。将下例的变量声明放入 Setup Script，文本表达式放入 Display Text；Condition 填 true 时持续更新显示，也可填写控制更新的布尔条件。</p> <ul> <li>适合格式化和拼接</li><li>适合带单位和条件文案</li><li>适合多个数据源组合成一句话</li> </ul> <pre class="docs-code-block"><code>var pressure = ReadTagDouble("PLC_LINE01.PUMP01.PRESSURE", 0.0);
"Pressure: " + pressure.toFixed(1) + " bar"</code></pre> </article><article id="text-behaviors-item-2" class="docs-detail-row"> <strong>Tag Text：一个 Tag 直接显示成文本</strong> <p>Tag Text 用于显示单个 Tag 并附加前缀或单位。Target tag 可直接填完整名称、带占位符的名称或名称字符串变量；对象属性使用 =bindingConfig.temperatureTag。Fallback value、Prefix 和 Suffix 是字符串表达式，固定文字或其中的占位符应写在引号内。</p> <ul> <li>适合直接显示一个 Tag</li><li>适合配 Prefix / Suffix</li><li>简单场景优先于 Script Text</li> </ul> <pre class="docs-code-block"><code>Target tag: '<PLC>.TEMP'
Fallback value: '<DEFAULT_TEXT>'
Prefix: '<TITLE>'
Suffix: " °C"</code></pre> </article><article id="text-behaviors-item-3" class="docs-detail-row"> <strong>Localized Text：文本不是值，而是语言键</strong> <p>当一个文本对象显示的是语言键对应的翻译，而不是实时数值时，用 Localized Text。按钮标题、面板标题、菜单项、固定状态词最适合这种方式。</p> </article><article id="text-behaviors-item-4" class="docs-detail-row"> <strong>模板参数在文本字段中的写法</strong> <p>模板实例先替换占位符，再按各字段规则使用结果。Target tag 可直接填 <PLC>.OVEN01.TEMPERATURE；Prefix、Fallback value 等字符串表达式填写 "<TITLE>"、"<DEFAULT_TEXT>"。需要运行时计算名称时，在目标字段使用 = 表达式；在 JavaScript 方法参数中直接使用名称变量。</p> </article><article id="text-behaviors-item-5" class="docs-detail-row"> <strong>Tag Text 的模板变量写法</strong> <p>Tag Text 的 Target tag 可直接填 <PLC>.TEMP；Fallback value、Prefix、Suffix 中的模板参数应写在字符串内，例如 `'<DEFAULT_TEXT>'`、`'<TITLE>'`。在 JavaScript 读取方法中使用带占位符的 Tag 名称时，也应加引号。</p> </article><article id="text-behaviors-item-6" class="docs-detail-row"> <strong>Script Text 的返回值要求</strong> <p>Script Text 的 Display Text 返回最终显示字符串。Setup Script 可读取多个 Tag 并准备中间值；Condition 决定是否更新文本。需要多语言时，固定文案优先使用 Localized Text，实时数值部分由脚本组合。</p> </article> </div> <div class="docs-note-grid"> <figure id="text-behaviors-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/TextBehaviorEditorForm.png" alt="Script Text" loading="lazy" decoding="async"> <figcaption> <strong>Script Text</strong> <p>文本需要拼接、格式化或组合多个值时，Script Text 更合适。</p> </figcaption> </figure><figure id="text-behaviors-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/TextBehaviorEditorFormTagText.png" alt="Tag Text" loading="lazy" decoding="async"> <figcaption> <strong>Tag Text</strong> <p>一个 Tag 直接显示成文本时，Tag Text 会比写脚本更简单。</p> </figcaption> </figure><figure id="text-behaviors-image-3" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/LanguageSettingsForm.png" alt="Localized Text" loading="lazy" decoding="async"> <figcaption> <strong>Localized Text</strong> <p>固定文案和语言键显示，优先使用 Localized Text。</p> </figcaption> </figure> </div> </section><section id="state-combos" class="docs-block"> <span class="section-kicker">组合</span> <h2>组合使用颜色、文本与质量提示</h2> <p>颜色帮助识别状态，文本说明含义，质量提示说明数据可信度。按显示需求组合这些行为。</p> <div class="docs-detail-list"> <article id="state-combos-item-1" class="docs-detail-row"> <strong>运行 / 停止 + 质量提示</strong> <p>用 State Color 的填充色表达运行 / 停止，在 Quality Override 中启用 Follow data quality (border / hide)，用质量边框提示通信是否可靠。</p> </article><article id="state-combos-item-2" class="docs-detail-row"> <strong>报警闪烁 + 文本文案</strong> <p>强提醒对象可以用 Blink Color 做外观闪烁，同时旁边文本用 Script Text 拼接报警文案或当前状态。这样视觉和文字信息能一起传达。</p> </article><article id="state-combos-item-3" class="docs-detail-row"> <strong>多状态颜色 + 多语言文本</strong> <p>对操作模式、设备工况这类多状态对象，可以用 Multi-State Color 管理颜色，用 Localized Text 管理文本。颜色负责快速识别，文本负责精确信息。</p> </article> </div> <div class="docs-note-grid"> <figure id="state-combos-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/TextBehaviorEditorFormTagText.png" alt="位状态与质量提示" loading="lazy" decoding="async"> <figcaption> <strong>位状态与质量提示</strong> <p>位状态表达开关或启停，质量边框补充数据是否可信；两者同时存在时要让用户能分辨。</p> </figcaption> </figure> </div> </section>