zul-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ZUL Writer

ZUL编写工具

Workflow Overview

工作流概述

This skill creates well-structured zul pages through a 4-step process:

Clarify Requirements - Gather page purpose, pattern, and layout needs
Generate ZUL - Create the ZUL file based on requirements
Validate ZUL - Verify correctness of the generated ZUL
Generate Controller Class - Create the corresponding Java class (ViewModel or Composer)

Alternative entry: When user provides a UI image (screenshot/mockup), perform the Visual Analysis below first, then proceed to the 4-step process.

本工具通过4步流程创建结构规范的zul页面：

需求澄清 - 收集页面用途、模式、布局需求
生成ZUL - 基于需求创建ZUL文件
验证ZUL - 校验生成的ZUL的正确性
生成控制器类 - 创建对应的Java类（ViewModel或Composer）

替代入口：当用户提供UI图片（截图/原型稿）时，先执行下方的可视化分析，再进入4步流程。

Visual Analysis (for Images/Mockups)

可视化分析（针对图片/原型稿）

When a UI screenshot or mockup image is provided, perform this analysis before starting the 4-step workflow:

Visual Breakdown: Identify all UI elements (layout, inputs, buttons, tables, navigation).
Component & Layout Strategy: Plan the ZK component mapping (refer to references/ui-to-component-mapping.md) and determine the overall layout (e.g.,
```
<borderlayout>
```
, nested
```
<vlayout>
```
).
Tab Content Scope: If tabs are present, determine content boundaries. Items switching with tabs must go INSIDE
```
<tabpanel>
```
. See assets/content-tabbox.zul.
Identify Custom Styling: Mark areas that require fallback HTML elements or custom CSS.

Transition: Use these findings to inform Step 1: Clarify User Requirements and eventually Step 2: Generate ZUL File.

当用户提供UI截图或原型稿图片时，在启动4步工作流之前先执行如下分析：

视觉拆解：识别所有UI元素（布局、输入框、按钮、表格、导航）。
组件与布局策略：规划ZK组件映射关系（参考 references/ui-to-component-mapping.md），确定整体布局（例如
```
<borderlayout>
```
、嵌套的
```
<vlayout>
```
）。
标签页内容范围：如果存在标签页，确定内容边界。通过标签页切换的内容必须放在
```
<tabpanel>
```
内部，参考 assets/content-tabbox.zul。
自定义样式识别：标记需要使用兜底HTML元素或自定义CSS的区域。

流转规则：使用上述分析结果支撑第1步：澄清用户需求，最终服务于第2步：生成ZUL文件。

Step 1: Clarify User Requirements

第1步：澄清用户需求

Ask targeted questions to understand needs. If starting from an image, use the results of the Visual Analysis to inform these questions.

提出针对性问题了解需求。如果是基于图片启动流程，使用可视化分析的结果来设计问题。

Questions to Ask

需要询问的问题

1. ZK Version

1. ZK版本

Detect from user's project (check

pom.xml

ivy.xml

, or

build.gradle

for ZK dependency version). If not found, ask:

9 or before
10.x

从用户项目中自动检测（检查

pom.xml

、

ivy.xml

或

build.gradle

中的ZK依赖版本）。如果找不到版本信息，询问用户：

9或更早版本
10.x版本

2. Page Purpose

2. 页面用途

Data entry form
Data list/grid display
Dashboard with multiple sections
Dialog/popup window
Master-detail view
Search and results page
Other: [specify]

数据录入表单
数据列表/网格展示
多区块仪表盘
对话框/弹窗
主从视图
搜索与结果页
其他：[请说明]

3. MVC or MVVM Pattern

3. MVC或MVVM模式

Present both options with equal weight — do NOT mark either as "(Recommended)":

MVVM: ViewModel-based with
```
@bind
```
/
```
@command
```
data binding — testable, requires more ZK familiarity
MVC: Composer-based with
```
apply
```
and wired components — straightforward, beginner-friendly

平等展示两个选项，不要将任意选项标记为「（推荐）」：

MVVM：基于ViewModel，使用
```
@bind
```
/
```
@command
```
数据绑定——可测试性高，需要更熟悉ZK
MVC：基于Composer，使用
```
apply
```
和组件绑定——逻辑直观，对新手友好

4. Layout Requirements

4. 布局需求

Borderlayout (north/south/east/west/center)
Vertical layout (vlayout)
Horizontal layout (hlayout)
Grid-based layout
Tabbed layout (tabbox)
Combined layouts

Borderlayout（北/南/东/西/中五区域布局）
垂直布局（vlayout）
水平布局（hlayout）
网格布局
标签页布局（tabbox）
组合布局

5. ZK Charts (only when charts are needed)

5. ZK Charts（仅当需要图表时询问）

If the ZUL page requires a

<charts>

component, follow references/charts-guidelines.md before generating any chart code.

如果ZUL页面需要使用

<charts>

组件，生成任何图表代码前先参考 references/charts-guidelines.md。

6. Theme and Data Density

6. 主题与数据密度

If a page is designed to show a high density of data, suggest to the user to use another free theme called

iceblue_c

, a compact theme that has smaller padding, margin, and font-size.

如果页面需要展示高密度数据，建议用户使用免费的

iceblue_c

紧凑主题，该主题的内边距、外边距和字体大小更小。

Step 2: Generate a ZUL File

第2步：生成ZUL文件

Generation Guidelines

生成规范

When generating the ZUL file, follow these technical guidelines:

Map UI Elements: Consult references/ui-to-component-mapping.md to choose the correct ZK components.
- Prioritize ZK components over native HTML.
- Use layout components like
```
<borderlayout>
```
  ,
```
<vlayout>
```
  , and
```
<hlayout>
```
  effectively.
Handle CSS Inclusion:
- If fallback native HTML elements (e.g.
```
<n:div>
```
  ) are used, identify and include the necessary CSS.
- Use the
```
<style>
```
  element for inline CSS; do not use the
```
<?style ?>
```
  processing instruction.
ZK Documentation:
- Query
```
zk-doc-mcp-server
```
  for detailed component info if available.
- Use ZK Javadoc for properties and event details.
Best Practices:
- Don't specify
```
hflex="min"
```
  on
```
<button>
```
  (it's
```
display: inline-block
```
  by default).
- Use meaningful IDs and follow the assets/template.zul structure.

生成ZUL文件时，遵循如下技术规范：

映射UI元素：参考 references/ui-to-component-mapping.md 选择正确的ZK组件。
- 优先使用ZK组件而非原生HTML。
- 合理使用
```
<borderlayout>
```
  、
```
<vlayout>
```
  、
```
<hlayout>
```
  等布局组件。
CSS引入处理：
- 如果使用了兜底原生HTML元素（例如
```
<n:div>
```
  ），识别并引入必要的CSS。
- 使用
```
<style>
```
  元素编写行内CSS；不要使用
```
<?style ?>
```
  处理指令。
ZK文档参考：
- 如有可用的
```
zk-doc-mcp-server
```
  ，查询其获取组件详细信息。
- 使用 ZK Javadoc 查看属性和事件详情。
最佳实践：
- 不要在
```
<button>
```
  上设置
```
hflex="min"
```
  （默认已经是
```
display: inline-block
```
  ）。
- 使用有意义的ID，遵循 assets/template.zul 的结构。

Layout & Component Patterns

布局与组件模式

XML & Pattern Structures

XML与模式结构

Base Template: assets/template.zul
MVC Structure: assets/mvc-sample.zul
MVVM Structure: assets/mvvm-pattern-structure.zul

基础模板：assets/template.zul
MVC结构：assets/mvc-sample.zul
MVVM结构：assets/mvvm-pattern-structure.zul

Sizing & Layouts

尺寸与布局

Flexible Sizing (hflex/vflex): assets/flexible-sizing.zul
Borderlayout Example: assets/borderlayout-example.zul

弹性尺寸（hflex/vflex）：assets/flexible-sizing.zul
Borderlayout示例：assets/borderlayout-example.zul

Common MVVM Patterns

常用MVVM模式

Form with Validation
Data Grid with Selection
Master-Detail Pattern
Dialog/Popup

带校验的表单
支持选择的数据网格
主从模式
对话框/弹窗

Step 3: Validate Generated ZUL

第3步：验证生成的ZUL

Run validation using the script from this skill's base directory (provided as "Base directory for this skill:" in the skill context header):

bash

python3 <skill-base-dir>/scripts/validate-zul.py <path-to-zul-file>

Example: if the skill base directory is

/Users/hawk/.claude/skills/zul-writer

, run:

bash

python3 /Users/hawk/.claude/skills/zul-writer/scripts/validate-zul.py path/to/file.zul

Layer 1: XML well-formedness (no dependencies)
Layer 2: XSD schema validation (requires
```
lxml
```
)
Layer 3: Attribute placement check (requires
```
lxml
```
) - catches misplaced attributes (e.g.
```
iconSclass
```
on
```
textbox
```
)
Layer 4: ZK 10 compatibility checks (only if target ZK version is 10)

使用本工具根目录下的脚本执行验证（工具根目录会在技能上下文头部的「Base directory for this skill:」字段中提供）：

bash

python3 <skill-base-dir>/scripts/validate-zul.py <path-to-zul-file>

示例：如果工具根目录是

/Users/hawk/.claude/skills/zul-writer

，执行：

bash

python3 /Users/hawk/.claude/skills/zul-writer/scripts/validate-zul.py path/to/file.zul

第1层：XML格式合法性校验（无依赖）
第2层：XSD schema校验（需要
```
lxml
```
）
第3层：属性位置校验（需要
```
lxml
```
）—— 捕获位置错误的属性（例如
```
textbox
```
上的
```
iconSclass
```
）
第4层：ZK 10兼容性校验（仅当目标ZK版本为10时执行）

Prerequisites

前置依赖

Layer 2 and 3 require

lxml

. The script handles this automatically — it will install

lxml

via

uv pip install

(preferred) or

pip install

if missing. No manual setup needed before running the script.

第2、3层校验需要

lxml

。脚本会自动处理依赖——如果缺少

lxml

，会优先通过

uv pip install

安装，其次使用

pip install

安装。运行脚本前无需手动配置。

Post-Validation Checklist

校验后检查清单

Pattern Consistency

模式一致性

MVC: Uses
```
apply
```
attribute, no MVVM binding expressions
MVVM: Uses
```
viewModel
```
attribute, proper binding syntax
No mixing of patterns on same component

MVC：使用
```
apply
```
属性，无MVVM绑定表达式
MVVM：使用
```
viewModel
```
属性，绑定语法正确
同一组件上不能混合使用两种模式

Best Practices

最佳实践

IDs are unique within each ID space owner (
```
<window>
```
,
```
<idspace>
```
)
Prefer
```
sclass
```
over inline styles
Prefer
```
hflex
```
/
```
vflex
```
over fixed dimensions
Include meaningful labels and tooltips for accessibility

每个ID空间所有者（
```
<window>
```
、
```
<idspace>
```
）内的ID唯一
优先使用
```
sclass
```
而非行内样式
优先使用
```
hflex
```
/
```
vflex
```
而非固定尺寸
为可访问性考虑，添加有意义的标签和提示文本

Step 4: Generate Controller Class

第4步：生成控制器类

Generate the corresponding Java controller class (ViewModel or Composer) for the ZUL page.

为ZUL页面生成对应的Java控制器类（ViewModel或Composer）。

Controller Generation Guidelines

控制器生成规范

Pattern Consistency:
- Use ViewModel for MVVM patterns.
- Use Composer for MVC patterns.
Implementation Details: Follow the technical requirements in references/controller-guidelines.md.

模式一致性：
- MVVM模式使用 ViewModel。
- MVC模式使用 Composer。
实现细节：遵循 references/controller-guidelines.md 中的技术要求。

MVC Pattern - Composer Class

MVC模式 - Composer类

assets/MyComposer.java

MVVM Pattern - ViewModel Class

MVVM模式 - ViewModel类

assets/MyViewModel.java

Complete Examples & Patterns

完整示例与模式

For complex UI patterns like Kanban Boards or Dashboards, and for complete template examples, refer to references/use-case-guidelines.md.

针对看板、仪表盘等复杂UI模式，以及完整模板示例，参考 references/use-case-guidelines.md。