跟踪

Trace 类是 console 日志记录的有效替代方案，它提供了以下优点

• 控制日志消息类别到控制台
• 一次性禁用多个消息日志记录
• 定义自定义错误处理

使用 Trace ​

以下步骤概述了 Trace 类的基本用法。步骤 1 和 2 应该在应用程序的早期执行，通常在 app.ts 文件中。

1. 指定一个或多个类别作为跟踪对象，以逗号分隔的列表形式

   ts

   // Use a single category only.
   Trace.setCategories('category')
   // Or, add multiple categories.
   Trace.addCategories('categ1, categ2')
   // Or, combine the default Trace categories with your own additional categories.
   Trace.setCategories(Trace.categories.concat('category1', 'category2'))

   在编写跟踪消息时，如果您没有设置类别，或者您传递给 Trace.write() 的类别之前没有使用上述命令添加，则该消息将不会被写入。

2. 在您的应用程序中启用跟踪

   ts

   Trace.enable()

3. 在您的应用程序中，您可以使用 Trace.write() 来记录消息，而不是使用 console.log()。

   ts

   // Add a trace message
   Trace.write('This is a simple message', 'category')
   // Add a trace message with a given message type
   Trace.write('This is an error message', 'category2', Trace.messageType.error)

4. 当您的应用程序处于生产环境中时，您现在可以简单地禁用跟踪，所有 Trace.write() 调用都将被忽略。

   ts

   if (!__DEV__) {
     Trace.disable()
   }

创建自定义 Trace 编写器 ​

默认情况下，Trace 消息将被写入控制台日志，类似于使用 console.log()。通过编写自定义 Trace 编写器，您可以控制控制台日志的输出，或将消息路由到另一个系统。

Trace 编写器实例必须指定一个 write 方法，该方法接受三个参数 - 消息、类别和（可选）消息类型。

const TimestampTraceWriter: TraceWriter = {
  write(message, category, type) {
    const now = new Date()
    const timestamp = now.toTimeString().substr(0, 8)

    switch (type) {
      case Trace.messageType.error:
        console.log(`${timestamp} [${category}] (error) ${message}`)
        return
      case Trace.messageType.warn:
        console.log(`${timestamp} [${category}] (warn) ${message}`)
        return
      case Trace.messageType.info:
        console.log(`${timestamp} [${category}] (info) ${message}`)
        return
      default:
        console.log(`${timestamp} [${category}] ${message}`)
        return
    }
  },
}

注册自定义 Trace 编写器 ​

要使用自定义 Trace 编写器实例，您需要使用 Trace.addWriter() 方法将其注册到 Trace 模块中。这样可以确保您的自定义编写器被识别并合并到 Trace 功能中。

如果您希望禁用 NativeScript 中包含的默认 Trace 编写器，您还应该首先使用 Trace.clearWriters() 方法来取消注册它们。

Trace.clearWriters()
Trace.addWriter(TimestampTraceWriter)

错误处理 ​

Trace 模块允许创建自定义错误处理程序。您应该在 main.ts 文件中注册您的错误处理程序，并使用 Trace.setErrorHandler() 设置它，并将错误使用 Trace.error() 传递给它。

const errorHandler: TraceErrorHandler = {
  handlerError(err) {
    // Option 1 (development) - throw the error
    throw err

    // Option 2 (development) - logging the error via write method provided from trace module
    Trace.write(err, 'unhandled-error', type.error)

    // (production) - custom functionality for error handling
    reportToAnalytics(err)
  },
}

// Register errorHandler
Trace.setErrorHandler(errorHandler)

Trace API ​

addCategories 和 setCategories ​

// Only allow the defined categories
Trace.setCategories(categories: string)

// Add the defined categories to the available existing categories
Trace.addCategories(categories: string)

设置或添加到 Trace 模块将跟踪的类别。categories 是一个以逗号分隔的类别列表，表示为字符串。

addWriter ​

Trace.addWriter(writer: TraceWriter)

将 TraceWriter 实例添加到跟踪模块中。

clearWriters ​

Trace.clearWriters()

清除跟踪模块中的所有编写器。在添加自定义跟踪编写器之前调用此方法，以避免预先注册的编写器干扰它。

disable ​

Trace.disable()

禁用跟踪。

enable ​

Trace.enable()

启用跟踪。

error ​

Trace.error(error: string | Error)

将错误传递给已注册的 TraceErrorHandler。

getErrorHandler ​

Trace.getErrorHandler()

获取已注册的 TraceErrorHandler。

setErrorHandler ​

Trace.setErrorHandler(handler: TraceErrorHandler)

注册错误处理程序。

isCategorySet ​

Trace.isCategorySet(category: string)

检查跟踪模块中是否已设置类别。

isEnabled() ​

Trace.isEnabled()

返回一个 boolean 值，表示跟踪是否已启用。

notifyEvent ​

Trace.notifyEvent(object: Object, name: string, data?: any)

通知发送方对象中发生的事件的所有已附加侦听器。

removeWriter ​

Trace.removeWriter(writer: TraceWriter)

从跟踪模块中删除 TraceWriter 实例。

write ​

Trace.write(message: any, category: string, type?: number)

使用可用编写器写入消息。您必须指定已添加到 Trace 模块的类别，才能将其写入。

您可以选择提供一个类型来指示严重程度。

API 参考 ​