From cf36a3216bd3fb68f8e1f8745143c725f57d5e40 Mon Sep 17 00:00:00 2001
From: Zeke Zhang <958414905@qq.com>
Date: Wed, 2 Apr 2025 16:58:01 +0800
Subject: [PATCH] chore: add comment

---
 .../collection-field/CollectionField.tsx      | 22 ++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/packages/core/client/src/data-source/collection-field/CollectionField.tsx b/packages/core/client/src/data-source/collection-field/CollectionField.tsx
index d9aa8ec998..4b00af3a79 100644
--- a/packages/core/client/src/data-source/collection-field/CollectionField.tsx
+++ b/packages/core/client/src/data-source/collection-field/CollectionField.tsx
@@ -102,12 +102,28 @@ const CollectionFieldInternalField = (props) => {
   const dynamicProps = useDynamicComponentProps(uiSchema?.['x-use-component-props'], props);
 
   useEffect(() => {
-    // There seems to be a bug in formily where after setting a field to readPretty, switching to editable,
-    // then back to readPretty, and refreshing the page, the field remains in editable state. The expected state is readPretty.
-    // This code is meant to fix this issue.
+    /**
+     * There seems to be a bug in formily where after setting a field to readPretty, switching to editable,
+     * then back to readPretty, and refreshing the page, the field remains in editable state. The expected state is readPretty.
+     * This code is meant to fix this issue.
+     */
     if (fieldSchema['x-read-pretty'] === true && !field.readPretty) {
       field.readPretty = true;
     }
+
+    /**
+     * This solves the issue: After creating a form and setting a field to "read-only", the field remains editable when refreshing the page and reopening the dialog.
+     *
+     * Note: This might be a bug in Formily
+     * When both x-disabled and x-read-pretty exist in the Schema:
+     * - If x-disabled appears before x-read-pretty in the Schema JSON, the disabled state becomes ineffective
+     * - The reason is that during field instance initialization, field.disabled is set before field.readPretty, which causes the pattern value to be changed to 'editable'
+     * - This issue is related to the order of JSON fields, which might return different orders in different environments (databases), thus making the issue inconsistent to reproduce
+     *
+     * Reference to Formily source code:
+     * 1. Setting readPretty may cause pattern to be changed to 'editable': https://github.com/alibaba/formily/blob/d4bb96c40e7918210b1bd7d57b8fadee0cfe4b26/packages/core/src/models/BaseField.ts#L208-L224
+     * 2. The execution order of the each method depends on the order of JSON fields: https://github.com/alibaba/formily/blob/123d536b6076196e00b4e02ee160d72480359f54/packages/json-schema/src/schema.ts#L486-L519
+     */
     if (fieldSchema['x-disabled'] === true) {
       field.disabled = true;
     }