docs: fix a few issues

ng-alain · Jan 16, 2018 · df790f7 · df790f7
1 parent 7d15d61
commit df790f7
Show file tree

Hide file tree

Showing 29 changed files with 184 additions and 53 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -1,4 +1,4 @@
-sudo: false
+sudo: required
 language: node_js
 node_js:
   - "8.5.0"

diff --git a/docs/data-render.md b/docs/data-render.md
@@ -35,7 +35,7 @@ registerLocaleData(localeZhHans);
 
 ## _date
 
-基于 moment 日期格式化，显示更多细节参考：//momentjs.com/docs/#/displaying
+基于 moment 日期格式化，显示更多细节参考 [momentjs](//momentjs.com/docs/#/displaying)
 
 最大好处是 moment 支持不同种类的时间格式，例如：
 

diff --git a/docs/delon.md b/docs/delon.md
@@ -26,4 +26,4 @@ type: Basic
     + Token 管理
     + Simple Web Token & JSON Web Token 拦截器
 + **@delon/mock**
-    + 简单 Angular Http Mock 类库，[Document](//ng-alain.com/docs/mock)
+    + 简单 Angular Http Mock 类库，[Document](http://ng-alain.com/docs/mock)
diff --git a/docs/graph.md b/docs/graph.md
@@ -23,7 +23,7 @@ type: Advance
 | 地图类 | - | -
 | 其它 | 标签云：`tag-cloud`<br>图表卡片：`chart-card`<br>自定义图表：`chart` | -
 
-[查看图表组件API文档](//ng-alain.com/components/charts)
+[查看图表组件API文档](http://ng-alain.com/components/charts)
 
 ## 如何使用？
 

diff --git a/docs/i18n.md b/docs/i18n.md
@@ -22,6 +22,12 @@ providers: [
 
 ## 如何删除？
 
+**通过CLI**
+
+默认通过 `ng new -c=@delon/cli demo` 是不会引入 i18n，需要加上 `-di` 才会加入 i18n。
+
+**通过Github**
+
 移除内容包括：
 
 + `src/app/core/i18n` 目录

diff --git a/docs/layout.md b/docs/layout.md
@@ -6,7 +6,7 @@ title:
 type: Basic
 ---
 
-页面整体布局是指包含导航、侧边栏、内容区域、页脚等最外层的框架结构。在页面之中，也有很多区块的布局结构，目前 ng-zorro-antd 有两套布局方案：[Layout](//ng.ant.design/components/layout) 和 [Grid](//ng.ant.design/components/grid)；而后者是日常都需要的，诸如：表单、列表页、明细页等多多少少都会涉及。
+页面整体布局是指包含导航、侧边栏、内容区域、页脚等最外层的框架结构。在页面之中，也有很多区块的布局结构，目前 ng-zorro-antd 有两套布局方案：[Layout](https://ng.ant.design/#/components/layout) 和 [Grid](https://ng.ant.design/#/components/grid)；而后者是日常都需要的，诸如：表单、列表页、明细页等多多少少都会涉及。
 
 ## 根据不同场景区分抽离布局组件
 

diff --git a/docs/module.md b/docs/module.md
@@ -0,0 +1,91 @@
+---
+order: 10
+title:
+  en-US: Module Guidelines
+  zh-CN: 模块注册指导原则
+type: Basic
+---
+
+一直以来 `AppModule`、`CoreModule`、`SharedModule` 模块使用没有很明确的规范，很容易让产生乱用。Angular模块目标是为了使组件、指令、服务和管道功能块更内聚，并每一个功能区域形成独立的业务领域或实用工具的集合。
+
+**AppModule**
+
+根模块，用于引导 Angular 启动；它非常适合导入一些需要在整个应用到处需要的模块，例如：主题系统、用户主认证模块、权限模块等模块，以及一些全局性HTTP拦截器、国际化服务等。
+
+**CoreModule**
+
+核心模块只会被导入一次，它等同 `AppModule`，但我们更应该把它当成一个**纯服务类模块**，例如：消息、数据访问等。
+
+**SharedModule**
+
+我们叫它共享模块；它不应该出现 `providers`，因为 `ShareModule` 会在所有业务模块中被导入，这会导致服务被覆盖。
+
+基于以上，这些模块在 ng-alain 中呈现有些混乱，因此将模块更区明确的区分：
+
+### AppModule
+
+**应** 导入模块：
+
++ Angular 模块：`BrowserModule`、`BrowserAnimationsModule`、`HttpClientModule`
++ `AlainThemeModule` 主题系统
++ `DelonMockModule` Mock数据
++ `AlainAuthModule` 用户认证模块
++ `AlainACLModule` 权限模块
++ 国际化模块
+
+**应** 包含服务：
+
++ Angular 国际化
++ HTTP 拦截器
++ Angular 启动服务
++ `ng-zorro-antd` 基础组件服务
++ `ng-zorro-antd-extra` 基础组件扩展服务
++ `@delon/abc` 业务组件服务
+
+**作用：** 贯穿整个应用的定义。
+
+### CoreModule
+
+**应** 仅只留 `providers` 属性。
+
+**作用：**  一些通用服务，例如：用户消息、HTTP数据访问。
+
+### ShareModule
+
+**应** 包含定义：
+
++ 应用通用自定义业务组件
+
+**应** 导入模块：
+
++ Angular 通用模块：`CommonModule`、`FormsModule`、`RouterModule`、`ReactiveFormsModule`
++ `ng-zorro-antd` 基础组件模块
++ `ng-zorro-antd-extra` 基础扩展组件模块
++ `@delon/abc` 业务组件模块
++ 第三方通用依赖组件模块
+
+**应** 导出所有包含的模块。
+
+**不应** 有 `providers` 属性。
+
+**作用：**  一些通用自定义、第三方组件定义，减少业务模块的导入。
+
+### 业务模块
+
+业务模块应该包括业务定义模块和路由模块。
+
+**模块**
+
+**应** 导入模块：
+
++ `SharedModule`
++ 对应的路由模块
+
+**不应**：
+
++ 导出任何组件
++ 尽可能不要使用 `providers` 属性
+
+**路由模块**
+
+**应** 只包括路由的 `import`、`exports` 模块。
diff --git a/docs/net.zh-CN.md b/docs/net.zh-CN.md
@@ -28,4 +28,4 @@ ng-alain 默认下有两处对任何网络请求进行一些处理。
 
 脚手架默认情况下使用了 `@delon/auth` 的 `SimpleInterceptor` 拦截器，导致在请求过程中若发现无法获取 Token 时会直接返回错误。
 
-[用户认证](//ng-alain.com/docs/auth)这个过程是中台必备的。
+[用户认证](http://ng-alain.com/docs/auth)这个过程是中台必备的。
diff --git a/docs/service.md b/docs/service.md
@@ -10,13 +10,13 @@ type: Theme
 
 ## _HttpClient
 
-见[网络请求](//localhost:4200/docs/net)章节。
+见[网络请求](http://ng-alain.com/docs/net)章节。
 
 ## MenuService
 
 菜单服务的数据格式是一个 [Menu](//github.com/cipchk/delon/blob/master/src/core/theme/services/menu/menu.service.ts#L4) 数组，其中 `text` 属性表示菜单文本为必填项，而且本身并不受外部组件的影响（例如[sidebar-nav](/components/sidebar-nav)组件），这是因为菜单是贯穿整个项目必不可少的组成部分，而将其独立成一个服务可以更有效被使用，例如：动态生成导航、标题等。
 
-**建议：** 在 Angular 启动服务（[startup.service.ts](//github.com/cipchk/ng-alain/blob/master/src/app/core/services/startup.service.ts)）从远程获取到菜单数据后，调用 `add()` 方法。
+**建议：** 在 Angular 启动服务（[startup.service.ts](//github.com/cipchk/ng-alain/blob/master/src/app/core/startup/startup.service.ts)）从远程获取到菜单数据后，调用 `add()` 方法。
 
 **API 接口**
 
@@ -42,7 +42,7 @@ type: Theme
 
 用于设置页面标题，一般需要配置路由变化一起使用，例如：[app.component.ts](//github.com/cipchk/ng-alain/blob/master/src/app/app.component.ts#L29)；而标题的数据来源于 `MenuService`。
 
-**建议：** 在 Angular 启动服务（[startup.service.ts](//github.com/cipchk/ng-alain/blob/master/src/app/core/services/startup.service.ts)）从远程获取到应用数据后，设置 `prefix` 或 `suffix` 值来调整统一的标题前后缀。
+**建议：** 在 Angular 启动服务（[startup.service.ts](//github.com/cipchk/ng-alain/blob/master/src/app/core/startup/startup.service.ts)）从远程获取到应用数据后，设置 `prefix` 或 `suffix` 值来调整统一的标题前后缀。
 
 ## ThemesService
 

diff --git a/docs/use-components-alone.md b/docs/use-components-alone.md
@@ -33,4 +33,4 @@ import { AlainABCModule } from '@delon/abc';
 组件会随着脚手架的更新而不断迭代，有任何问题和需求可以反馈到 [这里](//github.com/cipchk/ng-alain/issues)。
 
 - 最新版本：[![@delon/abc](//img.shields.io/npm/v/@delon/abc.svg?style=flat-square)](//www.npmjs.com/package/@delon/abc)
-- [更新日志](//ng-alain.com/docs/changelog)
+- [更新日志](http://ng-alain.com/docs/changelog)
diff --git a/site/app/layout/footer/footer.component.html b/site/app/layout/footer/footer.component.html
@@ -37,7 +37,7 @@ <h2>{{'app.footer.resources' | translate}}</h2>
         <div nz-col nzXs="24" nzSm="24" nzLg="6">
             <div class="footer-center">
                 <h2>{{'app.footer.community' | translate}}</h2>
-                <div><a href="/docs/changelog" target="_blank">{{ 'app.footer.change-log' | translate}}</a></div>
+                <div><a routerLink="/docs/changelog">{{ 'app.footer.change-log' | translate}}</a></div>
                 <div><a routerLink="/docs/faq">{{ 'app.footer.faq' | translate}}</a></div>
                 <div><a href="//github.com/cipchk/ng-alain/issues" target="_blank">{{ 'app.footer.issues' | translate}}</a></div>
                 <div><a [nz-clipboard]="'316911865'">{{ 'app.footer.qqgroup' | translate}}</a></div>

diff --git a/site/app/shared/components/code-box/code-box.component.html b/site/app/shared/components/code-box/code-box.component.html
@@ -8,7 +8,7 @@
 <section class="code-box-meta markdown">
     <div class="code-box-title">
         {{i18n.get(item.meta.title)}}
-        <edit-button [url]="item.source"></edit-button>
+        <edit-button [item]="item"></edit-button>
     </div>
     <div [innerHTML]="i18n.get(item.summary)"></div>
     <nz-tooltip [nzTitle]="expand ? 'Hide Code' : 'Show Code'">

diff --git a/site/app/shared/components/docs/docs.component.html b/site/app/shared/components/docs/docs.component.html
@@ -15,7 +15,7 @@
     <h1>
         {{meta.item.title}}
         <span *ngIf="meta.item.subtitle" class="subtitle">{{meta.item.subtitle}}</span>
-        <edit-button [url]="i18n.get(item.source)"></edit-button>
+        <edit-button [item]="item"></edit-button>
     </h1>
     <div *ngIf="i18n.get(item.content).content" [innerHTML]="safeHtml(i18n.get(item.content).content)"></div>
     <ng-container *ngIf="meta.item.module">

diff --git a/site/app/shared/components/docs/docs.component.ts b/site/app/shared/components/docs/docs.component.ts
@@ -1,4 +1,4 @@
-import { Component, Input, OnInit, OnDestroy } from '@angular/core';
+import { Component, Input, OnInit, OnDestroy, ChangeDetectionStrategy, ChangeDetectorRef } from '@angular/core';
 import { Router } from '@angular/router';
 import { DomSanitizer } from '@angular/platform-browser';
 import { I18NService } from '../../../i18n/service';
@@ -7,7 +7,8 @@ import { MetaService } from '../../../core/meta.service';
 @Component({
     selector: 'app-docs',
     templateUrl: './docs.component.html',
-    styleUrls: [ './docs.component.less' ]
+    styleUrls: [ './docs.component.less' ],
+    changeDetection: ChangeDetectionStrategy.OnPush
 })
 export class DocsComponent implements OnInit, OnDestroy {
 
@@ -46,23 +47,25 @@ export class DocsComponent implements OnInit, OnDestroy {
                         title: this.i18n.get(item.meta.title)
                     };
                 });
-                const demoTitle = this.i18n.fanyi('app.component.examples');
-                value.toc[lang].splice(0, 0, {
-                    h: 2,
-                    href: '#' + demoTitle,
-                    title: demoTitle
-                }, ...demoTocs);
+                value.toc[lang] = demoTocs;
+                // const demoTitle = this.i18n.fanyi('app.component.examples');
+                // value.toc[lang].splice(0, 0, {
+                //     h: 2,
+                //     href: '#' + demoTitle,
+                //     title: demoTitle
+                // }, ...demoTocs);
             }
         }
         // endregion
 
         this._item = value;
 
         // goTo
-        // setTimeout(() => {
-        //     const toc = this.router.parseUrl(this.router.url).queryParams._toc || '';
-        //     if (toc) this.goTo({ href: `#${toc}` });
-        // }, 800);
+        setTimeout(() => {
+            const toc = this.router.parseUrl(this.router.url).fragment || '';
+            if (toc) document.querySelector(`#${toc}`).scrollIntoView();
+        }, 200);
+        this.cd.detectChanges();
     }
     get item(): any {
         return this._item;
@@ -72,7 +75,11 @@ export class DocsComponent implements OnInit, OnDestroy {
         public i18n: I18NService,
         public meta: MetaService,
         private router: Router,
-        protected sanitizer: DomSanitizer) {}
+        protected sanitizer: DomSanitizer,
+        private cd: ChangeDetectorRef
+    ) {
+        cd.detach();
+    }
 
     goTo(item: any) {
         document.querySelector(item.href).scrollIntoView();
@@ -86,6 +93,7 @@ export class DocsComponent implements OnInit, OnDestroy {
             for (let i = 0, element; element = elements[i++];) {
                 hljs.highlightBlock(element);
             }
+            this.cd.detectChanges();
         }, 250);
     }
 

diff --git a/site/app/shared/components/edit-button/edit-button.component.ts b/site/app/shared/components/edit-button/edit-button.component.ts
@@ -1,5 +1,6 @@
 import { Component, Input } from '@angular/core';
 import { MetaService } from './../../../core/meta.service';
+import { I18NService } from '../../../i18n/service';
 
 @Component({
     selector: 'edit-button',
@@ -14,9 +15,9 @@ export class EditButtonComponent {
     _full: string;
 
     @Input()
-    set url(u: string) {
-        this._full = `${this.meta.github}/edit/master/${u}`;
+    set item(data: any) {
+        this._full = `${this.meta.github}/edit/master/${this.i18n.get(data.source)}`;
     }
 
-    constructor(private meta: MetaService) {}
+    constructor(private meta: MetaService, private i18n: I18NService) {}
 }
diff --git a/src/core/abc/README.md b/src/core/abc/README.md
@@ -1,6 +1,6 @@
 # @delon/abc module
 
-[Document](//ng-alain.com/components)
+[Document](http://ng-alain.com/components)
 
 ## Architecture
 

diff --git a/src/core/abc/avatar-list/demo/simple.md b/src/core/abc/avatar-list/demo/simple.md
@@ -5,6 +5,13 @@ title:
 order: 0
 ---
 
+
+## zh-CN
+
+最简单的用法。
+
+## en-US
+
 Simplest of usage.
 
 ```ts

diff --git a/src/core/abc/xlsx/demo/import.md b/src/core/abc/xlsx/demo/import.md
@@ -3,7 +3,7 @@ order: 1
 title: 导入
 ---
 
-导入Excel并输出JSON，支持 `<input type="file">`、URL 形式
+导入Excel并输出JSON，支持 File、URL 形式
 
 ```ts
 import { Component } from '@angular/core';

diff --git a/src/core/abc/xlsx/index.md b/src/core/abc/xlsx/index.md
@@ -2,7 +2,7 @@
 title: xlsx
 subtitle: Excel 操作
 order: 210
-cols: 2
+cols: 1
 module: AdXlsxModule
 ---
 
@@ -16,7 +16,7 @@ module: AdXlsxModule
 npm install --save file-saver
 ```
 
-由于 sheetjs 脚本大小以及对 Excel 的操作并不是刚需的原因，因此采用一种延迟加载脚本的形式。在导入 `AdXlsxModule` 模块时允许你指定个 URL、CDN 路径，默认情况下使用 `//cdn.bootcss.com/xlsx/0.11.14/xlsx.min.js`。
+由于 sheetjs 脚本大小以及对 Excel 的操作并不是刚需的原因，因此采用一种延迟加载脚本的形式。在导入 `AdXlsxModule` 模块时允许你指定个 URL、CDN 路径，默认情况下使用 `//cdn.bootcss.com/xlsx/0.11.17/xlsx.full.min.js`。
 
 ## API
 

diff --git a/src/core/abc/xlsx/interface.ts b/src/core/abc/xlsx/interface.ts
@@ -5,7 +5,7 @@ export const DA_XLSX_CONFIG = new InjectionToken<XlsxConfig>('DA_XLSX_CONFIG');
 export interface XlsxConfig {
     /**
      * Xlsx library path
-     * @default //cdn.bootcss.com/xlsx/0.11.14/xlsx.min.js
+     * @default //cdn.bootcss.com/xlsx/0.11.17/xlsx.full.min.js
      */
     url?: string;
     /**

diff --git a/src/core/abc/zip/demo/read.md b/src/core/abc/zip/demo/read.md
@@ -3,7 +3,7 @@ order: 1
 title: 解压
 ---
 
-读取Zip文件信息（含内容），支持 `<input type="file">`、URL 形式
+读取Zip文件信息（含内容），支持 File、URL 形式
 
 ```ts
 import { Component } from '@angular/core';

diff --git a/src/core/abc/zip/demo/save.md b/src/core/abc/zip/demo/save.md
@@ -17,7 +17,7 @@ import * as JSZip from 'jszip';
     <div *ngIf="instance">
         <button nz-button (click)="data.push({})" [nzType]="'primary'">new</button>
         <button nz-button (click)="download()">download</button>
-        <nz-table [nzDataSource]="data" [nzIsPagination]="false">
+        <nz-table [nzDataSource]="data" [nzIsPagination]="false" class="mt-sm">
             <thead nz-thead>
                 <tr>
                 <th nz-th><span>path</span></th>

diff --git a/src/core/abc/zip/index.md b/src/core/abc/zip/index.md
@@ -2,7 +2,7 @@
 title: zip
 subtitle: Zip 操作
 order: 220
-cols: 2
+cols: 1
 module: AdZipModule
 ---
 

diff --git a/src/core/acl/README.md b/src/core/acl/README.md
@@ -1,6 +1,6 @@
 # @delon/acl module
 
-[Document](//ng-alain.com/docs/acl)
+[Document](http://ng-alain.com/docs/acl)
 
 ## Architecture