Merge pull request #3164 from cnAbp/docs

Update document
6 years ago · aba6fd94b9
parent 82801c219f 5773c46e12
commit aba6fd94b9
12 changed files with 169 additions and 20 deletions
--- a/docs/en/Customizing-Application-Modules-Guide.md
+++ b/docs/en/Customizing-Application-Modules-Guide.md
@ -21,7 +21,7 @@ This approach has the following benefits:

 However, there is a drawback:

-* You may not able to **customize** the module source code as it is in your own solution.
+* You may not able to **customize** the module because the module source is not in your solution.

 This document explains **how to customize or extend** a depended module without need to change its source code. While it is limited compared to a full source code change opportunity, there are still some good ways to make some customizations.

--- a/docs/en/Customizing-Application-Modules-Overriding-User-Interface.md
+++ b/docs/en/Customizing-Application-Modules-Overriding-User-Interface.md
@ -3,7 +3,4 @@
 You may want to override a page, a component, a JavaScript, CSS or an image file of your depended module. Overriding the UI completely depends on the UI framework you're using. Select the UI framework to continue:

 * [ASP.NET Core (MVC / Razor Pages)](UI/AspNetCore/Customization-User-Interface.md)
-* [Angular](UI/Angular/Customization-User-Interface.md)
-
-
-
+* [Angular](UI/Angular/Customization-User-Interface.md)
--- a/docs/zh-Hans/Application-Services.md
+++ b/docs/zh-Hans/Application-Services.md
@ -200,7 +200,7 @@ public async Task<BookDto> GetAsync(Guid id)

 ### CRUD应用服务

-如果需要创建具有Create,Update,Delete和Get方法的简单CRUD应用服务,则可以使用ABP的基类轻松构建服务. 你可以继承CrudAppService.
+如果需要创建具有Create,Update,Delete和Get方法的简单**CRUD应用服务**,则可以使用ABP的基类轻松构建服务. 你可以继承CrudAppService.

 示例:

@ -218,7 +218,9 @@ public interface IBookAppService :
 }
 ````

-* ICrudAppService有泛型参数来获取实体的主键类型和CRUD操作的DTO类型(它不获取实体类型,因为实体类型未向客户端公开使用此接口).
+`ICrudAppService` 有泛型参数来获取实体的主键类型和CRUD操作的DTO类型(它不获取实体类型,因为实体类型未向客户端公开使用此接口).
+
+> 为应用程序服务创建一个接口是最佳做法,但是ABP框架并不强制你这么做,你可以跳过接口部分.

 `ICrudAppService`声明以下方法:

@ -291,7 +293,52 @@ public class BookAppService :

 `CrudAppService`实现了`ICrudAppService`接口中声明的所有方法. 然后,你可以添加自己的自定义方法或覆盖和自定义实现.

-### 生命周期
+> `CrudAppService` 有不同数量泛型参数的版本,你可以选择适合的使用.
+
+### AbstractKeyCrudAppService
+
+`CrudAppService` 要求你的实体拥有一个Id属性做为主键. 如果你使用的是复合主键,那么你无法使用它.
+
+`AbstractKeyCrudAppService` 实现了相同的 `ICrudAppService` 接口,但它没有假设你的主键.
+
+#### 示例
+
+假设你有实体 `District`,它的`CityId` 和 `Name` 做为复合主键,使用 `AbstractKeyCrudAppService` 时需要你自己实现 `DeleteByIdAsync` 和 `GetEntityByIdAsync` 方法:
+
+````csharp
+public class DistrictAppService
+    : AbstractKeyCrudAppService<District, DistrictDto, DistrictKey>
+{
+    public DistrictAppService(IRepository<District> repository)
+        : base(repository)
+    {
+    }
+
+    protected override async Task DeleteByIdAsync(DistrictKey id)
+    {
+        await Repository.DeleteAsync(d => d.CityId == id.CityId && d.Name == id.Name);
+    }

-应用服务的生命周期是[transient](Dependency-Injection)的，它们会自动注册到依赖注入系统.
+    protected override async Task<District> GetEntityByIdAsync(DistrictKey id)
+    {
+        return await AsyncQueryableExecuter.FirstOrDefaultAsync(
+            Repository.Where(d => d.CityId == id.CityId && d.Name == id.Name)
+        );
+    }
+}
+````
+
+这个实现需要你创建一个类做为复合键:
+
+````csharp
+public class DistrictKey
+{
+    public Guid CityId { get; set; }
+
+    public string Name { get; set; }
+}
+````
+
+### 生命周期

+应用服务的生命周期是[transient](Dependency-Injection)的，它们会自动注册到依赖注入系统.
--- a/docs/zh-Hans/AspNet-Boilerplate-Migration-Guide.md
+++ b/docs/zh-Hans/AspNet-Boilerplate-Migration-Guide.md
@ -0,0 +1,3 @@
+# ASP.NET Boilerplate v5+ 迁移到 ABP Framework
+
+TODO...
--- a/docs/zh-Hans/Authorization.md
+++ b/docs/zh-Hans/Authorization.md
@ -205,6 +205,10 @@ public class AuthorAppService : ApplicationService, IAuthorAppService

 参阅 [基于策略的授权](https://docs.microsoft.com/zh-cn/aspnet/core/security/authorization/policies) 文档了解如何自定义策略.

+### 更改依赖模块的权限定义
+
+从 `PermissionDefinitionProvider` 派生的类(就像上面的示例一样) 可以获取现有的权限定义(由依赖[模块](Module-Development-Basics.md)定义)并更改其定义.
+
 ## IAuthorizationService

 ASP.NET Core 提供了 `IAuthorizationService` 用于检查权限. 注入后使用它进行条件控制权限.
--- a/docs/zh-Hans/CLI.md
+++ b/docs/zh-Hans/CLI.md
@ -48,6 +48,9 @@ abp new Acme.BookStore
        * `--separate-identity-server`: 将Identity Server应用程序与API host应用程序分开. 如果未指定,则服务器端将只有一个端点.
      * `none`: 无UI. 这个模板还有一些额外的选项：
        * `--separate-identity-server`: 将Identity Server应用程序与API host应用程序分开. 如果未指定,则服务器端将只有一个端点.
+    * `--mobile` 或者 `-m`: 指定移动应用程序框架. 默认框架是 `react-native`. 其他选项:
+      * `none`: 不包含移动应用程序.
+      * `react-native`: React Native.
    * `--database-provider` 或者 `-d`: 指定数据库提供程序.默认是 `ef`.其他选项:
      * `ef`: Entity Framework Core.
      * `mongodb`: MongoDB.
@ -148,7 +151,7 @@ abp switch-to-stable [options]

 #### Options

-`--solution-path` 或 `-sp`: 指定解决方案(.sln)文件路径. 如果未指定,CLI试寻找当前目录中的.sln文件.
+`--solution-directory` 或 `-sd`: 指定解决方案文件夹. 解决方案应该在指定文件夹或子文件夹中. 如果未指定,默认为当前目录.

 ### login

--- a/docs/zh-Hans/Customizing-Application-Modules-Extending-Entities.md
+++ b/docs/zh-Hans/Customizing-Application-Modules-Extending-Entities.md
@ -0,0 +1,3 @@
+# 自定义应用模块: 扩展实体
+
+TODO...
--- a/docs/zh-Hans/Customizing-Application-Modules-Guide.md
+++ b/docs/zh-Hans/Customizing-Application-Modules-Guide.md
@ -0,0 +1,62 @@
+# 自定义现有模块
+
+ABP框架提供的设计旨在支持构建完全[模块化的应用程序](Module-Development-Basics.md)和系统. 它还提供了一些可以在任何类型的应用程序中**使用**的[预构建应用模块](Modules/Index.md)
+
+例如,你可以在你的应用程序中**重用**[身份管理模块](Modules/Identity.md)去添加用户,角色和权限管理. [应用程序启动模板](Startup-Templates/Application.md)已经**预装**了Identity和其他模块.
+
+## 复用应用模块
+
+你有两个选项去复用应用模块:
+
+### 添加包引用
+
+你可以添加相关模块的 **NuGet** 和 **NPM** 包引用到你的应用程序,并配置模块(根据它的文档)集成到你的应用程序中.
+
+正如前面提到,[应用程序启动模板](Startup-Templates/Application.md)已经**预装了一些基本模块**,它引用模块的NuGet和NPM包.
+
+这种方法具有以下优点:
+
+* 你的解决方案会非常**干净**,只包含你**自己的应用程序代码**.
+* 你可以**很简单的**升级模块到最新的可用模板. `abp update` [CLI](CLI.md) 命令会使更新变的更加简单. 通过这种方式, 你可以获得**最新功能和Bus修复**.
+
+然而有一个缺点:
+
+* 你可能无法**自定义**模块,因为模块源码没有在你的解决方案中.
+
+本文档介绍了 **或者自定义或扩展** 依赖模块并且无需更改其源码,尽快与更改完整的源码比起是有限的,但仍有一些好的方法可以自定义.
+
+如果你不认为自己会对预构建的模块进行重大更改,那么使用包引用的方法复用模块是推荐的方法.
+
+### 包含源码
+
+如果你想要在预构建的模块上进行**重大**更改或添加**主要功能**,但是可用的扩展点不够使用,那么可以考虑直接使用依赖模块的源码.
+
+这种情况下,你通常**添加模块源码**到你的解决方案中,并将**包引用替换**为本地项目引用. **[ABP CLI](CLI.md)** 可以为你自动化这一过程.
+
+#### 分离模块解决方案
+
+你可能不希望将模块源代码**直接包含在解决方案**中. 每个模块都包含十多个项目文件,添加**多个模块**会使解决方案变的臃肿可能还会影响**开发时的加载速度**,另外你可能有不同的开发团队维护不同模块.
+
+无论如何,你都可以为需要的模块创建**单独的解决方案**,将依赖模块做为解决方案中的项目引用. 比如在[abp仓库](https://github.com/abpframework/abp/),我们就是这样做的.
+
+> 我们看到的一个问题是Visual Studio在这种方式下不能很好的工作(解决方案目录之外对本地项目的引用不能很好地支持). 如果在开发过程中出错(对于外部模块),请在Visual Studio打开应用程序的解决方案后,在命令行运行 `dotnet restore`命令.
+
+#### 发布的自定义模块的包
+
+一个备选方案是将重新打包模块的源代码(NuGet/NPM包),使用包引用. 你可以为公司使用本地私人的Nuget/NPM服务器.
+
+## 模块自定义/扩展途径
+
+如果你决定使用预构建模块的NuGet/NPM包引用方式. 下面的文档详细解释了如何自定义/扩展现有模块的方法:
+
+* [扩展实体](Customizing-Application-Modules-Extending-Entities.md)
+* [重写服务](Customizing-Application-Modules-Overriding-Services.md)
+* [重写界面](Customizing-Application-Modules-Overriding-User-Interface.md)
+
+### 另请参阅
+
+另外,请参阅以下文档:
+
+* 参阅 [本地化文档](Localization.md) 学习如何扩展已存在的本地化资源.
+* 参阅 [设置文档](Settings.md) 学习如何更改依赖模块的设置定义.
+* 参阅 [授权文档](Authorization.md) 学习如何更改依赖模块的权限定义.
--- a/docs/zh-Hans/Customizing-Application-Modules-Overriding-Services.md
+++ b/docs/zh-Hans/Customizing-Application-Modules-Overriding-Services.md
@ -0,0 +1,3 @@
+# 自定义应用模块: 覆盖服务
+
+TODO...
--- a/docs/zh-Hans/Customizing-Application-Modules-Overriding-User-Interface.md
+++ b/docs/zh-Hans/Customizing-Application-Modules-Overriding-User-Interface.md
@ -0,0 +1,6 @@
+# 重写用户界面
+
+你可以想要重写页面,组件,JavaScript,CSS或你依赖模块的图片文件. 重写UI取决于你使用的UI框架. 选择UI框架以继续:
+
+* [ASP.NET Core (MVC / Razor Pages)](UI/AspNetCore/Customization-User-Interface.md)
+* [Angular](UI/Angular/Customization-User-Interface.md)
--- a/docs/zh-Hans/UI/AspNetCore/Customization-User-Interface.md
+++ b/docs/zh-Hans/UI/AspNetCore/Customization-User-Interface.md
@ -0,0 +1,3 @@
+# ASP.NET Core (MVC / Razor Pages) 用户界面自定义指南
+
+TODO...
--- a/docs/zh-Hans/docs-nav.json
+++ b/docs/zh-Hans/docs-nav.json
@ -42,6 +42,33 @@
        }
      ]
    },
+    {
+      "text": "指南",
+      "items": [
+        {
+          "text": "自定义应用模块",
+          "path": "Customizing-Application-Modules-Guide.md",
+          "items": [
+            {
+              "text": "扩展实体",
+              "path": "Customizing-Application-Modules-Extending-Entities.md"
+            },
+            {
+              "text": "重写服务",
+              "path": "Customizing-Application-Modules-Overriding-Services.md"
+            },
+            {
+              "text": "重写用户界面",
+              "path": "Customizing-Application-Modules-Overriding-User-Interface.md"
+            }
+          ]
+        },
+        {
+          "text": "从ASP.NET Boilerplate迁移",
+          "path": "AspNet-Boilerplate-Migration-Guide.md"
+        }
+      ]
+    },
    {
      "text": "CLI",
      "path": "CLI.md"
@ -249,16 +276,7 @@
            },
            {
              "text": "Tag Helpers",
-              "items":[
-                {
-                  "text": "在线演示",
-                  "path": "UI/AspNetCore/Tag-Helpers/Index.md"
-                },
-                {
-                  "text": "按钮",
-                  "path": "UI/AspNetCore/Tag-Helpers/Buttons.md"
-                }
-              ]
+              "path": "UI/AspNetCore/Tag-Helpers/Index.md"
            },
            {
              "text": "仪表板和小部件(Widget)系统",