docs: fields

Author: lissavxo

docs/README.md

@@ -1127,6 +1127,40 @@ donationRate = 10
 ```
 <!-- tabs:end -->
 
+## fields
+
+> **The 'fields' parameter specifies custom input fields to collect additional information from users before payment.**
+
+?> This parameter is optional. Default value is empty. Possible values are an array of field objects or a JSON string. Each field object can have the following properties: `name` (required, unique identifier), `text` (required, label displayed to user), `type` (input type like 'text', 'email', 'number'), `value` (default value), and `required` (boolean).
+
+**Example:**
+<!-- tabs:start -->
+
+#### ** HTML **
+
+```html
+fields='[{"name": "email", "text": "Email Address", "type": "email", "required": true}, {"name": "note", "text": "Note", "type": "text"}]'
+```
+
+#### ** JavaScript **
+
+```javascript
+fields: [
+  { name: 'email', text: 'Email Address', type: 'email', required: true },
+  { name: 'note', text: 'Note', type: 'text' }
+]
+```
+
+#### ** React **
+
+```react
+fields = {[
+  { name: 'email', text: 'Email Address', type: 'email', required: true },
+  { name: 'note', text: 'Note', type: 'text' }
+]}
+```
+<!-- tabs:end -->
+
 # Contribute
 
 PayButton is a community-driven open-source initiative. Contributions from the community are _crucial_ to the success of the project.

docs/zh-cn/README.md

@@ -1126,6 +1126,77 @@ donationRate = 10
 ```
 <!-- tabs:end -->
 
+## fields
+
+> **「fields」参数用于指定自定义输入字段，以便在付款前收集用户的额外信息。**
+
+?> 此参数是可选的。默认值为空。可接受的值是字段对象数组或 JSON 字符串。每个字段对象可以包含以下属性：`name`（必填，唯一标识符）、`text`（必填，显示给用户的标签）、`type`（输入类型，如 'text'、'email'、'number'）、`value`（默认值）和 `required`（布尔值）。
+
+**Example:**
+<!-- tabs:start -->
+
+#### ** HTML **
+
+```html
+fields='[{"name": "email", "text": "电子邮件地址", "type": "email", "required": true}, {"name": "note", "text": "备注", "type": "text"}]'
+```
+
+#### ** JavaScript **
+
+```javascript
+fields: [
+  { name: 'email', text: '电子邮件地址', type: 'email', required: true },
+  { name: 'note', text: '备注', type: 'text' }
+]
+```
+
+#### ** React **
+
+```react
+fields = {[
+  { name: 'email', text: '电子邮件地址', type: 'email', required: true },
+  { name: 'note', text: '备注', type: 'text' }
+]}
+```
+<!-- tabs:end -->
+
+## on-fields-submit
+
+> **「on-fields-submit」参数用于指定当用户提交自定义字段时运行的回调函数。**
+
+?> 此参数是可选的。默认值为空。可接受的值是任何已定义的函数。
+
+#### *callback* 参数
+
+- **fieldValues** (`object`): 包含以字段名称为键的字段值对象
+
+**Example:**
+<!-- tabs:start -->
+
+#### ** HTML **
+
+```html
+on-fields-submit="fieldsSubmitCallback"
+```
+
+#### ** JavaScript **
+
+```javascript
+onFieldsSubmit: (fieldValues) => {
+  console.log('Fields submitted:', fieldValues);
+  // fieldValues 示例: { email: 'user@example.com', note: '我的付款备注' }
+}
+```
+
+#### ** React **
+
+```react
+onFieldsSubmit = {(fieldValues) => {
+  console.log('Fields submitted:', fieldValues);
+}}
+```
+<!-- tabs:end -->
+
 
 # 贡献
 

docs/zh-tw/README.md

@@ -1122,6 +1122,77 @@ donationRate = 10
 ```
 <!-- tabs:end -->
 
+## fields
+
+> **「fields」參數用於指定自訂輸入欄位，以便在付款前收集用戶的額外資訊。**
+
+?> 此參數是可選的。預設值為空。可接受的值是欄位物件陣列或 JSON 字串。每個欄位物件可以包含以下屬性：`name`（必填，唯一識別碼）、`text`（必填，顯示給用戶的標籤）、`type`（輸入類型，如 'text'、'email'、'number'）、`value`（預設值）和 `required`（布林值）。
+
+**Example:**
+<!-- tabs:start -->
+
+#### ** HTML **
+
+```html
+fields='[{"name": "email", "text": "電子郵件地址", "type": "email", "required": true}, {"name": "note", "text": "備註", "type": "text"}]'
+```
+
+#### ** JavaScript **
+
+```javascript
+fields: [
+  { name: 'email', text: '電子郵件地址', type: 'email', required: true },
+  { name: 'note', text: '備註', type: 'text' }
+]
+```
+
+#### ** React **
+
+```react
+fields = {[
+  { name: 'email', text: '電子郵件地址', type: 'email', required: true },
+  { name: 'note', text: '備註', type: 'text' }
+]}
+```
+<!-- tabs:end -->
+
+## on-fields-submit
+
+> **「on-fields-submit」參數用於指定當用戶提交自訂欄位時執行的回呼函數。**
+
+?> 此參數是可選的。預設值為空。可接受的值是任何已定義的函數。
+
+#### *callback* 參數
+
+- **fieldValues** (`object`): 包含以欄位名稱為鍵的欄位值物件
+
+**Example:**
+<!-- tabs:start -->
+
+#### ** HTML **
+
+```html
+on-fields-submit="fieldsSubmitCallback"
+```
+
+#### ** JavaScript **
+
+```javascript
+onFieldsSubmit: (fieldValues) => {
+  console.log('Fields submitted:', fieldValues);
+  // fieldValues 示例: { email: 'user@example.com', note: '我的付款備註' }
+}
+```
+
+#### ** React **
+
+```react
+onFieldsSubmit = {(fieldValues) => {
+  console.log('Fields submitted:', fieldValues);
+}}
+```
+<!-- tabs:end -->
+
 
 # 貢獻