# @salla\.sa/base 中文文档

规范地址：https://npmcn.com/package/%40salla.sa/base/

版本：3\.0\.21
npm 元数据更新时间：2026-11-02T09:09:18.830Z
中文译文更新时间：2026-11-02T09:45:57.003Z
软件包许可：GPL-3\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40salla.sa/base
原文对照：https://npmcn.com/package/%40salla.sa/base/?lang=original
项目主页：https://github.com/SallaApp/base#readme
源码仓库：https://github.com/SallaApp/twilight

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：358 kB，18 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2022-09-11T12:40:41.795Z
- 最新版本发布：2026-11-02T09:09:18.569Z
- 已发布版本数：868（近 12 个月 325 个）

## 中文简介

萨拉基

## 安装

```sh
npm install @salla.sa/base
```

也可以使用：`pnpm add @salla.sa/base`、`yarn add @salla.sa/base`、`bun add @salla.sa/base`

## README

  

[![Logo](https://salla.dev/wp-content/uploads/2023/03/1-Light.png)](https://salla.dev/)

# Salla Core JS

用这个核心包启动你的Salla JS项目。它包含了构建JS项目所需的主要元素。最重要的是，它基于事件驱动架构。  
[**浏览我们的博客»**](https://salla.dev/)  
  
[报告错误](https://github.com/SallaApp/twilight/issues/new) · [请求功能](https://github.com/SallaApp/twilight/discussions/new) . [< /萨拉开发者>](https://t.me/salladev) . [官方文档](https://docs.salla.dev/docs/twilight-themes-documentation/8830a91f78c7d-event)

目录表

1.  [概述](https://npmcn.com/package/%40salla.sa/base/#readme-overview)
2.  [开始使用](https://npmcn.com/package/%40salla.sa/base/#readme-getting-started)
    -   [安装](https://npmcn.com/package/%40salla.sa/base/#readme-installation)
    -   [包括什么?](https://npmcn.com/package/%40salla.sa/base/#readme-whats-included)
3.  [使用](https://npmcn.com/package/%40salla.sa/base/#readme-usage)

-   [Confiruration](https://npmcn.com/package/%40salla.sa/base/#readme-confiruration)
-   [助手](https://npmcn.com/package/%40salla.sa/base/#readme-helpers)
-   [存储](https://npmcn.com/package/%40salla.sa/base/#readme-storage)
-   [饼干](https://npmcn.com/package/%40salla.sa/base/#readme-cookies)
-   [日志记录器](https://npmcn.com/package/%40salla.sa/base/#readme-logger)
-   [事件](https://npmcn.com/package/%40salla.sa/base/#readme-events)

-   [聆听事件](https://npmcn.com/package/%40salla.sa/base/#readme-listening-to-the-event)

5.  [支持](https://npmcn.com/package/%40salla.sa/base/#readme-support)
6.  [贡献](https://npmcn.com/package/%40salla.sa/base/#readme-contributing)
7.  [学分](https://npmcn.com/package/%40salla.sa/base/#readme-credits)
8.  [许可证](https://npmcn.com/package/%40salla.sa/base/#readme-license)

## 概述

**Salla Core JS** 包基于事件驱动架构，这是一种以表示“事件”的数据为中心的现代设计方法（例如，产品已添加到购物车中）。在事件驱动编程中，事件是单个或多个操作的结果。订阅者可以监听该事件，并在它被发射器释放后采取行动。

## 开始使用

**Salla Core JS** 使用 [EventEmitter2](https://www.npmjs.com/package/eventemitter2)的实现 [EventEmitter](https://nodejs.dev/learn/the-nodejs-event-emitter) 在Node.js中找到的模块。它不仅在基准测试中优于EventEmitter并且与浏览器兼容，而且还为EventEmitter接口添加了一系列新的非破坏性功能。

### 安装

**Salla Core JS** 可以从 `npm` 使用如下命令：

```npm
npm install @salla.sa/base --save
```

```yarn
yarn add @salla.sa/base
```

### 包括什么?

中的顶级文件的快速查看 **Salla Core JS** 项目:

```
.
├── src / helpers
├── src / config.d.ts
├── src / cookie.ts
├── src / event.js
├── src / index.ts
├── src / logger.ts
└── src / storage.js
```

## 使用

```js
import Salla from "@salla.sa/base"
```

安装后，开发人员将可以使用以下工具：

### Confiruration

当JS Core项目首次加载时，初始化过程用于获取必要的配置设置。开发人员有能力配置项目以满足他的需求。

### 助手

JS Core项目打包了各种有用的函数，这些函数可以在项目中直接访问和使用。

### 存储

开发人员可以使用本地存储在浏览器中保存和检索数据。本地存储中的数据没有截止日期。这意味着即使选项卡或浏览器窗口关闭，数据也会保留。此外，数据仅保存在本地。

### 饼干

JS Core项目使创建、检索和修改cookie变得很容易。可以限制名称、值和长度。

### 日志记录器

JS Core项目包括一个日志工具，它可以帮助跟踪执行流程，并确定为什么某些事情会在JS应用程序中发生。

### 事件

事件可以通过发射器的‘emit()’方法触发。此方法使用开发人员提供的数据来推送事件。

例如，开发人员可以根据用户验证的登录创建事件。简单, `emit()` 方法可以使用参数列表调用。这些参数说明了事件的动作和传递的数据，如下所示：

```js
// via event name
Salla.event.emit("auth::verified",  {success:  true},  'email')
```

#### 聆听事件

在创建事件及其数据列表之后，下一步是为该事件实现一个适当的侦听器。在 **萨拉JS事件**，这可以通过两种方法实现：

-   直接使用事件名称和结果以及匿名函数，根据事件结果执行所需的操作。

```js
// via event name
Salla.event.on('auth::verified',(response, authType)  =>  {
// lets do anything when the event emit
console.log('The customer has been verifed');
console.log(response, authType)
});
```

-   添加一个 `one` 事件的时间监听器以及基于事件结果执行所需操作的匿名函数。

```js
// Adds a one time listener for the event.
Salla.event.once('auth::verified',(response, authType)  =>  {
// The listener is invoked only the first time
// the event is fired, after which it is removed.
console.log('The customer has been verifed');
console.log(response, authType)
})
```

（[回到顶部](https://npmcn.com/package/%40salla.sa/base/#readme-top)）

### FormDataWrapper

FormDataWrapper提供了一个用于处理常规对象和FormData的统一接口，使得以一致的方式处理文件上传和表单数据变得更加容易。

#### 用法示例

##### 示例1：使用FormData处理基本文件

```js
const formData = new FormData();
const wrapped = createWrapper(formData);

// Adding a single file
const file1 = new File(['Hello World'], 'hello.txt', { type: 'text/plain' });
wrapped.document = file1;  // Works via proxy
// OR
wrapped.setFile('document', file1);  // Explicit file method

// Getting the file back
const retrievedFile = wrapped.document;  // Returns File object
console.log(retrievedFile.name);  // 'hello.txt'
console.log(retrievedFile.size);  // 11 (bytes)
```

##### 例2：具有相同密钥的多个文件

```js
const file2 = new File(['Second file'], 'second.txt', { type: 'text/plain' });
const file3 = new File(['Third file'], 'third.txt', { type: 'text/plain' });

// Setting multiple files at once (replaces existing)
wrapped.attachments = [file2, file3];

// Or append files one by one
wrapped.append('photos', new File(['Photo 1'], 'photo1.jpg', { type: 'image/jpeg' }));
wrapped.append('photos', new File(['Photo 2'], 'photo2.jpg', { type: 'image/jpeg' }));

// Get all files for a key
const allPhotos = wrapped.getFiles('photos');
console.log(allPhotos.length);  // 2
console.log(allPhotos.map(f => f.name));  // ['photo1.jpg', 'photo2.jpg']
```

##### 示例3：混合内容（文件和常规数据）

```js
wrapped.username = 'john_doe';
wrapped.age = 30;
wrapped.avatar = new File(['avatar data'], 'avatar.png', { type: 'image/png' });

// Check if property is a file
console.log(wrapped.isFile('avatar'));  // true
console.log(wrapped.isFile('username'));  // false

// Get file info without reading content
const fileInfo = wrapped.getFileInfo('avatar');
console.log(fileInfo);  // [{ name: 'avatar.png', size: 11, type: 'image/png' }]
```

##### 例4：使用object或FormData

```js
function processUserData(data: Record<string, any> | FormData) {
  const wrapped = createWrapper(data);
  
  // These operations work for both types
  wrapped.name = 'Jane Doe';
  wrapped.email = 'jane@example.com';
  
  // Handle file upload (works differently based on type)
  const profilePic = new File(['pic'], 'profile.jpg', { type: 'image/jpeg' });
  wrapped.profilePicture = profilePic;
  
  // Check if we have a file
  if (wrapped.isFile('profilePicture')) {
    const file = wrapped.getFile('profilePicture');
    console.log(`Uploaded file: ${file?.name}, Size: ${file?.size} bytes`);
  }
  
  // Convert to object for processing
  const obj = wrapped.toObject();
  console.log('Data keys:', Object.keys(obj));
  
  return wrapped;
}
```

##### 示例5：真实的表单提交场景

```js
function handleFormSubmit(formElement: HTMLFormElement) {
  const formData = new FormData(formElement);
  const wrapped = createWrapper(formData);
  
  // Add timestamp
  wrapped.submittedAt = Date.now();
  
  // Validate files
  const uploadedFiles = wrapped.getFiles('documents');
  const maxSize = 5 * 1024 * 1024; // 5MB
  
  for (const file of uploadedFiles) {
    if (file.size > maxSize) {
      console.error(`File ${file.name} exceeds maximum size`);
      wrapped.delete('documents');
      wrapped.error = 'File too large';
    }
  }
  
  // Add computed property
  wrapped.fileCount = uploadedFiles.length;
  
  // Get the modified FormData for submission
  const finalFormData = wrapped.getRawData() as FormData;
  
  // Submit with fetch
  fetch('/api/submit', {
    method: 'POST',
    body: finalFormData
  });
}
```

##### 示例6：类型安全的文件处理

```js
interface UserProfile {
  name: string;
  email: string;
  avatar?: File;
  documents?: File[];
}

function createUserProfile(data: UserProfile | FormData) {
  const wrapped = createWrapper(data);
  
  // Type-safe access
  const name: string = wrapped.name;
  const avatar: File | null = wrapped.getFile('avatar');
  const docs: File[] = wrapped.getFiles('documents');
  
  // Process files
  if (avatar) {
    console.log(`Avatar: ${avatar.name} (${avatar.type})`);
  }
  
  docs.forEach((doc, index) => {
    console.log(`Document ${index + 1}: ${doc.name}`);
  });
  
  return wrapped.toObject();
}
```

（[回到顶部](https://npmcn.com/package/%40salla.sa/base/#readme-top)）

## 支持

团队总是在这里帮助你。碰巧遇到了问题？想要报告bug？你可以在Github上提交一个 [问题跟踪器](https://github.com/SallaApp/twilight-vscode-extension/issues/new)。如果您还有任何问题，请通过电子邮件与我们联系 [电报机器人](https://t.me/SallaSupportBot) 或加入全球开发者社区 [电报](https://t.me/salladev).

（[回到顶部](https://npmcn.com/package/%40salla.sa/base/#readme-top)）

## 贡献

贡献使开源社区成为一个学习、启发和创造的神奇场所。 你做的任何贡献都是 **极大的赞赏**.

如果你有一个更好的建议，请fork repo并创建一个pull request。 你也可以简单地打开一个带有“增强”标签的问题。别忘了给这个项目打个星！再次感谢!

1.  分岔项目
2.  创建特性分支(`git checkout -b feature/AmazingFeature`）
3.  提交更改(`git commit -m 'Add some AmazingFeature'`）
4.  推至分行(`git push origin feature/AmazingFeature`）
5.  打开拉取请求

（[回到顶部](https://npmcn.com/package/%40salla.sa/base/#readme-top)）

## 学分

-   [萨拉](https://github.com/sallaApp)
-   [所有贡献者](https://npmcn.com/package/contributors)

（[回到顶部](https://npmcn.com/package/%40salla.sa/base/#readme-top)）

## 许可证

麻省理工学院许可证（MIT）。请参阅 [许可文件](https://npmcn.com/package/%40salla.sa/base/LICENSE.md) 了解更多信息。

（[回到顶部](https://npmcn.com/package/%40salla.sa/base/#readme-top)）

## 常见问题

### @salla\.sa/base 是什么？

萨拉基

### 如何安装 @salla\.sa/base？

在项目目录运行 npm install @salla\.sa/base，或使用 pnpm add / yarn add / bun add。

### @salla\.sa/base 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @salla\.sa/base 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @salla\.sa/base 可以商用吗？

@salla\.sa/base 使用 GPL-3\.0 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @salla\.sa/base 还在维护吗？

最新版本 3\.0\.21 发布于 2026/11/02（1 天前）；至今共发布 868 个版本，其中过去 12 个月发布了 325 个；首次发布于 2022/09/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。