using-instui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

InstUI is Instructure's open-source React component library and design system, providing accessible, themeable UI components for Canvas LMS and other Instructure products.

InstUI是Instructure的开源React组件库和设计系统，为Canvas LMS及其他Instructure产品提供具备可访问性、支持主题定制的UI组件。

Installation

安装

npm install @instructure/ui

npm install @instructure/ui

Import Pattern

导入模式

jsx

// Umbrella package (recommended for most consumers)
import { Button, TextInput, Modal } from '@instructure/ui'

jsx

//  umbrella包（推荐大多数使用者使用）
import { Button, TextInput, Modal } from '@instructure/ui'

Setup

配置

Wrap your app in a theme provider:

jsx

import { canvas } from '@instructure/ui-themes'
import { InstUISettingsProvider } from '@instructure/ui'

function App() {
  return (
    <InstUISettingsProvider theme={canvas}>
      {/* your app */}
    </InstUISettingsProvider>
  )
}

See usage.md for full setup details and theming-components.md for customization.

使用主题提供者包裹你的应用：

jsx

import { canvas } from '@instructure/ui-themes'
import { InstUISettingsProvider } from '@instructure/ui'

function App() {
  return (
    <InstUISettingsProvider theme={canvas}>
      {/* 你的应用内容 */}
    </InstUISettingsProvider>
  )
}

查看usage.md获取完整配置详情，查看theming-components.md了解定制方法。

Instructure UI (InstUI) - React Component Library

Instructure UI (InstUI) - React组件库

version 11.6.0
Instructure UI (InstUI) is a comprehensive React component library.

版本 11.6.0
Instructure UI（InstUI）是一个全面的React组件库。

Documentation

文档

User Guides

用户指南

Getting Started

快速入门

Accessibility: Instructure UI targets WCAG 2.1 AA/AAA standards with proper color contrast, keyboard navigation, screen reader support, and ARIA compliance. Components are perceivable, operable, understandable, and robust.
Theming components: InstUI has two themes:
```
canvas
```
(default) and
```
canvas-high-contrast
```
. Colors are layered: primitives (base), contrasts (theme-specific), and UI (curated tokens). Use
```
InstUISettingsProvider
```
to set themes. Overrides allow customization but must maintain accessibility.
Usage: Quick start: Create a React app, add
```
@instructure/ui
```
, wrap with
```
InstUISettingsProvider
```
, and use components. Integrate with existing projects by adding the dependency and provider. Read about theme overrides and accessibility for best practices.

可访问性：Instructure UI以WCAG 2.1 AA/AAA标准为目标，具备合适的色彩对比度、键盘导航、屏幕阅读器支持及ARIA合规性。组件具备可感知、可操作、易懂、健壮的特性。
组件主题定制：InstUI拥有两种主题：
```
canvas
```
（默认）和
```
canvas-high-contrast
```
。颜色分为多层：基础色（原始值）、对比色（主题专属）和UI色（精心调配的标记）。使用
```
InstUISettingsProvider
```
设置主题。允许进行自定义覆盖，但必须保持可访问性。
使用方法：快速入门步骤：创建React应用、添加
```
@instructure/ui
```
依赖、用
```
InstUISettingsProvider
```
包裹应用、使用组件。通过添加依赖和提供者将其集成到现有项目中。阅读主题覆盖和可访问性相关内容以了解最佳实践。

Guides

进阶指南

Accessing the dom: Guidance for properly accessing DOM elements in React components using refs instead of findDOMNode to avoid warnings. Examples show good and bad patterns for component ref handling.
Color system: Color system divided into primitive (hex values) and semantic (contextual) colors. Includes data visualization palette with primary and secondary hues for charts and graphs on white backgrounds.
Focus management: Comprehensive focus management system for dialogs, modals, and popovers. Uses Dialog component with FocusRegion and FocusRegionManager to trap focus, handle escape keys, and manage screen reader accessibility.
Form errors: InstUI form components use a
```
messages
```
prop for error/hint/success messages. Supports both
```
error
```
(legacy) and
```
newError
```
(accessible) types. Required fields now show an asterisk automatically. Examples provided for various form components like TextInput, Checkbox, and DateTimeInput.
Layout spacing: InstUI provides semantic spacing tokens (e.g., buttons, tags) for consistent layouts. Apply spacing via
```
margin
```
prop, container
```
gap
```
, or importing from theme. Legacy tokens are available for compatibility but not recommended for new layouts.
Module federation: InstUI supports module federation with specific version requirements. For v10.14+, use local themes (
```
canvasThemeLocal
```
). For older hosts, guest apps must use v10.14+ and local themes. Global theme overrides don't apply to local themes.
Server side rendering: SSR with Next.js requires wrapping the app with
```
InstUISettingsProvider
```
for deterministic ID generation. Avoid
```
@instructure/ui
```
meta-package; install only needed packages. CodeEditor isn't SSR-compatible and must be dynamically imported.
Typography system: Use
```
<Text>
```
and
```
<Heading>
```
components with semantic variants for consistent typography. Variants define font style, weight, size, and line height. Legacy tokens (e.g., fontSizeXSmall) are deprecated and should not be used in new designs.
Using theme overrides: Customize components via theme overrides while ensuring WCAG compliance. Use nested
```
InstUISettingsProvider
```
for subtree themes, override global or component themes, and leverage branding variables for user customization. Deprecated global theming causes issues with multiple InstUI versions.

DOM访问：指导如何在React组件中正确使用refs而非findDOMNode访问DOM元素，避免警告。示例展示了组件ref处理的正确和错误模式。
色彩系统：色彩系统分为基础色（十六进制值）和语义色（上下文相关）。包含数据可视化调色板，带有主色调和辅助色调，适用于白色背景上的图表和图形。
焦点管理：针对对话框、模态框和弹出框的全面焦点管理系统。使用Dialog组件搭配FocusRegion和FocusRegionManager来捕获焦点、处理ESC按键、管理屏幕阅读器可访问性。
表单错误：InstUI表单组件使用
```
messages
```
属性处理错误/提示/成功消息。同时支持
```
error
```
（旧版）和
```
newError
```
（符合可访问性）类型。必填字段现在会自动显示星号标记。提供了TextInput、Checkbox、DateTimeInput等各类表单组件的使用示例。
布局间距：InstUI提供语义化间距标记（如按钮、标签）以实现一致的布局。可通过
```
margin
```
属性、容器
```
gap
```
或从主题中导入来应用间距。为兼容保留了旧版标记，但不推荐在新布局中使用。
模块联邦：InstUI支持模块联邦，有特定版本要求。对于v10.14+版本，使用本地主题（
```
canvasThemeLocal
```
）。对于旧版宿主应用，客户端应用必须使用v10.14+版本并使用本地主题。全局主题覆盖不适用于本地主题。
服务端渲染：使用Next.js进行SSR时，需要用
```
InstUISettingsProvider
```
包裹应用以实现确定性ID生成。避免使用
```
@instructure/ui
```
元包；仅安装所需的包。CodeEditor不支持SSR，必须动态导入。
排版系统：使用
```
<Text>
```
和
```
<Heading>
```
组件搭配语义化变体实现一致的排版。变体定义了字体样式、字重、字号和行高。旧版标记（如fontSizeXSmall）已被弃用，不应在新设计中使用。
主题覆盖使用：通过主题覆盖定制组件，同时确保符合WCAG标准。使用嵌套的
```
InstUISettingsProvider
```
为子树设置主题，覆盖全局或组件主题，利用品牌变量实现用户定制。已弃用的全局主题会导致多版本InstUI共存时的问题。

Patterns

设计模式

Content alignment: Guidelines for main content area alignment with maximum width (948px) for readability, minimum width (320px) for accessibility, and responsive padding (24px/12px). Ensures proper centering, avoids two-dimensional scrolling, and allows exceptions for complex data displays.
Destroy action: A modal used for irreversible actions like deletion. Includes guidelines for usage: use clear language, avoid vague confirmations, and use a danger button for the destructive action.
Search: Provides search input patterns including auto-activated, activated, and autocomplete search. Includes guidelines, accessibility support, and clear state management examples.
Using icons: Guidelines for using icons with proper accessibility roles, size variants, and color options. Line icons for light backgrounds, solid for dark backgrounds. Icons scale with parent font-size by default.

内容对齐：主内容区域对齐指南，最大宽度为948px以保证可读性，最小宽度为320px以满足可访问性，响应式内边距为24px/12px。确保内容正确居中，避免二维滚动，复杂数据展示场景可例外。
销毁操作：用于不可逆操作（如删除）的模态框。包含使用规范：使用清晰语言、避免模糊确认、使用危险按钮执行销毁操作。
搜索：提供搜索输入模式，包括自动激活、手动激活和自动完成搜索。包含使用指南、可访问性支持和清晰的状态管理示例。
图标使用：图标使用指南，包括正确的可访问性角色、尺寸变体和颜色选项。浅色背景使用线性图标，深色背景使用实心图标。图标默认随父元素字体大小缩放。

Components

组件

InstUISettingsProvider: A global configuration component for applying themes and text direction settings across an application. It wraps Emotion's ThemeProvider and supports nested providers for theme inheritance and overrides. Also manages text direction (LTR/RTL) via context for descendant components.
Alert: Notifies users with contextual variants (success, info, error, warning). Supports dismissible dialogs, automatic timeout dismissal, live regions for screen readers, and inline usage without shadows. Includes accessibility guidelines for proper implementation.
Avatar: Displays user avatars with fallback to initials or icons. Supports circle/rectangle shapes, multiple sizes, colors, and inverse styling. Includes special AI avatar variant and accessibility considerations with aria-hidden attribute.
Badge: Displays numeric counts or notifications with accessibility features. Supports count limits, various placements, standalone usage, and color variants. Requires formatOutput prop for screen reader context beyond simple numbers.
Billboard: Used for empty states, 404 pages, and redirects. Supports various sizes, hero icons, and interactive behaviors (button or link). Can be disabled and includes structured messaging with headings and calls to action.
Breadcrumb: Shows navigation path location with automatic text truncation. Best for tablet+ screens; use Link for mobile. Supports multiple sizes, icons, and accessibility with aria-current attribute for current page indication.
Button: Triggers actions or changes with multiple color schemes, sizes, and display options. Supports icons, text wrapping control, and backgroundless variants. Includes specific AI button styles with gradients and icons.
CloseButton: Specialized button for closing modals, dialogs, or containers. Supports absolute positioning with placement options (start/end/static) and offset control. Built with accessibility in mind using IconButton with X icon and screen reader labels.
CondensedButton: Button variant without padding for tight spaces or alignment with other content. Ideal for table cells or areas where standard button padding would disrupt layout. Maintains button functionality while minimizing visual footprint.
IconButton: A button component designed specifically for icon-only actions. Requires screen reader labels for accessibility, supports various shapes (rectangle/circle), and can remove background/border for minimalist designs. Works well with Tooltip for additional context.
ToggleButton: Controlled button for toggling between two states (on/off), featuring icon support, tooltips, inverse variants for dark backgrounds, and accessibility labels. Perfect for status toggles like lock/unlock.
Byline: Combines visual elements (avatars, icons) with descriptive captions. Supports titles, various sizes, content alignment options, and margin control. Useful for author attribution or content metadata displays.
Calendar: Visual date selection component with configurable month navigation, disabled dates, selection handling, and optional year picker. Supports custom date libraries and accessibility features with proper weekday labels and screen reader support.
Checkbox: Custom styled checkbox component supporting standard, toggle, and indeterminate states. Includes size variants, accessibility features with aria-labelledby, and proper grouping for parent-child relationships. Guidelines recommend vertical stacking for multiple options.
CheckboxGroup: Groups multiple Checkbox components with shared name and value management. Supports vertical or horizontal layouts, toggle variants, and group-level disabled/readonly states. Handles validation messages and maintains consistent state across all checkboxes.
ColorContrast: WCAG 2.1 compliance tool that calculates and displays contrast ratios between two colors. Validates against normal text (4.5:1), large text (3:1), and graphics (3:1) standards. Provides pass/fail indicators and supports AA/AAA validation levels.
ColorIndicator: Displays color swatches with checkerboard background for transparency visualization. Supports circle and rectangle shapes, various color formats (hex, RGB, HSL, HWB), and can be used within buttons for color selection interfaces.
ColorMixer: Interactive color selection component with RGBA input fields, color sliders, and visual palette. Supports alpha transparency, keyboard navigation for accessibility, and can be disabled. Provides real-time color feedback and value changes.
ColorPicker: Versatile color selection component with hex input validation and optional popover color mixer. Supports controlled/uncontrolled operation, contrast checking, alpha transparency, and custom popover content. Includes comprehensive error messaging and accessibility features.
ColorPreset: Color selection from predefined palettes with support for adding/removing colors. Includes visual color indicators, screen reader labels, and optional color mixer integration for custom color creation. Handles color management and selection callbacks.
DateInput: A date input component with a calendar picker (uses Moment.js). Supports disabled dates, validation, and formatted display. Note: Being deprecated in favor of DateInput2 for better UX and accessibility.
DateInput2: An improved date input with easier configuration, better accessibility, and a year picker. Supports custom date parsing, timezone handling, validation, and disabled dates. Recommended over the original DateInput.
DateTimeInput: Combines DateInput and TimeSelect for entering date-time values. Supports localization, validation, disabled dates, and layout options (stacked or columns). Includes reset functionality and context-aware formatting.
DrawerLayout: A responsive layout component with a collapsible tray and content area. Tray can be placed at start or end and switches to overlay on small screens. Supports nested layouts and accessibility features.
Drilldown: A hierarchical navigation component for tree structures. Supports pages, groups, selectable options, and in-place editing. Replaces flyout menus and TreeBrowser for better responsiveness and accessibility.
Editable: Enables in-place editing of content. Manages state and transitions between view and edit modes. Provides render props for custom UI implementation. Used by InPlaceEdit.
InPlaceEdit: Enables inline editing of content with smooth transitions between view and edit modes. Provides controlled component pattern for mode management, custom renderers for viewer/editor components, and support for various layouts and read-only states.
FileDrop: A drag-and-drop file upload component with browse functionality. Supports file type validation via MIME types/extensions, multiple file uploads, and visual feedback for accepted/rejected files. Includes accessibility features and customizable rendering for labels and error messages.
Flex: A flexbox-based layout component for creating responsive multi-column designs. Supports directional layouts, gap control, item sizing (grow/shrink), alignment, and overflow handling. Includes visual debugging tools and common layout patterns like header-button combinations.
FormField: A foundational component for building form inputs with consistent styling and layout. Supports stacked and inline layouts, validation messages, and accessibility features. Typically used internally by other form components rather than directly.
FormFieldGroup: Organizes multiple form fields into cohesive groups with consistent spacing and alignment. Supports various layouts (inline, columns, stacked) and provides validation messaging at the group level. Includes accessibility guidance against placeholder text.
Grid: A 12-column grid system for creating responsive layouts. Features breakpoint-based stacking, customizable column widths, spacing control, and alignment options. Supports visual debugging and common patterns like responsive header layouts.
Heading: A typographic component for creating accessible headings with consistent styling. Supports semantic heading levels, color variants, borders, icons, and AI-specific styles. Includes important accessibility guidelines for proper heading hierarchy.
Img: An accessible image component with advanced features like color overlays, constraining options (cover/contain), and visual filters (grayscale/blur). Supports proper alt text implementation and follows accessibility guidelines for contextual vs. decorative images.
Link: An inline link component for navigation within text content. Supports variants (inline, inline-small, standalone, standalone-small), icons, margin, and underline control. Includes accessibility guidelines for proper usage and contrast.
InlineList: Displays list items horizontally with customizable delimiters, spacing, and sizing options. Supports various separator styles (pipe, slash, arrow) and controlled item spacing without affecting list boundaries.
List: A component for rendering ordered, unordered, or unstyled lists. Supports delimiters, spacing, sizing, and custom margins. Only accepts List.Item children and includes options for item spacing and visual customization.
Menu: A Popover-based component for action lists, often triggered by a button. Supports single/multiple selection, groups, separators, and nested menus. Not for navigation or complex content—only Menu.Items are allowed.
Metric: Displays a value and label with configurable text alignment (start, center, end). Used for showing key metrics like grades, counts, or percentages in a clean, aligned format.
MetricGroup: A container for displaying multiple Metric components in rows. Groups related metrics together for consolidated data presentation, such as grade-related statistics.
Modal: A centered dialog that overlays app content with a mask. Supports headers, bodies, footers, form integration, media display, and constrained positioning. Includes variants (default, inverse) and accessibility features.
AppNav: Navigation component for LTI apps that adapts to screen widths by truncating items. Provides update callbacks for visible item count and customizable truncation labels. Supports before/after items and responsive hamburger menu patterns.
NumberInput: A controlled input for numeric values with increment/decrement arrows. Supports validation, error messages, sizing, and accessibility. Must be used with event handlers; does not support uncontrolled usage.
Overlay: A closable/dismissible component that transitions content in and out via a Portal. Supports focus management, accessibility features, and can be used with Mask components. Includes guidelines for ensuring content behind the overlay is hidden from screen readers and dismissible with ESC key.
Pages: A component for rendering paginated content across multiple pages. Supports navigation between pages, back buttons, and focus management. Each page should contain at least one focusable element. Useful for multi-step workflows or detailed views like user profiles.
Pagination: Component for navigating through multi-page content. Offers compact, full, and input variants with configurable page indicators. Supports large page numbers, custom labels, and accessibility features. Includes both new simplified API and legacy support for complex pagination needs.
Pill: Displays short, contextual information with color-coded status indicators. Supports icons, status labels, and various color schemes. Text truncates with ellipsis if overflow occurs. Not intended for dismissible content or counts - use Tag or Badge components instead.
Popover: Shows/hides content connected to a trigger element via click, hover, or focus. Supports arrows, various placements, colors, and shadows. Can function as a dialog with focus trapping. Includes controlled and uncontrolled variants with extensive customization options.
ProgressBar: Styled HTML progress element with accessibility support. Offers multiple sizes, colors, and meter colors. Supports value formatting, animation, and screen reader customization. Meter color can be function-based for dynamic color changes.
ProgressCircle: Circular progress indicator with accessibility features. Supports sizes, colors, animations on mount, and custom value rendering. Meter color can be function-based. Useful for showing completion percentages in a compact visual format.
RadioInput: Custom styled radio button component. Typically used within RadioInputGroup for proper grouping and behavior. Supports different sizes and should always be used in groups rather than individually.
RadioInputGroup: Manages groups of radio buttons with shared name attribute. Supports various layouts (default, inline, columns), toggle variant, disabled states, and accessibility. Handles selection state and change events for the entire group.
RangeInput: An HTML5 range input/slider component with customizable size and thumb variants. Supports React class and functional component implementations with interactive examples for real-time updates.
Rating: Displays 3- or 5-star ratings based on valueNow and valueMax props. Supports rounding decimals, customizable sizes, animations, and accessibility-compliant text formatting for screen readers.
Responsive: Renders components differently based on element or viewport size. Supports breakpoint-based props and conditional rendering. Use sparingly to avoid performance issues.
Select: Accessible combobox component for single or multiple selections. Supports autocomplete, grouping, async loading, icons, and screen reader announcements. Fully controllable with extensive state management examples.
SideNavBar: Experimental top-level navigation component with toggleable minimized/expanded states. Supports icons, Avatars, badges, and theming. API may change significantly.
SimpleSelect: Simplified Select component mimicking native
```
<select>
```
behavior. Supports uncontrolled/controlled usage, option groups, and icons. Less configurable than Select but easier to implement.
SourceCodeEditor: Wrapper around CodeMirror with syntax highlighting, line numbers, folding, indentation, search, and RTL support. Recommended upgrade from deprecated CodeEditor component.
Spinner: Loading indicator with four sizes, inverse variant for dark backgrounds, configurable delay, and screen reader support via renderTitle prop.
Table: A versatile table component supporting multiple layouts (auto, fixed, stacked), column customization, sorting, selection, pagination, and responsive behavior. Includes accessibility features and supports custom components for advanced use cases.
Tabs: Accessible tabbed navigation component with support for secondary variants, overflow handling, size control, dynamic content, and tab persistence. Supports disabled tabs and controlled/uncontrolled usage patterns.
Tag: Compact component for representing categories or groups, featuring dismissible functionality, multiple sizes, inline variants, and accessibility support. Ideal for form elements and filtering interfaces.
Text: Comprehensive text styling component with semantic variants, color options, font properties, line heights, text transformation, and wrapping controls. Replaces deprecated legacy values with semantic alternatives.
TextArea: Resizable textarea input with height constraints, validation messages, disabled states, and inline display options. Supports controlled/uncontrolled usage and includes accessibility guidelines.
TextInput: Custom styled input supporting various types, prepend/append content, inline display, and controlled/uncontrolled behavior. Features validation, disabled/readonly states, and flexible content wrapping options.
TimeSelect: Specialized time selection component built on Select, supporting controlled/uncontrolled usage, freeform input, locale/timezone awareness, and step-based time increments. Ideal for time-based form inputs.
ToggleDetails: Collapsible content component with configurable expansion, icon positioning, sizing variants, and fluid width options. Supports controlled behavior and custom summary formatting with text components.
ToggleGroup: Enhanced toggle component with separated summary/toggle button, built-in padding/borders, and nesting support. Features custom icons, transition control, and expanded state management.
Tooltip: Contextual text overlays triggered by hover/focus, featuring placement options, color variants, and controlled/uncontrolled behavior. Designed for non-focusable content with comprehensive accessibility support.
TopNavBar: A responsive navigation bar component for site branding, navigation, user actions, and login. Adapts to small screens by truncating items and supports desktop and mobile layouts. Includes sections for brand, breadcrumbs, menu items, action items, and user controls.
Tray: A slide-out container triggered by click, appearing from top/bottom/start/end of viewport. Used for actionable content that doesn't require a modal overlay. Supports various sizes and placements with accessibility focus management.
TreeBrowser: A keyboard-accessible tree structure component for browsing hierarchical content. Supports custom icons, sorting, state management, and customizable node content. Not intended for site navigation.
TruncateText: Component for truncating text content with single or multiple line support. Supports custom ellipsis, truncation position (end or middle), and tooltips for full text accessibility. Not for buttons or navigation items.
ContextView: A container that renders inline with an arrow pointing to another element. It displays contextual information without being a popover. Supports padding, text alignment, and margin customization. Often used with components like RangeInput and internally by Popover.
View: The foundational visual component providing styling for backgrounds, borders, shadows, positioning, and focus states. Supports visual debugging and semantic HTML elements via the 'as' prop.

InstUISettingsProvider：全局配置组件，用于在应用中应用主题和文本方向设置。它包裹了Emotion的ThemeProvider，支持嵌套提供者以实现主题继承和覆盖。还通过上下文管理后代组件的文本方向（LTR/RTL）。
Alert：通过上下文变体（成功、信息、错误、警告）通知用户。支持可关闭对话框、自动超时关闭、屏幕阅读器实时区域，以及无阴影的内联使用方式。包含正确实现的可访问性指南。
Avatar：显示用户头像，支持回退显示首字母或图标。支持圆形/矩形形状、多种尺寸、颜色和反转样式。包含特殊的AI头像变体，以及使用aria-hidden属性的可访问性注意事项。
Badge：显示数字计数或通知，具备可访问性功能。支持计数限制、多种位置、独立使用和颜色变体。对于非简单数字的场景，需要使用formatOutput属性为屏幕阅读器提供上下文信息。
Billboard：用于空状态、404页面和重定向场景。支持多种尺寸、英雄图标和交互行为（按钮或链接）。可设置禁用状态，包含带标题和行动号召的结构化消息。
Breadcrumb：显示导航路径位置，支持自动文本截断。最适合平板及以上尺寸屏幕；移动端使用Link组件。支持多种尺寸、图标，以及使用aria-current属性标记当前页面的可访问性功能。
Button：触发操作或状态变更，具备多种配色方案、尺寸和显示选项。支持图标、文本换行控制和无背景变体。包含特定的AI按钮样式，带有渐变和图标。
CloseButton：用于关闭模态框、对话框或容器的专用按钮。支持绝对定位和位置选项（start/end/static）及偏移控制。基于IconButton构建，使用X图标和屏幕阅读器标签，具备可访问性。
CondensedButton：无边距的按钮变体，适用于空间有限或需与其他内容对齐的场景。非常适合表格单元格或标准按钮边距会破坏布局的区域。在最小化视觉占用的同时保留按钮功能。
IconButton：专为仅图标操作设计的按钮组件。为保证可访问性，需要设置屏幕阅读器标签，支持多种形状（矩形/圆形），可移除背景/边框实现极简设计。与Tooltip搭配使用可提供额外上下文信息。
ToggleButton：受控按钮，用于在两种状态（开/关）间切换，支持图标、工具提示、深色背景的反转变体和可访问性标签。非常适合锁定/解锁等状态切换场景。
Byline：将视觉元素（头像、图标）与描述性标题组合在一起。支持标题、多种尺寸、内容对齐选项和边距控制。适用于作者署名或内容元数据展示。
Calendar：可视化日期选择组件，支持可配置的月份导航、禁用日期、选择处理和可选的年份选择器。支持自定义日期库，具备合适的星期标签和屏幕阅读器支持等可访问性功能。
Checkbox：自定义样式的复选框组件，支持标准、切换和不确定状态。包含尺寸变体、使用aria-labelledby的可访问性功能，以及父子关系的正确分组。指南建议多个选项采用垂直堆叠布局。
CheckboxGroup：将多个Checkbox组件分组，共享名称和值管理。支持垂直或水平布局、切换变体，以及组级别的禁用/只读状态。处理验证消息并保持所有复选框状态一致。
ColorContrast：WCAG 2.1合规性工具，计算并显示两种颜色之间的对比度。针对普通文本（4.5:1）、大文本（3:1）和图形（3:1）标准进行验证。提供通过/失败指示器，支持AA/AAA验证级别。
ColorIndicator：显示颜色样本，带棋盘格背景以可视化透明度。支持圆形和矩形形状、多种颜色格式（十六进制、RGB、HSL、HWB），可在按钮中用于颜色选择界面。
ColorMixer：交互式颜色选择组件，带有RGBA输入字段、颜色滑块和可视化调色板。支持透明度、键盘导航以保证可访问性，可设置禁用状态。提供实时颜色反馈和值变更。
ColorPicker：多功能颜色选择组件，支持十六进制输入验证和可选的弹出式颜色混合器。支持受控/非受控操作、对比度检查、透明度和自定义弹出内容。包含全面的错误提示和可访问性功能。
ColorPreset：从预定义调色板中选择颜色，支持添加/移除颜色。包含可视化颜色指示器、屏幕阅读器标签，以及可选的颜色混合器集成以创建自定义颜色。处理颜色管理和选择回调。
DateInput：带日历选择器的日期输入组件（使用Moment.js）。支持禁用日期、验证和格式化显示。注意：正被DateInput2取代，后者具备更好的用户体验和可访问性。
DateInput2：改进版日期输入组件，配置更简单、可访问性更好，支持年份选择器。支持自定义日期解析、时区处理、验证和禁用日期。推荐替代原DateInput组件。
DateTimeInput：结合DateInput和TimeSelect组件，用于输入日期时间值。支持本地化、验证、禁用日期和布局选项（堆叠或分栏）。包含重置功能和上下文感知格式化。
DrawerLayout：响应式布局组件，包含可折叠的侧边栏和内容区域。侧边栏可放置在左侧或右侧，小屏幕下切换为覆盖层。支持嵌套布局和可访问性功能。
Drilldown：用于树形结构的层级导航组件。支持页面、分组、可选选项和内联编辑。替代弹出菜单和TreeBrowser组件，具备更好的响应性和可访问性。
Editable：支持内容的内联编辑。管理视图和编辑模式之间的状态和过渡。提供渲染属性以实现自定义UI。被InPlaceEdit组件使用。
InPlaceEdit：支持内容的内联编辑，在视图和编辑模式间平滑过渡。提供受控组件模式以管理状态，支持查看器/编辑器组件的自定义渲染器，支持多种布局和只读状态。
FileDrop：支持拖放的文件上传组件，具备浏览功能。支持通过MIME类型/扩展名验证文件类型、多文件上传，以及接受/拒绝文件的视觉反馈。包含可访问性功能和标签、错误消息的自定义渲染。
Flex：基于flexbox的布局组件，用于创建响应式多列设计。支持方向布局、间距控制、项目尺寸（增长/收缩）、对齐和溢出处理。包含视觉调试工具和常见布局模式（如头部-按钮组合）。
FormField：基础组件，用于构建具备一致样式和布局的表单输入。支持堆叠和内联布局、验证消息和可访问性功能。通常被其他表单组件内部使用，而非直接使用。
FormFieldGroup：将多个表单字段组织为连贯的组，具备一致的间距和对齐。支持多种布局（内联、分栏、堆叠），并在组级别提供验证消息。包含针对占位符文本的可访问性指南。
Grid：12列网格系统，用于创建响应式布局。具备基于断点的堆叠、自定义列宽、间距控制和对齐选项。支持视觉调试和常见模式（如响应式头部布局）。
Heading：排版组件，用于创建具备一致样式的可访问性标题。支持语义化标题级别、颜色变体、边框、图标和AI专属样式。包含正确标题层级的重要可访问性指南。
Img：具备高级功能的可访问性图片组件，支持颜色叠加、约束选项（覆盖/包含）和视觉滤镜（灰度/模糊）。支持正确的替代文本实现，遵循上下文图片与装饰性图片的可访问性指南。
Link：内联链接组件，用于文本内容内的导航。支持变体（内联、小型内联、独立、小型独立）、图标、边距和下划线控制。包含正确使用和对比度的可访问性指南。
InlineList：水平显示列表项，支持自定义分隔符、间距和尺寸选项。支持多种分隔符样式（竖线、斜杠、箭头），并控制项间距而不影响列表边界。
List：用于渲染有序、无序列表或无样式列表的组件。支持分隔符、间距、尺寸和自定义边距。仅接受List.Item作为子元素，包含项间距和视觉自定义选项。
Menu：基于Popover的动作列表组件，通常由按钮触发。支持单选/多选、分组、分隔符和嵌套菜单。不用于导航或复杂内容——仅允许Menu.Items作为子元素。
Metric：显示数值和标签，支持可配置的文本对齐（左、中、右）。用于以简洁、对齐的格式显示关键指标（如成绩、计数、百分比）。
MetricGroup：容器组件，用于在多行中显示多个Metric组件。将相关指标分组展示，如成绩相关统计数据。
Modal：居中对话框，覆盖应用内容并带有遮罩。支持头部、主体、底部、表单集成、媒体展示和约束定位。包含变体（默认、反转）和可访问性功能。
AppNav：LTI应用的导航组件，通过截断项适配屏幕宽度。提供可见项数量的更新回调和可自定义的截断标签。支持前后项和响应式汉堡菜单模式。
NumberInput：用于数值的受控输入组件，带有增减箭头。支持验证、错误消息、尺寸和可访问性。必须与事件处理器配合使用；不支持非受控使用方式。
Overlay：可关闭/隐藏的组件，通过Portal实现内容的进出过渡。支持焦点管理、可访问性功能，可与Mask组件配合使用。包含确保遮罩后内容对屏幕阅读器隐藏、可通过ESC键关闭的指南。
Pages：用于在多个页面中渲染分页内容的组件。支持页面间导航、返回按钮和焦点管理。每个页面应至少包含一个可聚焦元素。适用于多步骤工作流或用户资料等详细视图。
Pagination：用于浏览多页内容的组件。提供紧凑、完整和输入变体，支持可配置的页面指示器。支持大页码、自定义标签和可访问性功能。包含新的简化API和对复杂分页需求的旧版支持。
Pill：显示简短的上下文信息，带有颜色编码的状态指示器。支持图标、状态标签和多种配色方案。文本溢出时显示省略号。不用于可关闭内容或计数——请使用Tag或Badge组件。
Popover：通过点击、悬停或聚焦触发，显示/隐藏与触发元素关联的内容。支持箭头、多种位置、颜色和阴影。可作为具备焦点捕获功能的对话框使用。包含受控和非受控变体，支持广泛的自定义选项。
ProgressBar：带可访问性支持的样式化HTML进度元素。提供多种尺寸、颜色和进度条颜色。支持值格式化、动画和屏幕阅读器自定义。进度条颜色可通过函数实现动态变化。
ProgressCircle：带可访问性功能的圆形进度指示器。支持尺寸、颜色、挂载时动画和自定义值渲染。进度条颜色可通过函数实现。适用于以紧凑视觉格式显示完成百分比。
RadioInput：自定义样式的单选按钮组件。通常在RadioInputGroup中使用以实现正确分组和行为。支持不同尺寸，应始终分组使用而非单独使用。
RadioInputGroup：管理共享名称属性的多个单选按钮。支持多种布局（默认、内联、分栏）、切换变体、禁用状态和可访问性。处理整个组的选择状态和变更事件。
RangeInput：HTML5范围输入/滑块组件，支持自定义尺寸和滑块变体。支持React类组件和函数组件实现，带有实时更新的交互示例。
Rating：基于valueNow和valueMax属性显示3星或5星评分。支持小数四舍五入、自定义尺寸、动画和符合可访问性的屏幕阅读器文本格式化。
Responsive：根据元素或视口尺寸以不同方式渲染组件。支持基于断点的属性和条件渲染。应谨慎使用以避免性能问题。
Select：具备可访问性的组合框组件，支持单选或多选。支持自动完成、分组、异步加载、图标和屏幕阅读器通知。完全受控，包含丰富的状态管理示例。
SideNavBar：实验性的顶级导航组件，支持可切换的最小化/展开状态。支持图标、头像、徽章和主题定制。API可能会发生重大变化。
SimpleSelect：简化版Select组件，模仿原生
```
<select>
```
行为。支持非受控/受控使用、选项组和图标。配置项少于Select但更易于实现。
SourceCodeEditor：基于CodeMirror的封装组件，支持语法高亮、行号、折叠、缩进、搜索和RTL支持。推荐替代已弃用的CodeEditor组件。
Spinner：加载指示器，提供四种尺寸、深色背景的反转变体、可配置的延迟，以及通过renderTitle属性实现的屏幕阅读器支持。
Table：多功能表格组件，支持多种布局（自动、固定、堆叠）、列定制、排序、选择、分页和响应式行为。包含可访问性功能，支持高级场景的自定义组件。
Tabs：具备可访问性的标签导航组件，支持次要变体、溢出处理、尺寸控制、动态内容和标签持久化。支持禁用标签和受控/非受控使用模式。
Tag：紧凑组件，用于表示类别或分组，具备可关闭功能、多种尺寸、内联变体和可访问性支持。适用于表单元素和过滤界面。
Text：全面的文本样式组件，支持语义化变体、颜色选项、字体属性、行高、文本转换和换行控制。用语义化替代方案取代了已弃用的旧版值。
TextArea：可调整大小的文本域输入组件，支持高度约束、验证消息、禁用状态和内联显示选项。支持受控/非受控使用，包含可访问性指南。
TextInput：自定义样式的输入组件，支持多种类型、前置/后置内容、内联显示和受控/非受控行为。具备验证、禁用/只读状态和灵活的内容换行选项。
TimeSelect：基于Select构建的专用时间选择组件，支持受控/非受控使用、自由输入、区域设置/时区感知和基于步长的时间增量。适用于基于时间的表单输入。
ToggleDetails：可折叠内容组件，支持可配置的展开、图标位置、尺寸变体和流体宽度选项。支持受控行为和文本组件的自定义摘要格式化。
ToggleGroup：增强型切换组件，带有分离的摘要/切换按钮、内置内边距/边框和嵌套支持。支持自定义图标、过渡控制和展开状态管理。
Tooltip：上下文文本覆盖层，通过悬停/聚焦触发，支持位置选项、颜色变体和受控/非受控行为。专为非可聚焦内容设计，具备全面的可访问性支持。
TopNavBar：响应式导航栏组件，用于站点品牌展示、导航、用户操作和登录。小屏幕下通过截断项适配，支持桌面和移动布局。包含品牌、面包屑、菜单项、操作项和用户控制等区域。
Tray：滑出式容器，通过点击触发，从视口的顶部/底部/左侧/右侧出现。用于不需要模态框覆盖的可操作内容。支持多种尺寸和位置，具备可访问性焦点管理。
TreeBrowser：具备键盘可访问性的树形结构组件，用于浏览层级内容。支持自定义图标、排序、状态管理和可定制的节点内容。不用于站点导航。
TruncateText：文本截断组件，支持单行或多行截断。支持自定义省略号、截断位置（末尾或中间），以及完整文本的可访问性工具提示。不用于按钮或导航项。
ContextView：容器组件，与另一个元素内联渲染并带有指向该元素的箭头。它显示上下文信息但不是弹出框。支持内边距、文本对齐和边距定制。常与RangeInput等组件配合使用，被Popover内部使用。
View：基础视觉组件，提供背景、边框、阴影、定位和焦点状态的样式。支持视觉调试和通过'as'属性使用语义化HTML元素。

Utilities

工具组件

BaseButton: Low-level utility component for composing Instructure UI buttons. Not intended for direct use; developers should use Button, CloseButton, IconButton, or CondensedButton instead.
Dialog: A utility component for accessibility in modals, popovers, and trays. Manages focus trapping, screen reader visibility, and keyboard navigation. Essential for WCAG-compliant modal interactions.
Expandable: Handles expand/collapse functionality for components like ToggleDetails and ToggleGroup. Provides props for accessibility and event handling. Manages state for expanded content visibility.
Focusable: A utility component that detects when elements receive focus. Provides render props for creating accessible focus-based interactions, such as skip-to-content links or focus-triggered tooltips. Ensures WCAG compliance for focus management.
Transition: A wrapper component for transitioning elements in and out of the UI. Supports fade, scale, and slide transitions with customizable directions. Handles mount/unmount transitions and supports RTL mirroring for slide animations.
Options: A view-only component for building option lists or menus. Supports variants (default, highlighted, selected, disabled), icons, nesting, and custom roles. Does not manage state—requires external event handling.
Mask: A component that covers its nearest positioned parent element. Can be used fullscreen within a Portal and supports click-to-close functionality. Useful for overlays and blocking UI interactions.
Portal: Renders a React subtree into a different DOM element. Useful for modal-like components that need to break out of parent containers. Typically used with Overlay, Modal, or other components that need to render outside their parent hierarchy.
Position: Positions content relative to a target element with various placement options. Supports RTL internationalization, offset adjustments, and mounting in specific DOM nodes. Replaces older Target/Content pattern with renderTarget prop.
Selectable: Low-level utility for building custom combobox widgets. Provides ARIA-compliant prop getters and state management hooks. Use existing Select component when possible.
InlineSVG: Renders accessible SVG content inline with support for fixed dimensions or container filling. Differentiates from SVGIcon by being suitable for non-icon SVG graphics while maintaining accessibility standards.
SVGIcon: Renders accessible inline SVG icons. Supports custom sizing, color theming, rotation, and display properties. Accepts SVG content via children or external source strings.
TruncateList: A utility component that truncates items when space is limited, commonly used in navigation bars. Controls visible item count and provides dropdown for hidden items with customizable spacing and menu triggers.

BaseButton：用于组合Instructure UI按钮的底层工具组件。不建议直接使用；开发者应使用Button、CloseButton、IconButton或CondensedButton组件。
Dialog：用于模态框、弹出框和侧边栏可访问性的工具组件。管理焦点捕获、屏幕阅读器可见性和键盘导航。是符合WCAG标准的模态框交互的必备组件。
Expandable：处理ToggleDetails和ToggleGroup等组件的展开/折叠功能。提供可访问性和事件处理的属性。管理展开内容可见性的状态。
Focusable：检测元素何时获得焦点的工具组件。提供渲染属性以创建具备可访问性的基于焦点的交互（如跳转到内容链接或焦点触发的工具提示）。确保焦点管理符合WCAG标准。
Transition：包裹组件以实现UI元素的进出过渡。支持淡入淡出、缩放和滑动过渡，方向可定制。处理挂载/卸载过渡，支持滑动动画的RTL镜像。
Options：用于构建选项列表或菜单的仅视图组件。支持变体（默认、高亮、选中、禁用）、图标、嵌套和自定义角色。不管理状态——需要外部事件处理。
Mask：覆盖最近的定位父元素的组件。可在Portal中全屏使用，支持点击关闭功能。适用于覆盖层和阻止UI交互场景。
Portal：将React子树渲染到不同的DOM元素中。适用于需要突破父容器的类模态框组件。通常与Overlay、Modal或其他需要在父层级外渲染的组件配合使用。
Position：相对于目标元素定位内容，支持多种位置选项。支持RTL国际化、偏移调整和在特定DOM节点中挂载。用renderTarget属性取代了旧的Target/Content模式。
Selectable：用于构建自定义组合框小部件的底层工具。提供符合ARIA标准的属性获取器和状态管理钩子。尽可能使用现有的Select组件。
InlineSVG：渲染具备可访问性的内联SVG内容，支持固定尺寸或填充容器。与SVGIcon的区别在于，它适用于非图标类SVG图形，同时保持可访问性标准。
SVGIcon：渲染具备可访问性的内联SVG图标。支持自定义尺寸颜色主题、旋转和显示属性。通过子元素或外部源字符串接受SVG内容。
TruncateList：空间有限时截断项的工具组件，常用于导航栏。控制可见项数量，为隐藏项提供下拉菜单，支持自定义间距和菜单触发器。

Contexts

上下文

ApplyLocale: Sets locale and timezone context for child components like TimeSelect. Enables internationalization by providing consistent localization settings throughout the component tree.
DeterministicIdContextProvider: Deprecated utility component for providing deterministic ID context. Do not use the instanceCounterMap prop. Part of InstUISettingsProvider infrastructure.

ApplyLocale：为TimeSelect等子组件设置区域设置和时区上下文。通过在组件树中提供一致的本地化设置实现国际化。
DeterministicIdContextProvider：已弃用的工具组件，用于提供确定性ID上下文。不要使用instanceCounterMap属性。是InstUISettingsProvider基础设施的一部分。

AI Components

AI组件

AiInformation: Displays AI-related data in Instructure products. Composed from NutritionFacts and DataPermissionLevels components with prefixed APIs. Supports fullscreen modals for mobile viewports with comprehensive data structure for AI feature information.
DataPermissionLevels: Displays AI-related data permissions in Instructure products. Shows hierarchical permission levels with titles and descriptions. Includes a modal interface with close functionality and supports highlighting specific levels for emphasis.
NutritionFacts: A specialized modal component for displaying AI-related data in structured blocks. Includes model info, privacy/compliance details, and output metrics. Features a trigger button and modal presentation.

AiInformation：在Instructure产品中显示AI相关数据。由NutritionFacts和DataPermissionLevels组件组合而成，带有前缀API。支持移动端视口的全屏模态框，具备AI功能信息的全面数据结构。
DataPermissionLevels：在Instructure产品中显示AI相关数据权限。展示带标题和描述的层级权限。包含带关闭功能的模态框界面，支持高亮特定权限级别以强调。
NutritionFacts：专用模态框组件，用于以结构化块显示AI相关数据。包含模型信息、隐私/合规详情和输出指标。带有触发按钮和模态框展示方式。