独家
Relative Time <mv-relative-time>
能自动保持最新的“3 minutes ago”：一个真正的 <time datetime>，文本由 Intl.RelativeTimeFormat 生成（“now”、“in 2 days”，“yesterday”按日历日而非 24 小时计算），超过阈值后切换为绝对日期，并使用最近的 lang 所对应的语言区域。
工作原理
能自动保持最新的“3 minutes ago”：一个真正的 <time datetime>，文本由 Intl.RelativeTimeFormat 生成（“now”、“in 2 days”，“yesterday”按日历日而非 24 小时计算），超过阈值后切换为绝对日期，并使用最近的 lang 所对应的语言区域。别人忽略的细节：页面上的所有实例共享同一个计时器，它只在某段可见文本即将变化时（下一分钟、下一小时或午夜，绝不每秒）准确唤醒，并在标签页隐藏时休眠；带时区的精确日期会在悬停和键盘聚焦时显示，并作为屏幕阅读器的描述，而更新本身保持静默；纯函数 format() 导出可在服务器端渲染出相同的文本，因此没有 JS 也能正确显示。
| 分类 | 数据展示 |
|---|---|
| 类型 | Web Component（<mv-relative-time>） |
| 状态 | 稳定版 |
| Keywords | exclusive, light, time, date, relative-time, time-ago, intl, i18n, timestamp, ssr |
When to use
- A feed, comment thread or notification list shows when each item happened as “5 minutes ago”
- A table of deploys, orders or tickets needs compact ages that stay current without reloading
- Readers must be able to check the exact date and time zone behind an approximate “2 days ago”
- Server-rendered pages should print the relative time in HTML and keep it fresh once scripts load
Avoid when
- A deadline or event spans time zones and the day shift must be spelled out → use Dateline instead
- The value counts down to a launch or promo with ticking seconds
- The exact timestamp matters more than its age, as in audit logs or invoices
安装
node scripts/add.mjs relative-time --out ./src/marvelous使用 Marvelous UI MCP 服务器的 AI 智能体：install_components({ slugs: ["relative-time"], target_dir: "<absolute path>/src/marvelous", framework: "react" })。
复制的文件（含依赖）：tokens/tokens.css, core/base.css, core/dom.js, core/element.js, core/position.js, components/relative-time/relative-time.js, components/relative-time/relative-time.css。
用法
快速开始，最小可运行标记：
<mv-relative-time datetime="2026-09-24T10:00:00Z"></mv-relative-time>标准标记，可在此基础上通过属性、data-* 和 CSS 变量进行定制：
<div id="mv-relative-time-demo" style="display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,20rem),1fr));gap:1.25rem;width:min(100%,56rem);margin-inline:auto;align-items:start">
<section aria-labelledby="mv-rt-demo-feed" style="border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);overflow:hidden">
<h3 id="mv-rt-demo-feed" style="margin:0;padding:.75rem 1rem;border-bottom:1px solid var(--mv-border);font-size:.875rem;font-weight:600">Notifications</h3>
<ul style="list-style:none;margin:0;padding:.25rem 0;font-size:.875rem;line-height:1.4">
<li style="display:flex;gap:.75rem;padding:.6rem 1rem"><span class="mv-avatar" data-size="sm"><span class="mv-avatar-fallback" aria-hidden="true">AT</span></span><span style="flex:1"><b>Aiko Tanaka</b> commented on <b>Q4 launch checklist</b><br><mv-relative-time data-ago="48" style="color:var(--mv-fg-muted);font-size:.8125rem"></mv-relative-time></span></li>
<li style="display:flex;gap:.75rem;padding:.6rem 1rem"><span class="mv-avatar" data-size="sm"><span class="mv-avatar-fallback" aria-hidden="true">MR</span></span><span style="flex:1"><b>Mateo Rossi</b> approved invoice INV-0042 for $2,450.00<br><mv-relative-time data-ago="200" style="color:var(--mv-fg-muted);font-size:.8125rem"></mv-relative-time></span></li>
<li style="display:flex;gap:.75rem;padding:.6rem 1rem"><span class="mv-avatar" data-size="sm"><span class="mv-avatar-fallback" aria-hidden="true">PN</span></span><span style="flex:1"><b>Priya Nair</b> mentioned you in <b>#design</b><br><mv-relative-time data-ago="7900" style="color:var(--mv-fg-muted);font-size:.8125rem"></mv-relative-time></span></li>
<li style="display:flex;gap:.75rem;padding:.6rem 1rem"><span class="mv-avatar" data-size="sm"><span class="mv-avatar-fallback" aria-hidden="true">LM</span></span><span style="flex:1"><b>Lena Moore</b> shared <b>Brand refresh</b> with you<br><mv-relative-time data-ago="100800" style="color:var(--mv-fg-muted);font-size:.8125rem"></mv-relative-time></span></li>
<li style="display:flex;gap:.75rem;padding:.6rem 1rem"><span class="mv-avatar" data-size="sm"><span class="mv-avatar-fallback" aria-hidden="true">KB</span></span><span style="flex:1"><b>Kwame Boateng</b> joined the workspace<br><mv-relative-time data-ago="1036800" absolute-after="7d" style="color:var(--mv-fg-muted);font-size:.8125rem"></mv-relative-time></span></li>
</ul>
</section>
<div style="display:grid;gap:1.25rem">
<div class="mv-table-wrap">
<table class="mv-table">
<caption>Tab to a time to read the exact date and time zone.</caption>
<thead><tr><th>Environment</th><th>Commit</th><th data-align="end">Deployed</th></tr></thead>
<tbody>
<tr><td>Production</td><td><code>a3f9c1e</code></td><td data-align="end"><mv-relative-time tooltip format="short" data-ago="330"></mv-relative-time></td></tr>
<tr><td>Staging</td><td><code>7d21b04</code></td><td data-align="end"><mv-relative-time tooltip format="short" data-ago="11400"></mv-relative-time></td></tr>
<tr><td>Scheduled</td><td><code>e58a2f7</code></td><td data-align="end"><mv-relative-time tooltip format="short" data-ago="-180000"></mv-relative-time></td></tr>
</tbody>
</table>
</div>
<dl style="display:grid;grid-template-columns:auto 1fr;gap:.45rem 1rem;margin:0;padding:.85rem 1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);font-size:.875rem">
<dt style="color:var(--mv-fg-muted)">long</dt><dd style="margin:0"><mv-relative-time tooltip data-ago="1260"></mv-relative-time></dd>
<dt style="color:var(--mv-fg-muted)">short</dt><dd style="margin:0"><mv-relative-time tooltip format="short" data-ago="1260"></mv-relative-time></dd>
<dt style="color:var(--mv-fg-muted)">narrow</dt><dd style="margin:0"><mv-relative-time tooltip format="narrow" data-ago="1260"></mv-relative-time></dd>
<dt style="color:var(--mv-fg-muted)">lang="fr"</dt><dd style="margin:0" lang="fr"><mv-relative-time tooltip data-ago="172800"></mv-relative-time></dd>
<dt style="color:var(--mv-fg-muted)">lang="ja"</dt><dd style="margin:0" lang="ja"><mv-relative-time tooltip data-ago="-5400"></mv-relative-time></dd>
<dt style="color:var(--mv-fg-muted)">Asia/Tokyo</dt><dd style="margin:0"><mv-relative-time tooltip time-zone="Asia/Tokyo" absolute-after="1d" data-ago="259200"></mv-relative-time></dd>
</dl>
</div>
</div>
<script type="module">
// Demo only: anchor every timestamp to "now" so the demo reads the same any day.
const now = Date.now();
for (const el of document.querySelectorAll("#mv-relative-time-demo [data-ago]")) el.date = now - Number(el.dataset.ago) * 1000;
</script>API
Attributes
| Name | 类型 | Default | Description |
|---|---|---|---|
datetime | string | The moment: an ISO 8601 date or date-time (with an offset or Z), or epoch milliseconds. Without it, the datetime of a child <time> is used (server-rendered markup). | |
format | long | short | narrow | long | Intl style: “3 minutes ago”, “3 min. ago”, “3m ago”. Absolute dates use a medium date (long, short) or a numeric date (narrow). |
absolute-after | span | 30d | Beyond this distance from now (past or future), show the absolute date instead: a number with s, m, h, d, w, mo or y (“7d”, “12h”), or “never”. |
time-zone | IANA zone | Time zone for calendar days, the absolute date and the tooltip (default: the viewer’s). | |
tooltip | boolean | Makes the time a tab stop so keyboard and touch users can open the exact date. Hover works without it; leave it off in long lists to avoid a tab stop per row. | |
lang (inherited) | BCP 47 | Locale comes from the nearest [lang] ancestor, else the browser’s; changing any lang re-localizes every instance. | |
data-mode | relative | absolute | Set by the component (for styling). | |
data-invalid | boolean | Set by the component when the date cannot be parsed (the existing text is kept). |
Properties
| Name | 类型 | Description |
|---|---|---|
date | Date | The moment as a Date; accepts a Date, an ISO string or epoch ms (writes datetime). Can be set before the element is defined. |
locale | string | undefined | Resolved locale (read-only). |
Methods
| Name | Description |
|---|---|
refresh() | Re-render now (rarely needed: the shared scheduler does it). |
format(date, now?, { locale, format, absoluteAfter, timeZone }?) | Named export (and static MvRelativeTime.format): pure, server-safe, returns the same text the element shows. |
formatExact(date, { locale, timeZone }?) | Named export: pure, server-safe exact date, time and zone (“Thursday, September 24, 2026 at 10:00 AM GMT+2”), for a server-side title. |
Content structure
| Name | Description |
|---|---|
time (optional) | A server-rendered <time datetime> child is adopted and kept (its title, the no-JS fallback, is removed once the tooltip takes over). |
CSS classes
| Name | Description |
|---|---|
mv-relative-time-text | The <time> element. |
mv-relative-time-tip / -zone | The exact date bubble (top layer popover) and its time zone chip. |
CSS variables
| Name | Default | Description |
|---|---|---|
--mv-relative-time-tip-bg | light-dark(var(--mv-gray-950), var(--mv-gray-50)) | Bubble background. |
--mv-relative-time-tip-fg | light-dark(var(--mv-gray-50), var(--mv-gray-950)) | Bubble text. |
--mv-relative-time-hint | var(--mv-fg-subtle) | Dotted underline shown on hover (and always with tooltip). |
Accessibility
Renders a real <time datetime> in the light DOM, so the text is plain inline content that screen readers read once, in place. There is no live region: minute-by-minute updates change the text silently, and the DOM is only written when the text actually changes. The exact date, time and time zone (“Thursday, September 24, 2026 at 10:00 AM GMT+2”) is the <time>’s accessible description (aria-describedby to the bubble, which is itself aria-hidden so it is never read twice), announced on focus rather than in the reading flow. With tooltip, the time is a tab stop: focus opens the bubble, Escape closes it, blur closes it, and a tap opens it on touch screens. With a mouse (hover: hover and pointer: fine), the bubble opens after a short delay, stays open while the pointer is over it (the text can be selected) and closes on scroll. Visible focus ring; forced colors give the bubble and chip a CanvasText border; opacity-only entry that the reduced-motion duration tokens make instant. Every string comes from Intl (RelativeTimeFormat, DateTimeFormat) in the inherited lang, so there is nothing to translate by hand and no sentence is assembled from fragments. Server-side, format() and formatExact() produce the same text and a title so the page reads correctly without JS. Known limits: months and years are counted from calendar days (a month is about 30.4 days), so “1 month ago” can differ by a day from a calendar-month reading; the locale is only the nearest lang attribute (there is no locale property), and the words come from the browser's Intl data, so wording can differ slightly between browsers.