🌐 Language: English (this file) · Italian → README.it.md
SVGHMI Preview (WinCC Unified)
A VS Code extension that opens .svghmi files (Siemens WinCC Unified HMI widgets)
in a single-view Custom Editor (preview + editing in the same panel):
- Top left — Graphic preview: the rendered SVG, with dynamic bindings
(
hmi-bind:*) converted into visible static values.
- Top right — Info panel: widget metadata (from
<hmi:self>), a parameters
table (<hmi:paramDef>) and the list of all bindings, with a count.
- Bottom — Integrated editor: the source XML, editable. As you type, the
preview and info update in real time; save with
Ctrl+S like a normal file.
No second editor opens for the file.
- Indentation: see the shortcuts below.
🌐 The extension UI automatically follows the VS Code display language
(Italian or English).
Indentation and shortcuts
The integrated editor behaves like a code editor. Every action updates the preview
and info in real time and stays in the undo history (Ctrl+Z).
| Shortcut / Action |
Effect |
Tab |
Inserts one indentation level (2 spaces) at the cursor |
Tab (with a multi-line selection) |
Indents all selected lines |
Shift+Tab |
Removes one indentation level from the line / selected lines |
Enter |
Keeps the current line's indentation, with one extra level after an opening tag |
| Format button |
Puts each tag on its own line (>< → >⏎<) and re-indents the whole XML by nesting level |
Ctrl+S |
Saves the file |
Ctrl+Z |
Undoes the last change (including indentation and formatting) |
The Format button is in the top-right bar of the integrated editor. It
respects quotes in attributes (a > inside {{...}} does not break the tag),
the Siemens DOCTYPE, comments and the <?xml?> declaration, and preserves blank
separator lines.
Panels and zoom
The Views bar at the top opens a menu with three checkboxes to show/hide
each panel independently; the remaining areas redistribute the space (at least one
panel must stay visible).
| Command |
Effect |
| Views menu → Preview / Info / Editor |
Toggles the corresponding panel |
| − / 100% / + (top right of the preview) |
Decrease / reset / increase the SVG graphic zoom |
| A− / 100% / A+ (editor bar) |
Decrease / reset / increase the code text size |
Ctrl + wheel over the preview |
Zoom the SVG graphic |
Ctrl + wheel over the editor |
Zoom the code text |
The preview zoom and the editor zoom are independent. The state (zoom and
visible panels) is remembered and restored on reopen.
Adjustable layout
- Side by side / Stack: the button in the top bar switches the Preview and Info
arrangement between side by side (row) and stacked (column), handy on
portrait monitors.
- Draggable splitters: between Preview and Info, and between the top row and the
Editor, there are two splitters you can drag to resize the panels. The
Preview/Info splitter adapts automatically to the current orientation.
Orientation and panel sizes are remembered on reopen too.
Theme
The webview automatically follows the VS Code theme (light, dark or
high-contrast) using the --vscode-* variables, with a fallback to the original
dark palette.
Why it is needed
.svghmi files are XML/SVG with a proprietary DOCTYPE, custom namespaces
(hmi, hmi-bind) and hmi-bind:* attributes that are invalid in standard SVG.
A browser ignores them, so the dynamic graphic is not shown. This extension removes
the DOCTYPE and replaces the bindings with static values so the shape becomes visible.
Project structure
| File |
Role |
src/extension.ts |
Entry point + CustomTextEditorProvider (links document ↔ webview) |
src/parser.ts |
Metadata extraction with fast-xml-parser (no regex) |
src/renderer.ts |
SVG conversion for the preview + webview HTML generation |
src/i18n.ts |
Localized UI strings (English by default, Italian override) |
package.json |
Manifest + customEditors on *.svghmi, viewType svghmi.preview |
package.nls.json / package.nls.it.json |
Manifest translations (name and description) |
examples/sample.svghmi |
Sample file for testing |
Build
Prerequisites: Node.js ≥ 18 and npm.
npm install # install dependencies (incl. fast-xml-parser)
npm run compile # compile TypeScript -> out/
To recompile automatically on every change:
npm run watch
Debugging (F5)
- Open this folder in VS Code.
- Run
npm install (once).
- Press F5 ("Run Extension"): an Extension Development Host window opens.
- In that window open
examples/sample.svghmi (or one of your .svghmi files).
- The Custom Editor opens automatically with the preview + info panel.
Edit the file: the preview updates in real time.
If it does not exist yet, create .vscode/launch.json with the standard
"Run Extension" configuration (type: extensionHost). The generator-code
scaffolding generates it automatically.
Packaging (.vsix)
npx --yes @vscode/vsce package
This produces a svghmi-preview-0.2.1.vsix file. To install it:
code --install-extension svghmi-preview-0.2.1.vsix
or in VS Code: Extensions → … → Install from VSIX…
Technical notes
- Robust parsing:
fast-xml-parser keeps namespace prefixes, so hmi:self,
hmi:paramDef and the hmi-bind:* attributes stay recognizable.
- Security: all extracted data goes through HTML escaping before reaching the
webview (anti-injection).
- Robustness: if the file is malformed, a readable error page is shown instead
of a crash or a blank webview.
- Localization: UI strings live in
src/i18n.ts (English by default, Italian
when VS Code runs in Italian); the extension name and description use the
package.nls*.json files.
