Skip to content

Commit

Permalink
docs: refactor guides with presets
Browse files Browse the repository at this point in the history
  • Loading branch information
wzhudev committed Oct 22, 2024
1 parent 06223d4 commit 726eb72
Show file tree
Hide file tree
Showing 27 changed files with 1,621 additions and 358 deletions.
10 changes: 0 additions & 10 deletions src/docs/guides/doc/getting-started/installation.zh-CN.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,6 @@ import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup'

<BadgeGroup values={[UniverTypes.SHEET, UniverTypes.DOC, UniverTypes.SLIDE]} value={UniverTypes.DOC} />

## 使用包管理器

如果你对现代前端开发有所了解,那么使用包管理工具来构建包含 Univer 的应用将会是一个不错的选择。

我们推荐使用 [Vite](https://vitejs.dev/)[esbuild](https://esbuild.github.io/)[Webpack 5](https://webpack.js.org/) 等对 ES Module 支持较好的构建工具来构建 Univer 应用。如果你使用了其它构建工具(例如 Webpack 4),可能会需要一些额外的配置,请阅读 [常见问题](/guides/sheet/troubleshooting) 获取更多信息。

### 安装

Univer 以插件的形式提供了一系列功能,除了一些产品所必需的核心插件外,你还可以根据需要选择性地引入其它插件。

<Callout>
- 如果你正在使用 npm,请确保使用的版本为 npm@7 及以上。这是因为 npm@3 ~ npm@6 并不会正确地安装 `peerDependencies`[^1]
- 如果你正在使用 pnpm,请确保使用的版本为 pnpm@8 及以上。如果你正在使用 pnpm@6 ~ pnpm@7,可以尝试配置 `auto-install-peers=true` [^2]来解决依赖安装问题。
Expand Down
6 changes: 6 additions & 0 deletions src/docs/guides/general/concepts.en-US.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,12 @@ 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:
Expand Down
50 changes: 28 additions & 22 deletions src/docs/guides/general/concepts.zh-CN.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { Callout } from 'nextra/components'
import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup'

# 基本概念
# 基础概念

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

Expand All @@ -13,66 +13,72 @@ import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup'
* 快照 Snapshot
* 命令 Command
* Facade API
* Presets

## 插件

Univer 的功能均由插件提供,插件是 Univer 的基本组成单元,多个插件组合在一起构成了 Univer 应用。

插件的职责包括:

1. 实现功能,例如 `@univerjs/sheets-filter` 提供筛选功能
1. 实现功能,例如 `@univerjs/sheets-filter` 实现了筛选功能
2. 提供某种基础能力,例如 `@univerjs/engine-render` 提供渲染能力

你可以按照自己的需要组合 Univer 提供的插件,定制符合你的需求的 Univer 应用,避免加载多余代码。你也可以通过编写插件来扩展 Univer 的功能,满足个性化的需求。
你可以按照自己的需要组合 Univer 提供的插件,定制符合你的需求的 Univer 应用,避免加载多余代码;也可以通过编写插件来扩展 Univer 的功能,满足个性化的需求。

### 相关链接
相关链接

1. [编写一个 CSV 导入插件](/guides/sheet/tutorials/csv-import-plugin) 了解如何编写一个插件
2. [Univer 架构](/guides/sheet/architecture/univer) 详细了解 Univer 的架构设计

## 快照

你需要在 Univer 中加载快照来加载文档,每种类型的文档都提供了自己的快照格式,请参考以上 API 文档了解如何编写符合格式要求的快照:
你需要在 Univer 中加载快照来加载文档,每种类型的文档都提供了自己的快照格式,请参考以下 API 文档了解如何编写符合格式要求的快照:

1. 电子表格的快照格式是 [`IWorkbookData`](/typedoc/@univerjs/core/interfaces/IWorkbookData)
1. [单元格配置](guides/sheet/getting-started/cell-data) 介绍了单元格的数据结构
2. 文档的快照格式是 [`IDocumentData`](/typedoc/@univerjs/core/interfaces/IDocumentData)
1. 电子表格的完整快照格式可参考 API 手册中的 [`IWorkbookData`](/typedoc/@univerjs/core/interfaces/IWorkbookData)
1. [工作簿数据结构](/guides/sheet/getting-started/workbook-data) 介绍了工作簿的基本结构
1. [单元格配置](/guides/sheet/getting-started/cell-data) 介绍了单元格的数据结构
2. 文档的完整快照结构可参考 API 手册中的 [`IDocumentData`](/typedoc/@univerjs/core/interfaces/IDocumentData)

功能插件可以通过 `resources` 字段来存储资源,例如图片等等,可参考 [插件自定义模型](/guides/sheet/advanced/custom-model)

<Callout emoji="⚠️">
<Callout type="error" emoji="🚨">
注意!Univer 的快照仅用于存储数据,在运行时,它并不会反映最新的文档状态!如果你想把文档状态保存为快照,请使用 Facade API 上的保存快照的方法。
</Callout>

### 相关链接
相关链接

1. [入门示例](/guides/sheet/getting-started/installation#入门示例加载数据修改数据和存储数据) 了解如何加载、保存快照
1. [安装和基本使用](/guides/sheet/getting-started/installation#表格基本操作) 了解如何加载、保存快照

## 命令

在 Univer 中,对于数据的修改都需要通过命令执行,基于命令的方式可以更好地追踪值的变化,并且能够实现撤销、重做和协同编辑等功能,以及处理功能之间复杂的关联逻辑等等。

如果你想通过命令的方式修改文档数据,请参考 [如何查找命令 ID](/guides/sheet/tutorials/find-the-command-id)。如果你选择通过 Facade API 来修改文档数据,实际上 Facade API 在背后会为你准备参数并执行命令。

<Callout emoji="⚠️">
**请不要直接修改 snapshot!** 这不会生效,不会触发视图或者 UI 的更新,请通过命令或者 Facade API 来修改数据
<Callout type="error" emoji="🚨">
Univer 基于[命令系统](/guides/sheet/architecture/univer#%E5%91%BD%E4%BB%A4%E7%B3%BB%E7%BB%9F)对状态和数据进行操作和更新,因此你**必须**使用命令或者相应的 Facade API 来更新数据,任何直接对数据进行修改以更新视图的操作都不会生效
</Callout>

### 相关链接

1. [入门示例](/guides/sheet/getting-started/installation#入门示例加载数据修改数据和存储数据) 了解如何通过 Facade API 修改数据

## Facade API

由于办公应用的复杂度非常高,Univer 的架构相应地也非常复杂,为了让开发者更容易地使用 Univer,我们提供了 Facade API,它是对 Univer 第一方插件的封装,提供了更简单的接口,让开发者可以更容易地使用 Univer。
Facade API 是对 Univer 第一方插件底层接口的封装,提供了更简单的使用方式,让开发者可以使用 Univer 而无需了解内部设计

目前 Facade API 在不断完善中,如果你有任何建议或者需求,欢迎在 GitHub 上提 issue
当然凡事皆有两面,Facade API 虽然让 Univer 更易用,但它同时也使得用户无法接触到 Univer 内部一些更强大的 API。如果你需要更高级的自定义能力,就需要在了解 Univer 架构的基础上使用底层 API

当然,简单性是有代价的,如果你需要更高级的自定义能力,就需要在了解 Univer 架构的基础上使用更加底层的命令和模块所暴露的 API。

### 相关链接
相关链接

1. [Facade API 介绍](/guides/sheet/getting-started/facade)
2. [Facade API 常用方法](/guides/sheet/facade/general-api)
3. [Facade Sheet API 常用方法](/zh-CN/guides/sheet/facade/sheet-api)
4. [Facade API 参考手册](/typedoc/@univerjs/facade/README)

## Presets

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

相关链接

1. [使用 Presets](/guides/sheet/getting-started/presets)
2. [开源仓库](https://github.com/dream-num/univer-presets)

13 changes: 10 additions & 3 deletions src/docs/guides/general/introduction.en-US.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,17 @@ import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup'
Univer provides a comprehensive enterprise-level solution for document and data collaboration, supporting three core document types: [**spreadsheets**](/guides/sheet/introduction), [**documents**](/guides/doc/introduction), and [**slides**](/guides/slide/introduction). Through a flexible API and plugin mechanism, developers can customize and extend personalized features on Univer to meet the specific needs of different users in various scenarios.

export const features = [{
title: '🚀 High Performance',
description: 'Univer uses a rendering engine based on Canvas and a formula engine that supports Web Worker, ensuring high performance on large-scale data rendering and processing.'
}, {
title: '🧩 Plugin-based',
description: 'The core functionality and capabilities of Univer are provided through plugins, allowing developers to freely combine the required functionality or create custom plugins to extend Univer.'
}, {
title: '🧙‍♀️ Isomorphic',
description: 'Univer can run both on browsers and Node.js, with the exactly same API. Write once, run everywhere.',
}, {
title: '🪄 Customizable',
description: 'Developers can customize the appearance and interaction of Univer by importing custom themes, icons, component libraries, etc.'
}, {
title: '🚀 High Performance',
description: 'Univer uses a rendering engine based on Canvas and a formula engine that supports Web Worker, ensuring high performance on large-scale data rendering and processing.'
}, {
title: '🌍 Internationalization',
description: 'Supports multiple languages, allowing developers to freely switch languages and customize language packs.'
Expand All @@ -40,6 +43,10 @@ export const features = [{

<FeatureBox features={features} />

## Getting Started

Bootstrap Univer in 5 minutes. Start from [here](/guides/sheet/getting-started/quickstart).

## Features

### 🛠 General Capabilities
Expand Down
9 changes: 6 additions & 3 deletions src/docs/guides/general/introduction.zh-CN.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,17 @@ import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup'
Univer 提供了一个全面的企业级文档与数据协同的解决方案,支持[**电子表格**](/guides/sheet/introduction)[**文本文档**](/guides/doc/introduction)[**演示幻灯片**](/guides/slide/introduction)三大核心文档类型。通过灵活的 API 和插件机制,开发者可以在 Univer 的基础上进行个性化功能的定制和扩展,以适应不同用户在不同场景下的特定需求。

export const features = [{
title: '🚀 高性能',
description: '基于 Canvas 的渲染引擎和公式引擎,支持 Web Worker,保证了高性能的同时,也能够支持大规模的数据处理。'
}, {
title: '🧩 插件化',
description: 'Univer 的核心功能和能力都是通过插件的方式提供的,开发者可以自由组合所需功能或扩展自定义插件。'
}, {
title: '🧙‍♀️ 多端同构',
description: 'Univer 可以在浏览器和 Node.js 上运行,提供完全相同的 API。一次编写,随处运行。',
}, {
title: '🪄 可定制',
description: '通过导入自定义主题、图标、组件库等方式,开发者可以定制化 Univer 的外观和交互。'
}, {
title: '🚀 高性能',
description: '基于 Canvas 的渲染引擎和公式引擎,支持 Web Worker,保证了高性能的同时,也能够支持大规模的数据处理。'
}, {
title: '🌍 国际化',
description: '支持多语言,开发者可以自由切换语言,也可以自定义语言包。'
Expand Down
Loading

0 comments on commit 726eb72

Please sign in to comment.