iop-bpmn-react 0.0.3 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 IOP Platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,10 +5,12 @@
 ## 特性
 
 - 🎨 **开箱即用** - 提供 BpmnViewer 和 BpmnModeler 两个 React 组件
-- 📝 **Flowable 扩展属性** - 完整支持 26 种 Flowable/activiti 扩展类型
-- 🌐 **国际化** - 内置中文翻译支持
+- 📝 **Flowable 扩展属性** - 完整支持 26 种 Flowable/activiti 扩展类型，属性面板可视化编辑
+- 🌐 **国际化** - 内置中文翻译支持，可扩展其他语言
 - 🎯 **TypeScript** - 完整的类型定义
-- 📦 **多种构建格式** - 支持 ES Module 和 UMD 格式
+- 📐 **自动布局** - 内置 bpmn-auto-layout，支持为缺少坐标信息的 XML 自动生成布局
+- 🔍 **规则校验** - 内置 bpmnlint，实时校验流程规范性
+- ✏️ **手绘风格** - 支持 sketchy 手绘风格渲染
 
 ## 安装
 
@@ -23,16 +25,114 @@ import { BpmnViewer, BpmnModeler } from 'iop-bpmn-react'
 import 'iop-bpmn-react/style.css'
 
 // 只读查看
-function Viewer() {
-  return <BpmnViewer bpmnXml={xml} />
+function ViewerDemo() {
+  return <BpmnViewer xml={bpmnXml} />
 }
 
 // 可编辑建模
-function Modeler() {
-  return <BpmnModeler bpmnXml={xml} />
+function ModelerDemo() {
+  return <BpmnModeler xml={bpmnXml} />
 }
 ```
 
+## 导入
+
+```tsx
+// 组件
+import { BpmnViewer, BpmnModeler } from 'iop-bpmn-react'
+import 'iop-bpmn-react/style.css'
+
+// 工具函数
+import { fitToView, layoutProcess } from 'iop-bpmn-react'
+
+// 国际化
+import { i18n, zhTranslations, addTranslations, getTranslations } from 'iop-bpmn-react'
+
+// 令牌模拟模块
+import { TokenSimulationModule } from 'iop-bpmn-react'
+```
+
+## API
+
+### BpmnViewer
+
+只读 BPMN 流程查看器组件。
+
+```tsx
+<BpmnViewer
+  xml={bpmnXml}
+  autoLayout={false}
+  locale="zh"
+  className="viewer"
+  style={{ width: '100%', height: '500px' }}
+  onInit={(viewer) => { /* viewer 初始化完成 */ }}
+/>
+```
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `xml` | `string` | **必填** | BPMN 2.0 XML 字符串 |
+| `autoLayout` | `boolean` | `false` | 是否自动布局（为缺少 DI 信息的 XML 生成坐标） |
+| `locale` | `'zh' \| 'en' \| 'ja'` | `'zh'` | 界面语言 |
+| `className` | `string` | — | 自定义类名 |
+| `style` | `CSSProperties` | — | 自定义样式 |
+| `onInit` | `(viewer: Viewer) => void` | — | 初始化完成回调 |
+
+### BpmnModeler
+
+可编辑 BPMN 流程建模器组件，内置属性面板。
+
+```tsx
+<BpmnModeler
+  xml={bpmnXml}
+  autoLayout={false}
+  linting={true}
+  sketchy={false}
+  locale="zh"
+  className="modeler"
+  style={{ width: '100%', height: '500px' }}
+  onSave={(xml) => console.log(xml)}
+  onChange={(xml) => console.log(xml)}
+  onInit={(modeler) => { /* modeler 初始化完成 */ }}
+/>
+```
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `xml` | `string` | **必填** | BPMN 2.0 XML 字符串 |
+| `autoLayout` | `boolean` | `false` | 是否自动布局 |
+| `linting` | `boolean` | `false` | 是否启用规则校验 |
+| `sketchy` | `boolean` | `false` | 是否启用手绘风格 |
+| `locale` | `'zh' \| 'en' \| 'ja'` | `'zh'` | 界面语言 |
+| `className` | `string` | — | 画布容器类名 |
+| `style` | `CSSProperties` | — | 画布容器样式 |
+| `panelClassName` | `string` | — | 属性面板容器类名 |
+| `panelStyle` | `CSSProperties` | — | 属性面板容器样式 |
+| `onSave` | `(xml: string) => void` | — | 保存回调 |
+| `onChange` | `(xml: string) => void` | — | 内容变更回调 |
+| `onInit` | `(modeler: Modeler) => void` | — | 初始化完成回调 |
+
+### fitToView
+
+将流程图适配到视口并居中显示。
+
+```tsx
+import { fitToView } from 'iop-bpmn-react'
+
+// 在 onInit 回调中使用
+<BpmnViewer onInit={(viewer) => fitToView(viewer)} />
+```
+
+### layoutProcess
+
+对 BPMN XML 进行自动布局，为缺少坐标信息的元素生成位置。
+
+```tsx
+import { layoutProcess } from 'iop-bpmn-react'
+
+const layoutedXml = await layoutProcess(xmlString)
+```
+
 ## 开发命令
 
 | 任务 | 命令 |
@@ -283,8 +383,8 @@ src/
 
 ## 技术栈
 
-- **Vite** - 构建工具
-- **React 18** + TypeScript
+- **Vite 8** - 构建工具
+- **React 19** + TypeScript
 - **bpmn-js** - BPMN 2.0 流程图引擎
 - **bpmn-js-properties-panel** - 属性面板组件
 - **bpmn-js-i18n** - 国际化翻译