SoybeanAdmin

https://docs.soybeanjs.cn/zh/
Admin
SoybeanAdmin is a fresh and elegant admin template built with Vue3, Vite6, TypeScript, and UnoCSS,...
Tokens:41,257
Snippets:84
Trust Score:5.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install klona

Source: https://docs.soybeanjs.cn/zh/recommend/klona

Shows how to install the klona package using npm for use in your project.

```bash
npm install --save klona
```

--------------------------------

### klona Usage Example

Source: https://docs.soybeanjs.cn/zh/recommend/klona

Provides a practical example of using the `klona` function to deep copy an object and demonstrates that modifications to the cloned object do not affect the original.

```javascript
import { klona } from 'klona';

const input = {
  foo: 1,
  bar: {
    baz: 2,
    bat: {
      hello: 'world'
    }
  }
};

const output = klona(input);

// 与原始对象完全相同
// assert.deepStrictEqual(input, output); // 在 Node.js 环境中断言

// 深层更新...
output.bar.bat.hola = 'mundo';
output.bar.baz = 99;

// ...不会影响源对象!
console.log(JSON.stringify(input, null, 2));
// {
//   "foo": 1,
//   "bar": {
//     "baz": 2,
//     "bat": {
//       "hello": "world"
//     }
//   }
// }
```

--------------------------------

### SystemLogo Component Implementation

Source: https://docs.soybeanjs.cn/zh/guide/theme/logo

Demonstrates the implementation of the `SystemLogo` component, a Vue Single File Component (SFC). It shows how to use the `icon-local-logo` and mentions that its style can be configured via props. Refer to the local icon guide for specific implementation details.

```vue
<script lang="ts" setup>
defineOptions({ name: 'SystemLogo' });
</script>

<template>
  <icon-local-logo />
</template>

<style scoped></style>
```

--------------------------------

### klona/full Mode Import

Source: https://docs.soybeanjs.cn/zh/recommend/klona

Demonstrates importing the `klona/full` version. It extends the default `klona` by adding support for Symbol properties and non-enumerable properties.

```javascript
import { klona } from 'klona/full';
```

--------------------------------

### useTable Configuration Example

Source: https://docs.soybeanjs.cn/zh/guide/hooks/use-table

Illustrates the configuration options for the useTable hook, a wrapper around useHookTable that provides default settings. This example shows how to define API functions, parameters, and columns.

```typescript
useTable({
  apiFn: getUsers,
  apiParams: { page: 1, size: 10 },
  immediate: true,
  showTotal: true,
  columns: [
    {
      key: 'userName',
      title: '用户名',
      align: 'center',
      minWidth: 100
    }
    // 更多列...
  ]
});
```

--------------------------------

### klona/lite Mode Import

Source: https://docs.soybeanjs.cn/zh/recommend/klona

Demonstrates importing the `klona/lite` version. It extends `klona/json` by adding support for custom classes, Date, and RegExp objects.

```javascript
import { klona } from 'klona/lite';
```

--------------------------------

### 路由跳转使用示例 (.vue)

Source: https://docs.soybeanjs.cn/zh/guide/router/push

展示了在Vue组件的 `<script setup>` 中如何导入并使用 `useRouterPush` hook，并通过 `routerPushByKey` 方法跳转到首页。

```vue
<!-- 某个.vue文件 -->
<script lang="ts" setup>
import { useRouterPush } from '@/hooks/common/router';

const { routerPushByKey } = useRouterPush();
</script>

<template>
  <div>
    <NButton type="primary" @click="routerPushByKey('root')">返回首页</NButton>
  </div>
</template>
```

--------------------------------

### klona (Default) Mode Import

Source: https://docs.soybeanjs.cn/zh/recommend/klona

Demonstrates importing the default `klona` version. It extends `klona/lite` by adding support for Map, Set, DataView, ArrayBuffer, and TypedArray.

```javascript
import { klona } from 'klona';
```

--------------------------------

### TypeScript Debugger Example

Source: https://docs.soybeanjs.cn/zh/tutorial/debug

A sample TypeScript code snippet demonstrating a function `transformToKebabCase` and a `start` function. This code can be used to test the VSCode debugger configuration for TypeScript files.

```ts
function transformToKebabCase(input: string): string {
  return input.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
}

function start() {
  const input = 'HelloWorld';
  const result = transformToKebabCase(input);
  return result;
}

start();
```

--------------------------------

### klona/json Mode Import

Source: https://docs.soybeanjs.cn/zh/recommend/klona

Demonstrates importing the `klona/json` version, optimized for JSON data types. This is the smallest version.

```javascript
import { klona } from 'klona/json';
```

--------------------------------

### Custom Route Configuration Example (TypeScript)

Source: https://docs.soybeanjs.cn/zh/guide/router/structure

This TypeScript example demonstrates how to define custom routes using `ElegantVueRouter`. It allows mapping specific route names to paths, like root and notFound, and specifying custom route names.

```typescript
ElegantVueRouter({
  customRoutes: {
    map: {
      root: '/',
      notFound: '/:pathMatch(.*)*'
    },
    names: ['two-level_route']
  }
});
```

--------------------------------

### SoybeanAdmin CLI 概述

Source: https://docs.soybeanjs.cn/zh/guide/cli/intro

项目中的 `sa` 命令行工具集提供了多种辅助开发的功能。这些命令旨在简化常见的项目维护和开发流程。

```bash
sa cleanup
sa update-pkg
sa git-commit
sa git-commit-verify
sa changelog
sa release
sa gen-route
```

--------------------------------

### 集成加载函数到应用启动 (TypeScript)

Source: https://docs.soybeanjs.cn/zh/guide/theme/loading

为了使系统加载动画生效，需要将 `setupLoading` 函数在应用挂载到 DOM 之前调用。此代码片段展示了如何在 `main.ts` 文件中注册此函数，确保在应用启动时首先执行加载逻辑。

```typescript
async function setupApp() {
  setupLoading();
  app.mount('#app');
}
```

--------------------------------

### 发布项目

Source: https://docs.soybeanjs.cn/zh/guide/cli/intro

执行 `sa release` 命令可以自动化发布流程，包括更新版本号、生成 Changelog 和提交代码。

```bash
sa release
```

--------------------------------

### Install tsx

Source: https://docs.soybeanjs.cn/zh/tutorial/debug

Installs the `tsx` command-line tool globally using npm. `tsx` is a Node.js enhancement for running TypeScript files directly, supporting ES modules and CommonJS with built-in source map support.

```bash
npm install -g tsx
```

--------------------------------

### useHookTable Vue Usage Example

Source: https://docs.soybeanjs.cn/zh/guide/hooks/use-table

Demonstrates how to use the useHookTable hook directly within a Vue.js component to fetch and manage table data. It shows the setup of API functions, parameters, columns, and data transformation.

```vue
<script setup lang="tsx">
import { ref } from 'vue';
import { fetchGetUserList } from '@/service/api';
import useHookTable from '@sa/hooks';

const apiParams = ref({
  current: 1,
  size: 10
});

const columns = () => [
  {
    key: 'userName',
    title: 'User Name',
    align: 'center',
    minWidth: 100
  }
  // ...其他列配置
];

const getColumnChecks = columns => columns.map(column => ({ key: column.key, title: column.title, checked: true }));

const getColumns = (columns, checks) =>
  columns.filter(column => checks.find(check => check.key === column.key && check.checked));

const transformer = response => ({
  data: response.data,
  pageNum: response.pageNum,
  pageSize: response.pageSize,
  total: response.total
});

const { loading, empty, data, getData } = useHookTable({
  apiFn: fetchGetUserList,
  apiParams,
  transformer,
  columns,
  getColumnChecks,
  getColumns,
  immediate: true
});

// 当需要获取数据时，例如在组件挂载完成后或者用户点击刷新按钮时，调用 getData 函数
getData();
</script>
```

--------------------------------

### SoybeanJS CLI Commands Overview

Source: https://docs.soybeanjs.cn/zh/recommend/soybean-cli

This section outlines the primary commands provided by the @soybeanjs/cli tool, detailing their functionality and common use cases.

```APIDOC
SoybeanJS CLI Commands:

- git-commit: Generates git commit messages conforming to Angular conventions. Prefixing the commit message with '!' signifies a breaking change.
- git-commit-verify: Validates if git commit messages adhere to Angular conventions.
- cleanup: Provides a quick and thorough method to clear project dependencies and build artifacts.
- ncu: An alias for npm-check-updates, used to upgrade project dependencies.
- changelog: Generates changelogs based on version tags. The --total flag generates changelogs from all tags.
- release: Automates the release process, including updating version numbers, generating changelogs, and committing code.
```

--------------------------------

### SoybeanAdmin CLI 命令

Source: https://docs.soybeanjs.cn/zh/guide/cli/command

SoybeanAdmin 提供了一系列命令行工具，用于简化开发流程，包括清理目录、更新依赖、管理 Git 提交和发布流程。

```bash
sa cleanup
  删除目录: node_modules, dist, 等
```

```bash
sa update-pkg
  更新 package.json 依赖版本
```

```bash
sa git-commit
  生成符合 Conventional Commits 标准的提交信息
```

```bash
sa git-commit-verify
  验证 git 提交信息，确保符合 Conventional Commits 标准
```

```bash
sa changelog
  生成 changelog
```

```bash
sa release
  发布，更新版本，生成 changelog，提交代码
```

```bash
sa gen-route
  生成路由
```

--------------------------------

### 配置 simple-git-hooks 和脚本

Source: https://docs.soybeanjs.cn/zh/standard/lint

在 `package.json` 中配置 `simple-git-hooks` 以定义 Git 钩子行为，并添加 `prepare` 脚本以激活钩子。

```json
{
  "simple-git-hooks": {
    "commit-msg": "pnpm sa git-commit-verify",
    "pre-commit": "pnpm typecheck && pnpm lint-staged"
  },
  "scripts": {
    "prepare": "simple-git-hooks"
  }
}
```

--------------------------------

### 生成路由

Source: https://docs.soybeanjs.cn/zh/guide/cli/intro

`sa gen-route` 命令用于根据项目结构自动生成路由配置，简化路由的创建和管理。

```bash
sa gen-route
```

--------------------------------

### 配置后端请求成功的 code

Source: https://docs.soybeanjs.cn/zh/guide/request/backend

通过修改 `.env` 文件中的 `VITE_SERVICE_SUCCESS_CODE` 配置项来指定后端请求成功的 code。注意，环境文件加载的配置为字符串类型，若后端返回的 code 为数字类型，对比时需进行类型转换。

```env
VITE_SERVICE_SUCCESS_CODE=200
```

--------------------------------

### useTable Return Values Example

Source: https://docs.soybeanjs.cn/zh/guide/hooks/use-table

Shows the properties returned by the useTable hook, which are used to manage table state, data, pagination, and user interactions like updating search parameters.

```typescript
const {
  loading,
  empty,
  data,
  columns,
  columnChecks,
  reloadColumns,
  pagination,
  mobilePagination,
  updatePagination,
  getData,
  searchParams,
  updateSearchParams,
  resetSearchParams
} = useTable(config);
```

--------------------------------

### klona API: klona(input)

Source: https://docs.soybeanjs.cn/zh/recommend/klona

The main API function for klona. It takes an input value and returns a deep copy (clone) of it. The return type matches the input type.

```APIDOC
klona(input)
  - Returns: typeof input
  - Description: Returns a deep copy/clone of the input value.
  - Parameters:
    - input: The value to be deep copied.
```

--------------------------------

### Enable Source Maps in Vite

Source: https://docs.soybeanjs.cn/zh/tutorial/debug

Configuration snippet for `vite.config.ts` to enable source map generation during the build process. This is crucial for effective debugging of Vue.js applications in development environments.

```ts
export default defineConfig({
  build: {
    sourcemap: true
  }
})
```

--------------------------------

### VSCode Vue Debug Configuration

Source: https://docs.soybeanjs.cn/zh/tutorial/debug

Configures VSCode to launch and debug Vue.js applications running in Chrome. It requires the application to be running locally, typically on `http://localhost:9527`, and specifies the project's root directory.

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Vue Debugger",
      "url": "http://localhost:9527",
      "webRoot": "${workspaceFolder}"
    }
  ]
}
```

--------------------------------

### 生成 Changelog

Source: https://docs.soybeanjs.cn/zh/guide/cli/intro

使用 `sa changelog` 命令可以根据 Git 提交历史自动生成项目的 Changelog 文件。

```bash
sa changelog
```

--------------------------------

### VSCode tsx Debug Configuration

Source: https://docs.soybeanjs.cn/zh/tutorial/debug

Provides the necessary `launch.json` configuration for VSCode to debug TypeScript files. It specifies `tsx` as the runtime executable, enabling features like breakpoints and variable inspection directly within the IDE.

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "TS Debugger",
      "runtimeExecutable": "tsx",
      "skipFiles": ["<node_internals>/**", "${workspaceFolder}/node_modules/**"],
      "program": "${file}"
    }
  ]
}
```

--------------------------------

### 本地 SVG 图标存放位置

Source: https://docs.soybeanjs.cn/zh/guide/icon/intro

本地 SVG 图标文件应放置在 src/assets/svg-icon 目录下，以便 unplugin-icons 和 vite-plugin-svg-icons 插件进行处理。

```path
src/assets/svg-icon/
```

--------------------------------

### 更新 package.json 依赖

Source: https://docs.soybeanjs.cn/zh/guide/cli/intro

使用 `sa update-pkg` 命令可以更新 `package.json` 文件中的依赖版本，确保项目依赖是最新的。

```bash
sa update-pkg
```

--------------------------------

### 安装 simple-git-hooks

Source: https://docs.soybeanjs.cn/zh/standard/lint

安装 `simple-git-hooks` 作为开发依赖，用于管理 Git 钩子，如提交信息校验和代码检查。

```bash
pnpm i simple-git-hooks -D
```

--------------------------------

### 路由跳转使用示例 (.ts)

Source: https://docs.soybeanjs.cn/zh/guide/router/push

演示了如何在TypeScript文件中（非Vue setup上下文）使用 `useRouterPush` hook，并调用 `routerPushByKey` 方法跳转到首页。

```ts
import { useRouterPush } from '@/hooks/common/router';

// 注意传入false
const { routerPushByKey } = useRouterPush(false);

function backToRoot() {
  routerPushByKey('root')
}
```
Tokens:
Raw