使用分支

概述

gt-next 中的分支组件能够根据特定条件动态渲染内容。这些组件包括：

<Branch>：根据匹配的 branch 属性渲染内容。
<Plural>：根据给定数字的复数规则渲染内容。

这两个组件为本地化应用中的条件逻辑和动态内容管理提供了强大的工具。

在本指南中，我们将介绍：

什么是分支组件？

如何使用分支组件

何时使用分支组件

示例

常见陷阱

什么是分支组件？

分支组件会根据特定的条件或数值动态选择要渲染的内容。

`<Branch>`

<Branch> 组件允许你根据提供的 branch 值渲染不同的内容。如果没有找到匹配的分支，则会渲染备用的 children 内容。

例如，<Branch> 组件非常适合根据应用状态、用户偏好或任何动态数据进行条件渲染。

最常见的用法是用它来替代三元或条件运算符。

`<Plural>`

<Plural> 组件通过自动处理复数和数字一致性，扩展了 <Branch> 的功能。它会根据提供的 n 值和本地化规则，自动判断显示哪种复数形式。

例如，<Plural> 组件非常适合动态渲染单数和复数文本，比如 “1 item” 和 “2 items”。

复数组件通常会与 <Num> 组件结合使用，以本地化数字及其对应的文本。

与 `<T>` 搭配使用

<Branch> 和 <Plural> 组件应当在 <T> 组件内部使用，以便对动态内容进行翻译和安全处理。

当它们在 <T> 组件内部使用时，内容会自动被翻译并以用户选择的语言渲染。

如果单独使用，它们只会按原样渲染内容，不会进行翻译。

如何使用分支组件

使用 `<Branch>` 进行分支逻辑

<Branch> 组件用于根据 branch 值灵活切换内容。

你可以定义多个可能的分支，组件会渲染与匹配分支键对应的内容。

此外，你还可以将其他变量组件与 <Branch> 组件结合使用。

const branch: 'option1' | 'option2' = 'option1';
<T>
  <Branch 
    branch={branch}
    option1={<p>Option 1</p>}
    option2={<p>Option 2</p>}
  >
    Fallback content
  </Branch>
</T>

<Branch> 组件应当在 <T> 组件内部使用。这样可以让内容自动翻译。

查看更多详情，请参阅 API 参考。

使用 `<Plural>` 进行复数处理

<Plural> 组件会根据 n 的值自动处理复数逻辑。该组件会根据给定的数字和语言环境动态选择合适的复数形式。

const count: number = 1;
<T>
  <Plural
    n={count}
    singular={<><Num>{1}</Num> item.</>}
    plural={<><Num>{count}</Num> items.</>}
    // Additional options
    zero={<><Num>{count}</Num> items.</>}
    one={<><Num>{count}</Num> item.</>}
    two={<><Num>{count}</Num> items.</>}
    few={<><Num>{count}</Num> items.</>}
    many={<><Num>{count}</Num> items.</>}
    other={<><Num>{count}</Num> items.</>}
    dual={<><Num>{count}</Num> items.</>}
  />
</T>

可用的复数形式取决于语言环境，并遵循 Unicode CLDR 复数规则。

查看更多详情，请参阅 API 参考。

何时使用分支组件

分支组件对于管理应用中的动态内容非常重要。

当你需要根据某个条件显示不同内容时，请使用 <Branch>。

这些条件可以基于变量组件、布尔值或函数。

例如，如果你的代码中有三元运算符或条件渲染，你可以用 <Branch> 来替代它。

const isActive = true;
// Ternary operator
<Branch branch={isActive} true={<p>The user is active.</p>} false={<p>The user is inactive.</p>}>
  <p>Status unknown.</p>
</Branch>

// Conditional rendering
<Branch branch={isActive} true={<p>The user is active.</p>}>
  <></>
</Branch>

// Ternary operator
const isActive = true;
{isActive ? <p>The user is active.</p> : <p>The user is inactive.</p>}

// Conditional rendering
{isActive && <p>The user is active.</p>}

如果你想根据数量正确地渲染内容的复数形式，请使用 <Plural>。

const count = 1;
<Plural n={count} one={<p>1 item</p>} other={<p>{count} items</p>} />

const count = 1;
{count === 1 ? <p>1 item</p> : <p>{count} items</p>}

<Branch> 和 <Plural> 组件可以单独使用，无需 <T> 组件。单独使用时，它们会直接渲染内容，不会进行翻译。

不过，它们通常会在 <T> 组件中使用，以便对动态内容进行翻译前的处理。

示例

`<Branch>`

import { T, Branch, Var } from 'gt-next';

export default function UserStatus() {
  const [status, setStatus] = useState<'active' | 'inactive' | undefined>(undefined);
  const [name, setName] = useState<string>('John Doe');
  return (
    <T>
      <Branch
        branch={status}
        active={<p>The user <Var>{name}</Var> is active.</p>}
        inactive={<p>The user <Var>{name}</Var> is inactive.</p>}
      >
        <p>Status unknown.</p>
      </Branch>
    </T>
  );
}

在上面的示例中，<Branch> 组件会根据 status 的值动态切换渲染三种内容。

当 status 为 "active" 时，组件渲染：

<p>The user <Var>{name}</Var> is active.</p>

当 status 为 "inactive" 时，组件渲染：

<p>The user <Var>{name}</Var> is inactive.</p>

当 status 既不是 "active" 也不是 "inactive" 时，组件渲染备用内容：

<p>Status unknown.</p>

由于 <Branch> 组件被包裹在 <T> 组件中，渲染的内容会自动根据上下文进行翻译。

在这个例子中，会根据用户的订阅方案显示不同的描述。

import { Branch } from 'gt-next';

export default function SubscriptionDetails() {
  const [plan, setPlan] = useState<'free' | 'premium' | 'enterprise' | undefined>(undefined);
  return (
    <Branch
      branch={plan}
      free={<p>You are on the Free plan. Upgrade to unlock more features!</p>}
      premium={<p>You are enjoying the Premium plan with full access to features.</p>}
      enterprise={<p>You are on the Enterprise plan. Contact support for tailored solutions.</p>}
    >
      <p>No subscription plan detected.</p>
    </Branch>
  );
}

branch 属性决定显示哪个方案的提示信息。
如果 plan 是 "free"、"premium" 或 "enterprise"，则会显示对应的信息。
如果 plan 不匹配上述任意值，则会显示备用内容（"No subscription plan detected."）。

`<Plural>`

<Plural> 组件会根据 n 的值动态处理单数和复数内容。此示例会显示用户收件箱中的未读消息数量。

import { T, Plural, Num } from 'gt-next';

export default function UnreadMessages() {
  const [unreadCount, setUnreadCount] = useState<number>(1);
  return (
    <T>
      <Plural
        n={unreadCount}
        one={<>You have <Num>{unreadCount}</Num> unread message.</>}
        other={<>You have <Num>{unreadCount}</Num> unread messages.</>}
      />
    </T>
  );
}

n 属性指定未读消息的数量。
如果 unreadCount 为 1，组件渲染："You have 1 unread message."
其他情况下，渲染："You have X unread messages."，其中 X 是由 <Num> 格式化的 unreadCount 的值。

常见陷阱

缺少分支值

如果未提供分支值或分支值未匹配到任何键，<Branch> 组件将会渲染备用子内容。请始终确保所有可能的分支键与传递给 branch 属性的值相匹配。

import { Branch } from 'gt-next';

export default function StatusMessage({ status }) {
  return (
    <Branch
      branch={status}
      active={<p>The user is active.</p>}
      inactive={<p>The user is inactive.</p>}
    >
      <p>Status unknown.</p>
    </Branch>
  );
}

如果 status 是 undefined 或者不是 active 或 inactive，则会显示备用内容 “Status unknown.”。

缺少复数形式

请记得在默认语言中指定所有必要的复数形式。这样，gt-next 可以确保你的应用始终有备用内容可供显示。

例如，如果英语是你的默认语言，你应当为英语提供所有的复数形式。

import { Plural, Num } from 'gt-next';

<Plural
  n={count}
  one={<>You have <Num>{count}</Num> unread message.</>}
  other={<>You have <Num>{count}</Num> unread messages.</>}
/>

在这里，我们为英语提供了 one 和 other 两种复数形式。

另外，你也可以为英语提供 singular 和 plural 形式。

注意事项

Branch 组件对于管理应用中的动态和本地化内容至关重要。
<Branch> 组件非常灵活，可以适应各种条件和状态。
<Plural> 组件通过自动遵循特定语言环境的规则，简化了复数处理。
始终包含一个备用的 children 属性，以获得更好的错误处理和用户体验。

后续步骤

在 API 参考中查看 <Branch> 和 <Plural> 以获取更多详细信息。
了解更多关于复数规则和分支逻辑的信息，请参阅 Unicode CLDR 复数规则。
探索如何使用变量组件。

使用分支

在本页面