Skip to content

Commit

Permalink
docs: add english translation
Browse files Browse the repository at this point in the history
  • Loading branch information
wzhudev committed Oct 23, 2024
1 parent 0809fbd commit 375d078
Show file tree
Hide file tree
Showing 10 changed files with 384 additions and 203 deletions.
48 changes: 22 additions & 26 deletions src/docs/guides/general/concepts.en-US.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,17 @@ import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup'

<BadgeGroup values={[UniverTypes.GENERAL]} value={UniverTypes.GENERAL} />

Before diving deeper into Univer, please read this document to understand the basic concepts of Univer, which will help you use Univer more smoothly.
<Callout type="info" emoji="🧱">
Before diving deeper into Univer, please read this document to understand the basic concepts of Univer, which will help you use Univer more smoothly.
</Callout>

The basic concepts include:

* Plugin
* Snapshot
* Command
* Facade API
* Presets

## Plugins

Expand All @@ -30,51 +33,35 @@ You can combine Univer's plugins to customize a Univer application that meets yo
1. [Write a CSV import plugin](/guides/sheet/tutorials/csv-import-plugin) to learn how to write a plugin.
2. [Univer Architecture](/guides/sheet/architecture/univer) to learn more about Univer's architecture design.

## Presets

We provide some presets that combine multiple plugins to meet common requirements. You can use presets directly to quickly build a Univer application that meets your requirements.

### Related Links

## Snapshot

You need to load a snapshot in Univer to load a document. Each type of document provides its own snapshot format. Please refer to the above API documentation to learn how to write a snapshot that meets the format requirements:

1. The snapshot format of a spreadsheet is [`IWorkbookData`](/typedoc/@univerjs/core/interfaces/IWorkbookData).
1. [Configure Cell Data](guides/sheet/getting-started/cell-data) gives a detailed introduction to the data structure of cells.
2. The snapshot format of a document is [`IDocumentData`](/typedoc/@univerjs/core/interfaces/IDocumentData).
1. The complete snapshot structure of the document can be found in the API manual [`IDocumentData`](/typedoc/@univerjs/core/interfaces/IDocumentData).
1. The complete snapshot format of the spreadsheet can be found in the API manual [`IWorkbookData`](/typedoc/@univerjs/core/interfaces/IWorkbookData).
1. [Configure Workbook Data](/guides/sheet/getting-started/workbook-data) introduces the basic structure of the workbook.
1. [Configure Cell Data](/guides/sheet/getting-started/cell-data) introduces the data structure of the cell.
1. You may need to save custom data in the snapshot, see [Plugin Custom Model](/guides/sheet/advanced/custom-model).

Functional plugins can store resources, such as images, etc., through the `resources` field. For more information, see [Plugin Custom Model](/guides/sheet/advanced/custom-model).

<Callout emoji="⚠️">
<Callout type="error" emoji="🚨">
Note! Univer's snapshot is only used to store data. It does not reflect the latest document status at runtime! If you want to save the document status as a snapshot, use the method to save the snapshot on the Facade API.
</Callout>

### Related Links

1. [Getting Started Example](/guides/sheet/getting-started/installation#Getting-Started-Example-Loading-Data-Modifying-Data-and-Storing-Data) to learn how to load and save snapshots.

## Command

In Univer, all data modifications need to be executed through commands. The command-based approach can better track changes in values, implement functions such as undo, redo, and collaborative editing, handle complex associated logic between functions, etc.

If you want to modify document data through commands, please refer to [How to Find Command ID](/guides/sheet/tutorials/find-the-command-id). If you choose to modify document data through the Facade API, the Facade API will actually prepare parameters for you and execute commands behind the scenes.
If you want to modify document data through commands, please refer to [How to Find Command ID](/guides/sheet/tutorials/find-the-command-id).

<Callout emoji="⚠️">
**Do not modify the snapshot directly!** This will not take effect and will not trigger the update of views or UI. Please modify data through commands or the Facade API.
</Callout>

### Related Links

1. [Getting Started Example](/guides/sheet/getting-started/installation#Getting-Started-Example-Loading-Data-Modifying-Data-and-Storing-Data) to learn how to modify data through the Facade API

## Facade API

Due to the high complexity of office applications, Univer's architecture is also very complex. To make it easier for developers to use Univer, we provide the Facade API, which is a wrapper for Univer's first-party plugins, providing simpler interfaces that make it easier for developers to use Univer.
Facade API is a wrapper for the underlying interfaces provided by plugins, allowing developers to use Univer more easily without having to understand its internal design.

We are improving the Facade API. Stay tuned for more updates. If you have any questions or requirements, please submit an issue on GitHub.

Of course, everything comes with a price. The Facade API is a high-level API that abstracts the underlying details. If you need to implement some complex features, you may need to understand Univer's architecture and use the low-level API directly.
Of course, everything has two sides. Although the Facade API makes Univer easier to use, it also prevents you from accessing some more powerful APIs internally. If you need more advanced custom capabilities, you need to use the underlying API based on an understanding of the architecture.

### Related Links

Expand All @@ -83,3 +70,12 @@ Of course, everything comes with a price. The Facade API is a high-level API tha
3. [Univer Doc API](/guides/doc/facade/doc-api)
4. [Univer Sheet API](/guides/sheet/facade/sheet-api)
5. [Facade API Reference](/typedoc/@univerjs/facade/README)

## Presets

We have prepared some out-of-the-box solutions for users who are new to Univer. If your use case is more common, you can start with Presets. The code for Presets is also open source, so you can refer to the source code of Presets to learn how to further customize Univer.

### Related Links

1. [Presets](/guides/sheet/getting-started/presets)
1. [Presets Source Code](https://github.com/dream-num/univer-presets)
7 changes: 4 additions & 3 deletions src/docs/guides/general/concepts.zh-CN.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup'

你可以根据使用场景自由组合插件,同时避免加载多余代码;也可以通过编写插件来扩展 Univer 的功能,满足个性化的需求。

相关链接
### 相关链接

1. [编写一个 CSV 导入插件](/guides/sheet/tutorials/csv-import-plugin) 了解如何编写一个插件。
1. [Univer 架构](/guides/sheet/architecture/univer) 详细了解 Univer 的架构设计。
Expand Down Expand Up @@ -57,13 +57,14 @@ import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup'
Univer 基于 [命令系统](/guides/sheet/architecture/univer#%E5%91%BD%E4%BB%A4%E7%B3%BB%E7%BB%9F) 对状态和数据进行操作和更新,因此你**必须**使用 Facade API(或其对应的命令)来更新数据,任何直接对数据进行修改以更新视图的操作都不会生效。
</Callout>


## Facade API

Facade API 是对插件所提供的底层接口的封装,让开发者可以更简易地使用 Univer 而无需了解其内部设计。

当然凡事皆有两面,Facade API 虽然让 Univer 更易用,但它同时也使得你无法接触到内部一些更强大的 API。如果你需要更高级的自定义能力,就需要在了解架构的基础上使用底层 API。

相关链接
### 相关链接

1. [引入 Facade API](/guides/sheet/getting-started/facade)
1. [Facade Sheet API 常用方法](/zh-CN/guides/sheet/facade/sheet-api)
Expand All @@ -72,7 +73,7 @@ Facade API 是对插件所提供的底层接口的封装,让开发者可以更

我们为首次接触 Univer 的用户准备了一些开箱即用的解决方案,如果你的使用场景比较常规,你可以选择从 Presets 开始。Presets 的代码也是开源的,因此你也可以参考 Presets 的源码来学习如何进一步定制 Univer。

相关链接
### 相关链接

1. [使用 Presets](/guides/sheet/getting-started/presets)
2. [Presets 开源仓库](https://github.com/dream-num/univer-presets)
Original file line number Diff line number Diff line change
Expand Up @@ -117,9 +117,7 @@ import SheetsFormulaUIZhCN from '@univerjs/sheets-formula-ui/locale/zh-CN';
大量插件的语言包和样式加载可能会使开发变得繁琐且难以维护。我们提供了 Univer Plugins 来帮助你更加方便地引入插件,详情请参考 [简化引入](/guides/sheet/getting-started/univer-plugins) 章节。
</Callout>
然后创建一个 Univer 实例,并注册这些插件,并组装 Facade API:
// TODO: 组装 Facade API 的代码
然后创建一个 Univer 实例,并注册这些插件:
```typescript
const univer = new Univer({
Expand Down
Loading

0 comments on commit 375d078

Please sign in to comment.