此篇介紹的 API 依序為：

• json-utils
  • appendPropertyInAstObject
  • insertPropertyInAstObjectInOrder
  • removePropertyInAstObject
  • appendValueInAstArray
  • findPropertyInAstObject
• dependencies
  • NodeDependencyType
  • NodeDependency
  • addPackageJsonDependency
  • removePackageJsonDependency
  • getPackageJsonDependency
• config
  • AppConfig
  • CliConfig
  • getWorkspacePath
  • getWorkspace
  • addProjectToWorkspace
  • updateWorkspace
  • configPath
  • getConfig
  • getAppFromConfig
• project
  • buildDefaultPath
  • getProject
  • isWorkspaceSchema
  • isWorkspaceProject
• project-targets
  • getProjectTargets
  • targetBuildNotFoundError

json-utils

看名字就知道這裡都是關於 JSON 操作的小工具。

引入路徑：

import { 
  appendPropertyInAstObject,
  insertPropertyInAstObjectInOrder,
  removePropertyInAstObject,
  appendValueInAstArray,
  findPropertyInAstObject
} from '@schematics/angular/utility/json-utils';

appendPropertyInAstObject

用途：使用傳入的UpdateRecorder 、 欲新增屬性的 JSON 的節點、 屬性名稱、 該屬性的值與縮排空格數來新增屬性到 JSON 裡。

回傳值：無。

用法：

const filePath = '/test.json';
const indent = 4;
const content = JSON.stringify({ gender: 'male', a: 'chen' }, null, indent);

_tree.create(filePath, content);
const ast = parseJsonAst(content) as JsonAstObject;
const rec = _tree.beginUpdate(filePath);
appendPropertyInAstObject(rec, ast, 'e', 'Leo', indent);
_tree.commitUpdate(rec);

console.log(_tree.read(filePath)!.toString());
/*
{
    "gender": "male",
    "a": "chen",
    "e": "Leo"
}
*/

原始碼

測試原始碼

insertPropertyInAstObjectInOrder

用途：基本上跟 appendPropertyInAstObject 一模一樣，只差在 appendPropertyInAstObject 會直接加到最後一個屬性，而 insertPropertyInAstObjectInOrder 會從尾巴開始找，然後按照找到的屬性名稱的字母順序插入。

回傳值：無。

用法：

const filePath = '/test.json';
const indent = 4;
const content = JSON.stringify({ gender: 'male', a: 'chen' }, null, indent);

_tree.create(filePath, content);
const ast = parseJsonAst(content) as JsonAstObject;
const rec = _tree.beginUpdate(filePath);
insertPropertyInAstObjectInOrder(rec, ast, 'e', 'Leo', indent);
_tree.commitUpdate(rec);

console.log(_tree.read(filePath)!.toString());
/*
{
    "e": "Leo",
    "gender": "male",
    "a": "chen"
}
*/

原始碼

測試原始碼

removePropertyInAstObject

用途：使用傳入的UpdateRecorder 、 欲移除屬性的 JSON 的節點與屬性名稱來移除屬性。

回傳值：無。

用法：

const filePath = '/test.json';
const indent = 4;
const content = JSON.stringify({ gender: 'male', a: 'chen' }, null, indent);

_tree.create(filePath, content);
const ast = parseJsonAst(content) as JsonAstObject;
const rec = _tree.beginUpdate(filePath);
removePropertyInAstObject(rec, ast, 'a');
_tree.commitUpdate(rec);

console.log(_tree.read(filePath)!.toString());
/*
{
    "gender": "male"
}
*/

原始碼

測試原始碼

appendValueInAstArray

用途：使用傳入的UpdateRecorder 、 欲加入值的 JSON 陣列的節點、欲加入的值與縮排空格數（非必要）來將值加入到 JSON 陣列裡。

回傳值：無。

用法：

const filePath = '/test.json';
const indent = 2;
const content = JSON.stringify([], null, indent);

_tree.create(filePath, content);
const ast = parseJsonAst(content) as JsonAstArray;
const rec = _tree.beginUpdate(filePath);
appendValueInAstArray(rec, ast, 'a', indent);
_tree.commitUpdate(rec);

console.log(_tree.read(filePath)!.toString());
/*
[
  "a"
]
*/

原始碼

測試原始碼

findPropertyInAstObject

用途：使用傳入的 ** JSON 物件的節點與欲尋找的屬性名稱**來找出該屬性的值的資料節點。

回傳值：有找到時，回傳該屬性的值的 JSON 資料節點；沒有找到時則回傳 null 。

用法：

const filePath = '/test.json';
const content = JSON.stringify({ gender: 'male' }, null);

_tree.create(filePath, content);
const ast = parseJsonAst(content) as JsonAstObject;

console.log(findPropertyInAstObject(ast, 'gender'));
/*
{
  kind: 'string',
  start: { offset: 10, line: 0, character: 10 },
  end: { offset: 16, line: 0, character: 16 },
  text: '"male"',
  value: 'male',
  comments: []
}
*/

原始碼

dependencies

關於操作 package.json 裡，相依性套件操作小工具。

引入路徑：

import { 
  NodeDependencyType,
  NodeDependency,
  addPackageJsonDependency,
  removePackageJsonDependency,
  getPackageJsonDependency
} from '@schematics/angular/utility/dependencies';

NodeDependencyType

用途： NodeDependencyType 是個列舉，定義所有相依性套件的依賴類型。

類型與相對應的屬性名稱如下所示：

enum NodeDependencyType {
  Default = 'dependencies',
  Dev = 'devDependencies',
  Peer = 'peerDependencies',
  Optional = 'optionalDependencies',
}

原始碼

NodeDependency

用途： NodeDependency 定義了相依性套件的資料節點應該要有的資料介面。

如下所示：

interface NodeDependency {
  type: NodeDependencyType;
  name: string;
  version: string;
  overwrite?: boolean;
}

原始碼

addPackageJsonDependency

用途：使用傳入的檔案樹與欲新增的相依性套件的資料節點來將該節點加入到 package.json 裡。

回傳值：無。

用法：

const pkgJsonPath = '/package.json';
const dependency: NodeDependency = {
  type: NodeDependencyType.Default,
  name: 'my-pkg',
  version: '1.2.3',
};

const testTree = new EmptyTree();
testTree.create(pkgJsonPath, '{}');
addPackageJsonDependency(testTree, dependency);

console.log(JSON.parse(testTree.read(pkgJsonPath)!.toString()));
/*
{ dependencies: { 'my-pkg': '1.2.3' } }
*/

原始碼

測試原始碼

removePackageJsonDependency

用途：使用傳入的檔案樹與欲刪除的相依性套件名稱來將該套件從 package.json 裡移除。

回傳值：無。

用法：

const pkgJsonPath = '/package.json';
const testTree = new EmptyTree();
const content = JSON.stringify({ dependencies: { 'my-pkg': '1.2.3' } });

testTree.create(pkgJsonPath, content);
removePackageJsonDependency(testTree, 'my-pkg');

console.log(JSON.parse(testTree.read(pkgJsonPath)!.toString()));
/*
{ dependencies: {} }
*/

原始碼

getPackageJsonDependency

用途：使用傳入的檔案樹與欲取得的相依性套件的名稱來從 package.json 裡取得該相依性套件的節點資料。

回傳值：有找到時，回傳該相依性套件的資料節點；沒有找到時則回傳 null 。

用法：

const pkgJsonPath = '/package.json';
const testTree = new EmptyTree();
const content = JSON.stringify({ dependencies: { 'my-pkg': '1.2.3' } });

testTree.create(pkgJsonPath, content);

console.log(getPackageJsonDependency(testTree, 'my-pkg'));
/*
{ type: 'dependencies', name: 'my-pkg', version: '1.2.3' }
*/

原始碼

測試原始碼

config

關於 Angular 專案相關的配置定義與小工具。

引入路徑：

import { 
  AppConfig,
  CliConfig,
  getWorkspacePath,
  getWorkspace,
  addProjectToWorkspace,
  updateWorkspace,
  configPath,
  getConfig,
  getAppFromConfig
} from '@schematics/angular/utility/config';

AppConfig

用途： AppConfig 定義了舊版 .angular-cli.json 的 apps 陣列裡的配置的資料介面。

由於程式碼太長，詳細請直接參閱原始碼

CliConfig

用途： CliConfig 定義了舊版 .angular-cli.json 整個 JSON 的資料介面。

由於程式碼太長，詳細請直接參閱原始碼

getWorkspacePath

用途：使用傳入的檔案樹取得 /angular.json 或是 /.angular.json 這兩個路徑其中之一（檔案樹裡有誰就回傳誰）。

回傳值：/angular.json 或是 /.angular.json 這兩個路徑其中之一 ，都沒有則回傳 undefined 。

用法：

const pkgJsonPath = '/angular.json';
const testTree = new EmptyTree();

testTree.create(pkgJsonPath, '{}');

console.log(getWorkspacePath(testTree)); // '/angular.json'

原始碼

getWorkspace

用途：使用傳入的檔案樹取得 /angular.json 或是 /.angular.json 這兩個路徑其中之一（檔案樹裡有誰就回傳誰）的資料。

回傳值： JSON 格式的資料， WorkspaceSchema 定義了這個資料的資料介面（後面會介紹到）。

用法：

getWorkspace(tree);

原始碼

addProjectToWorkspace

用途：用傳入專案名稱與專案資料加入到傳入的專案配置裡。

回傳值： Rule。

用法：

addProjectToWorkspace(workspace, name, project);

原始碼

updateWorkspace

用途：覆寫 /angular.json 或是 /.angular.json 這兩個路徑其中之一的檔案的資料。

回傳值： Rule。

用法：

updateWorkspace(workspace);

原始碼

configPath

用途：常數，定義舊版的 .angular-cli.json 的檔名含路徑。

如下所示：

const configPath = '/.angular-cli.json';

原始碼

getConfig

用途：根據傳入的檔案樹找到舊版的 .angular-cli.json 的配置資料。

回傳值： CliConfig ， .angular-cli.json 的配置資料。

用法：

getConfig(tree);

原始碼

getAppFromConfig

用途：根據傳入的舊版 Angular 專案配置與應用的名稱或路徑舊版的應用配置資料。

回傳值：有找到回傳 AppConfig ，舊版的應用配置資料；沒找到則回傳 null 。

用法：

getAppFromConfig(config, 'appName');

原始碼

project

關於 Angular 應用相關的小工具。

引入路徑：

import { 
  buildDefaultPath,
  getProject,
  isWorkspaceSchema,
  isWorkspaceProject
} from '@schematics/angular/utility/project';

buildDefaultPath

用途：根據傳入的 Angular 應用配置來取得該應用的路徑。

回傳值：該應用的路徑字串。

用法：

const project: WorkspaceProject = {
  projectType: ProjectType.Application,
  root: 'foo',
  prefix: 'app',
};

buildDefaultPath(project); // '/foo/src/app'

原始碼

測試原始碼

getProject

用途：根據傳入的檔案樹或者是專案配置與應用名稱來取得該應用的配置資料。

回傳值：該應用的配置資料。

用法：

getProject(tree, 'app');

原始碼

isWorkspaceSchema

用途：根據傳入的資料來判斷該資料是否為 Angular 專案的配置資料。

回傳值： true 或 false 。

用法：

isWorkspaceSchema({});

原始碼

isWorkspaceProject

用途：根據傳入的資料來判斷該資料是否為 Angular 應用的配置資料。

回傳值： true 或 false 。

用法：

isWorkspaceProject({});

原始碼

project-targets

關於取得 Angular 應用配置裡的 targets 或是 architect 的資料的小工具。

引入路徑：

import { 
  getProjectTargets,
  targetBuildNotFoundError
} from '@schematics/angular/utility/project-targets';

getProjectTargets

用途：根據傳入的檔案樹或是使用 Angular 專案的配置資料、 Angular 應用的配置資料與應用名稱來取得 Angular 應用配置裡的 targets 或是 architect 的資料

回傳值：有取得的話會回傳 Angular 應用配置裡的 targets 或是 architect 的資料，否則會拋出錯誤 。

用法：

getProjectTargets({});

// 或是

getProjectTargets({}, 'appName');

原始碼

targetBuildNotFoundError

用途：直接取得沒有找到對應資料的錯誤

回傳值：沒有找到對應資料的錯誤。

用法：

targetBuildNotFoundError();

原始碼

本日結語

不知道大家有沒有發現，今天筆者介紹的都是專案配置類型的 API ？！

參考資料

• Source Code