如何在 React + TypeScript 中實現 JSON 格式化功能

作為前端開發者，我們經常需要處理 JSON 數據。無論是 API 調試、配置文件編輯還是數據轉換，能夠格式化 JSON 是一項基本但非常有用的技能。本文將詳細介紹如何在 React 和 TypeScript 環境中實現 JSON 格式化功能，包括基礎知識、實現步驟和最佳實踐。

一、JSON 基礎知識回顧

1.1 什么是 JSON？

JSON（JavaScript Object Notation）是一種輕量級的數據交換格式，易于人閱讀和編寫，同時也易于機器解析和生成。它基于 JavaScript 的一個子集，但獨立于語言，幾乎所有現代編程語言都支持 JSON。

1.2 JSON 的基本結構

JSON 由以下幾種數據類型組成：

• 對象：無序的鍵值對集合，用花括號 {} 表示
• 數組：有序的值集合，用方括號 [] 表示
• 字符串：用雙引號 "" 包裹的文本
• 數字：整數或浮點數
• 布爾值：true 或 false
• null：表示空值

1.3 有效的 JSON 示例

{"name": "Alice","age": 25,"isStudent": false,"skills": ["TypeScript", "React", "Node.js"],"address": {"city": "Beijing","postalCode": "100000"}
}

二、JavaScript 中的 JSON 處理方法

JavaScript 提供了兩個內置方法來處理 JSON：

2.1 JSON.parse()

JSON.parse() 方法用于將 JSON 字符串解析為 JavaScript 值或對象。

語法：

JSON.parse(text[, reviver])

• text: 要解析的 JSON 字符串
• reviver (可選): 轉換結果的函數，類似于映射函數

示例：

const jsonString = '{"name":"Alice","age":25}';
const obj = JSON.parse(jsonString);
console.log(obj.name); // 輸出: Alice

注意事項：

• 如果傳入的字符串不是有效的 JSON，JSON.parse() 會拋出 SyntaxError
• JSON 字符串中的屬性名必須用雙引號 "" 包裹，單引號無效
• JSON 不支持注釋

2.2 JSON.stringify()

JSON.stringify() 方法用于將 JavaScript 值或對象轉換為 JSON 字符串。

語法：

JSON.stringify(value[, replacer[, space]])

• value: 要轉換的 JavaScript 值或對象
• replacer (可選): 用于轉換結果的函數或數組
• space (可選): 用于縮進的空格數或字符串

示例：

const obj = {name: "Alice", age: 25};
const jsonString = JSON.stringify(obj, null, 2);
console.log(jsonString);
/*
輸出:
{"name": "Alice","age": 25
}
*/

參數詳解：

• replacer 參數可以是：
  • null 或 undefined: 不使用替換器
  • 函數: 對每個屬性進行轉換
  • 數組: 指定要包含的屬性名
• space 參數用于控制縮進：
  • 數字: 表示縮進的空格數（通常 2 或 4）
  • 字符串: 使用該字符串作為縮進（最多 10 個字符）

三、在 React + TypeScript 中實現 JSON 格式化

現在，讓我們實現一個完整的 React + TypeScript 組件，用于格式化用戶輸入的 JSON 字符串。

3.1 創建基本組件結構

首先，我們創建一個基本的 React 組件，包含一個文本區域用于輸入 JSON 和一個顯示格式化結果的文本區域。

import React, { useState } from 'react';
import { Form, Input, Button, notification } from 'antd';const JsonFormatter: React.FC = () => {const [inputJson, setInputJson] = useState<string>('');const [formattedJson, setFormattedJson] = useState<string>('');const handleFormat = () => {try {// 嘗試解析 JSONconst parsed = JSON.parse(inputJson);// 格式化 JSONconst formatted = JSON.stringify(parsed, null, 2);// 更新狀態setFormattedJson(formatted);// 顯示成功通知notification.success({message: 'JSON 格式化成功',});} catch (error) {// 處理錯誤console.error('JSON 解析失敗:', error);notification.error({message: 'JSON 格式錯誤',description: '請輸入有效的 JSON 字符串。',});}};return (<div style={{ padding: '20px' }}><h1>JSON 格式化工具</h1><div style={{ marginBottom: '10px' }}><label htmlFor="jsonInput">輸入 JSON: </label><Input.TextAreaid="jsonInput"value={inputJson}onChange={(e) => setInputJson(e.target.value)}rows={6}style={{ width: '100%' }}/></div><Button type="primary" onClick={handleFormat}>格式化 JSON</Button><div style={{ marginTop: '20px' }}><label>格式化結果: </label><Input.TextAreavalue={formattedJson}rows={6}style={{ width: '100%' }}readOnly/></div></div>);
};export default JsonFormatter;

3.2 使用 Ant Design Form 的實現

如果你已經在項目中使用 Ant Design 的 Form 組件，可以這樣實現：

import React from 'react';
import { Form, Input, Button, notification } from 'antd';interface JsonFormatterFormProps {form: any; // 實際使用時應該使用 FormInstance 類型
}const JsonFormatterForm: React.FC<JsonFormatterFormProps> = ({ form }) => {const handleFormatJson = () => {try {// 獲取表單中的輸入值const input = form.getFieldValue('jsonInput') || '';// 嘗試解析 JSONconst parsed = JSON.parse(input);// 格式化 JSONconst formatted = JSON.stringify(parsed, null, 2);// 設置格式化后的值到表單form.setFieldsValue({ jsonOutput: formatted });// 顯示成功通知notification.success({message: 'JSON 格式化成功',});} catch (error) {// 處理錯誤console.error('JSON 解析失敗:', error);notification.error({message: 'JSON 格式錯誤',description: '請輸入有效的 JSON 字符串。',});}};return (<Form form={form}><Form.Item name="jsonInput" label="輸入 JSON"><Input.TextArea rows={6} /></Form.Item><Button type="primary" onClick={handleFormatJson}>格式化 JSON</Button><Form.Item name="jsonOutput" label="格式化結果"><Input.TextArea rows={6} readOnly /></Form.Item></Form>);
};export default JsonFormatterForm;

3.3 添加高級功能

我們可以進一步增強這個組件，添加一些有用的功能：

1. 自動檢測并格式化：當用戶停止輸入一段時間后自動格式化
2. 復制到剪貼板：添加一個按鈕將格式化后的 JSON 復制到剪貼板
3. 支持 JSON 注釋：使用第三方庫處理帶注釋的 JSON

3.3.1 自動檢測并格式化

import React, { useState, useEffect } from 'react';
import { Form, Input, Button, notification } from 'antd';const JsonFormatterWithAutoFormat: React.FC = () => {const [inputJson, setInputJson] = useState<string>('');const [formattedJson, setFormattedJson] = useState<string>('');const [typingTimeout, setTypingTimeout] = useState<number | null>(null);const handleInputChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {const value = e.target.value;setInputJson(value);// 清除之前的定時器if (typingTimeout) {clearTimeout(typingTimeout);}// 設置新的定時器，300ms 后執行格式化const timeoutId = window.setTimeout(() => {formatJson(value);}, 300);setTypingTimeout(timeoutId);};const formatJson = (jsonString: string) => {try {const parsed = JSON.parse(jsonString);const formatted = JSON.stringify(parsed, null, 2);setFormattedJson(formatted);notification.success({message: 'JSON 格式化成功',});} catch (error) {// 輸入過程中允許有錯誤，不顯示通知setFormattedJson(''); // 清空結果}};// 組件卸載時清除定時器useEffect(() => {return () => {if (typingTimeout) {clearTimeout(typingTimeout);}};}, [typingTimeout]);return (<div style={{ padding: '20px' }}><h1>JSON 格式化工具 (自動)</h1><div style={{ marginBottom: '10px' }}><label htmlFor="jsonInput">輸入 JSON: </label><Input.TextAreaid="jsonInput"value={inputJson}onChange={handleInputChange}rows={6}style={{ width: '100%' }}/></div><div style={{ marginTop: '20px' }}><label>格式化結果: </label><Input.TextAreavalue={formattedJson}rows={6}style={{ width: '100%' }}readOnly/></div></div>);
};export default JsonFormatterWithAutoFormat;

3.3.2 復制到剪貼板功能

import React, { useState } from 'react';
import { Form, Input, Button, notification } from 'antd';const JsonFormatterWithCopy: React.FC = () => {const [inputJson, setInputJson] = useState<string>('');const [formattedJson, setFormattedJson] = useState<string>('');const handleFormat = () => {try {const parsed = JSON.parse(inputJson);const formatted = JSON.stringify(parsed, null, 2);setFormattedJson(formatted);notification.success({message: 'JSON 格式化成功',});} catch (error) {notification.error({message: 'JSON 格式錯誤',description: '請輸入有效的 JSON 字符串。',});}};const handleCopy = () => {if (!formattedJson) {notification.warning({message: '沒有可復制的內容',});return;}navigator.clipboard.writeText(formattedJson).then(() => {notification.success({message: '已復制到剪貼板',});}).catch(err => {console.error('復制失敗:', err);notification.error({message: '復制失敗',description: '請手動復制或檢查瀏覽器權限。',});});};return (<div style={{ padding: '20px' }}><h1>JSON 格式化工具 (帶復制功能)</h1><div style={{ marginBottom: '10px' }}><label htmlFor="jsonInput">輸入 JSON: </label><Input.TextAreaid="jsonInput"value={inputJson}onChange={(e) => setInputJson(e.target.value)}rows={6}style={{ width: '100%' }}/></div><Button type="primary" onClick={handleFormat} style={{ marginRight: '10px' }}>格式化 JSON</Button><Button onClick={handleCopy} disabled={!formattedJson}>復制到剪貼板</Button><div style={{ marginTop: '20px' }}><label>格式化結果: </label><Input.TextAreavalue={formattedJson}rows={6}style={{ width: '100%' }}readOnly/></div></div>);
};export default JsonFormatterWithCopy;

四、錯誤處理和邊界情況

在實現 JSON 格式化功能時，我們需要考慮各種可能的錯誤情況和邊界條件。

4.1 常見的 JSON 格式錯誤

1. 缺少引號：JSON 屬性名必須用雙引號包裹

   • 錯誤示例: {name: "Alice"}
   • 正確示例: {"name": "Alice"}

2. 尾隨逗號：對象或數組最后一項不能有逗號

   • 錯誤示例: {"a": 1, "b": 2,}
   • 正確示例: {"a": 1, "b": 2}

3. 單引號：JSON 必須使用雙引號，單引號無效

   • 錯誤示例: {'name': 'Alice'}
   • 正確示例: {"name": "Alice"}

4. 注釋：標準 JSON 不支持注釋

   • 錯誤示例: {"name": "Alice" /* 注釋 */}
   • 正確示例: {"name": "Alice"}

4.2 增強錯誤處理

我們可以改進錯誤處理，提供更具體的錯誤信息：

const handleFormat = () => {if (!inputJson.trim()) {notification.warning({message: '輸入為空',description: '請輸入 JSON 字符串。',});return;}try {const parsed = JSON.parse(inputJson);const formatted = JSON.stringify(parsed, null, 2);setFormattedJson(formatted);notification.success({message: 'JSON 格式化成功',});} catch (error) {if (error instanceof SyntaxError) {notification.error({message: 'JSON 語法錯誤',description: error.message,});} else {notification.error({message: '未知錯誤',description: '發生未知錯誤，請檢查輸入。',});}console.error('JSON 解析失敗:', error);}
};

五、性能優化考慮

對于大型 JSON 文件，格式化操作可能會消耗較多資源，影響用戶體驗。以下是一些性能優化建議：

1. 限制輸入大小：設置最大輸入字符數，防止用戶粘貼過大的 JSON 文件
2. Web Worker：將 JSON 解析和格式化操作放到 Web Worker 中執行，避免阻塞主線程
3. 分塊處理：對于非常大的 JSON 文件，可以考慮分塊處理
4. 進度指示：長時間操作時顯示進度指示器

5.1 限制輸入大小的實現

const MAX_JSON_SIZE = 100000; // 100KBconst handleInputChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {const value = e.target.value;if (value.length > MAX_JSON_SIZE) {notification.warning({message: '輸入過大',description: `JSON 輸入不能超過 ${MAX_JSON_SIZE / 1000}KB`,});return;}setInputJson(value);// ...其余代碼不變
};

六、總結

在本文中，我們詳細介紹了如何在 React 和 TypeScript 環境中實現 JSON 格式化功能。我們從 JSON 的基礎知識開始，回顧了 JavaScript 中的 JSON.parse() 和 JSON.stringify() 方法，然后逐步構建了一個完整的 React 組件，實現了以下功能：

1. 基本的 JSON 格式化功能
2. 完善的錯誤處理和用戶反饋
3. 自動檢測和格式化
4. 復制到剪貼板功能
5. 性能優化考慮

這個功能雖然簡單，但在實際開發中非常實用，無論是作為獨立的工具組件還是集成到更大的應用中。通過這個例子，我們不僅學習了如何處理 JSON 數據，還實踐了 React 和 TypeScript 的最佳實踐，包括狀態管理、錯誤處理和用戶體驗優化。

---

推薦更多閱讀內容
程序員視角：第三方風險管理那些事兒
程序員視角：為什么攻擊后企業總愛“裝死”？我們能做點啥？
大語言模型（LLM）來了，程序員該怎么應對安全問題？
AI 生成的經典貪吃蛇小游戲
普通職場人如何理解AI安全？從五個關鍵問題說起
瀏覽器存儲機制對比（cookie、localStorage、sessionStorage）
Cookie的HttpOnly屬性：作用、配置與前后端分工
從威脅檢測需求看兩類安全監測平臺差異
深入理解JavaScript數組過濾操作（提升代碼優雅性）
JavaScript 數組合并與去重（解析 […value, …ids] 技巧）