优化docs文档

kaokei · kaokei · commit 622a3d0f96da · 2025-07-01T11:40:39.000+08:00
diff --git a/.gitignore b/.gitignore
@@ -11,7 +11,7 @@
 # production
 /build
 /lib
-/dist
+dist
 /example/dist
 
 # misc
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -9,8 +9,8 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'API', link: '/api/' },
       { text: 'Guide', link: '/guide/' },
+      { text: 'API', link: '/api/' },
       { text: 'Note', link: '/note/' },
     ],
 
diff --git a/docs/guide/index.md b/docs/guide/index.md
@@ -55,6 +55,7 @@ import { CountService, LoggerService } from './service.ts';
 // 这行代码将CountService、LoggerService和当前组件进行了绑定
 declareProviders([CountService, LoggerService]);
 // 这行代码实例化了CountService得到一个countService对象
+// 并且countService对象自动注入了logger属性，是一个LoggerService实例对象
 const countService = useService(CountService);
 </script>
 
diff --git a/docs/index.md b/docs/index.md
@@ -15,10 +15,10 @@ hero:
       link: /api/
 
 features:
-  - title: Feature A
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature B
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature C
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+  - title: 深度 DI 集成​
+    details: 无缝融合 Vue 3 的依赖注入机制，在组件、服务和模块间轻松注入、共享和管理状态，极大提升复杂应用架构的灵活性与可测试性。
+  - title: 极致轻量化​
+    details: 专注核心功能，gzip 压缩后仅 ​约 4kB​ 的超小体积，为你的项目带来强大的状态管理能力，却几乎不增加包负担。
+  - title: 开箱即用的类型安全​
+    details: 为 TypeScript 提供开箱即用的强力支持，精准的类型推导和验证贯穿状态访问与变更全过程，有效杜绝低级错误，提升开发效率和代码健壮性。
 ---
diff --git a/docs/note/01.不同场景.md b/docs/note/01.不同场景.md
@@ -1,3 +1,5 @@
+# 不同场景
+
 ## 场景
 
 #### 场景 1：一个服务可以被多个组件绑定，一个组件也可以绑定多个服务
diff --git a/docs/note/02.父组件与子组件的理解.md b/docs/note/02.父组件与子组件的理解.md
@@ -1,4 +1,6 @@
-# 假设如下场景
+# 父组件与子组件的理解
+
+## 假设如下场景
 
 父组件是 ParentComp，绑定的服务是 ParentService。
 
diff --git a/docs/note/03.子组件获取父组件服务.md b/docs/note/03.子组件获取父组件服务.md
@@ -1,4 +1,6 @@
-# 假设如下场景
+# 子组件获取父组件服务
+
+## 假设如下场景
 
 父组件是 ParentComp，绑定的服务是 ParentService。
 
diff --git a/docs/note/04.父组件获取子组件服务.md b/docs/note/04.父组件获取子组件服务.md
@@ -1,4 +1,6 @@
-# 假设如下场景
+# 父组件获取子组件服务
+
+## 假设如下场景
 
 父组件是 ParentComp，绑定的服务是 ParentService。
 
@@ -70,7 +72,12 @@ function handleClickEvent() {
 场景 1：在服务中使用
 
 ```ts
-import { Inject, FIND_CHILD_SERVICE, Token, useService } from '@kaokei/use-vue-service';
+import {
+  Inject,
+  FIND_CHILD_SERVICE,
+  Token,
+  useService,
+} from '@kaokei/use-vue-service';
 const token = new Token<ChildServiceType>('child service name');
 
 class DemoService {
diff --git a/docs/note/05.响应式方案.md b/docs/note/05.响应式方案.md
@@ -1,3 +1,5 @@
+# 响应式方案
+
 ## 默认整体实例不是响应式，手动指定属性为响应式属性
 
 可以使用 ref/shallowRef/reactive 等 API 将指定属性设置为响应式变量，这样在 vue 组件的 template 中就可以直接消费这些响应式属性。
diff --git a/docs/note/06.装饰器.md b/docs/note/06.装饰器.md
@@ -1,3 +1,5 @@
+# 装饰器
+
 ## @Computed 装饰器
 
 [When "reactive" uses "class" and "computed", the "computed" attribute will not Reactive](https://github.com/vuejs/core/issues/1036)
diff --git a/docs/note/07.SSR-deepseek.md b/docs/note/07.SSR-deepseek.md
@@ -1,3 +1,5 @@
+# SSR-deepseek
+
 ## 方案设计
 
 以下方案来自 DeepSeek，可以作为参考。
@@ -179,4 +181,4 @@ if (import.meta.server) {
 
 ## 参考
 
-[彻底理解服务端渲染 - SSR原理](https://github.com/yacan8/blog/issues/30)
+[彻底理解服务端渲染 - SSR 原理](https://github.com/yacan8/blog/issues/30)
diff --git a/docs/note/08.SSR-angular.md b/docs/note/08.SSR-angular.md
@@ -1,3 +1,5 @@
+# SSR-angular
+
 ## Angular 中的 ssr
 
 虽然 Angular 的数据是保存在 service 中的，但是 angular 并不是像 pinia 一样默认将 service 作为整体进行 ssr。
diff --git a/docs/note/09.SSR-pinia.md b/docs/note/09.SSR-pinia.md
@@ -1,3 +1,5 @@
+# SSR-pinia
+
 ## vite-ssr
 
 [参考文档在这里](https://pinia.vuejs.org/zh/ssr/)
diff --git a/docs/note/10.SSR.md b/docs/note/10.SSR.md
@@ -1,3 +1,5 @@
+# SSR
+
 ## 简介
 
 首先需要明确本库并没有实现支持 SSR 的功能，因为整体实现方案相对比较复杂，而且我本身也基本不会涉及到 SSR 项目。没有必要增加项目复杂度。
diff --git a/docs/note/99.基本命令.md b/docs/note/99.基本命令.md
@@ -1,3 +1,5 @@
+# 基本命令
+
 ## pnpm test
 
 运行所有单元测试
diff --git a/docs/note/index.md b/docs/note/index.md
@@ -1,18 +1,18 @@
-## 各种使用场景
+# 组件和服务互相访问
 
 组件和服务是绑定的。
 
 假设有 A，B 两个组件。A 组件中声明了 A 服务，B 组件中声明了 B 服务。同时 B 组件是 A 组件的子组件/子孙组件。
 
 当然一个组件也是可以声明多个服务的。这样就可以实现服务的拆分，避免单个服务过于庞大。这里只是以 AB 组件为例。
 
-### A 组件访问 A 服务/B 组件访问 B 服务
+## A 组件访问 A 服务/B 组件访问 B 服务
 
 A 组件中可以使用 useService(A) 获取 A 服务实例对象。
 
 B 组件中可以使用 useService(B) 获取 B 服务实例对象。
 
-### A 组件访问 B 服务
+## A 组件访问 B 服务
 
 因为 A 组件是 B 组件的父组件，所以不能直接使用 useService(B) 获取 B 服务实例对象。
 
@@ -22,49 +22,49 @@ B 组件中可以使用 useService(B) 获取 B 服务实例对象。
 
 对于 const findChildrenService = useService(FIND_CHILDREN_SERVICES)是类似的工具方法，只是用于获取多个实例对象。
 
-### A 服务访问 B 服务
+## A 服务访问 B 服务
 
 A 服务中可以使用 @Inject(FIND_CHILD_SERVICE) 来获取工具方法。然后调用工具方法获取 B 服务实例对象。
 
 对于 @Inject(FIND_CHILDREN_SERVICES) 是类似的工具方法，只是用于获取多个实例对象。
 
-### B 组件访问 A 服务
+## B 组件访问 A 服务
 
 B 组件中可以使用 useService(A) 获取 A 服务实例对象。
 
-### B 服务访问 A 服务
+## B 服务访问 A 服务
 
 B 服务中可以使用 @Inject(A) 来获取 A 服务实例对象。
 
-### 假设 A 组件声明了多个服务，比如 A1，A2，A3 服务。A1 服务访问 A2 服务或者 A3 服务
+## 假设 A 组件声明了多个服务，比如 A1，A2，A3 服务。A1 服务访问 A2 服务或者 A3 服务
 
 A1 服务中可以使用 @Inject(A2) 来获取 A2 服务实例对象。
 
 A1 服务中可以使用 @Inject(A3) 来获取 A3 服务实例对象。
 
-### A 服务访问 A 组件/B 服务访问 B 组件
+## A 服务访问 A 组件/B 服务访问 B 组件
 
 不支持。
 
 历史版本中曾经支持过 A 服务可以注入 A 组件，从而可以在 A 服务中直接访问 A 组件的数据。但是现在已经废弃了。
 
-### A 组件访问 B 组件
+## A 组件访问 B 组件
 
 不支持。
 
 访问子组件属于 vue 原生功能，通过 ref 来引用子组件，但是不能引用子组件的子组件。
 
-### A 服务访问 B 组件
+## A 服务访问 B 组件
 
 不支持。
 
-### B 组件访问 A 组件
+## B 组件访问 A 组件
 
 不支持。
 
 可以使用 vue 的原生能力，也就是 instance.parent 属性
 
-### B 服务访问 A 组件
+## B 服务访问 A 组件
 
 不支持。
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# 不同场景`
	`2`	`+`
`1`	`3`	`## 场景`
`2`	`4`
`3`	`5`	`#### 场景 1：一个服务可以被多个组件绑定，一个组件也可以绑定多个服务`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# 响应式方案`
	`2`	`+`
`1`	`3`	`## 默认整体实例不是响应式，手动指定属性为响应式属性`
`2`	`4`
`3`	`5`	`可以使用 ref/shallowRef/reactive 等 API 将指定属性设置为响应式变量，这样在 vue 组件的 template 中就可以直接消费这些响应式属性。`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# 装饰器`
	`2`	`+`
`1`	`3`	`## @Computed 装饰器`
`2`	`4`
`3`	`5`	`[When "reactive" uses "class" and "computed", the "computed" attribute will not Reactive](https://github.com/vuejs/core/issues/1036)`