electron-store 中文文档

electron-store

简介

为您的Electron应用或模块提供简单的数据持久化功能 —— 保存和加载用户设置、应用状态、缓存等。

Electron本身没有内置的方式来持久化用户设置和其他数据。此模块为您处理这些问题，以便您可以专注于构建应用。数据被保存在一个名为config.json的JSON文件中，位于app.getPath('userData')目录下。

您可以在主进程和渲染进程中直接使用此模块。如果仅在渲染进程中使用，则需要在主进程中调用Store.initRenderer()，或者在主进程中创建一个新的Store实例 (new Store() )。

安装

npm install electron-store

要求Electron版本30或更高。

注意：此包为原生ESM模块，不再提供CommonJS导出。如果您的项目使用CommonJS，您需要将其转换为ESM。更多关于Electron和ESM的信息。请不要为此类问题提交issues。

使用

import Store from 'electron-store';
const store = new Store();
store.set('unicorn', '🦄');
console.log(store.get('unicorn'));
//=> '🦄'
// 使用点表示法访问嵌套属性
store.set('foo.bar', true);
console.log(store.get('foo'));
//=> {bar: true}
store.delete('unicorn');
console.log(store.get('unicorn'));
//=> undefined

API

所有更改都会原子性地写入磁盘，因此即使进程在写入过程中崩溃，也不会破坏现有的配置。

Store(options?)

返回一个新的实例。

options

类型：object

defaults

类型：object 默认值用于存储项。

注意：defaults中的值会覆盖schema选项中的default键。

schema

类型：object 用于验证您的配置数据的JSON Schema。

底层使用JSON Schema验证器ajv来验证您的配置。我们使用JSON Schema草案-2020-12，并支持所有的验证关键字和格式。

您应该定义一个对象作为schema，其中每个键是您的数据属性的名称，每个值是一个用来验证该属性的JSON schema。更多信息见这里。

示例：

import Store from 'electron-store';
const schema = {
  foo: {
    type: 'number',
    maximum: 100,
    minimum: 1,
    default: 50
  },
  bar: {
    type: 'string',
    format: 'url'
  }
};
const store = new Store({schema});
console.log(store.get('foo'));
//=> 50
store.set('foo', '1');
// [Error: Config schema violation: `foo` should be number]

注意：默认值将被defaults选项覆盖，如果设置了的话。

migrations

类型：object 重要：我无法为此特性提供支持。它有一些已知的bug。我没有计划对其进行改进，但欢迎提交pull request。

您可以使用migrations在版本升级时对store执行操作。

migrations对象应包含'版本': handler形式的键值对。版本也可以是一个semver范围。

示例：

import Store from 'electron-store';
const store = new Store({
  migrations: {
    '0.0.1': store => {
      store.set('debugPhase', true);
    },
    '1.0.0': store => {
      store.delete('debugPhase');
      store.set('phase', '1.0.0');
    },
    '1.0.2': store => {
      store.set('phase', '1.0.2');
    },
    '>=2.0.0': store => {
      store.set('phase', '>=2.0.0');
    }
  }
});

beforeEachMigration

类型：Function 默认：undefined 给定的回调函数将在每次迁移步骤之前被调用。

此函数接收store作为第一个参数，以及一个包含以下属性的上下文对象作为第二个参数：

fromVersion - 迁移步骤前的版本。
toVersion - 迁移步骤后的版本。
finalVersion - 所有迁移完成后的最终版本。
versions - 所有具有迁移步骤的版本。

这对于日志记录、准备迁移数据等目的很有用。

示例：

import Store from 'electron-store';
console.log = someLogger.log;
const mainConfig = new Store({
  beforeEachMigration: (store, context) => {
    console.log(`[main-config] 迁移从 ${context.fromVersion} → ${context.toVersion}`);
  },
  migrations: {
    '0.4.0': store => {
      store.set('debugPhase', true);
    }
  }
});
const secondConfig = new Store({
  beforeEachMigration: (store, context) => {
    console.log(`[second-config] 迁移从 ${context.fromVersion} → ${context.toVersion}`);
  },
  migrations: {
    '1.0.1': store => {
      store.set('debugPhase', true);
    }
  }
});

name

类型：string 默认：'config' 存储文件的名称（不含扩展名）。

初始化渲染进程

初始化器用于设置必要的IPC通信通道，当未在主进程中创建Store实例且仅在Electron渲染进程中创建Store实例时。

在主进程中：

import Store from 'electron-store';
Store.initRenderer();

在渲染进程中：

import Store from 'electron-store';
const store = new Store();
store.set('unicorn', '🦄');
console.log(store.get('unicorn'));
//=> '🦄'

常见问题解答

与window.localStorage相比的优势

我可以使用YAML或其他序列化格式吗？

serialize和deserialize选项可用于自定义配置文件的格式，只要该表示形式与utf8编码兼容即可。

示例使用YAML：

import Store from 'electron-store';
import yaml from 'js-yaml';
const store = new Store({
  fileExtension: 'yaml',
  serialize: yaml.safeDump,
  deserialize: yaml.safeLoad
});

如何在渲染进程中获取由主进程初始化的store值？

store不是一个单例，因此您需要在主进程和渲染进程都导入的文件中初始化store，或者通过消息来回传递值。Electron提供了一个方便的invoke/handle API，非常适合访问这些值。

ipcMain.handle('getStoreValue', (event, key) => {
  return store.get(key);
});
const foo = await ipcRenderer.invoke('getStoreValue', 'foo');

我可以使用它来存储大量数据吗？

此包不是一个数据库。它只是使用一个JSON文件，在每次更改时读取/写入。建议用于较小的数据量，如用户设置、值缓存、状态等。

如果您需要存储大量数据，我建议将其保存到磁盘，并使用此包来存储文件路径。

余以为