填寫這份《一分鐘調查》,幫我們(開發組)做得更好!去填寫Home

使用已發佈的函式庫

Using published libraries

當建構 Angular 應用時,你可以從精緻的第一方函式庫,比如 Angular Material,以及豐富的第三方函式庫生態系統中獲益。參閱 Angular 資源集頁面,瞭解最常用的函式庫連結。

When building Angular applications you can take advantage of sophisticated first-party libraries, such as Angular Material, as well as rich ecosystem of third-party libraries. See the Angular Resources page for links to the most popular ones.

安裝函式庫

Installing libraries

這些函式庫都是作為 npm 套件發佈的,它們通常都帶有一些與 Angular CLI 整合好的 schematic。要把可複用的函式庫程式碼整合到應用中,你需要安裝該軟體包並在使用時匯入它提供的功能。對於大多數已發佈的 Angular 函式庫,你可以使用 Angular CLI 的 ng add <lib_name> 命令。

Libraries are published as npm packages, usually together with schematics that integrate them with the Angular CLI. To integrate reusable library code into an application, you need to install the package and import the provided functionality where you will use it. For most published Angular libraries, you can use the Angular CLI ng add <lib_name> command.

ng add 命令使用 npm 套件管理器或 yarn 來安裝函式庫套件,並呼叫該套件中的 schematic 在專案程式碼中的新增腳手架,比如新增 import 語句、新增 fonts,新增 themes 等。

The ng add command uses a package manager such as npm or yarn to install the library package, and invokes schematics that are included in the package to other scaffolding within the project code, such as adding import statements, fonts, themes, and so on.

已發佈的函式庫通常會提供 README 或者其它文件來介紹如何把該函式庫新增到你的應用中。例子可參閱 Angular Material 文件。

A published library typically provides a README or other documentation on how to add that lib to your app. For an example, see Angular Material docs.

函式庫的型別

Library typings

函式庫套件中通常會在 .d.ts 檔案中包含型別資訊。參閱 node_modules/@angular/material 中的例子。如果你的函式庫套件中沒有包含型別資訊並且你的 IDE 報錯,你可能需要安裝與這個函式庫關聯的 @types/<lib_name> 套件。

Library packages often include typings in .d.ts files; see examples in node_modules/@angular/material. If your library's package does not include typings and your IDE complains, you may need to install the library's associated @types/<lib_name> package.

比如,假設你有一個名為 d3 的函式庫:

For example, suppose you have a library named d3:

      
      npm install d3 --save
npm install @types/d3 --save-dev
    

已安裝到工作區中的 @types/ 套件中所定義的型別,會自動新增到使用該函式庫的專案的 TypeScript 配置檔案中。TypeScript 預設就會在 node_modules/@types 資料夾中查詢型別,所以你不必單獨新增每一個型別套件。

Types defined in a @types/ package for a library installed into the workspace are automatically added to the TypeScript configuration for the project that uses that library. TypeScript looks for types in the node_modules/@types folder by default, so you don't have to add each type package individually.

如果某個函式庫沒有 @types/ 型別資訊,你仍然可以手動為它新增一些型別資訊。為此你要:

If a library doesn't have typings available at @types/, you can still use it by manually adding typings for it. To do this:

  1. src/ 資料夾中建立一個 typings.d.ts 檔案。該檔案會自動包含在全域性型別定義中。

    Create a typings.d.ts file in your src/ folder. This file is automatically included as global type definition.

  2. src/typings.d.ts 中新增如下程式碼。

    Add the following code in src/typings.d.ts:

      
      declare module 'host' {
  export interface Host {
    protocol?: string;
    hostname?: string;
    pathname?: string;
  }
  export function parse(url: string, queryString?: string): Host;
}
    
  1. 在使用該函式庫的元件或檔案中,新增如下程式碼。

    In the component or file that uses the library, add the following code:

      
      import * as host from 'host';
const parsedUrl = host.parse('https://angular.io');
console.log(parsedUrl.hostname);
    

你可以按需定義更多型別。

You can define more typings as needed.

更新這些函式庫

Updating libraries

函式庫的發佈者可以對這些函式庫進行更新,而這些函式庫也有自己的依賴,所有依賴都需要保持最新。要檢查已安裝函式庫的更新,請使用 ng update 命令

Libraries can be updated by their publishers, and also have their own dependencies which need to be kept current. To check for updates to your installed libraries, use the ng update command.

使用 ng update <lib_name> 來單獨更新某個函式庫的版本。Angular CLI 會檢查函式庫中最新發布的版本,如果最新版本比你已安裝的版本新,就會下載它並更新你的 package.json 以匹配最新版本。

Use ng update <lib_name> to update individual library versions. The Angular CLI checks the latest published release of the library, and if the latest version is newer than your installed version, downloads it and updates your package.json to match the latest version.

當把 Angular 更新到新版本時,你需要確保所用的函式庫都是最新的。如果函式庫之間相互依賴,你可能還要按特定的順序更新它們。請參閱 Angular 升級指南以獲取幫助。

When you update Angular to a new version, you need to make sure that any libraries you are using are current. If libraries have interdependencies, you might have to update them in a particular order. See the Angular Update Guide for help.

把某個函式庫新增到執行時的全域性範圍中

Adding a library to the runtime global scope

那些沒有匯入到應用中的舊版 JavaScript 函式庫可以新增到執行時的全域性作用域中,並像在 script 標籤中一樣載入。可以在 CLI 配置檔案 angular.json 中的建構目標(build target)的 "scripts" 和 "styles" 選項中配置 CLI,以便在建構期間新增這些檔案。

Legacy JavaScript libraries that are not imported into an app can be added to the runtime global scope and loaded as if they were in a script tag. Configure the CLI to do this at build time using the "scripts" and "styles" options of the build target in the CLI configuration file, angular.json.

例如,要使用 Bootstrap 4,首先就要使用 npm 套件管理器來安裝該函式庫及其依賴:

For example, to use the Bootstrap 4 library, first install the library and its dependencies using the npm package manager:

      
      npm install jquery --save
npm install popper.js --save
npm install bootstrap --save
    

angular.json 配置檔案中,把關聯的指令碼檔案新增到 "scripts" 陣列中:

In the angular.json configuration file, add the associated script files to the "scripts" array:

      
      "scripts": [
  "node_modules/jquery/dist/jquery.slim.js",
  "node_modules/popper.js/dist/umd/popper.js",
  "node_modules/bootstrap/dist/js/bootstrap.js"
],
    

把 Bootstrap 的 CSS 檔案新增到 "styles" 陣列中:

Add the Bootstrap CSS file to the "styles" array:

      
      "styles": [
  "node_modules/bootstrap/dist/css/bootstrap.css",
  "src/styles.css"
],
    

執行或重啟 ng serve,看看你的應用是否正在使用 Bootstrap 4。

Run or restart ng serve to see Bootstrap 4 working in your app.

在你的應用中使用執行時全域性函式庫

Using runtime-global libraries inside your app

當你用 "scripts" 陣列匯入一個函式庫後,就不應該在你的 TypeScript 程式碼中再用 import 語句來匯入它了(比如:import * as $ from 'jquery';)。如果你這樣做,就會得到該函式庫兩個不同的副本:一個作為全域性函式庫匯入,另一個作為模組匯入。這對於那些帶有外掛的函式庫來說特別糟糕,比如 JQuery,因為每個副本都會有不同的外掛。

Once you import a library using the "scripts" array, you should not import it using an import statement in your TypeScript code (such as import * as $ from 'jquery';). If you do, you'll end up with two different copies of the library: one imported as a global library, and one imported as a module. This is especially bad for libraries with plugins, like JQuery, because each copy will have different plugins.

相反,為你的函式庫下載型別資訊(npm install @types/jquery),並按照函式庫的安裝步驟進行操作。這讓你可以訪問該函式庫暴露出來的全域性變數。

Instead, download typings for your library (npm install @types/jquery) and follow the library installation steps. This gives you access to the global variables exposed by that library.

定義執行時全域性函式庫的型別資訊

Defining typings for runtime-global libraries

如果你要用的全域性函式庫沒有全域性型別資訊,就可以在 src/typings.d.ts 中手動宣告它們。例如:

If the global library you need to use does not have global typings, you can declare them manually as any in src/typings.d.ts. For example:

      
      declare var libraryName: any;
    

有些指令碼擴充套件了其它函式庫,例如 JQuery 外掛:

Some scripts extend other libraries; for instance with JQuery plugins:

      
      $('.test').myPlugin();
    

在這種情況下,所安裝的 @types/jquery 就不包含 myPlugin,所以你需要在 src/typings.d.ts 中新增一個介面。例如:

In this case, the installed @types/jquery doesn't include myPlugin, so you need to add an interface in src/typings.d.ts. For example:

      
      interface JQuery {
  myPlugin(options?: any): any;
}
    

如果不為這個由指令碼定義的擴充套件新增介面,IDE 就會顯示錯誤:

If you don't add the interface for the script-defined extension, your IDE shows an error:

      
      [TS][Error] Property 'myPlugin' does not exist on type 'JQuery'