fix: 优化代码&增加注释

Author: DymoneLewis

packages/extension/src/bpmn-adapter/index.ts

@@ -127,6 +127,13 @@ const defaultRetainedFields = [
   'pointsList',
 ]
 
+/**
+ * XML 实体反转义：
+ * - 将常见的 XML 实体还原为字符：`&lt;`→`<`、`&gt;`→`>`、`&amp;`→`&`、`&quot;`→`"`、`&apos;`→`'`；保障流程图能正常回填
+ * - 使用 `String(text || '')` 规范化输入，避免 `null/undefined` 导致错误；
+ * - 注意：此实现为单次替换，若存在嵌套/二次编码（例如 `&amp;lt;`），会先还原为 `&lt;`，
+ *   如需完全解码，可在外层循环调用或调整替换顺序策略。
+ */
 const unescapeXml = (text: string) =>
   String(text || '')
     .replace(/&lt;/g, '<')

packages/extension/src/bpmn-adapter/json2xml.ts

@@ -26,15 +26,29 @@ function handleAttributes(o: any) {
   return t
 }
 
+/**
+ * 将普通文本中的一些特殊字符进行转移，保障文本安全地嵌入 XML：
+ * - 空值(`null/undefined`)返回空字符串，避免输出非法字面量；
+ * - 按顺序转义 XML 保留字符：`&`, `<`, `>`, `"`, `'`；
+ *   注意优先转义 `&`，避免后续生成的实体被再次转义。
+ * @param text 原始文本
+ * @returns 已完成 XML 转义的字符串
+ */
 function escapeXml(text: string) {
+  // 空值直接返回空字符串，防止在 XML 中出现 "null"/"undefined"
   if (text == null) return ''
-  return text
-    .toString()
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&apos;')
+  return (
+    text
+      .toString()
+      // & 必须先转义，避免影响后续 < > " ' 的实体
+      .replace(/&/g, '&amp;')
+      // 小于号与大于号，用于标签边界
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      // 双引号与单引号，用于属性值的包裹
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;')
+  )
 }
 
 function getAttributes(obj: any) {
@@ -110,4 +124,4 @@ function lfJson2Xml(o: Object) {
   return xmlStr
 }
 
-export { lfJson2Xml, handleAttributes }
+export { lfJson2Xml, handleAttributes, escapeXml }

packages/extension/src/bpmn-adapter/xml2json.ts

@@ -3,6 +3,7 @@
 // ========================================================================
 //  XML.ObjTree -- XML source code from/to JavaScript object like E4X
 // ========================================================================
+import { escapeXml } from './json2xml'
 
 let XML = function () {}
 
@@ -282,16 +283,7 @@ XML.ObjTree.prototype.scalar_to_xml = function (name, text) {
 
 //  method: xml_escape( text )
 
-XML.ObjTree.prototype.xml_escape = function (text) {
-  if (text == null) return ''
-  return text
-    .toString()
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&apos;')
-}
+XML.ObjTree.prototype.xml_escape = escapeXml
 
 /*
 // ========================================================================