-
Notifications
You must be signed in to change notification settings - Fork 121
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
8e9b488
commit fa00a4b
Showing
2 changed files
with
36 additions
and
36 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,12 +1,13 @@ | ||
| # Modèle d'extension Zotero | ||
| # Modèle d'extension Zotero | ||
|
|
||
| [](https://www.zotero.org) | ||
| [](https://github.com/windingwind/zotero-plugin-template) | ||
|
|
||
| Ceci est un modèle pour développer une extension pour [Zotero](https://www.zotero.org/). | ||
|
|
||
| [English](../README.md) | [简体中文](./README-zhCN.md) | [Français](./README-frFR.md) | ||
|
|
||
| - Documentation | ||
| - Documentation | ||
| - [📖 Plugin Development Documentation](https://zotero-chinese.com/plugin-dev-guide/) (Chinese, not yet complete) | ||
| - [📖 Plugin Development Documentation for Zotero 7](https://www.zotero.org/support/dev/zotero_7_for_developers) | ||
| - Outils pour le développement de pluqgins | ||
|
|
@@ -20,6 +21,7 @@ Ceci est un modèle pour développer une extension pour [Zotero](https://www.zot | |
| > 👁 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 | ||
|
|
||
| [](https://github.com/windingwind/zotero-better-notes) | ||
| [](https://github.com/windingwind/zotero-pdf-preview) | ||
| [](https://github.com/windingwind/zotero-pdf-translate) | ||
|
|
@@ -56,7 +58,7 @@ Si vous utilisez ce dépôt, je vous recommande de mettre le badge suivant dans | |
| - ⭐ [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](https://github.com/windingwind/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](https://github.com/windingwind/zotero-types)); | ||
| - 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](https://github.com/windingwind/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`); | ||
|
|
@@ -68,7 +70,7 @@ Si vous utilisez ce dépôt, je vous recommande de mettre le badge suivant dans | |
|
|
||
| Ce dépot fournit des exemples pour les API [zotero-plugin-toolkit](https://github.com/windingwind/zotero-plugin-toolkit). | ||
|
|
||
| Recherchez `@example` dans `src/examples.ts`. Les exemples sont appelés dans `src/hooks.ts`. | ||
| Recherchez `@example` dans `src/examples.ts`. Les exemples sont appelés dans `src/hooks.ts`. | ||
|
|
||
| ### Exemples basiques | ||
|
|
||
|
|
@@ -131,13 +133,14 @@ S'active avec `Shift+P`. | |
| - registerAlertPromptExample | ||
|
|
||
| ## Guide de démarrage rapide | ||
|
|
||
| ### 0. Pré-requis | ||
|
|
||
| 1. Installez une version beta de Zotero: <https://www.zotero.org/support/beta_builds> | ||
| 2. Installez [Node.js](https://nodejs.org/en/) and [Git](https://git-scm.com/) | ||
|
|
||
| > [!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 [documentation](https://www.zotero.org/support/dev/zotero_7_for_developers)et aux exemples officiels de l'extension [Make It Red](https://github.com/zotero/make-it-red) en premier lieu. | ||
| > 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 [documentation](https://www.zotero.org/support/dev/zotero_7_for_developers)et aux exemples officiels de l'extension [Make It Red](https://github.com/zotero/make-it-red) en premier lieu. | ||
| ### 1. Créez votre dépôt | ||
|
|
||
|
|
@@ -150,14 +153,14 @@ S'active avec `Shift+P`. | |
|
|
||
| Effectuez les étapes ci-dessus et créez votre première extension en 30 secondes! | ||
|
|
||
| - Allez en haut de la [page d'accueil](https://github.com/windingwind/zotero-plugin-template), cliquez sur le bouton vert `Use this template`, cliquez sur `Open in codespace`. ous devrez peut-être vous connecter à votre compte GitHub. | ||
| - Allez en haut de la [page d'accueil](https://github.com/windingwind/zotero-plugin-template), 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. | ||
|
|
||
| </details> | ||
|
|
||
| 3. Entrez dans le dossier du dépôt | ||
|
|
||
| ### 2. Configurez les paramètres du Modèle et l'environnement de développement | ||
| ### 2. Configurez les paramètres du Modèle et l'environnement de développement | ||
|
|
||
| 1. Modifier les paramètres dans `./package.json`, y compris : | ||
|
|
||
|
|
@@ -177,36 +180,38 @@ S'active avec `Shift+P`. | |
| } | ||
| ``` | ||
|
|
||
| > ![WARNING] | ||
| > Veillez à bien définir addonID et addonRef pour éviter tout conflit. | ||
| > ![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`. | ||
| Si vous avez besoin d'héberger vos paquets XPI en dehors de GitHub, modifiez `updateURL` et ajoutez `xpiDownloadLink` dans `zotero-plugin.config.ts`. | ||
|
|
||
| 2. Copiez le fichier de la variable d'environnement. Modifiez la commandes quilance la version beta de Zotero. | ||
| 2. 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 ! | ||
| ```sh | ||
| cp .env.example .env | ||
| vim .env | ||
| ``` | ||
| > 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 ! | ||
| ```sh | ||
| 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. | ||
|
|
||
| 3. 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. | ||
| 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à. | ||
| - 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 | ||
|
|
||
|
|
@@ -230,14 +235,15 @@ Vous pouvez également : | |
|
|
||
| - Tester les extraits de code dans Outils -> Développeur -> Run Javascript ; | ||
| - Déboguer la sortie avec`Zotero.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](https://udn.realityripple.com/docs/Archive/Mozilla/XUL_Explorer). | ||
| - 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](https://udn.realityripple.com/docs/Archive/Mozilla/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.). | ||
|
|
@@ -275,13 +281,10 @@ npm run release | |
|
|
||
| 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>. | ||
|
|
||
| > 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 | ||
|
|
||
|
|
@@ -290,23 +293,21 @@ Lorsque la prochaine version normale sera mise à jour, `update.json` et `update | |
| > Voir également [`src/hooks.ts`](https://github.com/windingwind/zotero-plugin-template/blob/main/src/hooks.ts) | ||
| 1. 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+ | ||
| - 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+ | ||
| 2. 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. | ||
| - 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. | ||
| 3. 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. | ||
| - `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 : | ||
|
|
||
| ```ts | ||
|
|
@@ -315,7 +316,6 @@ 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. | ||
|
|
@@ -340,6 +340,7 @@ Recherchez le label de l'interface utilisateur dans les fichiers `.xhtml`/`.flt` | |
| ### 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`. | ||
|
|
@@ -405,4 +406,4 @@ Cette section montre la structure des répertoires d'un modèle. | |
|
|
||
| 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 : <[email protected]> | ||
| Si vous souhaitez modifier la licence, veuillez me contacter à l'adresse suivante : <[email protected]> | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters