From 0f6d49238b73f84349d8786b9a095e5ebb40dc86 Mon Sep 17 00:00:00 2001 From: Jeffz Date: Mon, 29 Jan 2024 23:32:16 +0800 Subject: [PATCH] translation: declaration-files/By example.md --- .../zh/declaration-files/By Example.md | 124 +++++++++--------- 1 file changed, 60 insertions(+), 64 deletions(-) diff --git a/docs/documentation/zh/declaration-files/By Example.md b/docs/documentation/zh/declaration-files/By Example.md index 3830965..d359751 100644 --- a/docs/documentation/zh/declaration-files/By Example.md +++ b/docs/documentation/zh/declaration-files/By Example.md @@ -1,24 +1,21 @@ --- -title: Declaration Reference +title: 声明文件参考 layout: docs permalink: /zh/docs/handbook/declaration-files/by-example.html -oneline: "How to create a d.ts file for a module" +oneline: "如何为一个模块创建一个 d.ts 文件" --- -The purpose of this guide is to teach you how to write a high-quality definition file. -This guide is structured by showing documentation for some API, along with sample usage of that API, -and explaining how to write the corresponding declaration. +本指南的目的是教你如何编写高质量的声明文件。本指南通过展示某些 API 的文档、API 的示例用法，并解释如何编写相应的声明。 -These examples are ordered in approximately increasing order of complexity. +这些示例大致按照复杂性递增的顺序排列。 -## Objects with Properties +## 带有属性的对象 -_Documentation_ +_文档_ -> The global variable `myLib` has a function `makeGreeting` for creating greetings, -> and a property `numberOfGreetings` indicating the number of greetings made so far. +> 全局变量`myLib`有一个用于创建问候语的函数`makeGreeting`，以及一个表示到目前为止已经制造的问候语数量的属性`numberOfGreetings`。 -_Code_ +_代码_ ```ts let result = myLib.makeGreeting("hello, world"); @@ -27,9 +24,9 @@ console.log("The computed greeting is:" + result); let count = myLib.numberOfGreetings; ``` -_Declaration_ +_声明_ -Use `declare namespace` to describe types or values accessed by dotted notation. +使用`声明命名空间`来描述通过点符号访问的类型或值。 ```ts declare namespace myLib { @@ -38,13 +35,13 @@ declare namespace myLib { } ``` -## Overloaded Functions +## 重载函数 -_Documentation_ +_文档_ -The `getWidget` function accepts a number and returns a Widget, or accepts a string and returns a Widget array. +`getWidget` 函数接受一个数字并返回一个 Widget，或接受一个字符串并返回一个 Widget 数组。 -_Code_ +_代码_ ```ts let x: Widget = getWidget(43); @@ -52,38 +49,38 @@ let x: Widget = getWidget(43); let arr: Widget[] = getWidget("all of them"); ``` -_Declaration_ +_声明_ ```ts declare function getWidget(n: number): Widget; declare function getWidget(s: string): Widget[]; ``` -## Reusable Types (Interfaces) +## 可复用类型（接口） -_Documentation_ +_文档_ -> When specifying a greeting, you must pass a `GreetingSettings` object. -> This object has the following properties: +> 指定问候语时，你必须传递一个`GreetingSettings`对象。 +> 此对象具有以下属性： > -> 1 - greeting: Mandatory string +> 1 - greeting: 必需的字符串 > -> 2 - duration: Optional length of time (in milliseconds) +> 2 - duration: 可选的持续时间（以毫秒为单位） > -> 3 - color: Optional string, e.g. '#ff00ff' +> 3 - color: 可选的字符串，比如'#ff00ff' -_Code_ +_代码_ ```ts greet({ greeting: "hello world", - duration: 4000 + duration: 4000, }); ``` -_Declaration_ +_声明_ -Use an `interface` to define a type with properties. +使用`interface`来定义具有属性的类型。 ```ts interface GreetingSettings { @@ -95,13 +92,13 @@ interface GreetingSettings { declare function greet(setting: GreetingSettings): void; ``` -## Reusable Types (Type Aliases) +## 可复用类型（类型别名） -_Documentation_ +_文档_ -> Anywhere a greeting is expected, you can provide a `string`, a function returning a `string`, or a `Greeter` instance. +> 任何需要问候语的地方，你都可以提供一个`string`，一个返回`string`的函数，或一个`Greeter`实例。 -_Code_ +_代码_ ```ts function getGreeting() { @@ -114,9 +111,9 @@ greet(getGreeting); greet(new MyGreeter()); ``` -_Declaration_ +_声明_ -You can use a type alias to make a shorthand for a type: +你可以使用类型别名来为一个类型做简写： ```ts type GreetingLike = string | (() => string) | MyGreeter; @@ -124,14 +121,14 @@ type GreetingLike = string | (() => string) | MyGreeter; declare function greet(g: GreetingLike): void; ``` -## Organizing Types +## 组织类型 -_Documentation_ +_文档_ -> The `greeter` object can log to a file or display an alert. -> You can provide LogOptions to `.log(...)` and alert options to `.alert(...)` +> `greeter`对象可以记录到文件或显示警告。 +> 你可以向`.log(...)`提供 LogOptions，向`.alert(...)`提供警报选项 -_Code_ +_代码_ ```ts const g = new Greeter("Hello"); @@ -139,9 +136,9 @@ g.log({ verbose: true }); g.alert({ modal: false, title: "Current Greeting" }); ``` -_Declaration_ +_声明_ -Use namespaces to organize types. +使用命名空间来组织类型。 ```ts declare namespace GreetingLib { @@ -156,7 +153,7 @@ declare namespace GreetingLib { } ``` -You can also create nested namespaces in one declaration: +你还可以在一个声明中创建嵌套命名空间： ```ts declare namespace GreetingLib.Options { @@ -172,13 +169,13 @@ declare namespace GreetingLib.Options { } ``` -## Classes +## 类 -_Documentation_ +_文档_ -> You can create a greeter by instantiating the `Greeter` object, or create a customized greeter by extending from it. +> 你可以通过实例化`Greeter`对象来创建一个问候者，或通过继承它来创建一个定制的问候者。 -_Code_ +_代码_ ```ts const myGreeter = new Greeter("hello, world"); @@ -192,10 +189,10 @@ class SpecialGreeter extends Greeter { } ``` -_Declaration_ +_声明_ -Use `declare class` to describe a class or class-like object. -Classes can have properties and methods as well as a constructor. +使用`declare class`来描述一个类或类似类的对象。 +类可以有属性和方法以及构造函数。 ```ts declare class Greeter { @@ -206,23 +203,23 @@ declare class Greeter { } ``` -## Global Variables +## 全局变量 -_Documentation_ +_文档_ -> The global variable `foo` contains the number of widgets present. +> 全局变量`foo`包含当前存在的小部件数量。 -_Code_ +_代码_ ```ts console.log("Half the number of widgets is " + foo / 2); ``` -_Declaration_ +_声明_ -Use `declare var` to declare variables. -If the variable is read-only, you can use `declare const`. -You can also use `declare let` if the variable is block-scoped. +使用`declare var`来声明变量。 +如果变量是只读的，你可以使用`declare const`。 +如果变量是块作用域的，你也可以使用`declare let`。 ```ts /** The number of widgets present */ @@ -231,21 +228,20 @@ declare var foo: number; ## Global Functions -_Documentation_ +_文档_ -> You can call the function `greet` with a string to show a greeting to the user. +> 你可以用一个字符串调用函数`greet`来向用户显示问候语。 -_Code_ +_代码_ ```ts greet("hello, world"); ``` -_Declaration_ +_声明_ -Use `declare function` to declare functions. +使用`declare function`来声明函数。 ```ts declare function greet(greeting: string): void; ``` -