Utilisation de l’objet UndoRecord

À mesure que les utilisateurs finaux travaillent dans Word, les actions qu’ils effectuent qui peuvent être annulées sont enregistrées dans une file d’attente ( la « pile d’annulation ») de sorte que si l’utilisateur décide d’inverser l’action, Word peut rappeler l’action effectuée et l’annuler. Cette pile visible dans l’interface utilisateur de Word, sur le ruban via le bouton Annuler, dans laquelle chaque opération est listée en tant qu’enregistrement discret dans la pile. Automation utilisant le modèle objet Word écrit également ces « enregistrements d’annulation » dans la pile d’annulation, mais l’utilisation de la pile d’annulation à l’aide de peut être problématique.

Les développeurs écrivent parfois du code qui effectue une tâche logique à l’aide d’une série d’actions, où chaque action est enregistrée en tant qu’entrée distincte dans la pile d’annulation. Toutefois, même si l’utilisateur final peut annuler chaque action séparément, il est parfois logique d’annuler toutes les étapes de la tâche en tant qu’unité et non individuellement.

Par exemple, un développeur peut écrire du code qui effectue la tâche d’insertion de métadonnées de document dans le pied de page d’un document Word, comme indiqué dans l’exemple de code suivant.

Sub AddDocMetadata() 
Dim rngFooter As Range 
 
    Set rngFooter = ActiveDocument.Sections(1) _ 
        .Footers(wdHeaderFooterPrimary).Range 
         
    With rngFooter 
        .Delete 
        .Fields.Add Range:=rngFooter, Type:=wdFieldFileName, Text:="\p" 
        .InsertAfter Text:=vbTab & vbTab 
        .Collapse Direction:=wdCollapseStart 
        .Fields.Add Range:=rngFooter, Type:=wdFieldAuthor 
    End With     
End Sub 

Les enregistrements d’annulation résultants apparaissent sur la pile d’annulation pour les actions effectuées par le code.

Si l’utilisateur final doit ensuite restaurer ou annuler la tâche « Insérer des métadonnées », chaque action associée à la tâche doit être annulée individuellement (en appuyant sur Ctrl+Z ou en cliquant sur la flèche déroulante du bouton Annuler , puis en sélectionnant les actions à annuler). Dans ce cas, l’utilisateur final peut annuler partiellement la série d’actions associées à la tâche unique, ce qui laisse éventuellement le document dans un état indésirable.

Le modèle objet Word offre un moyen d’éviter ce problème en offrant aux développeurs la possibilité de lier une série d’actions individuelles à un enregistrement d’annulation personnalisé qui peut ensuite être utilisé pour annuler les actions en une seule unité. Un enregistrement d’annulation personnalisé est représenté dans le modèle objet Word par l’objet UndoRecord .

Utilisation de l’objet UndoRecord

L’objet UndoRecord est une propriété de l’objet Application dans Word. Vous créez un enregistrement d’annulation personnalisé à l’aide des méthodes StartCustomRecord et EndCustomRecord de l’objet UndoRecord . Prenons l’exemple de code suivant qui modifie l’exemple précédent pour inclure un enregistrement d’annulation personnalisé.

Dim objUndo As UndoRecord 
 
Sub AddDocMetadata() 
Dim rngFooter As Range 
 
Set objUndo = Application.UndoRecord 
 
'Begin the custom undo record and provide a name for the record 
objUndo.StartCustomRecord ("Add Doc Metadata") 
     
 Set rngFooter = ActiveDocument.Sections(1) _ 
        .Footers(wdHeaderFooterPrimary).Range 
         
 With rngFooter 
        .Delete 
        .Fields.Add Range:=rngFooter, Type:=wdFieldFileName, Text:="\p" 
        .InsertAfter Text:=vbTab & vbTab 
        .Collapse Direction:=wdCollapseStart 
        .Fields.Add Range:=rngFooter, Type:=wdFieldAuthor 
 End With 
 
'End the custom undo record 
objUndo.EndCustomRecord 
     
End Sub 

La méthode StartCustomRecord commence à enregistrer les actions incluses dans l’enregistrement d’annulation personnalisé. Vous pouvez attribuer un nom à l’enregistrement d’annulation personnalisé en tant qu’argument de la méthode StartCustomRecord , mais cela est facultatif. Si vous ne spécifiez pas de nom, Word utilise le nom Visual Basic de la première commande exécutée comme nom de l’enregistrement. Le nom de l’enregistrement d’annulation personnalisé est la chaîne qui apparaît dans l’interface utilisateur dans la liste déroulante en regard du bouton Annuler .

La méthode EndCustomRecord arrête l’enregistrement d’annulation personnalisé. Toutes les actions effectuées par le code entre l’appel StartCustomRecord et l’appel EndCustomRecord sont liées dans un objet UndoRecord . Lorsque vous exécutez du code qui crée un enregistrement d’annulation personnalisé, comme dans l’exemple de code précédent, l’enregistrement d’annulation personnalisé est répertorié dans la pile d’annulation en tant qu’entrée unique.

UndoRecord, membres de l’objet

Le tableau suivant répertorie les autres membres importants de l’objet UndoRecord.

Meilleures pratiques

• Fermez chaque enregistrement d’annulation personnalisé avec un appel à EndCustomRecord. Word tente de déterminer où terminer l’enregistrement, mais il se peut qu’il ne se trouve pas au point souhaité d’exécution du code.

• Appelez la méthode Undo de l’objet Document dans l’ordre approprié lors de l’appel à partir d’un enregistrement d’annulation personnalisé. L’appel de la méthode Undo dans un ordre incorrect dans un enregistrement d’annulation personnalisé peut avoir des effets indésirables sur l’exécution de votre code. L’exemple de code suivant montre la méthode Undo appelée à partir d’un enregistrement d’annulation personnalisé.

Sub UndoInUndoRecord() 
   
  Set objUndo = Application.UndoRecord 
  
  objUndo.StartCustomRecord ("New Paragraph") 
  
  ActiveDocument.Content.InsertAfter Text:=" The end." 
  ActiveDocument.Undo 
  ActiveDocument.Content.InsertAfter Text:=" The end, again." 
  ActiveDocument.Content.InsertAfter Text:=" The last end." 
 
  objUndo.EndCustomRecord 
 
End Sub

Lorsque ce code est exécuté, chaque action de l’enregistrement d’annulation personnalisé avant l’appel de méthode Undo est annulée. Chaque action de l’enregistrement d’annulation personnalisé après l’appel de méthode Undo est placée dans la pile d’annulation.

• Évitez de changer de document à l’intérieur d’un enregistrement d’annulation personnalisé. L’exemple de code suivant passe d’un document à un autre à l’intérieur d’un enregistrement d’annulation personnalisé.

Dim objUndo As UndoRecord 

Sub SwitchDocsInsideUndo() 
  Set objUndo = Application.UndoRecord objUndo.StartCustomRecord ("New Paragraph") 
  
  'Insert some text into the first document Documents(1).Content.InsertAfter "A new paragraph in doc1." 
  
  'Switch documents to the second document 
  'The custom undo record will terminate here Documents(2).Content.InsertAfter "A new paragraph in doc2." 
  
  objUndo.EndCustomRecord 
End Sub

Lorsque ce code est exécuté, Word met fin à l’enregistrement d’annulation personnalisé lorsque le code commence à écrire dans le deuxième document. Une fois la procédure terminée, seul le premier document a un enregistrement d’annulation personnalisé nommé « Nouveau paragraphe ».

• Évitez d’utiliser Breaks lors de l’exécution de code qui contient des enregistrements d’annulation personnalisés en mode Débogage. Lorsque le code qui contient des enregistrements d’annulation est exécuté en mode Débogage dans l’éditeur Visual Basic et que le code rencontre un point d’arrêt, Word met automatiquement fin à tous les enregistrements personnalisés en cours d’exécution.

Assistance et commentaires

Avez-vous des questions ou des commentaires sur Office VBA ou sur cette documentation ? Consultez la rubrique concernant l’assistance pour Office VBA et l’envoi de commentaires afin d’obtenir des instructions pour recevoir une assistance et envoyer vos commentaires.