Modèle d'extension Zotero

Ceci est un modèle pour développer une extension pour Zotero.

Documentation
- 📖 Plugin Development Documentation (Chinese, not yet complete)
- 📖 Plugin Development Documentation for Zotero 7
Outils pour le développement de pluqgins

Tip

👁 Surveillez ce dépôt afin d'être informé des corrections et des mises à jour.

Exetensions développées sur la base de ce modèle

Si vous utilisez ce dépôt, je vous recommande de mettre le badge suivant dans votre README :

[![Using Zotero Plugin Template](https://img.shields.io/badge/Using-Zotero%20Plugin%20Template-blue?style=flat-square&logo=github)](https://github.com/windingwind/zotero-plugin-template)

Fonctionalités

Architecture orientée événements, basée sur la programmation fonctionnelle utilisant des squeletteq étendus ;
Simple et convivial, il est prêt à l'emploi.
⭐ [Nuveauté !] Rechargement automatique à chaud ! Chaque fois que le code source est modifié, il est automatiquement compilé et rechargé. [Voir ici→]((#auto-hot-reload)
Nombreux exemples dans src/modules/examples.ts ; ils couvrent la plupart des usages des APIs habituellement utilisées dans les extensions (en utilisant zotero-plugin-toolkit);
Support de TypeScript :
- Prise en charge complète de la définition des types pour l'ensemble du projet Zotero, qui est écrit en JavaScript (avec les zotero-types);
- Variables globales et configuration de l'environnement ;
Gestion des workflows pour le développement, la finalisation et la publication des extensions :
- - Génére / met à jour automatiquement l'id/version de l'extension, met à jour les configurations, et définit les variables d'environnement (development / production);
- Construit et recharge automatiquement le code dans Zotero ;
- Publie automatiquement les nouvelles versions sur GitHub.
Intégration avec Prettier et ES Lint (analyseur et formatteur de code).

Exemples

Ce dépot fournit des exemples pour les API zotero-plugin-toolkit.

Recherchez @example dans src/examples.ts. Les exemples sont appelés dans src/hooks.ts.

Exemples basiques

registerNotifier
registerPrefs, unregisterPrefs

Exemples utilisant les raccourcis clavier

registerShortcuts
exampleShortcutLargerCallback
exampleShortcutSmallerCallback
exampleShortcutConflictionCallback

Exemples d'interface utilisateur (UI)

registerStyleSheet (utilisé par l'extension officielle make-it-red qui sert d'exemple)
registerRightClickMenuItem
registerRightClickMenuPopup
registerWindowMenuWithSeprator
registerExtraColumn
registerExtraColumnWithCustomCell
registerCustomItemBoxRow
registerLibraryTabPanel
registerReaderTabPanel

Exemples avec des panneaux de préférences

Liaisons avec les préférences
Événements de l'interface utilisateur
Table
Locale

Voir src/modules/preferenceScript.ts

Exemples de fenêtre d'aide

dialogExample
clipboardExample
filePickerExample
progressWindowExample
vtableExample (voir Exemples avec des panneaux de préférences)

Exemples de prompts

Un module d'invite (entrée de commande contextuelle) de style Obsidian. Il accepte les commandes textuelles pour exécuter le callback, avec un affichage optionnel dans la fenêtre popup.

S'active avec Shift+P.

registerAlertPromptExample

Guide de démarrage rapide

0. Pré-requis

Installez une version beta de Zotero: https://www.zotero.org/support/beta_builds
Installez Node.js and Git

Note

Ce guide suppose que vous avez une compréhension initiale de la structure de base et du fonctionnement des extensiosn Zotero. Si ce n'est pas le cas, veuillez vous référer à la documentationet aux exemples officiels de l'extension Make It Red en premier lieu.

1. Créez votre dépôt

Cliquez sur Use this template
Clonez votre dépôt avec git.
💡 Démarrer votre projet avec GitHub Codespace

GitHub CodeSpace vous permet de démarrer votre projet sans avoir à télécharger le code/IDE/dépendances localement.

Effectuez les étapes ci-dessus et créez votre première extension en 30 secondes!
- Allez en haut de la page d'accueil, cliquez sur le bouton vert Use this template, cliquez sur Open in codespace. ous devrez peut-être vous connecter à votre compte GitHub.
- Attendez que GitHub CodeSpace se charge.
Entrez dans le dossier du dépôt

2. Configurez les paramètres du Modèle et l'environnement de développement

Modifier les paramètres dans ./package.json, y compris :

{
  version: "", // to 0.0.0
  author: "",
  description: "",
  homepage: "",
  config: {
    addonName: "", // name to be displayed in the plugin manager
    addonID: "", // ID to avoid conflict. IMPORTANT!
    addonRef: "", // e.g. Element ID prefix
    addonInstance: "", // the plugin's root instance: Zotero.${addonInstance}
    prefsPrefix: "extensions.zotero.${addonRef}", // the prefix of prefs
  },
}

![WARNING] Veillez à bien définir addonID et addonRef pour éviter tout conflit.

Si vous avez besoin d'héberger vos paquets XPI en dehors de GitHub, modifiez updateURL et ajoutez xpiDownloadLink dans zotero-plugin.config.ts.

Copiez le fichier de la variable d'environnement. Modifiez la commandes quilance la version beta de Zotero.

Créez un profil de développement (Optionnel)
Démarrez la version beta de Zotero avec /path/to/zotero -p. Créez un nouveau profil et utilisez-le comme profil de développement. Ne le faites qu'une seule fois !

cp .env.example .env
vim .env

Si vous développez plus d'une extension, vous pouvez stocker le chemin bin et le chemin profile dans les variables d'environnement du système, qui peuvent être omises ici.

Installez les dépendances avec npm install

Si vous utilisez pnpm comme gestionnaire de paquets pour votre projet, vous devez ajouter public-hoist-pattern[]=*@types/bluebird* à .npmrc, voir https://github.com/windingwind/zotero-types?tab=readme-ov-file#usage.

Si vous obtenez npm ERR ! ERESOLVE unable to resolve dependency tree avec npm install, qui est un bogue de dépendance en amont de typescript-eslint, utilisez la commande npm i -f pour l'installer.

3. Codez !

Démarrez le serveur de développement avec npm start:

Il fera La pré-construction de l'extension en mode développement
Il démarrera Zotero avec l'extension chargée depuis build/
Il surveillera src/** et addon/**.
- Si src/** a changé, lancez esbuild et rechargez.
- Si addon/** a changé, reconstruisez l'extension (en mode développement) et recharger là.

Rechargement automatique à chaud

Fatigué des redémarrages incessants ? Oubliez-les !

Lancez npm start.
Coder. (Oui, c'est tout)

Lorsque des changements de fichiers sont détectés dans src ou addon, l'extension 'sera automatiquement compilé et rechargé.

💡 Étapes pour ajouter cette fonctionnalité à une extension existante :

Voir zotero-plugin-scaffold.

Déboguer dans Zotero

Vous pouvez également :

Tester les extraits de code dans Outils -> Développeur -> Run Javascript ;
Déboguer la sortie avecZotero.debug(). Trouver les sorties dans Aide->Journal de débogage->Voir le journal;
Déboguer l'interface utilisateur. Zotero est construit sur le cadre XUL de Firefox. Déboguez l'interface utilisateur XUL avec un logiciel comme XUL Explorer.

Documentation de XUL : http://www.devdoc.net/web/developer.mozilla.org/en-US/docs/XUL.html

4. Construction (Build)

Exécutez npm run build construire l'extension en mode production : t le xpi pour l'installation et le code construit se trouve dans le dossier build.

Étapes de la construction :

Créez/videz build/.
Copiez addon/** dans build/addon/**.
Remplacez les espaces réservés : utilisez replace-in-file pour remplacer les mots-clés et les configurations définis dans package.json dans les fichiers non-construits (xhtml, json, et al.).
Préparez les fichiers de locale pour [éviter les conflits] (https://www.zotero.org/support/dev/zotero_7_for_developers#avoiding_localization_conflicts)
Renommer **/*.flt en **/${addonRef}-*.flt
Préfixez chaque message fluent[TODO] avec addonRef-
Utilisez ESBuild pour construire le code source .ts vers .js, construisez src/index.ts vers ./build/addon/content/scripts.
(Mode production uniquement) Zipper le fichier ./build/addon vers ./build/*.xpi.
(Mode production uniquement) Préparez update.json ou update-beta.json

Note

Quelle est la différence entre mode développement et production ?

Cette variable d'environnement est stockée dans Zotero.${addonInstance}.data.env. La sortie vers la console est désactivée en mode production.
Vous pouvez décider ce que les utilisateurs ne peuvent pas voir/utiliser en fonction de cette variable.
En mode production, le script de construction va empaqueter l'extension et mettre à jour le fichier update.json.

5. Produire une Release

pour construire et produire une Release, utilisez :

# version increase, git add, commit and push
# then on ci, npm run build, and release to GitHub
npm run release

Note

Cela utilisera Bumpp pour saisir le nouveau numéro de version, modifier localement la version, exécuter tous les scripts (pré/post) version définis dans package.json, commit, build (optionnel), marquer le commit avec le numéro de version et pousser les commits et les tags git. Bumpp peut être configuré dans zotero-plugin-config.ts ; par exemple, ajoutez release : { bumpp : { execute : « npm run build » } } pour construire également avant de commiter. Par la suite, GitHub Action reconstruira l'extensions et utilisera le script release de zotero-plugin-scaffold pour publier l'XPI sur GitHub Release. De plus, une version séparée (tag : release) sera créée ou mise à jour qui inclura les manifestes de mise à jour update.json et update-beta.json en tant qu'actifs. Ceux-ci seront disponibles à https://github.com/{{owner}}/{{repo}}/releases/download/release/update*.json.

À propos des pré-releases

Le modèle définit prerelease comme la version beta de l'extension, lorsque vous sélectionnez une version prerelease dans Bumpp (avec - dans le numéro de version). Le script de construction créera un nouveau update-beta.json pour l'utilisation de la prerelease, ce qui assure que les utilisateurs de la version normale ne seront pas en mesure de mettre à jour vers la version beta. Seuls les utilisateurs qui ont téléchargé et installé manuellement la version bêta seront en mesure de mettre à jour automatiquement vers la prochaine version bêta.

Lorsque la prochaine version normale sera mise à jour, update.json et update-beta.json seront tous deux mis à jour (sur la version spéciale release, voir ci-dessus) afin que les utilisateurs de la version normale et de la version bêta puissent se mettre à jour vers la nouvelle version normale.

Warning

La distinction entre les versions des extensions compatibles avec Zotero 6 et Zotero 7 devrait être strictement faite en configurant applications.zotero.strict_min_version dans addons.__addonID__.updates[] de update.json respectivement, afin que Zotero le reconnaisse correctement, voir https://www.zotero.org/support/dev/zotero_7_for_developers#updaterdf_updatesjson.

Détails

À propos des hooks

Voir également src/hooks.ts

Lorsque l'installation/activation/démarrage est déclenché par Zotero, bootstrap.js > startup est appelé
- Attendez que Zotero soit prêt ;
- Chargez de index.js (l'entrée principale du code de lextension, construit à partir de index.ts) ;
- Enregistrez les ressources si Zotero 7+
Dans l'entrée principale index.js, l'objet extension est injecté sous Zotero et hooks.ts > onStartup est appelé.
- Initialisez tout ce que vous voulez, y compris les auditeurs de notifications (hooks), les panneaux de préférences et les éléments de l'interface utilisateur.
Lorsque la désinstallation/désactivation est déclenchée depuis Zotero, bootstrap.js > shutdown est appelé.
- events.ts > onShutdown est appelé. Cela supprime les éléments de l'interface utilisateur, les panneaux de préférences, ou tout ce qui a été créé par l'extension'.
- Supprimez les scripts et libérez les ressources.

À propos des variables globales

Voir aussi [src/index.ts] (https://github.com/windingwind/zotero-plugin-template/blob/main/src/index.ts)

L'extension 'bootstrappé' fonctionne dans un bac à sable, qui n'a pas de variables globales par défaut comme Zotero ou window, que nous avions l'habitude d'avoir en superposition dans la fenêtre d'environnement des extensions.

Ce modèle enregistre les variables suivantes avec une portée globale :

Zotero, ZoteroPane, Zotero_Tabs, window, document, rootURI, ztoolkit, addon;

Création d'une API pour les éléments de l'extension

Le modèle d'extension fournit de nouvelles API pour les extensions 'bootstrappées'. Nous avons deux raisons d'utiliser ces APIs, au lieu de createElement/createElementNS :

En mode bootstrap, les extensions doivent nettoyer tous les éléments de l'interface utilisateur à la sortie (désactivation ou désinstallation), ce qui est très ennuyeux. En utilisant createElement, le modèle de l'eextensions va maintenir ces éléments. Il suffit de lancer unregisterAll à la sortie.
Zotero 7 requiert createElement()/createElementNS() → createXULElement() pour les éléments XUL restants, alors que Zotero 6 ne supporte pas createXULElement. L'API React.createElement-like createElement détecte l'espace de noms (xul/html/svg) et crée des éléments automatiquement, avec l'élément de retour dans le type d'élément TS correspondant.

createElement(document, "div"); // returns HTMLDivElement
createElement(document, "hbox"); // returns XUL.Box
createElement(document, "button", { namespace: "xul" }); // manually set namespace. returns XUL.Button

À propos de l'API Zotero

La documentation de Zotero est obsolète et incomplète. Clonez https://github.com/zotero/zotero et recherchez le mot-clé globalement.

⭐Le zotero-types fournit les API de Zotero les plus fréquemment utilisées. Il est inclus dans ce modèle par défaut. Votre IDE devrait fournir des indices pour la plupart des API.

Une astuce pour trouver l'API que vous voulez :

Recherchez le label de l'interface utilisateur dans les fichiers .xhtml/.flt, trouvez la clé correspondante dans le fichier locale. Ensuite, recherchez cette clé dans les fichiers .js/.jsx.

Structure des répertoires

Cette section montre la structure des répertoires d'un modèle.

Tous les fichiers de code .js/.ts sont dans ./src ;
Les fichiers de configuration des addons : ./addon/manifest.json ;
Fichiers d'interface utilisateur : ./addon/content/*.xhtml.
Les fichiers des Locales : ./addon/locale/**/*.flt ;
Fichier de préférences : ./addon/prefs.js ;

.
|-- .github/                  # github conf
|-- .vscode/                  # vscode conf
|-- addon                     # static files
|   |-- bootstrap.js
|   |-- content
|   |   |-- icons
|   |   |   |-- favicon.png
|   |   |   `-- favicon@0.5x.png
|   |   |-- preferences.xhtml
|   |   `-- zoteroPane.css
|   |-- locale
|   |   |-- en-US
|   |   |   |-- addon.ftl
|   |   |   |-- mainWindow.ftl
|   |   |   `-- preferences.ftl
|   |   `-- zh-CN
|   |       |-- addon.ftl
|   |       |-- mainWindow.ftl
|   |       `-- preferences.ftl
|   |-- manifest.json
|   `-- prefs.js
|-- build                         # build dir
|-- node_modules
|-- src                           # source code of scripts
|   |-- addon.ts                  # base class
|   |-- hooks.ts                  # lifecycle hooks
|   |-- index.ts                  # main entry
|   |-- modules                   # sub modules
|   |   |-- examples.ts
|   |   `-- preferenceScript.ts
|   `-- utils                 # utilities
|       |-- locale.ts
|       |-- prefs.ts
|       |-- wait.ts
|       |-- window.ts
|       `-- ztoolkit.ts
|-- typings                   # ts typings
|   `-- global.d.ts

|-- .env                      # enviroment config (do not check into repo)
|-- .env.example              # template of enviroment config, https://github.com/northword/zotero-plugin-scaffold
|-- .gitignore                # git conf
|-- .gitattributes            # git conf
|-- .prettierrc               # prettier conf, https://prettier.io/
|-- eslint.config.mjs         # eslint conf, https://eslint.org/
|-- LICENSE
|-- package-lock.json
|-- package.json
|-- tsconfig.json             # typescript conf, https://code.visualstudio.com/docs/languages/jsconfig
|-- README.md
`-- zotero-plugin.config.ts   # scaffold conf, https://github.com/northword/zotero-plugin-scaffold

Clause de non-responsabilité

Utilisez ce code sous AGPL. Aucune garantie n'est fournie. Gardez à l'esprit les lois de votre pays !

Si vous souhaitez modifier la licence, veuillez me contacter à l'adresse suivante : wyzlshx@foxmail.com

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README-frFR.md

README-frFR.md

Modèle d'extension Zotero

Exetensions développées sur la base de ce modèle

Fonctionalités

Exemples

Exemples basiques

Exemples utilisant les raccourcis clavier

Exemples d'interface utilisateur (UI)

Exemples avec des panneaux de préférences

Exemples de fenêtre d'aide

Exemples de prompts

Guide de démarrage rapide

0. Pré-requis

1. Créez votre dépôt

2. Configurez les paramètres du Modèle et l'environnement de développement

3. Codez !

Rechargement automatique à chaud

Déboguer dans Zotero

4. Construction (Build)

5. Produire une Release

À propos des pré-releases

Détails

À propos des hooks

À propos des variables globales

Création d'une API pour les éléments de l'extension

À propos de l'API Zotero

Structure des répertoires

Clause de non-responsabilité

Files

README-frFR.md

Latest commit

History

README-frFR.md

File metadata and controls

Modèle d'extension Zotero

Exetensions développées sur la base de ce modèle

Fonctionalités

Exemples

Exemples basiques

Exemples utilisant les raccourcis clavier

Exemples d'interface utilisateur (UI)

Exemples avec des panneaux de préférences

Exemples de fenêtre d'aide

Exemples de prompts

Guide de démarrage rapide

0. Pré-requis

1. Créez votre dépôt

2. Configurez les paramètres du Modèle et l'environnement de développement

3. Codez !

Rechargement automatique à chaud

Déboguer dans Zotero

4. Construction (Build)

5. Produire une Release

À propos des pré-releases

Détails

À propos des hooks

À propos des variables globales

Création d'une API pour les éléments de l'extension

À propos de l'API Zotero

Structure des répertoires

Clause de non-responsabilité