https://github.com/windingwind/zotero-types
TypeScript definitions for Zotero.
https://github.com/windingwind/zotero-types
api npm npm-package plugin types typescript typing zotero
Last synced: 6 months ago
JSON representation
TypeScript definitions for Zotero.
- Host: GitHub
- URL: https://github.com/windingwind/zotero-types
- Owner: windingwind
- License: mit
- Created: 2022-08-29T10:29:49.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2025-04-20T13:35:12.000Z (6 months ago)
- Last Synced: 2025-04-20T13:42:07.335Z (6 months ago)
- Topics: api, npm, npm-package, plugin, types, typescript, typing, zotero
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/zotero-types
- Size: 1.98 MB
- Stars: 62
- Watchers: 7
- Forks: 11
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Zotero Types
This package contains type definitions for Zotero () plugin.
npm package:
## Installation
Run `npm install --save-dev zotero-types`.
## Usage
### Include Type Definitions
You can include the type definitions in your Zotero plugin project in three ways:
1. Extend the `tsconfig.json` file in your Zotero plugin project. This is the recommended way.
```jsonc
// tsconfig.json
{
"extends": "zotero-types/entries/sandbox",
}
```
For the best practices, see as a reference.
Available entries:
| Entry | Description | Privileged | Zotero | XUL | DOM | MainWindow | WebWorker |
| ------------ | ------------------------------------------------------------------------------------------------------------------- | ---------- | ------ | --- | --- | ---------- | --------- |
| `sandbox` | The default entry for Zotero plugin development. For Zotero plugin's `bootstrap.js` sandbox environment. | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| `xhtml` | The entry for Zotero's `xhtml` environment. | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| `mainWindow` | Besides definitions from the `xhtml` entry, it also includes main window APIs, such as `ZoteroPane`, `Zotero_Tabs`. | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `html` | Same as normal HTML environment. | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| `webworker` | Same as normal web worker environment. | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| `base` | The base entry. Does not include any extra type definitions. | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `shared` | The entry for privileged APIs. | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
2. Use `compileOptions > types` in your Zotero plugin project's `tsconfig.json` file.
```jsonc
// tsconfig.json
{
"compilerOptions": {
"types": ["zotero-types"],
},
}
```
This is equivalent to the combination of `sandbox` and `xhtml` entries.
3. Use triple-slash directive in your Zotero plugin project's `d.ts` file.
Similar to the `tsconfig.json` file, you can use the `/// ` directive to include the type definitions.
```ts
///
```
### Use in Code
```ts
// Example 1: get Zotero.Item by id
const item = Zotero.Items.get(1234);
// Example 2: use XUL.Element type with specific properties
const exportFiles = document.querySelector(
"#menu_export_files",
) as XULMenuItemElement;
exportFiles.disabled = true;
// Example 3: use platform APIs (OS)
const filepath = "/path/to/file";
if (await IOUtils.exists(filepath)) {
let contentRaw = await IOUtils.readUTF8(filepath);
}
```
## Contributing
This type definition only contains frequently used typings and is not complete. Please check the source code of Zotero here: [https://github.com/zotero/zotero](https://github.com/zotero/zotero).
The `d.ts` files of Zotero are set accordingly to their corresponding file in the Zotero repository.
Planning to merge to
To release this to the npm package, use `npm run release`.
## Disclaimer
Use this code under MIT License. No warranties are provided. Keep the laws of your locality in mind!
If you want to change the license, please contact me at
Part of the code of this repo refers to other open-source projects within the allowed scope.
- zotero-better-bibtex(`d.ts`)