Excel to HTML — 过程工程计算 HTML 工作流

> 本 Skill 固化了我（灵犀）在将 Excel 工程计算表转化为单文件 HTML 过程中积累的所有经验。

核心概念

将过程工程计算（Excel / VBA / 手工公式）转化为单文件 HTML 应用，具备专业工业 UI、双主题、SVG 可视化图标、实时计算和导出功能。

输入来源

• Excel (.xlsm)：含 VBA 计算逻辑
• 工程标准公式文档（HG/T、GB、API 等）
• 现有计算表格/电子表格

输出文件

• 单文件 HTML：内嵌 CSS + JavaScript，无外部框架依赖（CDN 除外）
• 双主题支持：
• 亮色模式：绿松石 #2aa889 + 琥珀 #e7a642（清爽专业风，默认）
• 暗色模式：科技深邃风（霓虹青 #00E5FF + 紫蓝 #7B61FF）
• 动效增强：Canvas 粒子背景、扫描线纹理、数字跳动动画、卡片呼吸光晕

源文件校验原则（必须先执行，第 0 步）

> ⚠️ 核心原则：发现源文件逻辑错误时，先暂停任务，提醒用户修正原始 Excel，绝不直接在 HTML 中将错就错。

执行流程

1. 提取公式后、开始转换前，必须对所有关键公式做合理性校验
2. 发现可疑点时（数值异常大/小、单位换算可疑、与标准公式不符），立即暂停
3. 暂停动作：
• 向用户明确列出可疑公式的位置（单元格坐标）
• 说明可疑原因（"数值大了 1000 倍" / "单位换算方向可能反了"）
• 提醒用户先去修正 Excel 源文件
• 等用户确认 Excel 已修正后，再重新提取公式、继续转换
4. 禁止行为：
• ❌ 不在 HTML 中"悄悄修正" Excel 的错误公式
• ❌ 不假设"可能是用户故意这样写的"而直接照抄
• ❌ 不在未告知用户的情况下，用"我认为正确"的数值覆盖源文件逻辑

典型可疑信号（遇到立即暂停）

提示用户的话术模板

⚠️ 发现源文件公式可疑，已暂停转换：

  [单元格坐标]：[原始公式]
  可疑原因：[具体说明]
  正确应为：[标准公式或合理值]

请先修正 Excel 源文件中的公式，保存后告诉我，我再重新提取并继续。

工作流步骤

Step 1: 读取 Excel 理解计算逻辑

1. 用 Python zipfile 读取 .xlsm 内部结构
2. 提取 VBA 代码 (xl/vbaProject.bin)
3. 识别关键计算函数及其参数含义

Step 2: 提取计算函数并转换为 JavaScript

将 VBA 函数逻辑改写为 JavaScript，注意：

• VBA 数组索引从 1 开始 → JS 从 0 开始
• Application.WorksheetFunction → 原生 JS Math API
• 保持与 Excel 一致的计算精度

关键函数对照：

Step 3: 创建 HTML 基础结构

参考 assets/html-template.html 模板，包含：

• Head: CDN 依赖（Chart.js、XLSX.js、jsPDF、Google Fonts）
• CSS Variables: Design Tokens 配色方案
• Body: 布局 + 输入卡片 + 结果展示 + 图表区域
• JavaScript: 计算函数 + 事件监听 + 图表渲染 + 导出功能

Step 4: 应用配色方案与 UI 组件

选择配色方案（见 references/color-schemes.md），并根据需要添加：

• SVG 工业图标可视化面板
• 合并式输入组件
• 响应式布局
• 实时计算模块

Step 5: 验证计算精度

• 对比 HTML 输出与 Excel 原数据的数值
• 确保误差在可接受范围内（< 0.001）
• 测试边界条件

参考资料

• 计算公式与推导：references/formulas.md
• 配色方案详细定义：references/color-schemes.md

模板文件

• 基础 HTML 模板：assets/html-template.html

UI 可视化设计规范（基于 V2.Visual 实践）

设计理念

将工程示意图（SVG矢量图标）与数据输入框合并为统一面板，让用户一眼看到设备类型、输入数量、当量参数，无需在两处来回跳转。

已验证参考：D:\RayClaw\PE Calculation\01-Pipelines\不可压缩流体压力降计算-Pipe Pressure Drop-V2.Visual.html

SVG 工业图标设计规范

viewBox 统一标准

<svg class="valve-svg" viewBox="0 0 100 60" fill="none" xmlns="http://www.w3.org/2000/svg">

• 宽高比 5:3，适合横向排列的设备/管件示意
• 所有图标统一 viewBox，确保 Grid 布局中大小一致

图标绘制原则

• 线条风格：stroke-based，linecap/linejoin round，线条清晰
• 填充策略：默认 fill="none"，通过 CSS stroke 和 currentColor 控制颜色
• 关键元素突出：阀门本体用粗线（stroke-width: 2.5），管道用细线（stroke-width: 1.5）
• 中英文标注：SVG 内不写文字，文字放在 DOM 中（便于 i18n 和 CSS 控制）

10 种标准管件图标

SVG 颜色与主题适配

/* 亮色模式 - 图标颜色 */
.valve-svg { stroke: var(--brand-primary); opacity: 0.7; transition: all 0.3s ease; }

/* 暗色模式 - 霓虹发光效果 */
[data-theme="dark"] .valve-svg { stroke: var(--neon-cyan); opacity: 0.6; }
[data-theme="dark"] .valve-item.active .valve-svg {
    stroke: var(--neon-cyan); opacity: 1;
    filter: drop-shadow(0 0 6px rgba(0, 229, 255, 0.5));
}

/* 选中/激活状态 */
.valve-item.active .valve-svg { opacity: 1; stroke-width-adjust: 1.2; }

合并式可视化输入面板（Valve Grid Panel）

设计原则

将「设备示意图」和「数量输入框」合并为一个 .valve-item 单元：

• 上方：SVG 图标 + 设备名称 + 当量长度标注
• 下方：数量输入框
• 激活时：图标高亮 + 输入框绿色边框

HTML 结构模板

<div class="card">
    <h3 class="sec-title">管件当量长度 (个数)</h3>
    <div class="valve-grid">
        <!-- 每个管件一个 valve-item -->
        <div class="valve-item" id="valve_ball">
            <svg class="valve-svg" viewBox="0 0 100 60">
                <!-- 球阀 SVG 路径 -->
            </svg>
            <div class="valve-name">球阀 Ball Valve</div>
            <div class="valve-le">30d</div>
            <input type="number" class="valve-input" id="f_ball" value="0" min="0"
                   oninput="highlightFit(this, 'ball'); triggerRealtime()">
        </div>
        <!-- 更多管件... -->
    </div>
</div>

CSS 响应式 Grid 布局

.valve-grid {
    display: grid;
    grid-template-columns: repeat(5, 1fr);  /* 桌面端5列 */
    gap: 12px;
}

/* 平板端 */
@media (max-width: 900px) {
    .valve-grid { grid-template-columns: repeat(4, 1fr); }
}

/* 小平板/大手机 */
@media (max-width: 680px) {
    .valve-grid { grid-template-columns: repeat(3, 1fr); }
}

/* 手机 */
@media (max-width: 440px) {
    .valve-grid { grid-template-columns: repeat(2, 1fr); }
}

输入框样式

.valve-input {
    width: 100%;
    padding: 7px 4px;
    text-align: center;
    font-family: var(--font-mono);
    font-size: 0.85rem;
    background: rgba(0, 0, 0, 0.04);
    border: 1px solid var(--bd);
    border-radius: 6px;
    color: var(--txt-primary);
    transition: all 0.25s ease;
}

/* 有值时 - 绿色高亮 */
.valve-input.has-value {
    color: var(--ok);
    border-color: rgba(0, 230, 118, 0.3);
    background: rgba(0, 230, 118, 0.04);
}

[data-theme="dark"] .valve-input {
    background: rgba(0, 0, 0, 0.25);
}
[data-theme="dark"] .valve-input.has-value {
    color: var(--ok);
    border-color: rgba(0, 230, 118, 0.35);
    background: rgba(0, 230, 118, 0.06);
}

当量长度标注

.valve-le {
    font-family: var(--font-mono);
    font-size: 0.58rem;
    color: var(--txt-muted);
    margin-bottom: 8px;
}

管件名称

.valve-name {
    font-size: 0.72rem;
    font-weight: 500;
    color: var(--txt-secondary);
    margin-bottom: 4px;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
}

JS 交互逻辑

valveMap 映射表

const valveMap = {
    'f_ball': 'ball',
    'f_gate': 'gate',
    'f_globe': 'globe',
    'f_butterfly': 'butterfly',
    'f_90elbow': '90elbow',
    'f_45elbow': '45elbow',
    'f_180bend': '180bend',
    'f_tee_run': 'tee_run',
    'f_tee_branch': 'tee_branch'
};

高亮与状态更新

function updateValveVisual() {
    for (const [inputId, valveType] of Object.entries(valveMap)) {
        const input = document.getElementById(inputId);
        if (!input) continue;
        const count = parseInt(input.value) || 0;
        const valveItem = document.getElementById('valve_' + valveType);
        if (valveItem) {
            input.classList.toggle('has-value', count > 0);
            if (count > 0) {
                valveItem.classList.add('active', 'valve-active');
            } else {
                valveItem.classList.remove('active', 'valve-active');
            }
        }
    }
}

function highlightFit(el, valveType) {
    updateValveVisual();
}

关键注意事项

• DOM ID 唯一性：每个 f_* 输入框 ID 在整个 HTML 中只能出现一次（旧版曾出现 SVG 区域和表格中重复 ID 的问题）
• 初始化调用：页面加载后调用一次 updateValveVisual() 以恢复默认状态
• 输入框必须绑定：oninput="highlightFit(this, 'xxx'); triggerRealtime()"

其他工业设备图标扩展

当需要为其他过程工程场景（安全阀、换热器、泵、容器等）添加 SVG 图标时：

1. 遵循统一的 viewBox="0 0 100 60" 标准
2. 使用 stroke-based 绘制，保持线条风格一致
3. 添加 .valve-item / .valve-grid 同样的响应式布局
4. 确保暗色模式下的霓虹发光效果

管道压力降计算 HTML 设计规范（HG/T 20570.7-95）

设计参考文件

• 用户认可的设计：D:\RayClaw\PE Calculation\01-Pipelines\不可压缩流体压力降计算-Pipe Pressure Drop-Incompressible-Ver2.1.html
• 生成文件示例：D:\RayClaw\PE Calculation\01-Pipelines\不可压缩流体压力降计算-Pipe Pressure Drop-Incompressible.html
• Visual 版本：D:\RayClaw\PE Calculation\01-Pipelines\不可压缩流体压力降计算-Pipe Pressure Drop-V2.Visual.html

INPUT PARAMETERS 必须包含的 5 个子项

流量输入方式（必须实现）

<!-- 模式切换按钮 -->
<div class="mode-toggle">
    <button class="mode-btn active" onclick="setMode('vol')">体积流量 qv (m³/h)</button>
    <button class="mode-btn" onclick="setMode('mass')">质量流量 qm (kg/h)</button>
</div>
<!-- 体积流量输入 -->
<div id="grpVol">
    <label>体积流量 qv (m³/h)</label>
    <input type="number" id="qv" oninput="syncFlow('vol')">
</div>
<!-- 质量流量输入 -->
<div id="grpMass" style="display:none">
    <label>质量流量 qm (kg/h)</label>
    <input type="number" id="qm" oninput="syncFlow('mass')">
</div>

• 切换时同步显示另一字段的值
• syncFlow() 函数根据密度自动换算

管壁粗糙度参考（必须实现）

• 使用 .tip-wrap 包裹粗糙度输入框
• Hover 显示常见管材粗糙度表格
• 点击表格中的数值自动填入输入框

<div class="fg tip-wrap">
    <label>管壁粗糙度 ε (mm) <span class="tip-hint">⬡ 参考</span></label>
    <input type="number" id="eps" value="0.2">
    <div class="tip">
        <div class="tip-head">常见管材粗糙度参考值</div>
        <table>
            <tr><td>碳钢管（无缝）</td><td class="tv" onclick="pickEps(0.2)">0.2</td></tr>
            <!-- 更多管材... -->
        </table>
    </div>
</div>

管件当量长度（推荐使用可视化面板）

推荐方案：使用上方的「合并式可视化输入面板」替代传统表格。

摩擦系数计算流程

1. 判断流态：Re < 2000 → 层流（λ = 64/Re）
2. 湍流：Swamee-Jain 初值 → Colebrook 迭代（50次收敛）
3. 条件判据：crit = 1/(ε/d × Re × √λ)
• crit < 0.05 → 完全湍流区，采用尼库拉则-卡门公式
• crit ≥ 0.05 → 过渡/光滑区，采用 Colebrook 结果

压力降分解

• 摩擦压降 ΔPf = λ × (L/d) × (ρu²/2) × 10⁻³ kPa
• 静压降 ΔPs = ρg(Z₂-Z₁) × 10⁻³ kPa
• 速度压降 ΔPv = ρ(u₂²-u₁²)/2 × 10⁻³ kPa
• 设备压降 ΔPe = 换热器 + 流量计 + 过滤器 + 其他

常见坑点与修复经验

坑点 1：JS 顶层代码 null reference 导致整个

Skill工具集 © 2026