Skip to content

FORMATS_FICHIERS.md

Latest commit

 

History

History
772 lines (608 loc) · 16.5 KB

FORMATS_FICHIERS.md

File metadata and controls

772 lines (608 loc) · 16.5 KB

Guide des Formats de Fichiers - MiniSheet

📋 Table des Matières

  1. Introduction
  2. Format JSON de MiniSheet
  3. Structure du Fichier
  4. Exemples de Fichiers
  5. Formats Non Supportés
  6. Édition Manuelle
  7. Conversion et Migration
  8. Limitations
  9. FAQ

Introduction

MiniSheet utilise le format JSON (JavaScript Object Notation) pour sauvegarder les feuilles de calcul. Ce format est :

  • ✅ Lisible par l'homme : Vous pouvez ouvrir et lire les fichiers dans un éditeur de texte
  • ✅ Portable : Compatible avec de nombreux outils et langages
  • ✅ Standard : Format largement utilisé et supporté
  • ✅ Complet : Sauvegarde toutes les données, formules et formatage

Extension de Fichier

Les fichiers MiniSheet utilisent l'extension .json par défaut.

Exemple : mon_tableur.json

Format JSON de MiniSheet

Vue d'Ensemble

Un fichier MiniSheet est un fichier JSON valide qui contient :

  • Les dimensions de la feuille (nombre de lignes et colonnes)
  • Le contenu brut de toutes les cellules (valeurs et formules)
  • Le formatage de toutes les cellules (couleurs, polices, alignement)

Format de Sérialisation

MiniSheet utilise JSON formaté (pretty-printed), ce qui signifie que le fichier est indenté et facile à lire.

Avantages :

  • Facile à déboguer
  • Facile à éditer manuellement
  • Facile à comparer avec des outils de diff

Inconvénient :

  • Fichiers légèrement plus volumineux (mais généralement négligeable)

Structure du Fichier

Structure Principale

{
  "rows": 30,
  "cols": 15,
  "raw": [...],
  "formats": [...]
}

Champs Principaux

rows (nombre)

  • Type : Nombre entier
  • Description : Nombre de lignes dans la feuille
  • Exemple : 30

cols (nombre)

  • Type : Nombre entier
  • Description : Nombre de colonnes dans la feuille
  • Exemple : 15

raw (tableau)

  • Type : Tableau d'objets
  • Description : Contenu brut de toutes les cellules non vides
  • Structure : Chaque entrée contient row, col, et value

formats (tableau)

  • Type : Tableau d'objets
  • Description : Formatage de toutes les cellules formatées
  • Structure : Chaque entrée contient row, col, et format

Structure d'une Entrée raw

{
  "row": 0,
  "col": 0,
  "value": "10"
}

Champs :

  • row : Numéro de ligne (0-indexé, 0 = première ligne)
  • col : Numéro de colonne (0-indexé, 0 = colonne A)
  • value : Contenu brut de la cellule (texte, nombre, ou formule commençant par =)

Exemples de valeurs :

  • "10" : Nombre
  • "Hello" : Texte
  • "=A1+B1" : Formule
  • "=SUM(A1:A10)" : Formule avec fonction

Structure d'une Entrée formats

{
  "row": 0,
  "col": 0,
  "format": {
    "bold": false,
    "italic": false,
    "fg_color": null,
    "bg_color": [255, 240, 240],
    "alignment": "Left"
  }
}

Champs du format :

  • bold : true ou false (gras)
  • italic : true ou false (italique)
  • fg_color : null ou [r, g, b] (couleur du texte, RGB 0-255)
  • bg_color : null ou [r, g, b] (couleur de fond, RGB 0-255)
  • alignment : "Left", "Center", ou "Right"

Note : null signifie qu'aucune couleur personnalisée n'est définie (couleur par défaut).

Exemples de Fichiers

Exemple 1 : Feuille Simple

Contenu de la feuille :

  • A1: 10
  • A2: 20
  • A3: =A1+A2

Fichier JSON :

{
  "rows": 30,
  "cols": 15,
  "raw": [
    {
      "row": 0,
      "col": 0,
      "value": "10"
    },
    {
      "row": 1,
      "col": 0,
      "value": "20"
    },
    {
      "row": 2,
      "col": 0,
      "value": "=A1+A2"
    }
  ],
  "formats": []
}

Exemple 2 : Avec Formatage

Contenu de la feuille :

  • A1: Titre (gras, centré, fond bleu)
  • B1: Valeur (gras)
  • A2: 10
  • B2: 20

Fichier JSON :

{
  "rows": 30,
  "cols": 15,
  "raw": [
    {
      "row": 0,
      "col": 0,
      "value": "Titre"
    },
    {
      "row": 0,
      "col": 1,
      "value": "Valeur"
    },
    {
      "row": 1,
      "col": 0,
      "value": "10"
    },
    {
      "row": 1,
      "col": 1,
      "value": "20"
    }
  ],
  "formats": [
    {
      "row": 0,
      "col": 0,
      "format": {
        "bold": true,
        "italic": false,
        "fg_color": null,
        "bg_color": [173, 216, 230],
        "alignment": "Center"
      }
    },
    {
      "row": 0,
      "col": 1,
      "format": {
        "bold": true,
        "italic": false,
        "fg_color": null,
        "bg_color": null,
        "alignment": "Left"
      }
    }
  ]
}

Exemple 3 : Feuille Complexe

Contenu de la feuille :

  • A1: Produit
  • B1: Prix
  • C1: Quantité
  • D1: Total
  • A2: Pommes
  • B2: 2.50
  • C2: 10
  • D2: =B2*C2
  • A3: Bananes
  • B3: 1.80
  • C3: 5
  • D3: =B3*C3
  • D4: =SUM(D2:D3)

Fichier JSON :

{
  "rows": 30,
  "cols": 15,
  "raw": [
    {
      "row": 0,
      "col": 0,
      "value": "Produit"
    },
    {
      "row": 0,
      "col": 1,
      "value": "Prix"
    },
    {
      "row": 0,
      "col": 2,
      "value": "Quantité"
    },
    {
      "row": 0,
      "col": 3,
      "value": "Total"
    },
    {
      "row": 1,
      "col": 0,
      "value": "Pommes"
    },
    {
      "row": 1,
      "col": 1,
      "value": "2.50"
    },
    {
      "row": 1,
      "col": 2,
      "value": "10"
    },
    {
      "row": 1,
      "col": 3,
      "value": "=B2*C2"
    },
    {
      "row": 2,
      "col": 0,
      "value": "Bananes"
    },
    {
      "row": 2,
      "col": 1,
      "value": "1.80"
    },
    {
      "row": 2,
      "col": 2,
      "value": "5"
    },
    {
      "row": 2,
      "col": 3,
      "value": "=B3*C3"
    },
    {
      "row": 3,
      "col": 3,
      "value": "=SUM(D2:D3)"
    }
  ],
  "formats": []
}

Formats Non Supportés

Formats Actuellement Non Supportés

MiniSheet ne supporte pas les formats suivants :

❌ Excel (.xlsx, .xls)

  • Raison : Format binaire complexe nécessitant des bibliothèques spécialisées
  • Alternative : Utilisez un convertisseur externe (voir section Conversion)

❌ CSV (.csv)

  • Raison : Format simple mais ne supporte pas les formules ni le formatage
  • Alternative : Utilisez un convertisseur externe si vous avez besoin de CSV

❌ OpenDocument Spreadsheet (.ods)

  • Raison : Format XML complexe
  • Alternative : Utilisez un convertisseur externe

❌ Google Sheets

  • Raison : Format propriétaire nécessitant une API
  • Alternative : Exportez depuis Google Sheets vers CSV, puis convertissez

Formats Futurs Potentiels

Les formats suivants pourraient être ajoutés dans de futures versions :

  • ✅ CSV (import/export simple)
  • ✅ Excel (.xlsx) (via bibliothèque externe)
  • ✅ OpenDocument (.ods)

Édition Manuelle

Quand Éditer Manuellement ?

Vous pouvez éditer un fichier MiniSheet manuellement dans les cas suivants :

  • ✅ Correction d'une erreur de syntaxe JSON
  • ✅ Modification en masse de valeurs
  • ✅ Ajout de données depuis un script
  • ✅ Réparation d'un fichier corrompu
  • ✅ Extraction de données

Précautions

⚠️ Attention : L'édition manuelle peut corrompre le fichier si vous faites une erreur.

Avant d'éditer :

  1. Faites une copie de sauvegarde du fichier
  2. Vérifiez que le JSON est valide (utilisez un validateur JSON)
  3. Testez le fichier dans MiniSheet après modification

Outils Recommandés

Éditeurs de texte :

  • VS Code (avec extension JSON)
  • Notepad++ (Windows)
  • Sublime Text
  • Vim/Emacs

Validateurs JSON en ligne :

  • jsonlint.com
  • jsonformatter.org

Outils de ligne de commande :

# Vérifier la validité JSON
python -m json.tool fichier.json

# Formater le JSON
jq . fichier.json > fichier_formate.json

Exemples d'Édition

Ajouter une Cellule

Avant :

{
  "raw": [
    {"row": 0, "col": 0, "value": "10"}
  ]
}

Après (ajout de A2 = 20) :

{
  "raw": [
    {"row": 0, "col": 0, "value": "10"},
    {"row": 1, "col": 0, "value": "20"}
  ]
}

Modifier une Valeur

Avant :

{"row": 0, "col": 0, "value": "10"}

Après (changer en 15) :

{"row": 0, "col": 0, "value": "15"}

Ajouter du Formatage

Avant :

{
  "formats": []
}

Après (gras sur A1) :

{
  "formats": [
    {
      "row": 0,
      "col": 0,
      "format": {
        "bold": true,
        "italic": false,
        "fg_color": null,
        "bg_color": null,
        "alignment": "Left"
      }
    }
  ]
}

Supprimer une Cellule

Supprimez simplement l'entrée correspondante du tableau raw :

Avant :

{
  "raw": [
    {"row": 0, "col": 0, "value": "10"},
    {"row": 1, "col": 0, "value": "20"}
  ]
}

Après (suppression de A2) :

{
  "raw": [
    {"row": 0, "col": 0, "value": "10"}
  ]
}

Conversion et Migration

Depuis Excel (.xlsx)

Méthode 1 : Copier-Coller

  1. Ouvrez votre fichier Excel
  2. Sélectionnez et copiez les données (Ctrl+A, Ctrl+C)
  3. Ouvrez MiniSheet
  4. Collez les données (Ctrl+V)
  5. Enregistrez dans MiniSheet (Ctrl+S)

Méthode 2 : Export CSV puis Import

  1. Dans Excel : Fichier > Enregistrer sous > CSV
  2. Ouvrez le CSV dans un éditeur de texte
  3. Copiez les données
  4. Collez dans MiniSheet
  5. Ajustez le formatage si nécessaire

Méthode 3 : Script Python (avancé)

import json
import openpyxl  # pip install openpyxl

# Lire Excel
wb = openpyxl.load_workbook('fichier.xlsx')
ws = wb.active

# Convertir en format MiniSheet
raw = []
for row_idx, row in enumerate(ws.iter_rows()):
    for col_idx, cell in enumerate(row):
        if cell.value is not None:
            raw.append({
                "row": row_idx,
                "col": col_idx,
                "value": str(cell.value)
            })

sheet = {
    "rows": ws.max_row,
    "cols": ws.max_column,
    "raw": raw,
    "formats": []
}

# Sauvegarder
with open('fichier.json', 'w', encoding='utf-8') as f:
    json.dump(sheet, f, indent=2, ensure_ascii=False)

Vers Excel (.xlsx)

Méthode 1 : Copier-Coller

  1. Dans MiniSheet : Sélectionnez toutes les cellules (Ctrl+A)
  2. Copiez (Ctrl+C)
  3. Ouvrez Excel
  4. Collez (Ctrl+V)
  5. Enregistrez dans Excel

Méthode 2 : Script Python (avancé)

import json
import openpyxl

# Lire MiniSheet
with open('fichier.json', 'r', encoding='utf-8') as f:
    sheet = json.load(f)

# Créer Excel
wb = openpyxl.Workbook()
ws = wb.active

# Écrire les données
for entry in sheet['raw']:
    row = entry['row'] + 1  # Excel est 1-indexé
    col = entry['col'] + 1
    ws.cell(row=row, column=col, value=entry['value'])

# Sauvegarder
wb.save('fichier.xlsx')

Depuis CSV

Méthode 1 : Copier-Coller

  1. Ouvrez le CSV dans un éditeur de texte
  2. Copiez tout (Ctrl+A, Ctrl+C)
  3. Dans MiniSheet, collez dans A1 (Ctrl+V)
  4. Les données seront collées ligne par ligne

Méthode 2 : Script Python

import json
import csv

# Lire CSV
raw = []
with open('fichier.csv', 'r', encoding='utf-8') as f:
    reader = csv.reader(f)
    for row_idx, row in enumerate(reader):
        for col_idx, value in enumerate(row):
            if value.strip():  # Ignorer les cellules vides
                raw.append({
                    "row": row_idx,
                    "col": col_idx,
                    "value": value
                })

# Créer MiniSheet
sheet = {
    "rows": max([e["row"] for e in raw]) + 1 if raw else 30,
    "cols": max([e["col"] for e in raw]) + 1 if raw else 15,
    "raw": raw,
    "formats": []
}

# Sauvegarder
with open('fichier.json', 'w', encoding='utf-8') as f:
    json.dump(sheet, f, indent=2, ensure_ascii=False)

Vers CSV

Méthode 1 : Copier-Coller

  1. Dans MiniSheet : Sélectionnez les données
  2. Copiez (Ctrl+C)
  3. Collez dans un éditeur de texte
  4. Sauvegardez avec l'extension .csv

Méthode 2 : Script Python

import json
import csv

# Lire MiniSheet
with open('fichier.json', 'r', encoding='utf-8') as f:
    sheet = json.load(f)

# Créer un dictionnaire pour accès rapide
cells = {(e['row'], e['col']): e['value'] for e in sheet['raw']}

# Écrire CSV
with open('fichier.csv', 'w', encoding='utf-8', newline='') as f:
    writer = csv.writer(f)
    for row in range(sheet['rows']):
        csv_row = []
        for col in range(sheet['cols']):
            value = cells.get((row, col), '')
            csv_row.append(value)
        writer.writerow(csv_row)

Limitations

Limitations du Format JSON

  1. Pas de Support Multi-Feuilles

    • Un fichier = une feuille
    • Pour plusieurs feuilles, utilisez plusieurs fichiers

  2. Pas de Graphiques

    • Les graphiques ne sont pas sauvegardés
    • Seules les données sont préservées

  3. Pas de Macros

    • Les macros ne sont pas supportées
    • Utilisez des formules à la place

  4. Pas de Commentaires de Cellules

    • Les commentaires ne sont pas sauvegardés

  5. Pas de Validation de Données

    • Les règles de validation ne sont pas sauvegardées

  6. Pas de Tableaux Croisés Dynamiques

    • Non supporté

Limitations Techniques

  1. Taille des Fichiers

    • Les très grandes feuilles peuvent produire des fichiers volumineux
    • Le JSON formaté augmente légèrement la taille

  2. Performance

    • Les très grandes feuilles peuvent prendre du temps à charger/sauvegarder

  3. Compatibilité

    • Les fichiers ne sont pas compatibles avec Excel directement
    • Nécessite une conversion

FAQ

Q: Puis-je ouvrir un fichier MiniSheet dans Excel ?

R: Non, directement. Vous devez convertir le fichier JSON en Excel en utilisant un script ou en copiant-collant les données.

Q: Puis-je ouvrir un fichier Excel dans MiniSheet ?

R: Non, directement. Vous devez convertir le fichier Excel en JSON ou copier-coller les données.

Q: Les formules sont-elles préservées lors de la conversion ?

R:

  • MiniSheet → Excel : Oui, si vous copiez-collez, les formules sont préservées
  • Excel → MiniSheet : Oui, si vous copiez-collez, les formules sont converties (si compatibles)

Q: Le formatage est-il préservé lors de la conversion ?

R:

  • MiniSheet → Excel : Le formatage de base (gras, italique, couleurs) est préservé lors du copier-coller
  • Excel → MiniSheet : Le formatage de base est préservé lors du copier-coller

Q: Puis-je éditer un fichier MiniSheet avec un éditeur de texte ?

R: Oui, mais soyez prudent. Assurez-vous que le JSON reste valide après modification.

Q: Que se passe-t-il si je corromps un fichier JSON ?

R: MiniSheet affichera une erreur lors de l'ouverture. Vous pouvez essayer de réparer le JSON manuellement ou restaurer depuis une sauvegarde.

Q: Puis-je compresser un fichier MiniSheet ?

R: Oui, vous pouvez utiliser un outil de compression (ZIP, 7z) pour réduire la taille. MiniSheet peut toujours ouvrir le fichier compressé après décompression.

Q: Les fichiers MiniSheet sont-ils sécurisés ?

R: Les fichiers JSON sont en texte clair. Ne partagez pas de fichiers contenant des informations sensibles sans les protéger (chiffrement, mots de passe, etc.).

Q: Puis-je automatiser la création de fichiers MiniSheet ?

R: Oui, vous pouvez créer des fichiers JSON programmatiquement (Python, JavaScript, etc.) et les ouvrir dans MiniSheet.

Q: Quelle est la taille maximale d'un fichier MiniSheet ?

R: Il n'y a pas de limite stricte, mais les très grandes feuilles (millions de cellules) peuvent être lentes à charger/sauvegarder.

Résumé

Format Supporté

  • ✅ JSON : Format natif de MiniSheet

Formats Non Supportés

  • ❌ Excel (.xlsx, .xls)
  • ❌ CSV (.csv)
  • ❌ OpenDocument (.ods)
  • ❌ Google Sheets

Caractéristiques

  • ✅ Format lisible par l'homme
  • ✅ Format standard et portable
  • ✅ Supporte toutes les fonctionnalités de MiniSheet
  • ✅ Facile à éditer manuellement
  • ✅ Facile à convertir depuis/vers d'autres formats

Recommandations

  1. Sauvegardez régulièrement : Utilisez Ctrl+S fréquemment
  2. Faites des sauvegardes : Gardez des copies de vos fichiers importants
  3. Validez le JSON : Si vous éditez manuellement, validez le JSON
  4. Utilisez la conversion : Pour Excel/CSV, utilisez les méthodes de conversion décrites

Dernière mise à jour : 2026-01-20

Version : 0.1.0