@abcnews/env-utils 中文文档教程

Question

@abcnews/env-utils

用于识别代码执行环境的各个方面并尊重地与 DOM 交互的实用程序。

您可以识别当前环境的application、generation 和tier（请参阅API 了解什么每一个都是）。

关于我们应该如何以及何时修改 DOM，每一代都有自己的假设。 始终首先请求许可，然后收听该许可被撤销的通知。

Usage

npm i @abcnews/env-utils

假设我们在 Presentation Layer News Web 在我们的预览网站

import {
  getApplication,
  getGeneration,
  getTier,
  requestDOMPermit,
} from '@abcnews/env-utils';

getApplication();
// > 'pln'

getGeneration();
// > 'pl'

getTier();
// > 'preview'

requestDOMPermit('article').then(() => {
  // It is now safe to modify the DOM tree below the <Decoy key="article"> PL compoonent
});

API

APPLICATIONS, GENERATIONS, & TIERS

枚举（命名）应用程序、代和层上呈现的文章中使用此模块； 对论证抽象有用 & 记录。

import { APPLICATIONS, GENERATIONS, TIERS } from '@abcnews/env-utils';

console.log(APPLICATIONS);
// > {
//     P1M: 'p1m', // Phase 1 Mobile
//     P1S: 'p1s', // Phase 1 Standard
//     P2:  'p2',  // Phase 2
//     PLA: 'pla', // Presentation Layer ABC AMP
//     PLC: 'plc', // Presentation Layer Core
//     PLE: 'ple', // Presentation Layer Everyday
//     PLN: 'pln', // Presentation Layer News Web
//   }
console.log(GENERATIONS);
// > {
//     P1: 'p1', // Phase 1
//     P2: 'p2', // Phase 2
//     PL: 'pl', // Presentation Layer
//   }
console.log(TIERS);
// > {
//     LIVE: 'live',
//     PREVIEW: 'preview',
//   }

getApplication(): string | null

返回环境的应用程序（Phase 1 Mobile；Phase 1 Standard；Phase 2；Presentation Layer ABC AMP；Presentation Layer Core；Presentation Layer Everyday；Presentation Layer News Web）作为 中的字符串值APPLICATIONS 枚举，如果无法确定应用程序，则为 null。

import { APPLICATIONS, getApplication } from '@abcnews/env-utils';

getApplication();
// > 'pln'

getApplication() === APPLICATIONS.PLN;
// > true

应用程序目前由在文档中选择 DOM 节点的成功/失败决定，这暗示了用于在服务器上呈现它们的技术。

getGeneration(): string | null

从 GENERATIONS 枚举中返回环境的 generation（Phase 1；Phase 2；Presentation Layer）作为字符串值，如果生成不能，则返回 null下定决心。

import { GENERATIONS, getGeneration } from '@abcnews/env-utils';

getGeneration();
// > 'pl'

getGeneration() === GENERATIONS.PL;
// > true

当前通过对检测到的应用程序进行分类来确定世代。

getTier(): string | null

返回环境的 tier（实时；预览）作为 TIERS 枚举中的字符串值，如果无法确定层，则返回 null。

import { TIERS, getTier } from '@abcnews/env-utils';

getTier();
// > 'preview'

getTier() === TIERS.PREVIEW;
// > true

目前，层级是通过将 window.location.hostname 与可能提供层级的域进行比较来确定的。

requestDOMPermit(key: string, onRevokeHandler?: Function): Promise<true|HTMLElement[]>

请求修改 DOM 的许可。

建议在修改表示层生成应用程序上的 DOM 之前这样做（因为它们由 React 控制，并且几乎肯定会撤消您自己的更改）。

DOM 修改在老一代应用程序上通常是安全的，但为了一致性，无论如何都应该请求许可。

表示层使用 key 参数来激活其各自的 组件。

可以传递可选的 onRevokeHandler 参数，如果表示层选择停用 并恢复其原始 DOM，将调用该参数。

注意：key 值可以是任何 [az] 字符串，但是 Presentation Layer News Web 应用程序提供了几个预先确定的值，该库公开为 DECOY_KEYS< /代码>。

import { DECOY_KEYS, requestDOMPermit } from '@abcnews/env-utils';

requestDOMPermit(DECOY_KEYS.PAGE, () => {
  // It is no longer safe to modify the DOM tree below <Decoy listenKey="page"> PL compoonents
}).then(() => {
  // It is now safe to modify the DOM tree below <Decoy listenKey="page"> PL compoonents
});

返回的承诺根据其运行的 GENERATION 进行不同的解析。 在表示层站点上，promise 将使用激活诱饵的所有节点的 HTMLElement 引用数组来解析。 在前几代中，它将解析为 true。

如果所有预期的诱饵都没有被激活，承诺将在 5 秒后被拒绝。 此外，库将尝试通过向 PL 发送另一个请求以使用给定密钥停用诱饵来撤消任何成功的激活。

whenDOMReady(): Promise<void>

在 DOM 准备就绪时解析的承诺。 在表示层文档上，DOM 直到 React 树重新水合后才被视为准备就绪。

whenOdysseyLoaded(): Promise<window.__ODYSSEY__>

当 Odyssey 完成加载时解决的承诺。 这将通过引用 Odyssey API 来解决。

Development

此 repo 使用 tsdx 进行开发，使用 np 进行发布。

你需要的一切都应该在 npm 脚本中：

npm start
npm test
npm run release

运行测试需要设置一些环境变量。 这些环境变量的规范版本作为秘密存储在 GitHub 中，但如果您需要它们在本地运行测试，请与下面列出的作者之一聊天。

Authors

• Colin Gourlay (Gourlay.Colin@abc.net.au)
• Simon Elvery (elvery.simon@abc.net.au)