Pine/newsui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

-

Browse Source
This commit is contained in:
sunzhongyi
2026-05-19 21:09:56 +08:00
commit f3e6b95be9
78 changed files with 10099 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/docs/app/components/article/page.tsx
+192
View File
@@ -0,0 +1,192 @@
'use client';
import { Demo } from '@/components/Demo';
import { PropsTable } from '@/components/PropsTable';
import { Layout, Section, Article, Headline, BodyText, Subhead } from '@newspaperui/components';
export default function ArticlePage() {
return (
<div className="prose prose-lg max-w-none">
<h1>Article 组件</h1>
<p className="text-xl text-gray-600">
Article 是内容容器组件，用于组织文章内容，支持跨栏布局和优先级控制。
</p>
<h2>组件说明</h2>
<p>
<code>Article</code> 组件是报纸布局中的基本内容单元，可以包含标题、正文、图片等多种内容。
通过 span 属性控制文章占据的列数，实现灵活的跨栏布局。
</p>
<h2>API 文档</h2>
<PropsTable
data={[
{
name: 'span',
type: 'number',
required: true,
description: '文章占据的列数，必须 ≤ 所在 Section 的 columns',
},
{
name: 'priority',
type: 'number',
default: '0',
description: '优先级，数值越大优先级越高，影响排序',
},
{
name: 'weight',
type: '"High" | "Medium" | "Low"',
default: '"Medium"',
description: '视觉权重，影响内部文本组件的默认样式',
},
{
name: 'breakable',
type: 'boolean',
default: 'true',
description: '是否允许在此处分页断开',
},
{
name: 'className',
type: 'string',
description: '自定义 CSS 类名',
},
{
name: 'children',
type: 'React.ReactNode',
required: true,
description: '文章内容',
},
]}
/>
<h2>基础用法</h2>
<Demo
title="单列文章"
description="创建一个占据 8 列的文章"
code={`<Layout columns={24}>
<Section columns={24}>
<Article span={8}>
<Headline weight="High">文章标题</Headline>
<Subhead>副标题说明</Subhead>
<BodyText>
这是文章的正文内容。Article 组件提供了内容容器，
可以包含多种文本和媒体组件。
</BodyText>
</Article>
</Section>
</Layout>`}
>
<Layout columns={24}>
<Section columns={24}>
<Article span={8}>
<Headline weight="High">文章标题</Headline>
<Subhead>副标题说明</Subhead>
<BodyText>
这是文章的正文内容。Article 组件提供了内容容器，
可以包含多种文本和媒体组件。
</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>跨栏布局</h2>
<p>
通过调整 span 属性，可以实现不同宽度的文章布局。较大的 span 值适合重要内容，
较小的 span 值适合次要内容或侧边栏。
</p>
<Demo
title="多列文章并排"
description="在 24 列布局中创建三个 8 列的文章"
code={`<Layout columns={24}>
<Section columns={24}>
<Article span={8}>
<Headline weight="High">主要文章</Headline>
<BodyText>占据 8 列的主要内容</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">次要文章</Headline>
<BodyText>占据 8 列的次要内容</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">更多内容</Headline>
<BodyText>占据 8 列的更多内容</BodyText>
</Article>
</Section>
</Layout>`}
>
<Layout columns={24}>
<Section columns={24}>
<Article span={8}>
<Headline weight="High">主要文章</Headline>
<BodyText>占据 8 列的主要内容，使用 High 权重突出显示。</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">次要文章</Headline>
<BodyText>占据 8 列的次要内容，使用 Medium 权重。</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">更多内容</Headline>
<BodyText>占据 8 列的更多内容，与其他文章并排显示。</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>不同宽度组合</h2>
<Demo
title="混合宽度布局"
description="组合不同宽度的文章实现复杂布局"
code={`<Layout columns={24}>
<Section columns={24}>
<Article span={16}>
<Headline weight="High">宽文章 (16 列)</Headline>
<BodyText>
这是一篇占据 16 列的宽文章，适合放置重要内容或长篇文章。
</BodyText>
</Article>
<Article span={8}>
<Headline weight="Low">窄文章 (8 列)</Headline>
<BodyText>这是占据 8 列的窄文章，适合侧边栏或简短内容。</BodyText>
</Article>
</Section>
</Layout>`}
>
<Layout columns={24}>
<Section columns={24}>
<Article span={16}>
<Headline weight="High">宽文章 (16 列)</Headline>
<BodyText>
这是一篇占据 16 列的宽文章，适合放置重要内容或长篇文章。
更宽的列宽提供了更好的阅读体验。
</BodyText>
</Article>
<Article span={8}>
<Headline weight="Low">窄文章 (8 列)</Headline>
<BodyText>这是占据 8 列的窄文章，适合侧边栏或简短内容。</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>使用建议</h2>
<ul>
<li>主要文章建议使用 12-16 列，提供良好的阅读宽度</li>
<li>次要文章或侧边栏使用 6-8 列</li>
<li>确保同一 Section 内所有 Article 的 span 总和 ≤ Section.columns</li>
<li>使用 priority 属性控制文章的显示顺序</li>
<li>通过 weight 属性影响内部文本组件的默认样式</li>
<li>重要内容使用更大的 span 值以获得更多视觉权重</li>
</ul>
<h2>注意事项</h2>
<ul>
<li>Article 的 span 值必须小于或等于所在 Section 的 columns 值</li>
<li>如果 Section 内多个 Article 的 span 总和超过 Section.columns，会自动换行</li>
<li>在响应式布局中，Article 会根据屏幕尺寸自动调整宽���</li>
<li>breakable 属性在打印或分页场景中很有用</li>
</ul>
</div>
);
}
packages/docs/app/components/layer/page.tsx
+199
View File
@@ -0,0 +1,199 @@
'use client';
import { Demo } from '@/components/Demo';
import { PropsTable } from '@/components/PropsTable';
import { Layout, Section, Article, Layer, Headline, BodyText } from '@newspaperui/components';
export default function LayerPage() {
return (
<div className="prose prose-lg max-w-none">
<h1>Layer 组件</h1>
<p className="text-xl text-gray-600">
Layer 是浮动层组件，支持绝对定位，用于实现浮动广告、拉引、浮动图片等效果。
</p>
<h2>组件说明</h2>
<p>
<code>Layer</code> 组件脱离正常的栅格流，使用绝对定位。
它可以浮动在其他内容之上，常用于实现报纸中的浮动元素，如拉引、浮动广告、浮动图片等。
</p>
<h2>API 文档</h2>
<PropsTable
data={[
{
name: 'position',
type: '"absolute" | "fixed" | "sticky"',
default: '"absolute"',
description: 'CSS position 属性',
},
{
name: 'top',
type: 'string | number',
description: '距离顶部的距离',
},
{
name: 'right',
type: 'string | number',
description: '距离右侧的距离',
},
{
name: 'bottom',
type: 'string | number',
description: '距离底部的距离',
},
{
name: 'left',
type: 'string | number',
description: '距离左侧的距离',
},
{
name: 'zIndex',
type: 'number',
default: '10',
description: 'z-index 层级',
},
{
name: 'className',
type: 'string',
description: '自定义 CSS 类名',
},
{
name: 'children',
type: 'React.ReactNode',
required: true,
description: '浮动层内容',
},
]}
/>
<h2>基础用法</h2>
<Demo
title="浮动拉引"
description="在文章旁边添加浮动的拉引文字"
code={`<Layout columns={24}>
<Section columns={24}>
<div style={{ position: 'relative', minHeight: '300px' }}>
<Article span={16}>
<Headline weight="High">主要文章</Headline>
<BodyText>
这是一篇主要文章的内容。旁边有一个浮动的拉引，
用于突出显示文章中的重要引用或观点。
</BodyText>
</Article>
<Layer position="absolute" top="20px" right="20px" zIndex={10}>
<div className="bg-yellow-50 border-l-4 border-yellow-400 p-4 max-w-xs">
<p className="text-lg font-semibold text-gray-800">
"这是一段重要的引用文字"
</p>
</div>
</Layer>
</div>
</Section>
</Layout>`}
>
<Layout columns={24}>
<Section columns={24}>
<div style={{ position: 'relative', minHeight: '300px' }}>
<Article span={16}>
<Headline weight="High">主要文章</Headline>
<BodyText>
这是一篇主要文章的内容。旁边有一个浮动的拉引，
用于突出显示文章中的重要引用或观点。Layer 组件使用绝对定位，
可以精确控制元素的位置。
</BodyText>
</Article>
<Layer position="absolute" top="20px" right="20px" zIndex={10}>
<div className="bg-yellow-50 border-l-4 border-yellow-400 p-4 max-w-xs">
<p className="text-lg font-semibold text-gray-800">
"这是一段重要的引用文字"
</p>
</div>
</Layer>
</div>
</Section>
</Layout>
</Demo>
<h2>浮动广告</h2>
<Demo
title="侧边浮动广告"
description="在页面侧边添加固定位置的广告"
code={`<Layout columns={24}>
<Section columns={24}>
<div style={{ position: 'relative', minHeight: '400px' }}>
<Article span={18}>
<Headline weight="High">文章内容</Headline>
<BodyText>
这是文章的主要内容区域。右侧有一个浮动的广告位，
使用 Layer 组件实现。
</BodyText>
</Article>
<Layer position="absolute" top="0" right="0" zIndex={5}>
<div className="bg-blue-100 border border-blue-300 p-6 w-48">
<p className="text-center font-bold text-blue-900">广告位</p>
<p className="text-sm text-blue-700 mt-2">300x250</p>
</div>
</Layer>
</div>
</Section>
</Layout>`}
>
<Layout columns={24}>
<Section columns={24}>
<div style={{ position: 'relative', minHeight: '400px' }}>
<Article span={18}>
<Headline weight="High">文章内容</Headline>
<BodyText>
这是文章的主要内容区域。右侧有一个浮动的广告位，
使用 Layer 组件实现。广告不会影响正常的文章布局流。
</BodyText>
<BodyText>
Layer 组件非常适合实现这类需要脱离文档流的元素。
</BodyText>
</Article>
<Layer position="absolute" top="0" right="0" zIndex={5}>
<div className="bg-blue-100 border border-blue-300 p-6 w-48 text-center">
<p className="font-bold text-blue-900">广告位</p>
<p className="text-sm text-blue-700 mt-2">300x250</p>
</div>
</Layer>
</div>
</Section>
</Layout>
</Demo>
<h2>使用建议</h2>
<ul>
<li>Layer 的父容器需要设置 <code>position: relative</code></li>
<li>使用 zIndex 控制多个 Layer 的层叠顺序</li>
<li>浮动元素不应遮挡重要内容</li>
<li>考虑移动端的显示效果，必要时隐藏或调整 Layer</li>
<li>使用 <code>position="fixed"</code> 可以实现固定在视口的效果</li>
<li>使用 <code>position="sticky"</code> 可以实现粘性定位效果</li>
</ul>
<h2>注意事项</h2>
<ul>
<li>Layer 脱离了栅格系统，不受 Section 和 Article 的列数限制</li>
<li>需要手动控制 Layer 的宽度和位置</li>
<li>在响应式设计中，可能需要根据屏幕尺寸调整 Layer 的位置</li>
<li>过多的 Layer 可能影响页面性能和可访问性</li>
<li>确保 Layer 内容在所有屏幕尺寸下都能正常显示</li>
</ul>
<h2>典型应用场景</h2>
<ul>
<li>浮动拉引 - 突出显示文章中的重要引用</li>
<li>浮动广告 - 侧边或角落的广告位</li>
<li>浮动图片 - 文章中的浮动配图</li>
<li>固定导航 - 使用 fixed 定位的导航栏</li>
<li>粘性标题 - 使用 sticky 定位的章节标题</li>
</ul>
</div>
);
}
packages/docs/app/components/media/page.tsx
+271
View File
@@ -0,0 +1,271 @@
'use client';
import { Demo } from '@/components/Demo';
import { PropsTable } from '@/components/PropsTable';
import { Layout, Section, Article, Headline, BodyText } from '@newspaperui/components';
import { Image, Figure } from '@newspaperui/components';
export default function MediaPage() {
return (
<div className="prose prose-lg max-w-none">
<h1>媒体组件</h1>
<p className="text-xl text-gray-600">
NewspaperUI 提供了 Image、Figure 和 Video 组件用于展示媒体内容。
</p>
<h2>Image 组件</h2>
<p>
<code>Image</code> 组件用于显示图片，支持响应式和跨栏布局。
</p>
<PropsTable
data={[
{
name: 'src',
type: 'string',
required: true,
description: '图片 URL',
},
{
name: 'alt',
type: 'string',
required: true,
description: '图片替代文本（无障碍）',
},
{
name: 'span',
type: 'number',
description: '图片占据的列数',
},
{
name: 'aspectRatio',
type: 'string',
default: '"16/9"',
description: '图片宽高比',
},
{
name: 'objectFit',
type: '"cover" | "contain" | "fill"',
default: '"cover"',
description: '图片填充方式',
},
{
name: 'className',
type: 'string',
description: '自定义 CSS 类名',
},
]}
/>
<Demo
title="基础图片"
description="在文章中插入图片"
code={`<Article span={12}>
<Headline weight="High">带图片的文章</Headline>
<Image
src="https://via.placeholder.com/800x600"
alt="示例图片"
span={12}
/>
<BodyText>图片下方的文字说明</BodyText>
</Article>`}
>
<Layout columns={24}>
<Section columns={24}>
<Article span={12}>
<Headline weight="High">带图片的文章</Headline>
<Image
src="https://via.placeholder.com/800x600"
alt="示例图片"
span={12}
/>
<BodyText>图片下方的文字说明</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>Figure 组件</h2>
<p>
<code>Figure</code> 组件是带标题的图片容器，包含图片和图注。
</p>
<PropsTable
data={[
{
name: 'src',
type: 'string',
required: true,
description: '图片 URL',
},
{
name: 'alt',
type: 'string',
required: true,
description: '图片替代文本',
},
{
name: 'caption',
type: 'string',
required: true,
description: '图注文字',
},
{
name: 'span',
type: 'number',
description: 'Figure 占据的列数',
},
{
name: 'aspectRatio',
type: 'string',
default: '"16/9"',
description: '图片宽高比',
},
{
name: 'className',
type: 'string',
description: '自定义 CSS 类名',
},
]}
/>
<Demo
title="带图注的图片"
description="使用 Figure 组件添加图注"
code={`<Article span={12}>
<Headline weight="High">新闻标题</Headline>
<Figure
src="https://via.placeholder.com/800x600"
alt="新闻配图"
caption="这是图片的说明文字，描述图片内容"
span={12}
/>
<BodyText>新闻正文内容...</BodyText>
</Article>`}
>
<Layout columns={24}>
<Section columns={24}>
<Article span={12}>
<Headline weight="High">新闻标题</Headline>
<Figure
src="https://via.placeholder.com/800x600"
alt="新闻配图"
caption="这是图片的说明文字，描述图片内容"
span={12}
/>
<BodyText>新闻正文内容...</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>Video 组件</h2>
<p>
<code>Video</code> 组件用于嵌入视频内容。
</p>
<PropsTable
data={[
{
name: 'src',
type: 'string',
required: true,
description: '视频 URL',
},
{
name: 'poster',
type: 'string',
description: '视频封面图片 URL',
},
{
name: 'span',
type: 'number',
description: '视频占据的列数',
},
{
name: 'controls',
type: 'boolean',
default: 'true',
description: '是否显示控制条',
},
{
name: 'autoPlay',
type: 'boolean',
default: 'false',
description: '是否自动播放',
},
{
name: 'loop',
type: 'boolean',
default: 'false',
description: '是否循环播放',
},
{
name: 'muted',
type: 'boolean',
default: 'false',
description: '是否静音',
},
{
name: 'className',
type: 'string',
description: '自定义 CSS 类名',
},
]}
/>
<Demo
title="嵌入视频"
description="在文章中嵌入视频内容"
code={`<Article span={16}>
<Headline weight="High">视频新闻</Headline>
<Video
src="https://example.com/video.mp4"
poster="https://via.placeholder.com/800x450"
span={16}
controls
/>
<BodyText>视频相关的文字说明...</BodyText>
</Article>`}
>
<Layout columns={24}>
<Section columns={24}>
<Article span={16}>
<Headline weight="High">视频新闻</Headline>
<div className="bg-gray-200 aspect-video flex items-center justify-center">
<p className="text-gray-600">视频播放器占位</p>
</div>
<BodyText>视频相关的文字说明...</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>使用建议</h2>
<ul>
<li>使用 Image 组件展示简单图片</li>
<li>使用 Figure 组件为图片添加说明文字</li>
<li>使用 Video 组件嵌入视频内容</li>
<li>通过 span 属性控制媒体元素的宽度</li>
<li>设置合适的 aspectRatio 保持图片比例</li>
<li>始终提供 alt 文本以提高无障碍性</li>
<li>考虑图片和视频的加载性能</li>
</ul>
<h2>响应式媒体</h2>
<p>
媒体组件会根据容器宽度自动调整大小。在小屏设备上，
媒体元素会自动适应屏幕宽度，保持良好的显示效果。
</p>
<h2>性能优化</h2>
<ul>
<li>使用适当的图片格式（WebP、AVIF）</li>
<li>提供多种尺寸的图片用于响应式加载</li>
<li>使用懒加载（lazy loading）优化页面性能</li>
<li>压缩图片和视频文件大小</li>
<li>考虑使用 CDN 加速媒体资源加载</li>
</ul>
</div>
);
}
packages/docs/app/examples/responsive/page.tsx
+251
View File
@@ -0,0 +1,251 @@
'use client';
import { Demo } from '@/components/Demo';
import { Layout, Section, Article } from '@newspaperui/components';
import { Headline, BodyText } from '@newspaperui/components';
export default function ResponsivePage() {
return (
<div className="prose prose-lg max-w-none">
<h1>响应式布局示例</h1>
<p className="text-xl text-gray-600">
展示 NewspaperUI 如何在不同屏幕尺寸下自动调整布局。
</p>
<h2>响应式原理</h2>
<p>
NewspaperUI 的响应式系统基于栅格列数的动态调整。在不同的屏幕尺寸下，
栅格系统会自动调整列数，确保内容在各种设备上都能良好显示。
</p>
<div className="bg-blue-50 border-l-4 border-blue-400 p-4 my-6">
<h3 className="text-lg font-semibold text-blue-900 mt-0">响应式断点</h3>
<ul className="mb-0 text-blue-800">
<li><strong>大屏（≥1024px）</strong>: 24 列</li>
<li><strong>中屏（768px-1023px）</strong>: 16 列</li>
<li><strong>小屏（&lt;768px）</strong>: 12 列</li>
</ul>
</div>
<h2>自适应布局示例</h2>
<p>
以下示例展示了布局如何在不同屏幕尺寸下自动调整。
尝试调整浏览器窗口大小查看效果。
</p>
<Demo
title="响应式三栏布局"
description="大屏显示三栏，中屏显示两栏，小屏显示单栏"
code={`<Layout columns={24}>
<Section columns={24}>
{/* 大屏: 8+8+8, 中屏: 12+12, 小屏: 24 */}
<Article span={8} className="lg:span-8 md:span-12 sm:span-24">
<Headline weight="Medium">第一栏</Headline>
<BodyText>内容自动适应屏幕宽度</BodyText>
</Article>
<Article span={8} className="lg:span-8 md:span-12 sm:span-24">
<Headline weight="Medium">第二栏</Headline>
<BodyText>响应式布局</BodyText>
</Article>
<Article span={8} className="lg:span-8 md:span-12 sm:span-24">
<Headline weight="Medium">第三栏</Headline>
<BodyText>自动换行</BodyText>
</Article>
</Section>
</Layout>`}
>
<Layout columns={24}>
<Section columns={24}>
<Article span={8}>
<Headline weight="Medium">科技新闻</Headline>
<BodyText>
在大屏上，这三栏并排显示。在中屏上，变为两栏布局。
在小屏上，每栏占据全宽，垂直堆叠。
</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">财经要闻</Headline>
<BodyText>
响应式布局确保内容在所有设备上都能良好显示，
提供最佳的阅读体验。
</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">文化艺术</Headline>
<BodyText>
NewspaperUI 的响应式系统会自动处理列宽调整，
无需手动编写复杂的媒体查询。
</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>主次内容响应式</h2>
<p>
在响应式布局中，主要内容和次要内容的比例也会自动调整。
</p>
<Demo
title="主次内容自适应"
description="大屏 16+8，中屏 12+12，小屏全宽堆叠"
code={`<Layout columns={24}>
<Section columns={24}>
<Article span={16}>
<Headline weight="High">主要内容</Headline>
<BodyText weight="High">
主要内容在大屏占据 16 列，在中屏占据 12 列，
在小屏占据全宽。
</BodyText>
</Article>
<Article span={8}>
<Headline weight="Low">侧边栏</Headline>
<BodyText weight="Low">
侧边栏在大屏占据 8 列，在中屏占据 12 列，
在小屏移到主内容下方。
</BodyText>
</Article>
</Section>
</Layout>`}
>
<Layout columns={24}>
<Section columns={24}>
<Article span={16}>
<Headline weight="High">深度报道</Headline>
<BodyText weight="High">
这是主要内容区域，在大屏幕上占据较大的空间。
当屏幕变小时，布局会自动调整以保持良好的可读性。
</BodyText>
<BodyText>
响应式设计确保用户在任何设备上都能获得最佳的阅读体验。
</BodyText>
</Article>
<Article span={8}>
<Headline weight="Low">相关链接</Headline>
<BodyText weight="Low">
• 相关文章 1<br />
• 相关文章 2<br />
• 相关文章 3<br />
• 更多内容...
</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>移动优先设计</h2>
<p>
NewspaperUI 采用移动优先的设计理念，确保内容在小屏设备上也能完美呈现。
</p>
<Demo
title="移动优先布局"
description="小屏优化的单栏布局"
>
<Layout columns={24}>
<Section columns={24}>
<Article span={24}>
<Headline weight="High">移动端标题</Headline>
<BodyText>
在移动设备上，内容占据全宽，提供最佳的阅读体验。
字体大小和行高也会根据屏幕尺寸自动调整。
</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>响应式图片</h2>
<p>
图片和媒体元素也会根据容器宽度自动调整大小。
</p>
<Demo
title="响应式媒体"
description="图片自动适应容器宽度"
>
<Layout columns={24}>
<Section columns={24}>
<Article span={16}>
<Headline weight="High">带图片的文章</Headline>
<div className="bg-gray-200 aspect-video flex items-center justify-center my-4">
<span className="text-gray-600">响应式图片占位</span>
</div>
<BodyText>
图片会根据容器宽度自动缩放，保持宽高比不变。
</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>响应式最佳实践</h2>
<ul>
<li>使用相对单位（rem、em）而不是绝对单位（px）</li>
<li>在小屏设备上简化布局，避免过多的列</li>
<li>确保文字大小在移动设备上足够大（至少 16px）</li>
<li>触摸目标（按钮、链接）至少 44x44px</li>
<li>测试不同设备和屏幕尺寸的显示效果</li>
<li>考虑横屏和竖屏两种方向</li>
<li>优化图片和媒体资源的加载性能</li>
</ul>
<h2>测试响应式布局</h2>
<p>
建议在以下设备和尺寸上测试响应式布局：
</p>
<div className="grid grid-cols-1 md:grid-cols-3 gap-4 my-6">
<div className="border border-gray-200 rounded-lg p-4">
<h3 className="text-lg font-semibold mb-2">移动设备</h3>
<ul className="text-sm space-y-1 mb-0">
<li>iPhone SE (375px)</li>
<li>iPhone 12/13 (390px)</li>
<li>iPhone 14 Pro Max (430px)</li>
<li>Android 小屏 (360px)</li>
</ul>
</div>
<div className="border border-gray-200 rounded-lg p-4">
<h3 className="text-lg font-semibold mb-2">平板设备</h3>
<ul className="text-sm space-y-1 mb-0">
<li>iPad Mini (768px)</li>
<li>iPad (810px)</li>
<li>iPad Pro (1024px)</li>
<li>Android 平板 (800px)</li>
</ul>
</div>
<div className="border border-gray-200 rounded-lg p-4">
<h3 className="text-lg font-semibold mb-2">桌面设备</h3>
<ul className="text-sm space-y-1 mb-0">
<li>笔记本 (1366px)</li>
<li>桌面 (1920px)</li>
<li>大屏 (2560px)</li>
<li>超宽屏 (3440px)</li>
</ul>
</div>
</div>
<h2>调试工具</h2>
<p>
使用浏览器开发者工具的响应式设计模式测试不同屏幕尺寸：
</p>
<ul>
<li><strong>Chrome DevTools</strong>: Cmd/Ctrl + Shift + M</li>
<li><strong>Firefox</strong>: Cmd/Ctrl + Shift + M</li>
<li><strong>Safari</strong>: Develop → Enter Responsive Design Mode</li>
</ul>
<h2>性能优化</h2>
<ul>
<li>使用懒加载（lazy loading）延迟加载图片</li>
<li>提供不同尺寸的图片用于不同设备</li>
<li>使用现代图片格式（WebP、AVIF）</li>
<li>压缩和优化资源文件</li>
<li>使用 CDN 加速资源加载</li>
<li>减少不必要的 JavaScript 和 CSS</li>
</ul>
</div>
);
}
packages/docs/app/examples/spanning/page.tsx
+267
View File
@@ -0,0 +1,267 @@
'use client';
import { Demo } from '@/components/Demo';
import { Layout, Section, Article, Layer } from '@newspaperui/components';
import { Headline, Subhead, BodyText, Quote } from '@newspaperui/components';
export default function SpanningPage() {
return (
<div className="prose prose-lg max-w-none">
<h1>跨栏布局示例</h1>
<p className="text-xl text-gray-600">
展示如何使用 NewspaperUI 实现复杂的跨栏报纸布局。
</p>
<h2>经典报纸头版布局</h2>
<p>
这是一个典型的报纸头版布局，包含主要新闻、次要新闻和浮动拉引。
</p>
<Demo
title="报纸头版"
description="主新闻占据 16 列，侧边栏占据 8 列，带浮动拉引"
code={`<Layout columns={24}>
<Section columns={24}>
<div style={{ position: 'relative', minHeight: '600px' }}>
{/* 主新闻 - 16 列 */}
<Article span={16}>
<Headline weight="High">重大新闻标题占据主要版面</Headline>
<Subhead weight="High">
副标题提供更多背景信息和上下文
</Subhead>
<BodyText weight="High">
这是主要新闻的正文内容。在报纸布局中，最重要的新闻通常占据最大的版面，
使用最大的字号和最粗的字重。这样的布局能够立即吸引读者的注意力。
</BodyText>
<BodyText>
新闻的后续段落继续详细描述事件的发展。通过合理的跨栏布局，
我们可以在有限的版面中呈现丰富的内容。
</BodyText>
</Article>
{/* 侧边栏 - 8 列 */}
<Article span={8}>
<Headline weight="Medium">次要新闻</Headline>
<BodyText weight="Medium">
侧边栏的新闻使用较小的字号，适合放置次要但仍然重要的内容。
</BodyText>
</Article>
{/* 浮动拉引 */}
<Layer position="absolute" top="100px" right="20px" zIndex={10}>
<div className="bg-yellow-50 border-l-4 border-yellow-400 p-4 max-w-xs">
<Quote weight="High">
"这是一段重要的引用，用于突出文章中的关键观点"
</Quote>
</div>
</Layer>
</div>
</Section>
</Layout>`}
>
<Layout columns={24}>
<Section columns={24}>
<div style={{ position: 'relative', minHeight: '600px' }}>
<Article span={16}>
<Headline weight="High">重大新闻标题占据主要版面</Headline>
<Subhead weight="High">
副标题提供更多背景信息和上下文
</Subhead>
<BodyText weight="High">
这是主要新闻的正文内容。在报纸布局中，最重要的新闻通常占据最大的版面，
使用最大的字号和最粗的字重。这样的布局能够立即吸引读者的注意力。
</BodyText>
<BodyText>
新闻的后续段落继续详细描述事件的发展。通过合理的跨栏布局，
我们可以在有限的版面中呈现丰富的内容。
</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">次要新闻</Headline>
<BodyText weight="Medium">
侧边栏的新闻使用较小的字号，适合放置次要但仍然重要的内容。
</BodyText>
</Article>
<Layer position="absolute" top="100px" right="20px" zIndex={10}>
<div className="bg-yellow-50 border-l-4 border-yellow-400 p-4 max-w-xs">
<Quote weight="High">
"这是一段重要的引用，用于突出文章中的关键观点"
</Quote>
</div>
</Layer>
</div>
</Section>
</Layout>
</Demo>
<h2>三栏等宽布局</h2>
<p>
将 24 列平均分为三个 8 列的区域，适合展示多个同等重要的内容。
</p>
<Demo
title="三栏布局"
description="三个 8 列的文章并排显示"
code={`<Layout columns={24}>
<Section columns={24}>
<Article span={8}>
<Headline weight="Medium">第一栏标题</Headline>
<BodyText>第一栏的内容...</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">第二栏标题</Headline>
<BodyText>第二栏的内容...</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">第三栏标题</Headline>
<BodyText>第三栏的内容...</BodyText>
</Article>
</Section>
</Layout>`}
>
<Layout columns={24}>
<Section columns={24}>
<Article span={8}>
<Headline weight="Medium">科技新闻</Headline>
<BodyText>
最新的科技动态和创新成果，展示技术发展的最新趋势。
</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">财经要闻</Headline>
<BodyText>
市场动态和经济分析，帮助读者了解财经领域的重要信息。
</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">文化艺术</Headline>
<BodyText>
文化活动和艺术展览，丰富读者的精神文化生活。
</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>不对称布局</h2>
<p>
使用不同的列宽组合创建视觉层次，突出重要内容。
</p>
<Demo
title="12 + 12 列布局"
description="两个等宽的 12 列区域"
code={`<Layout columns={24}>
<Section columns={24}>
<Article span={12}>
<Headline weight="High">左侧主要内容</Headline>
<BodyText weight="High">
占据 12 列的主要内容区域...
</BodyText>
</Article>
<Article span={12}>
<Headline weight="High">右侧主要内容</Headline>
<BodyText weight="High">
同样占据 12 列的内容区域...
</BodyText>
</Article>
</Section>
</Layout>`}
>
<Layout columns={24}>
<Section columns={24}>
<Article span={12}>
<Headline weight="High">深度报道：城市发展</Headline>
<BodyText weight="High">
这是一篇深度报道，详细分析城市发展的现状和未来趋势。
12 列的宽度提供了良好的阅读体验。
</BodyText>
</Article>
<Article span={12}>
<Headline weight="High">专题调查：环境保护</Headline>
<BodyText weight="High">
环境保护专题调查报告，展示环保工作的成果和挑战。
与左��内容形成对比和呼应。
</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>复杂混合布局</h2>
<p>
组合多种列宽，创建丰富的视觉层次和内容结构。
</p>
<Demo
title="混合列宽布局"
description="6 + 12 + 6 列的组合布局"
code={`<Layout columns={24}>
<Section columns={24}>
<Article span={6}>
<Headline weight="Low">侧边栏</Headline>
<BodyText weight="Low">简短内容</BodyText>
</Article>
<Article span={12}>
<Headline weight="High">主要内容</Headline>
<BodyText>详细的主要内容...</BodyText>
</Article>
<Article span={6}>
<Headline weight="Low">另一侧边栏</Headline>
<BodyText weight="Low">补充信息</BodyText>
</Article>
</Section>
</Layout>`}
>
<Layout columns={24}>
<Section columns={24}>
<Article span={6}>
<Headline weight="Low">快讯</Headline>
<BodyText weight="Low">
• 新闻 1<br />
• 新闻 2<br />
• 新闻 3
</BodyText>
</Article>
<Article span={12}>
<Headline weight="High">今日焦点</Headline>
<BodyText>
主要新闻内容占据中间的 12 列，提供充足的空间展示详细信息。
两侧的 6 列侧边栏提供补充内容和快讯。
</BodyText>
</Article>
<Article span={6}>
<Headline weight="Low">相关链接</Headline>
<BodyText weight="Low">
• 链接 1<br />
• 链接 2<br />
• 链接 3
</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>布局技巧</h2>
<ul>
<li>使用较大的 span 值（12-16 列）突出重要内容</li>
<li>侧边栏使用较小的 span 值（4-8 列）</li>
<li>保持布局的平衡感，避免过于拥挤或空旷</li>
<li>使用浮动 Layer 添加视觉亮点</li>
<li>通过视觉权重系统创建清晰的信息层次</li>
<li>考虑内容的重要性和阅读顺序</li>
</ul>
<h2>注意事项</h2>
<ul>
<li>确保所有 Article 的 span 总和不超过 Section 的 columns</li>
<li>在小屏设备上测试布局的响应式效果</li>
<li>避免过多的跨栏，保持布局的可读性</li>
<li>使用一致的列宽比例，如 8:16、6:12:6 等</li>
<li>浮动元素不要遮挡重要内容</li>
</ul>
</div>
);
}
packages/docs/app/globals.css
+35
View File
@@ -0,0 +1,35 @@
@import '@newspaperui/theme/variables.css';
@tailwind base;
@tailwind components;
@tailwind utilities;
@layer base {
body {
@apply bg-white text-gray-900;
}
h1 {
@apply text-4xl font-bold mb-4;
}
h2 {
@apply text-3xl font-semibold mt-8 mb-4;
}
h3 {
@apply text-2xl font-semibold mt-6 mb-3;
}
p {
@apply mb-4 leading-relaxed;
}
code {
@apply text-sm bg-gray-100 px-1.5 py-0.5 rounded;
}
pre code {
@apply bg-transparent p-0;
}
}
packages/docs/app/grid-system/page.tsx
+209
View File
@@ -0,0 +1,209 @@
'use client';
import { Demo } from '@/components/Demo';
import { PropsTable } from '@/components/PropsTable';
import { Layout, Section, Article, Headline, BodyText } from '@newspaperui/components';
export default function GridSystemPage() {
return (
<div className="prose prose-lg max-w-none">
<h1>栅格系统</h1>
<p className="text-xl text-gray-600">
NewspaperUI 采用 24 列栅格系统，提供灵活而精确的布局控制能力。
</p>
<h2>设计原理</h2>
<p>
24 列栅格系统借鉴了专业排版软件的设计思想，相比传统的 12 列��格��24 列提供了更细粒度的布局控制。
这使得我们可以实现更复杂的报纸风格布局，如 1/3、2/3、1/4、3/4 等多种列宽组合。
</p>
<h2>Layout 组件</h2>
<p>
<code>Layout</code> 是顶层容器组件，定义了整个页面的栅格系统。
</p>
<PropsTable
data={[
{
name: 'columns',
type: 'number',
default: '24',
description: '栅格总列数，默认 24 列',
},
{
name: 'maxWidth',
type: 'string',
default: '"1440px"',
description: '容器最大宽度',
},
{
name: 'gutter',
type: 'number',
default: '16',
description: '列间距（单位 px）',
},
{
name: 'padding',
type: 'string',
default: '"1rem"',
description: '容器内边距',
},
{
name: 'className',
type: 'string',
description: '自定义 CSS 类名',
},
]}
/>
<Demo
title="基础 Layout"
description="创建一个 24 列的栅格容器"
code={`<Layout columns={24}>
{/* 内容 */}
</Layout>`}
>
<Layout columns={24}>
<div className="bg-blue-50 border-2 border-blue-200 p-4 text-center">
24 列栅格容器
</div>
</Layout>
</Demo>
<h2>Section 组件</h2>
<p>
<code>Section</code> 组件用于将 Layout 划分为多个区域，每个 Section 可以占据不同的列数。
Section 内的所有对象的 span 总和不能超过 Section 的 columns 值。
</p>
<PropsTable
data={[
{
name: 'columns',
type: 'number',
required: true,
description: 'Section 占据的列数，必须 ≤ Layout.columns',
},
{
name: 'breakable',
type: 'boolean',
default: 'true',
description: '是否允许在此处分页断开',
},
{
name: 'priority',
type: "'High' | 'Medium' | 'Low'",
default: "'Medium'",
description: '优先级，用于排序',
},
{
name: 'className',
type: 'string',
description: '自定义 CSS 类名',
},
]}
/>
<Demo
title="多 Section 布局"
description="将 24 列划分为 8 列和 16 列两个区域"
code={`<Layout columns={24}>
<Section columns={8}>
<Article span={8}>
<Headline weight="High">8 列区域</Headline>
<BodyText>这个区域占据 8 列</BodyText>
</Article>
</Section>
<Section columns={16}>
<Article span={8}>
<Headline weight="Medium">16 列区域 - 左</Headline>
<BodyText>这个区域占据 16 列，分为两个 8 列文章</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">16 列区域 - 右</Headline>
<BodyText>第二个 8 列文章</BodyText>
</Article>
</Section>
</Layout>`}
>
<Layout columns={24}>
<Section columns={8}>
<Article span={8}>
<Headline weight="High">8 列区域</Headline>
<BodyText>这个区域占据 8 列，适合放置主要内容或大图。</BodyText>
</Article>
</Section>
<Section columns={16}>
<Article span={8}>
<Headline weight="Medium">16 列区域 - 左</Headline>
<BodyText>这个区域占据 16 列，分为两个 8 列文章。</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">16 列区域 - 右</Headline>
<BodyText>第二个 8 列文章，与左侧并排显示。</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>响应式栅格</h2>
<p>
在小屏设备上，栅格系统会自动调整为 12-16 列，确保内容在移动设备上也能良好显示。
你可以通过 CSS 媒体查询或响应式工具类来进一步控制不同屏幕尺寸下的布局。
</p>
<Demo
title="响应式栅格示例"
description="在不同屏幕尺寸下自动调整列数"
>
<Layout columns={24}>
<Section columns={6}>
<Article span={6}>
<Headline weight="Low">6 列</Headline>
<BodyText>小屏下可能变为全宽</BodyText>
</Article>
</Section>
<Section columns={6}>
<Article span={6}>
<Headline weight="Low">6 列</Headline>
<BodyText>自动适应屏幕</BodyText>
</Article>
</Section>
<Section columns={6}>
<Article span={6}>
<Headline weight="Low">6 列</Headline>
<BodyText>保持良好阅读体验</BodyText>
</Article>
</Section>
<Section columns={6}>
<Article span={6}>
<Headline weight="Low">6 列</Headline>
<BodyText>响应式布局</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>布局规则</h2>
<ul>
<li>Layout 的 columns 属性定义了整个页面的栅格总列数（默认 24）</li>
<li>Section 的 columns 属性必须 ≤ Layout 的 columns</li>
<li>Section 内所有对象的 span 总和必须 ≤ Section 的 columns</li>
<li>对象可以通过 span 属性跨越多列</li>
<li>小屏设备会自动调整为 12-16 列</li>
</ul>
<h2>最佳实践</h2>
<ul>
<li>使用 24 列栅格可以实现 1/2、1/3、1/4、1/6、1/8 等多种比例</li>
<li>主要内容区域建议使用 8-16 列</li>
<li>侧边栏或次要内容使用 4-8 列</li>
<li>重要内容可以跨越更多列以获得更大的视觉权重</li>
<li>保持 Section 之间的列数比例协调，如 8:16、6:18、12:12 等</li>
</ul>
</div>
);
}
packages/docs/app/layout.tsx
+29
View File
@@ -0,0 +1,29 @@
import type { Metadata } from 'next';
import { Sidebar } from '@/components/Sidebar';
import './globals.css';
export const metadata: Metadata = {
title: 'NewspaperUI - Documentation',
description: 'A newspaper-style UI component library',
};
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="zh-CN">
<body className="antialiased">
<div className="flex min-h-screen">
<Sidebar />
<main className="flex-1 overflow-x-hidden">
<div className="max-w-5xl mx-auto px-8 py-12">
{children}
</div>
</main>
</div>
</body>
</html>
);
}
packages/docs/app/page.tsx
+102
View File
@@ -0,0 +1,102 @@
'use client';
import { Demo } from '@/components/Demo';
import { Layout, Section, Article } from '@newspaperui/components';
import { Headline, BodyText } from '@newspaperui/components';
export default function HomePage() {
return (
<div className="prose prose-lg max-w-none">
<h1>NewspaperUI</h1>
<p className="text-xl text-gray-600">
生产级报纸布局组件库，参考 InDesign 设计理念，支持 24 列栅格、跨栏、视觉权重和主题系统。
</p>
<h2>设计理念</h2>
<p>
NewspaperUI 借鉴专业排版软件 InDesign 的设计思想，为 Web 应用提供报纸风格的布局能力。
组件设计遵循少而精、职责明确、无冗余、无歧义的原则。
</p>
<h2>核心特性</h2>
<ul>
<li><strong>24 列栅格系统</strong> - 灵活的栅格布局，支持精确的列控制</li>
<li><strong>跨栏布局</strong> - 内容可以跨越多列，实现复杂的报纸排版</li>
<li><strong>视觉权重系统</strong> - High/Medium/Low 三级权重，自动映射字体大小和样式</li>
<li><strong>主题系统</strong> - 基于 CSS Variables，支持主题切换和自定义</li>
<li><strong>响应式设计</strong> - 小屏自动调整为 12-16 列，保持良好的阅读体验</li>
<li><strong>浮动 Layer</strong> - 支持绝对定位的浮动元素，如广告、拉引等</li>
</ul>
<h2>快速开始</h2>
<h3>安装</h3>
<pre className="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto">
<code>pnpm add @newspaperui/components @newspaperui/theme</code>
</pre>
<h3>基础使用</h3>
<Demo
title="简单的报纸布局"
description="使用 Layout 和 Section 创建基础的栅格布局"
code={`import { Layout, Section, Article, Headline, BodyText } from '@newspaperui/components';
function MyPage() {
return (
<Layout columns={24}>
<Section columns={8}>
<Article span={8}>
<Headline weight="High">主要新闻标题</Headline>
<BodyText>这是一篇重要的新闻内容...</BodyText>
</Article>
</Section>
<Section columns={16}>
<Article span={8}>
<Headline weight="Medium">次要新闻</Headline>
<BodyText>这是另一篇新闻...</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">更多新闻</Headline>
<BodyText>更多内容...</BodyText>
</Article>
</Section>
</Layout>
);
}`}
>
<Layout columns={24}>
<Section columns={8}>
<Article span={8}>
<Headline weight="High">主要新闻标题</Headline>
<BodyText>这是一篇重要的新闻内容，使用 High 权重的标题和正文文本。</BodyText>
</Article>
</Section>
<Section columns={16}>
<Article span={8}>
<Headline weight="Medium">次要新闻</Headline>
<BodyText>这是另一篇新闻，使用 Medium 权重。</BodyText>
</Article>
<Article span={8}>
<Headline weight="Medium">更多新闻</Headline>
<BodyText>更多内容在这里展示。</BodyText>
</Article>
</Section>
</Layout>
</Demo>
<h2>下一步</h2>
<p>
探索文档了解更多功能：
</p>
<ul>
<li><a href="/grid-system">栅格系统</a> - 了解 24 列栅格的工作原理</li>
<li><a href="/components/article">核心组件</a> - 学习 Article、Layer 等核心组件</li>
<li><a href="/text">文本组件</a> - 掌握视觉权重系统</li>
<li><a href="/theme">主题系统</a> - 自定义主题和样式</li>
<li><a href="/examples/spanning">示例</a> - 查看完整的布局示例</li>
</ul>
</div>
);
}
packages/docs/app/text/page.tsx
+334
View File
@@ -0,0 +1,334 @@
'use client';
import { Demo } from '@/components/Demo';
import { PropsTable } from '@/components/PropsTable';
import { Headline, Subhead, BodyText, Quote, Byline, Caption } from '@newspaperui/components';
export default function TextPage() {
return (
<div className="prose prose-lg max-w-none">
<h1>文本组件</h1>
<p className="text-xl text-gray-600">
NewspaperUI 提供了完整的文本组件体系，支持视觉权重系统，自动映射字体大小和样式。
</p>
<h2>视觉权重系统</h2>
<p>
视觉权重（Visual Weight）是 NewspaperUI 的核心特性之一。
通过 High、Medium、Low 三级权重，组件会自动应用对应的字体大小、粗细、行高和颜色。
</p>
<h2>Headline 组件</h2>
<p>
<code>Headline</code> 是标题组件，支持三级视觉权重。
</p>
<PropsTable
data={[
{
name: 'weight',
type: '"High" | "Medium" | "Low"',
default: '"Medium"',
description: '视觉权重级别',
},
{
name: 'as',
type: '"h1" | "h2" | "h3" | "h4" | "h5" | "h6"',
default: '"h2"',
description: 'HTML 标签类型',
},
{
name: 'className',
type: 'string',
description: '自定义 CSS 类名',
},
{
name: 'children',
type: 'React.ReactNode',
required: true,
description: '标题内容',
},
]}
/>
<Demo
title="标题视觉权重"
description="展示不同权重的标题效果"
code={`<Headline weight="High">High 权重标题</Headline>
<Headline weight="Medium">Medium 权重标题</Headline>
<Headline weight="Low">Low 权重标题</Headline>`}
>
<div className="space-y-4">
<Headline weight="High">High 权重标题 (36-48px, 700)</Headline>
<Headline weight="Medium">Medium 权重标题 (28-34px, 600)</Headline>
<Headline weight="Low">Low 权重标题 (22-26px, 500)</Headline>
</div>
</Demo>
<h2>Subhead 组件</h2>
<p>
<code>Subhead</code> 是副标题组件，用于补充说明主标题。
</p>
<PropsTable
data={[
{
name: 'weight',
type: '"High" | "Medium"',
default: '"Medium"',
description: '视觉权重级别',
},
{
name: 'className',
type: 'string',
description: '自定义 CSS 类名',
},
{
name: 'children',
type: 'React.ReactNode',
required: true,
description: '副标题内容',
},
]}
/>
<Demo
title="副标题示例"
description="标题和副标题的组合使用"
code={`<Headline weight="High">主标题</Headline>
<Subhead weight="High">副标题说明文字</Subhead>
<BodyText>正文内容...</BodyText>`}
>
<div className="space-y-2">
<Headline weight="High">重大新闻事件</Headline>
<Subhead weight="High">详细的副标题说明，提供更多上下文信息</Subhead>
<BodyText>正文内容从这里开始，详细描述新闻事件的来龙去脉...</BodyText>
</div>
</Demo>
<h2>BodyText 组件</h2>
<p>
<code>BodyText</code> 是正文文本组件，用于文章主体内容。
</p>
<PropsTable
data={[
{
name: 'weight',
type: '"High" | "Medium" | "Low"',
default: '"Medium"',
description: '视觉权重级别',
},
{
name: 'className',
type: 'string',
description: '自定义 CSS 类名',
},
{
name: 'children',
type: 'React.ReactNode',
required: true,
description: '正文内容',
},
]}
/>
<Demo
title="正文文本权重"
description="不同权重的正文文本"
code={`<BodyText weight="High">High 权重正文 (16px)</BodyText>
<BodyText weight="Medium">Medium 权重正文 (14-15px)</BodyText>
<BodyText weight="Low">Low 权重正文 (12-14px)</BodyText>`}
>
<div className="space-y-3">
<BodyText weight="High">
High 权重正文文本，字号 16px，适合重要段落或引言。
</BodyText>
<BodyText weight="Medium">
Medium 权重正文文本，字号 14-15px，适合常规正文内容。
</BodyText>
<BodyText weight="Low">
Low 权重正文文本，字号 12-14px，适合次要说明或注释。
</BodyText>
</div>
</Demo>
<h2>Quote 组件</h2>
<p>
<code>Quote</code> 是引用组件，用于突出显示引用内容。
</p>
<PropsTable
data={[
{
name: 'weight',
type: '"High" | "Medium"',
default: '"Medium"',
description: '视觉权重级别',
},
{
name: 'className',
type: 'string',
description: '自定义 CSS 类名',
},
{
name: 'children',
type: 'React.ReactNode',
required: true,
description: '引用内容',
},
]}
/>
<Demo
title="引用文本"
description="在文章中插入引用"
code={`<Quote weight="High">
这是一段重要的引用文字，来自某位专家的观点。
</Quote>`}
>
<Quote weight="High">
这是一段重要的引用文字，来自某位专家的观点。引用组件会自动添加引号样式。
</Quote>
</Demo>
<h2>Byline 和 Caption 组件</h2>
<p>
<code>Byline</code> 用于作者署名，<code>Caption</code> 用于图片说明。
</p>
<PropsTable
data={[
{
name: 'className',
type: 'string',
description: '自定义 CSS 类名',
},
{
name: 'children',
type: 'React.ReactNode',
required: true,
description: '文本内容',
},
]}
/>
<Demo
title="署名和图注"
description="使用 Byline 和 Caption"
code={`<Headline weight="High">文章标题</Headline>
<Byline>作者：张三 | 2024年1月1日</Byline>
<BodyText>文章内容...</BodyText>
<Caption>图1：示例图片的说明文字</Caption>`}
>
<div className="space-y-2">
<Headline weight="High">重要新闻标题</Headline>
<Byline>记者：张三 | 2024年1月1日 | 北京报道</Byline>
<BodyText>文章正文内容从这里开始...</BodyText>
<div className="bg-gray-200 h-32 flex items-center justify-center">
<span className="text-gray-500">图片占位</span>
</div>
<Caption>图1：新闻现场照片，展示事件发生时的情况</Caption>
</div>
</Demo>
<h2>视觉权重映射表</h2>
<p>
以下是完整的视觉权重映射规则（基于 24 列栅格）：
</p>
<div className="my-6 overflow-x-auto">
<table className="w-full border-collapse text-sm">
<thead>
<tr className="border-b-2 border-gray-300">
<th className="text-left py-2 px-3">组件</th>
<th className="text-left py-2 px-3">权重</th>
<th className="text-left py-2 px-3">字号</th>
<th className="text-left py-2 px-3">字重</th>
<th className="text-left py-2 px-3">行高</th>
<th className="text-left py-2 px-3">颜色</th>
</tr>
</thead>
<tbody className="text-sm">
<tr className="border-b border-gray-200">
<td className="py-2 px-3">Headline</td>
<td className="py-2 px-3">High</td>
<td className="py-2 px-3">36-48px</td>
<td className="py-2 px-3">700</td>
<td className="py-2 px-3">1.1</td>
<td className="py-2 px-3">#111</td>
</tr>
<tr className="border-b border-gray-200">
<td className="py-2 px-3">Headline</td>
<td className="py-2 px-3">Medium</td>
<td className="py-2 px-3">28-34px</td>
<td className="py-2 px-3">600</td>
<td className="py-2 px-3">1.2</td>
<td className="py-2 px-3">#111</td>
</tr>
<tr className="border-b border-gray-200">
<td className="py-2 px-3">Headline</td>
<td className="py-2 px-3">Low</td>
<td className="py-2 px-3">22-26px</td>
<td className="py-2 px-3">500</td>
<td className="py-2 px-3">1.3</td>
<td className="py-2 px-3">#222</td>
</tr>
<tr className="border-b border-gray-200">
<td className="py-2 px-3">Subhead</td>
<td className="py-2 px-3">High</td>
<td className="py-2 px-3">20-24px</td>
<td className="py-2 px-3">600</td>
<td className="py-2 px-3">1.25</td>
<td className="py-2 px-3">#222</td>
</tr>
<tr className="border-b border-gray-200">
<td className="py-2 px-3">Subhead</td>
<td className="py-2 px-3">Medium</td>
<td className="py-2 px-3">16-18px</td>
<td className="py-2 px-3">500</td>
<td className="py-2 px-3">1.3</td>
<td className="py-2 px-3">#333</td>
</tr>
<tr className="border-b border-gray-200">
<td className="py-2 px-3">BodyText</td>
<td className="py-2 px-3">High</td>
<td className="py-2 px-3">16px</td>
<td className="py-2 px-3">400</td>
<td className="py-2 px-3">1.5</td>
<td className="py-2 px-3">#333</td>
</tr>
<tr className="border-b border-gray-200">
<td className="py-2 px-3">BodyText</td>
<td className="py-2 px-3">Medium</td>
<td className="py-2 px-3">14-15px</td>
<td className="py-2 px-3">400</td>
<td className="py-2 px-3">1.5</td>
<td className="py-2 px-3">#444</td>
</tr>
<tr className="border-b border-gray-200">
<td className="py-2 px-3">BodyText</td>
<td className="py-2 px-3">Low</td>
<td className="py-2 px-3">12-14px</td>
<td className="py-2 px-3">400</td>
<td className="py-2 px-3">1.4</td>
<td className="py-2 px-3">#555</td>
</tr>
</tbody>
</table>
</div>
<h2>使用建议</h2>
<ul>
<li>主标题使用 Headline High 权重</li>
<li>次要标题使用 Headline Medium 或 Low 权重</li>
<li>正文使用 BodyText Medium 权重</li>
<li>重要段落或引言使用 BodyText High 权重</li>
<li>注释或说明使用 BodyText Low 权重</li>
<li>引用使用 Quote 组件突出显示</li>
<li>作者信息使用 Byline 组件</li>
<li>图片说明使用 Caption 组件</li>
</ul>
</div>
);
}
packages/docs/app/theme/page.tsx
+310
View File
@@ -0,0 +1,310 @@
import { CodeBlock } from '@/components/CodeBlock';
export default function ThemePage() {
return (
<div className="prose prose-lg max-w-none">
<h1>主题系统</h1>
<p className="text-xl text-gray-600">
NewspaperUI 基于 CSS Variables 构建主题系统，支持主题切换和自定义。
</p>
<h2>CSS Variables</h2>
<p>
主题系统使用 CSS 自定义属性（CSS Variables）定义颜色、字体、间距等设计令牌。
这使得主题切换和自定义变得简单而灵活。
</p>
<h3>核心变量</h3>
<CodeBlock
title="CSS Variables"
language="css"
code={`:root {
/* 颜色系统 */
--color-text-primary: #111;
--color-text-secondary: #222;
--color-text-tertiary: #333;
--color-text-muted: #555;
--color-background: #ffffff;
--color-border: #e5e7eb;
/* 字体系统 */
--font-family-serif: Georgia, 'Times New Roman', serif;
--font-family-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
--font-family-mono: 'Courier New', monospace;
/* 间距系统 */
--spacing-gutter: 1rem;
--spacing-section: 2rem;
--spacing-article: 1.5rem;
/* 栅格系统 */
--grid-columns: 24;
--grid-max-width: 1280px;
}`}
/>
<h2>Tailwind 集成</h2>
<p>
NewspaperUI 的主题系统与 Tailwind CSS 深度集成，可以直接在 Tailwind 配置中使用主题变量。
</p>
<CodeBlock
title="tailwind.config.js"
language="javascript"
code={`import { newspaperTheme } from '@newspaperui/theme';
export default {
content: ['./src/**/*.{js,ts,jsx,tsx}'],
theme: {
extend: {
colors: {
newspaper: {
text: {
primary: 'var(--color-text-primary)',
secondary: 'var(--color-text-secondary)',
tertiary: 'var(--color-text-tertiary)',
muted: 'var(--color-text-muted)',
},
},
},
fontFamily: {
serif: 'var(--font-family-serif)',
sans: 'var(--font-family-sans)',
mono: 'var(--font-family-mono)',
},
},
},
plugins: [newspaperTheme],
};`}
/>
<h2>使用主题变量</h2>
<p>
在组件中可以直接使用 CSS Variables 或 Tailwind 工具类。
</p>
<CodeBlock
title="使用示例"
language="tsx"
code={`// 使用 CSS Variables
<div style={{ color: 'var(--color-text-primary)' }}>
主要文本
</div>
// 使用 Tailwind 工具类
<div className="text-newspaper-text-primary">
主要文本
</div>`}
/>
<h2>自定义主题</h2>
<p>
你可以通过覆盖 CSS Variables 来自定义主题。
</p>
<CodeBlock
title="自定义主题"
language="css"
code={`:root {
/* 覆盖默认颜色 */
--color-text-primary: #000000;
--color-text-secondary: #1a1a1a;
--color-background: #f9f9f9;
/* 自定义字体 */
--font-family-serif: 'Merriweather', Georgia, serif;
/* 调整间距 */
--spacing-gutter: 1.5rem;
--grid-max-width: 1440px;
}`}
/>
<h2>深色模式</h2>
<p>
通过定义深色模式的 CSS Variables，可以轻松实现主题切换。
</p>
<CodeBlock
title="深色模式"
language="css"
code={`@media (prefers-color-scheme: dark) {
:root {
--color-text-primary: #f5f5f5;
--color-text-secondary: #e0e0e0;
--color-text-tertiary: #cccccc;
--color-text-muted: #999999;
--color-background: #1a1a1a;
--color-border: #333333;
}
}
/* 或使用类名切换 */
.dark {
--color-text-primary: #f5f5f5;
--color-text-secondary: #e0e0e0;
--color-background: #1a1a1a;
}`}
/>
<h2>视觉权重配置</h2>
<p>
视觉权重系统的配置也可以通过主题系统进行自定义。
</p>
<CodeBlock
title="自定义视觉权重"
language="typescript"
code={`import { visualWeights } from '@newspaperui/theme';
// 查看默认配置
console.log(visualWeights.Headline.High);
// {
// fontSize: '36px',
// fontWeight: 700,
// lineHeight: 1.1,
// color: '#111',
// span: [6, 8],
// margin: '0 0 1rem 0',
// }
// 自定义权重配置
const customWeights = {
...visualWeights,
Headline: {
...visualWeights.Headline,
High: {
...visualWeights.Headline.High,
fontSize: '48px', // 更大的标题
fontWeight: 800,
},
},
};`}
/>
<h2>响应式主题</h2>
<p>
可以根据屏幕尺寸调整主题变量，实现响应式设计。
</p>
<CodeBlock
title="响应式变量"
language="css"
code={`:root {
--grid-columns: 24;
--spacing-gutter: 1rem;
}
@media (max-width: 768px) {
:root {
--grid-columns: 12;
--spacing-gutter: 0.75rem;
}
}
@media (max-width: 480px) {
:root {
--grid-columns: 6;
--spacing-gutter: 0.5rem;
}
}`}
/>
<h2>主题最佳实践</h2>
<ul>
<li>使用语义化的变量名，如 <code>--color-text-primary</code> 而不是 <code>--color-black</code></li>
<li>保持颜色对比度符合 WCAG 无障碍标准</li>
<li>使用相对单位（rem、em）而不是绝对单位（px）以支持用户字体大小偏好</li>
<li>在深色模式下确保所有颜色都有对应的深色版本</li>
<li>测试主题在不同设备和浏览器上的表现</li>
<li>提供主题切换的用户界面</li>
</ul>
<h2>导入主题</h2>
<p>
在你的应用中导入 NewspaperUI 主题：
</p>
<CodeBlock
title="导入主题"
language="typescript"
code={`// 在你的主 CSS 文件中
import '@newspaperui/theme/variables.css';
// 或在 Next.js 的 _app.tsx 中
import '@newspaperui/theme/variables.css';
import '@newspaperui/theme/tailwind.css';`}
/>
<h2>主题工具</h2>
<p>
NewspaperUI 提供了一些工具函数来帮助你使用主题系统：
</p>
<CodeBlock
title="主题工具"
language="typescript"
code={`import { getVisualWeight, applyTheme } from '@newspaperui/theme';
// 获取特定组件的视觉权重配置
const headlineHighConfig = getVisualWeight('Headline', 'High');
// 应用主题到元素
applyTheme(element, {
'--color-text-primary': '#000',
'--font-family-serif': 'Georgia',
});`}
/>
<h2>主题示例</h2>
<p>
以下是一些预设主题示例：
</p>
<div className="grid grid-cols-1 md:grid-cols-2 gap-6 my-8">
<div className="border border-gray-200 rounded-lg p-6">
<h3 className="text-lg font-semibold mb-3">经典报纸</h3>
<div className="space-y-2 text-sm">
<div className="flex justify-between">
<span>主色调</span>
<span className="font-mono">#111111</span>
</div>
<div className="flex justify-between">
<span>背景色</span>
<span className="font-mono">#ffffff</span>
</div>
<div className="flex justify-between">
<span>字体</span>
<span className="font-mono">Georgia</span>
</div>
</div>
</div>
<div className="border border-gray-200 rounded-lg p-6 bg-gray-900 text-white">
<h3 className="text-lg font-semibold mb-3">深色模式</h3>
<div className="space-y-2 text-sm">
<div className="flex justify-between">
<span>主色调</span>
<span className="font-mono">#f5f5f5</span>
</div>
<div className="flex justify-between">
<span>背景色</span>
<span className="font-mono">#1a1a1a</span>
</div>
<div className="flex justify-between">
<span>字体</span>
<span className="font-mono">Georgia</span>
</div>
</div>
</div>
</div>
<h2>更多资源</h2>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties">MDN: CSS Custom Properties</a></li>
<li><a href="https://tailwindcss.com/docs/customizing-colors">Tailwind CSS: Customizing Colors</a></li>
<li><a href="https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html">WCAG: Contrast Guidelines</a></li>
</ul>
</div>
);
}