majiayu000 AutoHotkey v1 - Guide de Référence Optimisé LLM
Guide structuré des bonnes pratiques AutoHotkey v1 pour développeurs et assistants IA
Structure du Guide
PARTIE I - RÈGLES CRITIQUES : Erreurs fatales à éviter absolument PARTIE II - STANDARDS FONDAMENTAUX : Encodage, nommage, architecture PARTIE III - DÉVELOPPEMENT : Patterns, GUI, performance PARTIE IV - VALIDATION : Tests et déploiement
PARTIE I - RÈGLES CRITIQUES
Erreur #0 : Section Auto-Execute - LA RÈGLE LA PLUS CRITIQUE
QU'EST-CE QUE L'AUTO-EXECUTE?
La section auto-execute est le code qui s'exécute automatiquement au démarrage du script. C'est la source #1 des bugs incompréhensibles en AutoHotkey!
CE QUI TERMINE L'AUTO-EXECUTE
L'auto-execute se termine dès qu'AutoHotkey rencontre:
- Un
returnexplicite - Un
Exit - UNE FONCTION (ligne commençant par
NomFonction() {) - UN HOTKEY/HOTSTRING (ligne contenant
::) - UN LABEL (ligne se terminant par
:) - La fin physique du fichier
ERREUR FATALE - Code après une fonction
#SingleInstance Force
global myVar := "value"
MyFunction() { ; CETTE FONCTION TERMINE L'AUTO-EXECUTE!
MsgBox, Function
}
; CE CODE NE S'EXÉCUTERA JAMAIS AU DÉMARRAGE!
MsgBox, Script started ; Jamais affiché!
Menu, Tray, Icon, icon.ico ; Jamais chargé!
return
STRUCTURE CORRECTE
#SingleInstance Force
global myVar := "value"
; Code d'initialisation (s'exécute au démarrage)
MsgBox, Script started
Menu, Tray, Icon, icon.ico
; FIN EXPLICITE de l'auto-execute
return
; Fonctions (après le return)
MyFunction() {
MsgBox, Function
}
; Hotkeys (après les fonctions)
^a::
MyFunction()
return
STRUCTURE DE FICHIER OBLIGATOIRE
#Directives (#SingleInstance, #Persistent, etc.)
↓
Variables globales
↓
AUTO-EXECUTE (code qui s'exécute au démarrage)
↓
return ← FIN EXPLICITE de l'auto-execute
↓
Fonctions
↓
Labels
↓
Hotkeys/Hotstrings
↓
#Include (À LA TOUTE FIN!)
PLACEMENT DES #INCLUDE - RÈGLE ABSOLUE
Les #Include DOIVENT être À LA TOUTE FIN du fichier, après:
- Toutes les fonctions
- Tous les labels
- Tous les hotkeys
POURQUOI? Les modules appellent souvent des fonctions du fichier principal (comme Logger_Info). Si l'include est placé avant la définition de ces fonctions, le script plantera!
Erreur #1 : Includes Manquants ou Incorrects
SOLUTION OBLIGATOIRE
#Include %A_ScriptDir%\VA.ahk ; Chemin absolu TOUJOURS
RÈGLE ABSOLUE
- Tous les includes doivent utiliser
%A_ScriptDir%\pour les chemins absolus
Erreur #2 : Syntaxe Variables dans %var%
SYNTAXE INVALIDE
MsgBox, Device: %devices[1].name% ; ERREUR FATALE
SOLUTION OBLIGATOIRE
deviceName := devices[1].name ; Extraire la propriété
MsgBox, Device: %deviceName% ; Utiliser la variable simple
Erreur #3 : Usage Incorrect de global
USAGE CORRECT
MyFunction() {
global ; En DÉBUT de fonction seulement
; OU global var1, var2 pour variables spécifiques
}
MyLabel:
; Les variables sont globales par défaut dans les labels
; PAS de déclaration global nécessaire
return
Erreur #4 : Gestion Tableaux Vides
.MaxIndex retourne "" (chaîne vide) pour un tableau vide, pas 0.
VÉRIFICATION CORRECTE
ArrayCount := Array.MaxIndex
if (ArrayCount = "") {
ArrayCount := 0 ; Conversion explicite
}
Loop % ArrayCount {
Element := Array[A_Index]
}
PARTIE II - STANDARDS FONDAMENTAUX
Encodage : UTF-8 avec BOM OBLIGATOIRE
Sans UTF-8 avec BOM, les caractères accentués deviennent illisibles.
SOLUTION UNIQUE
- Éditeur : Sauvegarder en UTF-8 AVEC BOM
- Lecture :
FileRead, var, *t *p65001 %file% - Écriture :
FileAppend, content, %file%, UTF-8
Architecture de Projet
PROJET SIMPLE (≤ 200 lignes)
MonScript.ahk # Tout en un seul fichier
PROJET MODULAIRE (200-1000 lignes)
Projet/
├── Main.ahk # Point d'entrée
├── Config.ahk # Variables globales
├── Modules/
│ ├── Module1.ahk # Fonctionnalités
│ └── Module2.ahk
└── logs/ # Logs (auto-créé)
Standards de Nommage
; Fichiers et dossiers : PascalCase
MyModule.ahk, Utils/, Core/
; Variables globales : MAJUSCULES
global LOG_ENABLED := true
global EMAIL_ADDRESS := "user@domain.com"
; Fonctions : PascalCase
SendEmailGmail()
GetAudioDevicesList()
; Variables locales : camelCase
local deviceName := "Speakers"
currentTime := A_Now
PARTIE III - DÉVELOPPEMENT
Gestion des Objets COM (Audio/System)
PATTERN OBLIGATOIRE
FunctionWithCOM() {
; 1. Créer les objets
if !(enumerator := VA_GetDeviceEnumerator()) {
return "Erreur création enumerator"
}
VA_IMMDeviceEnumerator_EnumAudioEndpoints(enumerator, 0, 1, devices)
; 2. Traitement
VA_IMMDeviceCollection_GetCount(devices, count)
Loop, %count% {
VA_IMMDeviceCollection_Item(devices, A_Index - 1, device)
; Traiter device...
ObjRelease(device) ; LIBÉRER CHAQUE OBJET
}
; 3. Nettoyage OBLIGATOIRE
ObjRelease(devices)
ObjRelease(enumerator)
}
Chaque objet COM créé DOIT être libéré avec ObjRelease().
Interface Graphique
SOLUTIONS SIMPLES ET ROBUSTES
Edit Control avec Scroll Natif
Gui, Add, Edit, x10 y10 w500 h300 ReadOnly VScroll HScroll vContentArea
GuiControl,, ContentArea, %LongText% ; Scroll automatique
RÈGLES GUI ESSENTIELLES
- Simplicité : Privilégier les contrôles natifs (Edit, ListBox)
- Séparation : GUI distinctes pour différentes fonctions
- Scroll natif : Laisser AutoHotkey gérer le scroll
- Boutons fixes : Placer les boutons hors des zones scrollables
PARTIE IV - VALIDATION
Checklist Pré-Déploiement
VALIDATION TECHNIQUE OBLIGATOIRE
- Encodage : UTF-8 avec BOM sur tous les fichiers .ahk
- Includes : Tous les chemins utilisent
%A_ScriptDir%\ - Tableaux : Vérification
MaxIndex = ""pour tableaux vides - COM : Tous les objets libérés avec
ObjRelease() - Global : Utilisé uniquement en début de fonctions
- Variables : Pas d'accès propriétés dans
%var%
Règles d'Or à Retenir
- UTF-8 avec BOM : Obligatoire pour les accents
- Includes absolus : Toujours avec
%A_ScriptDir%\ - Variables simples : Dans
%var%, pas de propriétés d'objets - Global correct : Fonctions seulement, jamais dans labels
- Tableaux vides : Vérifier
MaxIndex = "" - COM cleanup :
ObjRelease()obligatoire - Log unique : Un seul fichier actif par session
- Hotkeys à la fin : Convention et bonne pratique
- Auto-execute : Toujours terminer par
returnexplicite - Includes en dernier : À la fin du fichier principal